Primeros pasos
Integración / SDKs
Verificación de usuarios
Verificación de empresas
Monitorización de transacciones
Registro de cambioscurl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{
WorkflowID: "11111111-2222-3333-4444-555555555555",
VendorData: didit.String("user-123"),
Callback: didit.String("https://example.com/verification/callback"),
CallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod("both")),
Metadata: didit.Some[any](map[string]any{"user_type": "premium", "account_id": "ABC123"}),
Language: didit.Some(didit.SessionsCreateParamsLanguage("en")),
ContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{
Email: didit.String("john.doe@example.com"),
SendNotificationEmails: didit.Bool(true),
EmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang("en")),
Phone: didit.String("+14155552671"),
}),
ExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{
FirstName: didit.String("John"),
LastName: didit.String("Doe"),
DateOfBirth: didit.String("1990-05-15"),
Nationality: didit.String("USA"),
IDCountry: didit.String("USA"),
ExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{"P", "ID"}),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_husing System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary<string, object> { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"session_id": "11111111-2222-3333-4444-555555555555",
"session_number": 43762,
"session_token": "3FaJ9wLqX2Mz",
"url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz",
"vendor_data": "user-123",
"metadata": {
"user_type": "premium",
"account_id": "ABC123"
},
"status": "Not Started",
"workflow_id": "11111111-2222-3333-4444-555555555555",
"workflow_version": 3,
"callback": "https://example.com/verification/callback"
}API para crear sesión: inicia una verificación KYC o KYB
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{
WorkflowID: "11111111-2222-3333-4444-555555555555",
VendorData: didit.String("user-123"),
Callback: didit.String("https://example.com/verification/callback"),
CallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod("both")),
Metadata: didit.Some[any](map[string]any{"user_type": "premium", "account_id": "ABC123"}),
Language: didit.Some(didit.SessionsCreateParamsLanguage("en")),
ContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{
Email: didit.String("john.doe@example.com"),
SendNotificationEmails: didit.Bool(true),
EmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang("en")),
Phone: didit.String("+14155552671"),
}),
ExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{
FirstName: didit.String("John"),
LastName: didit.String("Doe"),
DateOfBirth: didit.String("1990-05-15"),
Nationality: didit.String("USA"),
IDCountry: didit.String("USA"),
ExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{"P", "ID"}),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_husing System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary<string, object> { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"session_id": "11111111-2222-3333-4444-555555555555",
"session_number": 43762,
"session_token": "3FaJ9wLqX2Mz",
"url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz",
"vendor_data": "user-123",
"metadata": {
"user_type": "premium",
"account_id": "ABC123"
},
"status": "Not Started",
"workflow_id": "11111111-2222-3333-4444-555555555555",
"workflow_version": 3,
"callback": "https://example.com/verification/callback"
}Compatibilidad con KYC y KYB
Un único endpoint crea tanto sesiones de Verificación de usuarios como de Verificación de empresas. El tipo del flujo de verificación (workflow) determina cuál se crea:- Si pasas el
workflow_idde un Flujo de trabajo KYC, se crea una sesión de Verificación de usuarios (KYC). La respuesta incluyesession_kind: "user". - Si pasas el
workflow_idde un Flujo de trabajo KYB, se crea una sesión de Verificación de empresas (KYB). La respuesta incluyesession_kind: "business".
Ejemplos
- Verificación de usuarios (KYC)
- Verificación de empresas (KYB)
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_KYC_WORKFLOW_ID",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback"
}'
{
"session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
"session_kind": "user",
"session_number": 1024,
"session_token": "...",
"url": "https://verify.didit.me/session/...",
"status": "Not Started",
"workflow_id": "YOUR_KYC_WORKFLOW_ID",
"vendor_data": "user-42"
}
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_KYB_WORKFLOW_ID",
"vendor_data": "biz-acme-001",
"callback": "https://yourapp.com/callback"
}'
{
"session_id": "bs-01HJX1...",
"session_kind": "business",
"session_number": 89,
"session_token": "...",
"url": "https://verify.didit.me/session/...",
"status": "Not Started",
"workflow_id": "YOUR_KYB_WORKFLOW_ID",
"vendor_data": "biz-acme-001"
}
Documentos de firma electrónica
Cuando el flujo tiene un paso de Firma electrónica que toma los documentos de la sesión (signature_documents_source con el valor session o both), envíalos en sign.documents. Cada documento es el archivo en base64, así que Didit nunca tiene que descargarlo desde una URL.
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"documents": [
{
"title": "Loan agreement",
"file_name": "loan-agreement.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"fields": [
{ "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 },
{ "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" },
{ "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" },
{ "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } }
]
}
],
"field_values": { "loan_amount": "12,000 EUR" }
}
}
| Campo | Reglas |
|---|---|
title | Se muestra al firmante. De 1 a 255 caracteres. Por defecto, file_name. |
file_name | Obligatorio. Termina en .pdf o .docx. De 1 a 255 caracteres. |
content_base64 | Obligatorio. Un PDF puede tener hasta 20 MB y 100 páginas, sin contraseña, scripts ni archivos adjuntos. Un archivo de Word puede tener hasta 20 MB y se convierte a PDF durante la solicitud, en un máximo de 25 segundos; el PDF resultante tiene entonces los mismos límites. Hasta 5 archivos de Word por sesión. |
fields | Opcional. Hasta 200 campos que colocar en el documento, con la estructura de campo sin id. Cada campo necesita una key y un type, y una posición (page, x, y, width y height) o un anchor. role toma por defecto el firmante del paso, y required y label toman su valor por defecto según el tipo. Didit establece position según dónde se encuentre el campo. Las páginas y posiciones se refieren al PDF o, en el caso de un archivo de Word, al PDF convertido. |
fields, el firmante lee el documento y lo acepta.
Colocar campos por texto de anclaje
En lugar de una posición, un campo puede llevar unanchor: un fragmento de texto del documento que marca dónde va el campo. Los anclajes son adecuados para documentos que generas para cada sesión, por ejemplo a partir de una plantilla de Word. Para los documentos del flujo, coloca los campos en la consola.
Propiedad de anchor | Reglas |
|---|---|
text | De 1 a 64 caracteres, que se buscan en el texto del documento. En un archivo de Word, en el PDF convertido. |
occurrence | first (por defecto) coloca un campo en la primera coincidencia. all coloca un campo por coincidencia, y las claves posteriores a la primera reciben _2, _3 y así sucesivamente. |
offset_x, offset_y | Fracciones de la página. La esquina superior izquierda del campo es la esquina superior izquierda del texto de anclaje más estos desplazamientos. |
width, height | El tamaño del campo, como fracciones de la página. |
400 con field_anchor_not_found y la clave del campo. Didit no elimina el texto de anclaje del PDF, así que escríbelo del mismo color que el fondo de la página.
Valores de campos
sign.field_values establece el valor de cada campo cuyo prefill sea api.<key>, tanto en los documentos del flujo como en los de la sesión. Es un objeto cuyas claves son esos nombres <key>. Los valores son cadenas de 1 a 500 caracteres para los campos text y data, y booleanos para un checkbox.
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
Error (400) | Cuándo |
|---|---|
field_value_unknown | Una clave que ningún campo usa. |
field_value_missing | Un campo obligatorio cuyo api.<key> no tiene valor. |
field_value_invalid | Un valor que no supera la validación de su campo. |
Errores y llamadas repetidas
Una sesión admite hasta 20 documentos y 50 MB en total. La llamada devuelve400 con un error sign cuando:
- El flujo no tiene un paso de Firma electrónica.
- Enviaste
sign.documentsy el paso solo admite documentos del flujo. - El paso solo admite documentos de la sesión y no enviaste ninguno, o no tiene documentos del flujo y no enviaste ninguno.
- Un documento es demasiado grande, no es base64 válido o no es un archivo compatible.
- Un archivo de Word se rechaza con
signature_document_not_supported, o no se puede convertir y devuelvesignature_document_conversion_failed, en ambos casos con elreasonindicado en Archivos compatibles. - Un campo no es válido, no se encuentra su anclaje (
field_anchor_not_found) o se rechaza un valor de campo.
workflow_id y vendor_data devuelve la sesión pendiente. Si esa llamada envía sign, sus documentos, campos y valores de campos deben ser idénticos a los de la primera llamada (mismo orden, títulos, nombres de archivo, contenido, campos y valores). Cualquier diferencia devuelve 400 con {"sign": "signature_document_changed"}: usa otro vendor_data o espera a que termine la sesión pendiente.
Pruebas con escenarios de sandbox
En una aplicación en modo sandbox, pasasandbox_scenario para precargar un resultado determinista (aprobación, un rechazo concreto o un escenario En revisión) sin tocar proveedores reales ni tu saldo:
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
sandbox_scenario se rechaza con 400 en las aplicaciones de producción. Si aún no conoces el resultado al crear la sesión, puedes activarlo (o reactivarlo) más tarde mediante POST /v3/session/{session_id}/sandbox/arm/, siempre que la sesión siga en Not Started: el selector de escenarios previo al flujo alojado usa este mismo endpoint. Consulta Sandbox y datos de prueba para ver el catálogo completo de escenarios, el registro de valores mágicos y la estructura de solicitud y respuesta del endpoint de activación.
vendor_data vincula la sesión a una entidad
- En los flujos KYC: se vincula a una entidad de usuario. Si el usuario no existe, se crea automáticamente.
- En los flujos KYB: se vincula a una entidad de empresa. Se crea automáticamente si es nueva.
Consentimiento biométrico en Illinois, Texas y Colorado
El flujo alojado y el SDK nativo 4.10.0 o posterior pueden mostrar un paso de consentimiento biométrico explícito antes de la primera captura facial, según el modo de consentimiento de la aplicación y el lugar donde se encuentre la persona. Dos campos opcionales intervienen en esa decisión:user_state: dónde reside la persona, si lo sabes (US-IL,ILoIllinois). En el modo Auto, si reside en un estado sujeto a esta normativa, el flujo solicita el consentimiento.biometric_consent: un objeto congiven_atytext_version, para el consentimiento que ya hayas recopilado. El flujo no vuelve a solicitarlo.
Importante: la información al usuario y el consentimiento siguen siendo responsabilidad de tu producto
Create Session genera una URL de verificación y un token de sesión. Por sí solo, no demuestra que hayas mostrado al usuario la información requerida ni que hayas obtenido el consentimiento necesario para tu caso de uso concreto.
Si inicias una sesión de Didit desde tu propia aplicación, sitio web, wrapper de SDK o flujo de marca blanca, deberías gestionar los aspectos legales en tu propia experiencia de usuario antes de que el usuario comience la captura.
Lista de comprobación recomendada antes de la verificación
- Informa al usuario de que tu empresa solicita la verificación y de que Didit es el proveedor / encargado del tratamiento que impulsa el flujo.
- Incluye un enlace a tu aviso de privacidad y a cualquier término legal del responsable del tratamiento que se aplique al proceso.
- Incluye un enlace al Aviso de privacidad de verificación y a los Términos para usuarios finales de verificación de identidad de Didit.
- Si tu flujo incluye captura de documentos, captura de selfie, prueba de vida o biometría, recopila un consentimiento afirmativo explícito siempre que la legislación aplicable o tu posición legal lo exijan.
- Si usas una interfaz personalizada, un dominio personalizado o un proceso solo por API, muestra esta información en tu propio producto antes de enviar al usuario al flujo de Didit.
- Conserva tu propio registro del texto del aviso / consentimiento, la marca de tiempo y los metadatos relacionados si tu equipo legal requiere un registro de auditoría.
Autorizaciones
La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.
Cuerpo
Identificador estable del flujo de verificación (workflow) que define qué pasos de verificación ejecutará la sesión. Los flujos se crean y gestionan en la página Workflows de la consola. El workflow_id también determina de forma implícita si la sesión es de KYC o de KYB.
"11111111-2222-3333-4444-555555555555"
Un identificador único del usuario que se verifica, como un UUID, un correo electrónico o un ID de usuario interno. Este campo se usa para: (1) Agrupación de usuarios: las sesiones con el mismo vendor_data se vinculan al mismo perfil de usuario en la pestaña Users. (2) Detección de duplicados entre sesiones: al buscar rostros, documentos, números de teléfono, correos electrónicos, direcciones IP o huellas de dispositivo duplicados, las sesiones con el mismo vendor_data se tratan como el mismo usuario y se excluyen de las coincidencias. Sin vendor_data, cada sesión se trata como un usuario único y se muestran todos los posibles duplicados. Recomendamos encarecidamente proporcionar siempre un vendor_data para reducir el ruido en la detección de duplicados.
"user-123"
Ámbito opcional de detección de duplicados dentro de tu organización. Las comprobaciones de rostro duplicado comparan esta sesión solo con otras sesiones que llevan el mismo segmento, de modo que las bases de cuentas separadas (cuentas personales y de empresa, o una por cada subcliente B2B) no marcan a una persona que legítimamente tiene una cuenta en cada una. Omítelo para usar el ámbito predeterminado único, que es el que usan hoy todas las sesiones. La coincidencia con la lista de bloqueo y la lista de permitidos ignora este campo.
64"business-accounts"
URL a la que se redirige al usuario cuando finaliza la verificación. Didit añade automáticamente verificationSessionId y status (Approved, Declined, In Review) como parámetros de consulta. Se admiten esquemas de URL personalizados (p. ej., myapp://) para callbacks en aplicaciones móviles. Si se omite, se usa el callback_url predeterminado del flujo. Cuando la aplicación tiene dominios permitidos (allowed_domains en PATCH /v3/webhook/), un callback http o https debe pertenecer a uno de esos orígenes (mismo esquema, host y puerto); de lo contrario, la solicitud falla con un error 400 en callback: callback must be on one of the application's allowed domains: https://app.example.com. Los esquemas de URL personalizados siempre se aceptan.
"https://example.com/verification/callback"
Determina qué dispositivo debe gestionar la redirección a la URL de callback proporcionada. Usa initiator para redirigir solo el dispositivo que inició el flujo, completer para el dispositivo que lo finaliza, o both para que cualquiera de los dos dispositivos pueda activar el callback. Si notas que el callback no se activa de forma fiable, te recomendamos establecer este valor en both.
initiator, completer, both "both"
JSON arbitrario que se guarda con la sesión y se devuelve en la respuesta y en los webhooks. Se acepta cualquier valor JSON (objeto, cadena, número, array), pero se recomienda un objeto JSON de pares clave/valor. No se muestra al usuario final. Úsalo para pasar tus propios ids de correlación, variantes A/B o contexto de negocio.
{
"user_type": "premium",
"account_id": "ABC123"
}
Etiquetas que se añaden a la sesión al crearla, por nombre. Hasta 10, cada una de hasta 50 caracteres. Los nombres no distinguen entre mayúsculas y minúsculas y se almacenan en mayúsculas. Un nombre que todavía no existe en la aplicación se crea como una etiqueta nueva. Las etiquetas aparecen en la sesión en la consola, donde puedes filtrar por ellas.
1050["VIP", "ONBOARDING Q4"]
Código de idioma (ISO 639-1) para la interfaz del proceso de verificación. Controla el idioma que ve el usuario final durante la verificación. Si no se proporciona, se detecta y se usa automáticamente el idioma del navegador. Consulta todos los idiomas admitidos aquí.
en, ar, bg, bn, bs, ca, cnr, cs, da, de, el, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, kk, ko, ky, lt, lv, mk, mn, ms, nl, no, pl, pt-BR, pt, ro, ru, sk, sl, so, sq, sr, sv, th, tr, uk, uz, vi, zh-CN, zh-TW, zh "en"
Información de contacto del usuario que puede usarse para notificaciones, para rellenar previamente los formularios de verificación y para la verificación de teléfono. Incluye la dirección de correo electrónico, el idioma preferido para las comunicaciones y el número de teléfono.
Show child attributes
Show child attributes
{
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
}
Datos esperados del usuario que se usan para la validación cruzada con los datos extraídos del documento de identidad del usuario, de la Prueba de domicilio y de otros pasos de verificación. Las discrepancias se muestran como advertencias en la decisión; algunos campos (p. ej., id_country, expected_document_types) también modifican el flujo que ve el usuario. En los flujos de Verificación de empresas (KYB) solo se usan los campos de la empresa (company_name, registry_country, registration_number), que rellenan previamente la búsqueda en el registro de empresas para el usuario, y se ignoran todos los campos de la persona.
Show child attributes
Show child attributes
{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
Imagen de retrato del rostro del usuario final codificada en base64 (máx. 2MB; JPEG, PNG, WebP o TIFF). Se usa como imagen de referencia para compararla con la captura de prueba de vida cuando el flujo es un flujo de Biometric Authentication con Coincidencia facial habilitada, o cualquier flujo de grafo en el que la Coincidencia facial se ejecute antes de la Verificación de identidad (OCR). Es opcional cuando el usuario de vendor_data ya tiene una imagen facial almacenada: Didit la reutiliza automáticamente, resuelta en este orden de prioridad: rostro de prueba de vida aprobada, foto del chip del pasaporte electrónico, retrato del documento de identidad, rostro de perfil registrado manualmente (solo se reutilizan rostros de sesiones aprobadas o rostros que hayas registrado tú). Cuando se proporciona, portrait_image siempre tiene prioridad sobre el rostro almacenado. Si se omite y no existe ningún rostro almacenado (o no se envía vendor_data), la creación de la sesión falla con 400. Se ignora para otros tipos de flujo.
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
Slug de escenario exclusivo de sandbox. Solo se acepta cuando la clave de API pertenece a una aplicación en modo sandbox; se rechaza en aplicaciones de producción. Cuando se define, el flujo de creación aplica los valores mágicos incluidos en el escenario a los campos de entrada de la sesión (contact_details, expected_details), de modo que los proveedores simulados reproducen el resultado del escenario a través del pipeline real del flujo. Consulta el catálogo de escenarios en GET /v1/sandbox/scenarios/ o en Sandbox y datos de prueba. También puedes activar (o volver a activar) un escenario después de la creación mediante POST /v3/session/{sessionId}/sandbox/arm/, siempre que la sesión siga en Not Started. Para la consulta sin documento, usa lookup_partial_match, lookup_no_match o lookup_provider_error para probar el número de intentos configurado y el mecanismo de respaldo. Para las wallets de identidad, usa wallet_cancelled, wallet_timeout o wallet_provider_error; approve simula una wallet verificada. Todas las wallets del catálogo se pueden probar en sandbox, incluidos los esquemas que no están disponibles en aplicaciones de producción. Los intentos simulados no se cobran.
"decline_document_expired"
Datos de firma electrónica para esta sesión. documents son los documentos que se deben firmar, para un flujo cuyo paso de Firma electrónica toma los documentos de la sesión (signature_documents_source session o both): hasta 20 documentos y 50 MB en total. field_values rellena los campos cuyo prefill es api.<key>, tanto en los documentos del flujo como en los de la sesión. Si vuelves a crear una sesión para el mismo workflow_id y vendor_data, se devuelve la sesión pendiente; si esa llamada envía sign, sus documentos, campos y valores deben ser idénticos a los primeros, y cualquier diferencia devuelve 400 con {"sign": "signature_document_changed"}. Consulta Documentos de firma electrónica.
Show child attributes
Show child attributes
Lugar de residencia de la persona, cuando lo conoces: un código de subdivisión ISO 3166-2 (US-IL, ES-M) o un código o nombre de estado de EE. UU. (IL, Illinois). Un estado cuya ley exige consentimiento biométrico explícito (Illinois, Texas, Colorado) hace que el flujo de verificación lo solicite antes de capturar un rostro, con el disparador declared_state. Un valor no reconocido devuelve 400. Consulta Consentimiento biométrico.
16"US-IL"
Consentimiento biométrico explícito que ya recopilaste de la persona. Cumple el requisito, por lo que el flujo de verificación no vuelve a pedirlo, y la decisión lo registra como status: "given" con el disparador customer_collected. Una respuesta que la persona ya dio en el flujo nunca se reemplaza. Consulta Consentimiento biométrico.
Show child attributes
Show child attributes
Respuesta
Sesión creada (o devuelta, si ya existe una sesión sin terminar con el mismo vendor_data en la última versión publicada del flujo). La respuesta es la sesión serializada, incluida la url de la verificación alojada a la que debes redirigir al usuario.
Identificador único de la sesión de verificación. Usa este id al llamar a GET /v3/session/{sessionId}/decision/.
"11111111-2222-3333-4444-555555555555"
Número secuencial y fácil de leer asignado a la sesión dentro de tu aplicación. Útil para soporte y paneles.
43762
Token de 12 caracteres seguro para URL que autoriza al usuario final a acceder al flujo de verificación alojado en url. Es válido hasta que la sesión expira. Trátalo como un secreto: cualquiera que lo tenga puede abrir el flujo de verificación de esta sesión.
"3FaJ9wLqX2Mz"
URL de verificación alojada a la que debes redirigir al usuario final. La URL incluye el session_token y, si está configurado, usa tu dominio de marca blanca. Cuando la solicitud incluye language, la URL contiene un segmento de ruta con el idioma: https://verify.didit.me/{language}/session/{session_token} (p. ej., /es/session/...); sin language, el segmento se omite.
"https://verify.didit.me/session/3FaJ9wLqX2Mz"
Identificador que pasaste en la solicitud para vincular la sesión con un usuario o una empresa de tu propio sistema. Se devuelve tal cual. Null si no se proporciona.
"user-123"
Payload JSON arbitrario que guardaste con la sesión al crearla. Se devuelve literalmente: cualquier valor JSON que hayas enviado (objeto, cadena, número, array) se devuelve tal cual, aunque se recomienda un objeto JSON. No se muestra al usuario final. Siempre está presente en las respuestas; es null si no se proporcionó al crearla.
{
"user_type": "premium",
"account_id": "ABC123"
}
Estado actual de la sesión. Las sesiones recién creadas devuelven Not Started. Si ya existía una sesión no finalizada para el mismo vendor_data en la última versión publicada del flujo, el estado devuelto refleja esa sesión existente.
Not Started, In Progress, Approved, Declined, In Review, Expired, Abandoned, Kyc Expired, Resubmitted, Awaiting User "Not Started"
URL de redirección final a la que se envía al usuario después de completar el flujo. Didit añade ?verificationSessionId={session_id}&status={status} a esta URL. Si no se proporciona en la solicitud, se usa la URL de callback configurada en el flujo; es null cuando no se ha definido ninguna de las dos. Cuando la aplicación tiene dominios permitidos y esta URL es una URL web fuera de ellos (por ejemplo, un valor predeterminado del flujo definido antes de que cambiara la lista), el flujo alojado no redirige al usuario a ella.
"https://example.com/verification/callback"
Identificador estable del flujo en el que se ejecuta esta sesión. Siempre es el identificador de grupo estable del flujo: aunque en la solicitud hayas indicado el UUID de una versión concreta del flujo (búsqueda compatible con versiones anteriores), la respuesta incluye el workflow_id estable. Úsalo para relacionar la sesión con el flujo que configuraste en la consola.
"11111111-2222-3333-4444-555555555555"
Número de la versión publicada del flujo a la que quedó fijada la sesión al crearse. Didit resuelve workflow_id a la última versión publicada del flujo cuando se crea la sesión, y la sesión sigue ejecutando esa versión aunque el flujo se vuelva a publicar más adelante.
3
Las etiquetas de la sesión, por nombre.
["VIP", "ONBOARDING Q4"]