> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/produtos/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/no-code-landing.md).

# 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:**

```json
{
    "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>"
}
```

<details>

<summary>Descrição dos campos (Onboarding)</summary>

| 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`

</details>

**Corpo para Autenticação:**

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

<details>

<summary>Descrição dos campos (Autenticação)</summary>

| 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                              |

</details>

{% hint style="info" %}
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.
{% endhint %}

#### 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:

```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

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

<details>

<summary>Descrição dos campos (Resposta)</summary>

<table><thead><tr><th width="171">Campo</th><th>Tipo</th><th>Valores</th><th>Descrição</th></tr></thead><tbody><tr><td>integrationId</td><td>string</td><td><code>&#x3C;tenantId>:&#x3C;integrationId></code></td><td>Identificador completo da integração</td></tr><tr><td>workflowId</td><td>string</td><td>UUID</td><td>Identificador do fluxo executado</td></tr><tr><td>operationId</td><td>string</td><td>UUID</td><td>Identificador único da operação</td></tr><tr><td>accessUrl</td><td>string</td><td>URL</td><td>URL de acesso único para o usuário</td></tr></tbody></table>

</details>

#### 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.*

{% hint style="info" %}
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.
{% endhint %}

***

### Comportamento da sessão

<table><thead><tr><th width="205.45703125">Aspecto</th><th>Comportamento</th></tr></thead><tbody><tr><td><strong>Duração</strong></td><td>A sessão tem duração limitada. Se o usuário não concluir o fluxo nesse tempo, a operação expira.</td></tr><tr><td><strong>Ao concluir o fluxo</strong></td><td>O usuário é redirecionado para a <code>outputUrl</code> configurada na integração (se uma tiver sido definida).</td></tr><tr><td><strong>Uso único</strong></td><td>A <code>accessUrl</code> gerada com parâmetros é de uso único. OPCIONAL</td></tr><tr><td><strong>Retomada</strong></td><td>Se o usuário precisar retomar um fluxo interrompido, o endpoint de retomada permite recuperar a sessão usando o <code>operationId</code>.</td></tr></tbody></table>

***

### Códigos de erro

<table><thead><tr><th width="99.09765625">Código</th><th width="339.671875">Identificador</th><th>Descrição</th></tr></thead><tbody><tr><td><code>400</code></td><td><code>INVALID_INTEGRATION_WORKFLOW_PARAMS</code></td><td>Parâmetros inválidos ou com formato incorreto. O detalhe inclui o campo afetado.</td></tr><tr><td><code>403</code></td><td><code>INVALID_INTEGRATION_WORKFLOW_ACCESS</code></td><td>A integração não permite essa modalidade de acesso.</td></tr><tr><td><code>404</code></td><td><code>WORKFLOW_NOT_FOUND</code></td><td>Fluxo ou integração não encontrada. Verifique o Integration ID.</td></tr><tr><td><code>404</code></td><td><code>OPERATION_NOT_FOUND</code></td><td>A operação em andamento não existe ou não corresponde à integração indicada.</td></tr><tr><td><code>422</code></td><td><code>INVALID_INTEGRATION_WORKFLOW_CONFIG</code></td><td>A configuração do fluxo na plataforma não é válida. Requer revisão no Designer de fluxos.</td></tr><tr><td><code>429</code></td><td><code>TOO_MANY_REQUESTS</code></td><td>Limite de solicitações excedido.</td></tr><tr><td><code>500</code></td><td><code>UNEXPECTED_ERROR</code></td><td>Erro interno. Entre em contato com a equipe de Suporte da Facephi.</td></tr><tr><td><code>500</code></td><td><code>REGION_CONFIGURATION_NOT_FOUND</code></td><td>Não existe configuração de região para o tenant.</td></tr><tr><td><code>500</code></td><td><code>TRACKING_PLATFORM_NOT_FOUND</code></td><td>Não existe configuração de plataforma de tracking para o tenant.</td></tr><tr><td><code>500</code></td><td><code>TRACKING_PLATFORM_CONNECTION_ERROR</code></td><td>Erro de conexão com a plataforma de tracking configurada.</td></tr></tbody></table>

***

### 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](/docs.facephi-pt-br/produtos/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/sdk-loader-idv.md).