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:

"operationId": "<uuid>"

---

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:

"authenticationId": "<operationId obtido em onboarding>"

⚠️ 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:

POST https://<base-url>/workflows/{workflowId}/create

Headers:

X-Auth: <API_KEY>
X-Integration-Id: <tenantId>:<integrationId>
Content-Type: application/json

Corpo para Onboarding:

{
    "payload": {
        "source": "<service-id>",
        "customerId": "<string-client-id>",
        "document": { //optional
            "issuer": "<alpha3-issuer-country-code>",
            "type": "<ID_CARD|PASSPORT|DRIVERS_LICENSE|RESIDENCE_PERMIT>",
            "number": "<document-number>",
            "code": "<document-code> (optional)",
            "gender": "<persona-name> (optional)",
            "name": "<person-name> (optional)",
            "surname": "<person-surname> (optional)"
        }
    },
    "timestamp": 1761228742430,
    "signature": "<firma-HMAC-SHA256>"
}

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:

{
    "payload": {
        "source": "<service-id>",
        "customerId": "<string-client-id>",
        "authenticationId": "<string-authentication-id>"
    },
    "timestamp": 1761228742430,
    "signature": "<firma-HMAC-SHA256>"
}

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:

import { createHmac } from 'crypto';

function getSignature(payload: object, secret: string): string {
  const hmac = createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  return hmac.digest('hex');
}

Resposta bem-sucedida

{
  "integrationId": "<tenantId>:<integrationId>",
  "workflowId": "<workflowId>",
  "operationId": "<operationId>",
  "accessUrl": "https://<base-url>/<tenantId>:<integrationId>?ref=<token>"
}

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 único — o 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.