For the complete documentation index, see llms.txt. This page is also available as Markdown.

No-code: Landing

A Integração Landing é a implementação técnica associada a uma integração do tipo No-Code. Uma vez configurada e publicada a integração na plataforma Facephi IDV Suite, a Landing é o canal web por meio do qual o usuário final executa o fluxo de verificação.

O modelo de integração é sempre backend to backend: o sistema do cliente gera a sessão a partir do seu servidor e entrega ao usuário final uma URL de acesso único. A Facephi IDV Suite gerencia integralmente a experiência a partir desse momento.


Pré-requisitos

Para colocar em funcionamento uma integração Landing, você precisa de:

  • Uma integração No-Code publicada na plataforma IDV Suite.

  • O Workflow ID, obtido no módulo Fluxos, acessando o fluxo que se deseja utilizar.

  • Integration ID, é obtido no módulo Integrações, acessando os detalhes da integração correspondente.

  • O Tenant ID, visível no seletor de tenants na parte superior da plataforma.

  • A API Key associada à integração (disponível na etapa Set up da configuração).

  • O base URL da API será fornecida pela equipe de Suporte ou Delivery da Facephi.


Iniciar uma sessão

O backend do cliente realiza uma chamada autenticada à API de IDV Suite para gerar uma sessão. A resposta inclui uma URL de acesso único (accessUrl) que é entregue ao usuário final para que conclua o fluxo.

Fluxo de Onboarding e Autenticação

A integração pode envolver duas etapas:

1. Onboarding

Inicia-se uma sessão de verificação por meio da geração de um accessUrl.

Como resultado do processo, obtém-se um identificador único da operação:


2. Autenticação (opcional)

Nos fluxos de autenticação, é necessário reutilizar o resultado de um onboarding anterior.

Para isso, o operationId obtido no onboarding deve ser enviado como authenticationId:

⚠️ Importante O operationId deve ser usado apenas como authenticationId se o processo de onboarding tiver sido concluído e validado com êxito.

Chamada à API

Endpoint:

Headers:

Corpo para Onboarding:

Descrição dos campos (Onboarding)
Campo
Tipo
Obrigatório
Valores
Descrição

payload.source

string

Identificador do serviço de origem

payload.customerId

string

Identificador único do cliente

payload.document

object

Informações do documento do usuário

payload.document.issuer

string

Condicional*

ISO alpha-3 (ex: ESP, ARG)

Código do país do documento

payload.document.type

string

Condicional*

ID_CARD, PASSPORT, DRIVERS_LICENSE, RESIDENCE_PERMIT

Tipo de documento

payload.document.number

string

Condicional*

Número do documento

payload.document.code

string

Código adicional do documento

payload.document.gender

string

Gênero do usuário

payload.document.name

string

Nome do usuário

payload.document.surname

string

Sobrenome do usuário

timestamp

number

epoch (ms)

Timestamp em milissegundos

signature

string

HMAC-SHA256

Assinatura do payload

Notas

⚠️ Campos condicionais (payload.document) O objeto payload.document é opcional. No entanto, se for incluído na solicitação, os seguintes campos tornam-se obrigatórios:

  • issuer

  • type

  • number

Corpo para Autenticação:

Descrição dos campos (Autenticação)
Campo
Tipo
Obrigatório
Valores
Descrição

payload.source

string

Identificador do serviço de origem

payload.customerId

string

Identificador único do cliente

payload.authenticationId

string

UUID

operationId obtido em um onboarding bem-sucedido

timestamp

number

epoch (ms)

Timestamp em milissegundos

signature

string

HMAC-SHA256

Assinatura do payload

Os campos dentro de payload dependem do fluxo configurado na plataforma. Consulte a equipe de Suporte da Facephi para saber quais campos são necessários para o seu caso de uso específico. Em qualquer caso, são opcionais.

Assinatura da solicitação

Todas as solicitações devem ser assinadas com HMAC-SHA256 calculado sobre JSON.stringify(payload). O resultado é incluído no campo signature como string hexadecimal.

Exemplo em TypeScript:

Resposta bem-sucedida

Descrição dos campos (Resposta)
Campo
Tipo
Valores
Descrição

integrationId

string

<tenantId>:<integrationId>

Identificador completo da integração

workflowId

string

UUID

Identificador do fluxo executado

operationId

string

UUID

Identificador único da operação

accessUrl

string

URL

URL de acesso único para o usuário

Detalhes importantes

O campo accessUrl contém a URL de acesso único para esse usuário. É a URL para a qual você deve redirecionar o usuário ou carregar no iframe. Cada accessUrl é de uso únicoo tempo de validade da URL é de 15 min.

O parâmetro ref incluído na accessUrl é um token que contém o operationId e o workflowId necessários para retomar a operação se o usuário interromper o fluxo.


Comportamento da sessão

Aspecto
Comportamento

Duração

A sessão tem duração limitada. Se o usuário não concluir o fluxo nesse tempo, a operação expira.

Ao concluir o fluxo

O usuário é redirecionado para a outputUrl configurada na integração (se uma tiver sido definida).

Uso único

A accessUrl gerada com parâmetros é de uso único. OPCIONAL

Retomada

Se o usuário precisar retomar um fluxo interrompido, o endpoint de retomada permite recuperar a sessão usando o operationId.


Códigos de erro

Código
Identificador
Descrição

400

INVALID_INTEGRATION_WORKFLOW_PARAMS

Parâmetros inválidos ou com formato incorreto. O detalhe inclui o campo afetado.

403

INVALID_INTEGRATION_WORKFLOW_ACCESS

A integração não permite essa modalidade de acesso.

404

WORKFLOW_NOT_FOUND

Fluxo ou integração não encontrada. Verifique o Integration ID.

404

OPERATION_NOT_FOUND

A operação em andamento não existe ou não corresponde à integração indicada.

422

INVALID_INTEGRATION_WORKFLOW_CONFIG

A configuração do fluxo na plataforma não é válida. Requer revisão no Designer de fluxos.

429

TOO_MANY_REQUESTS

Limite de solicitações excedido.

500

UNEXPECTED_ERROR

Erro interno. Entre em contato com a equipe de Suporte da Facephi.

500

REGION_CONFIGURATION_NOT_FOUND

Não existe configuração de região para o tenant.

500

TRACKING_PLATFORM_NOT_FOUND

Não existe configuração de plataforma de tracking para o tenant.

500

TRACKING_PLATFORM_CONNECTION_ERROR

Erro de conexão com a plataforma de tracking configurada.


Você precisa de mais controle sobre a experiência?

A integração Landing gerencia integralmente a UX do fluxo. Se o seu caso de uso exigir integração nativa na sua web ou maior controle sobre a interface, consulte a seção Solução Web — SDK Web Loader.

Atualizado