> 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/productos/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/no-code-landing.md).

# No-code: Landing

La integración Landing es la implementación técnica asociada a una integración de tipo No-Code. Una vez configurada y publicada la integración en la plataforma Facephi IDV Suite, la Landing es el canal web a través del cual el usuario final ejecuta el flujo de verificación.

El modelo de integración es siempre **backend to backend**: el sistema del cliente genera la sesión desde su servidor y entrega al usuario final una URL de acceso único. Facephi IDV Suite gestiona íntegramente la experiencia a partir de ese momento.

***

### Prerrequisitos

Para poner en marcha una integración Landing necesitas:

* Una **integración No-Code publicada** en la plataforma IDV Suite.
* El **Workflow ID**, se obtiene desde el módulo *Flujos*, accediendo al flujo que se desea utilizar.
* **Integration ID,** se obtiene desde el módulo *Integraciones*, accediendo al detalle de la integración correspondiente.
* El **Tenant ID**, visible desde el selector de tenants en la parte superior de la plataforma.
* La **API Key** asociada a la integración (disponible en el paso Set up de la configuración).
* El **base URL** de la API será proporcionado por el equipo de Soporte o Delivery de Facephi.

***

### Iniciar una sesión

El backend del cliente realiza una llamada autenticada a la API de IDV Suite para generar una sesión. La respuesta incluye una URL de acceso único (`accessUrl`) que se entrega al usuario final para que complete el flujo.

#### Flujo de Onboarding y Autenticación

La integración puede involucrar dos etapas:

#### 1. Onboarding

Se inicia una sesión de verificación mediante la generación de un `accessUrl`.

Como resultado del proceso, se obtiene un identificador único de operación:

```
"operationId": "<uuid>"
```

***

#### 2. Autenticación (opcional)

En flujos de autenticación, es necesario reutilizar el resultado de un onboarding previo.

Para ello, el `operationId` obtenido en el onboarding debe enviarse como `authenticationId`:

```
"authenticationId": "<operationId obtenido en onboarding>"
```

> ⚠️ **Importante**\
> El `operationId` solo debe utilizarse como `authenticationId` si el proceso de onboarding fue finalizado y validado exitosamente.

#### Llamada a la API

**Endpoint:**

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

**Headers:**

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

**Body 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>Descripción de campos (Onboarding)</summary>

| Campo                    | Tipo   | Requerido     | Valores                                                      | Descripción                           |
| ------------------------ | ------ | ------------- | ------------------------------------------------------------ | ------------------------------------- |
| payload.source           | string | ✅             | —                                                            | Identificador del servicio origen     |
| payload.customerId       | string | ✅             | —                                                            | Identificador único del cliente       |
| payload.document         | object | ❌             | —                                                            | Información del documento del usuario |
| payload.document.issuer  | string | Condicional\* | ISO alpha-3 (ej: ESP, ARG)                                   | Código de país del documento          |
| payload.document.type    | string | Condicional\* | `ID_CARD`, `PASSPORT`, `DRIVERS_LICENSE`, `RESIDENCE_PERMIT` | Tipo de documento                     |
| payload.document.number  | string | Condicional\* | —                                                            | Número de documento                   |
| payload.document.code    | string | ❌             | —                                                            | Código adicional del documento        |
| payload.document.gender  | string | ❌             | —                                                            | Género del usuario                    |
| payload.document.name    | string | ❌             | —                                                            | Nombre del usuario                    |
| payload.document.surname | string | ❌             | —                                                            | Apellido del usuario                  |
| timestamp                | number | ✅             | epoch (ms)                                                   | Timestamp en milisegundos             |
| signature                | string | ✅             | HMAC-SHA256                                                  | Firma del payload                     |

Notas

> ⚠️ **Campos condicionales (`payload.document`)**\
> El objeto `payload.document` es opcional.\
> Sin embargo, si se incluye en la petición, los siguientes campos pasan a ser obligatorios:
>
> * `issuer`
> * `type`
> * `number`

</details>

**Body para Autenticación:**

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

<details>

<summary>Descripción de campos (Autenticación)</summary>

| Campo                    | Tipo   | Requerido | Valores     | Descripción                                     |
| ------------------------ | ------ | --------- | ----------- | ----------------------------------------------- |
| payload.source           | string | ✅         | —           | Identificador del servicio origen               |
| payload.customerId       | string | ✅         | —           | Identificador único del cliente                 |
| payload.authenticationId | string | ✅         | UUID        | `operationId` obtenido en un onboarding exitoso |
| timestamp                | number | ✅         | epoch (ms)  | Timestamp en milisegundos                       |
| signature                | string | ✅         | HMAC-SHA256 | Firma del payload                               |

</details>

{% hint style="info" %}
Los campos dentro de payload dependen del flujo configurado en la plataforma. Consulta con el equipo de Soporte de Facephi qué campos son necesarios para tu caso de uso concreto. En todo caso son opcionales.
{% endhint %}

#### Firma de la petición

Todas las peticiones deben firmarse con **HMAC-SHA256** calculado sobre `JSON.stringify(payload)`. El resultado se incluye en el campo `signature` como cadena hexadecimal.

Ejemplo en 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');
}
```

#### Respuesta exitosa

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

<details>

<summary>Descripción de campos (Response)</summary>

<table><thead><tr><th width="171">Campo</th><th>Tipo</th><th>Valores</th><th>Descripción</th></tr></thead><tbody><tr><td>integrationId</td><td>string</td><td><code>&#x3C;tenantId>:&#x3C;integrationId></code></td><td>Identificador completo de la integración</td></tr><tr><td>workflowId</td><td>string</td><td>UUID</td><td>Identificador del flujo ejecutado</td></tr><tr><td>operationId</td><td>string</td><td>UUID</td><td>Identificador único de la operación</td></tr><tr><td>accessUrl</td><td>string</td><td>URL</td><td>URL de acceso único para el usuario</td></tr></tbody></table>

</details>

#### Detalles importantes

El campo `accessUrl` contiene la URL de acceso único para ese usuario. Es la URL a la que debes redirigir al usuario o cargar en el iframe. Cada `accessUrl` es de **un solo uso** — *el tiempo de validez de la URL es de 15 min.*

{% hint style="info" %}
El parámetro `ref` incluido en la `accessUrl` es un token que contiene el `operationId` y el `workflowId` necesarios para retomar la operación si el usuario interrumpe el flujo.
{% endhint %}

***

### Comportamiento de la sesión

<table><thead><tr><th width="205.45703125">Aspecto</th><th>Comportamiento</th></tr></thead><tbody><tr><td><strong>Duración</strong></td><td>La sesión tiene una duración limitada. Si el usuario no completa el flujo en ese tiempo, la operación expira.</td></tr><tr><td><strong>Al completar el flujo</strong></td><td>El usuario es redirigido a la <code>outputUrl</code> configurada en la integración (si se definió una).</td></tr><tr><td><strong>Uso único</strong></td><td>La <code>accessUrl</code> generada con parámetros es de un solo uso. OPCIONAL</td></tr><tr><td><strong>Reintento</strong></td><td>Si el usuario necesita retomar un flujo interrumpido, el endpoint de reanudación permite recuperar la sesión usando el <code>operationId</code>.</td></tr></tbody></table>

***

### Códigos de error

<table><thead><tr><th width="99.09765625">Código</th><th width="339.671875">Identificador</th><th>Descripción</th></tr></thead><tbody><tr><td><code>400</code></td><td><code>INVALID_INTEGRATION_WORKFLOW_PARAMS</code></td><td>Parámetros inválidos o con formato incorrecto. El detalle incluye el campo afectado.</td></tr><tr><td><code>403</code></td><td><code>INVALID_INTEGRATION_WORKFLOW_ACCESS</code></td><td>La integración no permite esta modalidad de acceso.</td></tr><tr><td><code>404</code></td><td><code>WORKFLOW_NOT_FOUND</code></td><td>Flujo o integración no encontrada. Verifica el Integration ID.</td></tr><tr><td><code>404</code></td><td><code>OPERATION_NOT_FOUND</code></td><td>La operación en curso no existe o no corresponde a la integración indicada.</td></tr><tr><td><code>422</code></td><td><code>INVALID_INTEGRATION_WORKFLOW_CONFIG</code></td><td>La configuración del flujo en la plataforma no es válida. Requiere revisión en el Diseñador de flujos.</td></tr><tr><td><code>429</code></td><td><code>TOO_MANY_REQUESTS</code></td><td>Límite de peticiones superado.</td></tr><tr><td><code>500</code></td><td><code>UNEXPECTED_ERROR</code></td><td>Error interno. Contacta con el equipo de Soporte de Facephi.</td></tr><tr><td><code>500</code></td><td><code>REGION_CONFIGURATION_NOT_FOUND</code></td><td>No existe configuración de región para el tenant.</td></tr><tr><td><code>500</code></td><td><code>TRACKING_PLATFORM_NOT_FOUND</code></td><td>No existe configuración de plataforma de tracking para el tenant.</td></tr><tr><td><code>500</code></td><td><code>TRACKING_PLATFORM_CONNECTION_ERROR</code></td><td>Error de conexión con la plataforma de tracking configurada.</td></tr></tbody></table>

***

### ¿Necesitas más control sobre la experiencia?

La integración Landing gestiona íntegramente la UX del flujo. Si tu caso de uso requiere integración nativa en tu web o mayor control sobre la interfaz, consulta la sección [Solución Web — SDK Web Loader](/productos/idv-suite/flujos-and-integraciones/configuracion-tecnica-del-cliente/solucion-web/sdk-loader-idv.md).