Primeiros passos
Integração / SDKs
Verificação de usuários
Verificação de empresas
Monitoramento de transações
Registro de alteraçõescurl -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 de criação de sessão: inicie a verificação KYC ou KYB
POST /v3/session/ da Didit inicia uma sessão de verificação. Endpoint unificado KYC + KYB, pagamento por uso, inferência sub-2s, $10 de crédito/mês.
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"
}Suporte a KYC e KYB
Um único endpoint cria sessões de Verificação de usuários e de Verificação de empresas. O tipo do fluxo de verificação (workflow) determina qual delas:- Envie o
workflow_idde um fluxo de KYC → é criada uma sessão de Verificação de usuários (KYC). Respostasession_kind: "user". - Envie o
workflow_idde um fluxo de KYB → é criada uma sessão de Verificação de empresas (KYB). Respostasession_kind: "business".
Exemplos
- Verificação de usuários (KYC)
- Verificação 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 assinatura eletrônica
Quando o fluxo tem uma etapa de Assinatura eletrônica que recebe documentos da sessão (signature_documents_source definido como session ou both), envie-os em sign.documents. Cada documento é o arquivo em base64, para que a Didit nunca precise buscá-lo em uma 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 | Regras |
|---|---|
title | Exibido para quem assina. De 1 a 255 caracteres. O padrão é file_name. |
file_name | Obrigatório. Termina em .pdf ou .docx. De 1 a 255 caracteres. |
content_base64 | Obrigatório. Um PDF pode ter até 20 MB e 100 páginas, sem senha, scripts ou arquivos anexados. Um arquivo Word pode ter até 20 MB e é convertido em PDF durante a requisição, em no máximo 25 segundos; o PDF resultante tem os mesmos limites. Até 5 arquivos Word por sessão. |
fields | Opcional. Até 200 campos para posicionar no documento, no formato de campo sem id. Cada campo precisa de um key e um type, e de uma posição (page, x, y, width e height) ou de um anchor. O padrão de role é o signatário da etapa, e os padrões de required e label vêm do tipo. A Didit define position de acordo com o local onde o campo fica. Páginas e posições se referem ao PDF ou, no caso de um arquivo Word, ao PDF convertido. |
fields, o signatário lê o documento e concorda com ele.
Posicionar campos por texto âncora
Em vez de uma posição, um campo pode ter umanchor: um trecho de texto no documento que marca onde o campo fica. Âncoras são adequadas para documentos que você gera para cada sessão, por exemplo a partir de um modelo do Word. Para documentos do fluxo, posicione os campos no console.
Propriedade de anchor | Regras |
|---|---|
text | De 1 a 64 caracteres, buscados no texto do documento. Para um arquivo Word, no PDF convertido. |
occurrence | first (padrão) posiciona um campo na primeira ocorrência. all posiciona um campo por ocorrência, e as chaves depois da primeira recebem _2, _3 e assim por diante. |
offset_x, offset_y | Frações da página. O canto superior esquerdo do campo é o canto superior esquerdo do texto âncora somado a esses deslocamentos. |
width, height | O tamanho do campo, em frações da página. |
400 com field_anchor_not_found e a chave do campo. A Didit não remove o texto âncora do PDF, então escreva-o na mesma cor do fundo da página.
Valores dos campos
sign.field_values define o valor de todo campo cujo prefill é api.<key>, tanto nos documentos do fluxo quanto nos documentos da sessão. É um objeto indexado por esses nomes <key>. Os valores são strings de 1 a 500 caracteres para campos text e data, e booleanos para um checkbox.
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
Erro (400) | Quando |
|---|---|
field_value_unknown | Uma chave que nenhum campo usa. |
field_value_missing | Um campo obrigatório cujo api.<key> não tem valor. |
field_value_invalid | Um valor que não passa na validação do seu campo. |
Erros e chamadas repetidas
Uma sessão aceita até 20 documentos e 50 MB no total. A chamada retorna400 com um erro em sign quando:
- O fluxo não tem etapa de Assinatura eletrônica.
- Você enviou
sign.documentse a etapa só aceita documentos do fluxo. - A etapa aceita apenas documentos da sessão e você não enviou nenhum, ou ela não tem documentos do fluxo e você não enviou nenhum.
- Um documento é grande demais, não é base64 válido ou não é um arquivo compatível.
- Um arquivo Word é recusado com
signature_document_not_supported, ou não pode ser convertido e retornasignature_document_conversion_failed, cada um com oreasonlistado em Arquivos compatíveis. - Um campo é inválido, sua âncora não é encontrada (
field_anchor_not_found) ou um valor de campo é recusado.
workflow_id e vendor_data retorna a sessão pendente. Se essa chamada enviar sign, seus documentos, campos e valores de campos devem ser idênticos aos da primeira (mesma ordem, títulos, nomes de arquivo, conteúdo, campos e valores). Qualquer diferença retorna 400 com {"sign": "signature_document_changed"}: use outro vendor_data ou aguarde até que a sessão pendente seja concluída.
Testes com cenários de sandbox
Em uma aplicação em modo sandbox, enviesandbox_scenario para pré-carregar um resultado determinístico (aprovação, uma recusa específica ou um cenário em revisão) sem acionar provedores reais nem consumir seu saldo:
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
sandbox_scenario é rejeitado com 400 em aplicações de produção. Se você ainda não souber o resultado no momento da criação, configure-o (ou reconfigure-o) depois via POST /v3/session/{session_id}/sandbox/arm/, desde que a sessão ainda esteja em Not Started: o seletor de cenários pré-fluxo do fluxo hospedado usa esse mesmo endpoint. Consulte Sandbox e dados de teste para ver o catálogo completo de cenários, o registro de valores mágicos e o formato de requisição e resposta do endpoint de configuração.
vendor_data vincula a sessão a uma entidade
- Em fluxos de KYC: vincula a uma entidade de usuário. Se o usuário não existir, ele é criado automaticamente.
- Em fluxos de KYB: vincula a uma entidade de empresa. Se a empresa não existir, ela será criada automaticamente.
Consentimento biométrico em Illinois, Texas e Colorado
O fluxo hospedado e o SDK nativo 4.10.0 ou posterior podem exibir uma etapa explícita de consentimento biométrico antes da primeira captura facial, de acordo com o modo de consentimento da aplicação e com o local onde a pessoa está. Dois campos opcionais alimentam essa decisão:user_state: onde a pessoa mora, quando você souber (US-IL,ILouIllinois). No modo Auto, um estado coberto faz o fluxo solicitar o consentimento.biometric_consent: um objeto comgiven_atetext_version, para o consentimento que você já coletou. O fluxo não solicita novamente.
Importante: a divulgação de informações e o consentimento continuam acontecendo no seu produto
Create Session gera uma URL de verificação e um token de sessão. Isso não comprova, por si só, que você apresentou ao usuário as informações obrigatórias nem que obteve o consentimento exigido para o seu caso de uso específico.
Se você inicia uma sessão da Didit a partir da sua própria aplicação, site, wrapper de SDK ou fluxo de marca própria, você deve tratar a camada jurídica na sua própria UX antes que o usuário comece a captura.
Checklist recomendado antes da verificação
- Informe ao usuário que a sua empresa está solicitando a verificação e que a Didit é a provedora / operadora de verificação que viabiliza o fluxo.
- Inclua um link para o seu aviso de privacidade e para quaisquer termos jurídicos aplicáveis ao controlador que se apliquem à jornada.
- Inclua um link para o Aviso de Privacidade de Verificação e para os Termos do Usuário Final para Verificação de Identidade da Didit.
- Se o seu fluxo incluir captura de documento, captura de selfie, prova de vida ou biometria, colete um consentimento explícito e afirmativo sempre que a legislação aplicável ou o seu posicionamento jurídico exigir.
- Se você usa uma UI personalizada, um domínio personalizado ou uma jornada somente via API, exiba essas informações no seu próprio produto antes de encaminhar o usuário para o fluxo da Didit.
- Mantenha o seu próprio registro do texto do aviso / consentimento, do registro de data e hora e dos metadados relacionados, caso a sua equipe jurídica exija uma trilha de auditoria.
Autorizações
Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.
Corpo
Identificador estável do fluxo de verificação (workflow) que define quais etapas de verificação a sessão executará. Os fluxos são criados e gerenciados na página Workflows do Console. O workflow_id também determina implicitamente se a sessão é KYC ou KYB.
"11111111-2222-3333-4444-555555555555"
Um identificador exclusivo do usuário que está sendo verificado, como um UUID, e-mail ou ID interno de usuário. Este campo é usado para: (1) Agrupamento de usuários — sessões com o mesmo vendor_data são vinculadas ao mesmo perfil de usuário na aba Usuários. (2) Detecção de duplicatas entre sessões — ao verificar rostos, documentos, números de telefone, e-mails, endereços IP ou impressões digitais de dispositivo duplicados, sessões com o mesmo vendor_data são tratadas como o mesmo usuário e excluídas das correspondências. Sem vendor_data, cada sessão é tratada como um usuário único e todas as possíveis duplicatas são exibidas. Recomendamos fortemente sempre fornecer um vendor_data para reduzir o ruído na detecção de duplicatas.
"user-123"
Domínio opcional de detecção de duplicados dentro da sua organização. As verificações de rosto duplicado comparam esta sessão apenas com outras sessões que tenham o mesmo segmento, de modo que bases de contas separadas (contas pessoais e empresariais, ou uma por subcliente B2B) não sinalizem uma pessoa que legitimamente tenha uma conta em cada uma. Omita-o para usar o domínio padrão único, que é o que todas as sessões usam hoje. As correspondências com a lista de bloqueio e a lista de permissões ignoram este campo.
64"business-accounts"
URL para a qual o usuário é redirecionado após a conclusão da verificação. A Didit acrescenta automaticamente verificationSessionId e status (Approved, Declined, In Review) como parâmetros de consulta. Esquemas de URL personalizados (por exemplo, myapp://) são compatíveis com callbacks em dispositivos móveis. Se omitida, é usado o callback_url padrão do fluxo de verificação. Quando a aplicação tem domínios permitidos (allowed_domains em PATCH /v3/webhook/), um callback http ou https deve estar em uma dessas origens (mesmo esquema, host e porta); caso contrário, a requisição falha com 400 em callback: callback must be on one of the application's allowed domains: https://app.example.com. Esquemas de URL personalizados são sempre aceitos.
"https://example.com/verification/callback"
Determina qual dispositivo deve tratar o redirecionamento para a URL de retorno informada. Use initiator para redirecionar apenas o dispositivo que iniciou o fluxo, completer para o dispositivo que o conclui ou both para permitir que qualquer um dos dispositivos acione o retorno. Se você notar que o retorno não é acionado de forma confiável, recomendamos definir este valor como both.
initiator, completer, both "both"
JSON arbitrário armazenado com a sessão e devolvido na resposta e nos webhooks. Qualquer valor JSON é aceito (objeto, string, número, array), mas recomenda-se um objeto JSON de pares chave/valor. Não é exibido ao usuário final. Use-o para passar seus próprios IDs de correlação, variantes de teste A/B ou contexto de negócio.
{
"user_type": "premium",
"account_id": "ABC123"
}
Tags adicionadas à sessão quando ela é criada, pelo nome. Até 10, cada uma com até 50 caracteres. Os nomes não diferenciam maiúsculas de minúsculas e são armazenados em maiúsculas. Um nome que ainda não existe na aplicação é criado como uma nova tag. As tags aparecem na sessão no console, onde você pode filtrar por elas.
1050["VIP", "ONBOARDING Q4"]
Código de idioma (ISO 639-1) para a interface do processo de verificação. Controla o idioma exibido ao usuário final durante a verificação. Se não for informado, o idioma do navegador será detectado e usado automaticamente. Confira todos os idiomas suportados aqui.
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"
Informações de contato do usuário que podem ser usadas para notificações, preenchimento prévio de formulários de verificação e verificação de telefone. Isso inclui endereço de e-mail, idioma preferido para comunicações e número de telefone.
Show child attributes
Show child attributes
{
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
}
Dados esperados do usuário, usados para validação cruzada com os dados extraídos do documento de identidade do usuário, do Comprovante de endereço e de outras etapas de verificação. Divergências aparecem como avisos na decisão; alguns campos (por exemplo, id_country, expected_document_types) também alteram o fluxo exibido ao usuário. Em fluxos de Verificação de empresas (KYB), somente os campos da empresa (company_name, registry_country, registration_number) são usados, pois pré-preenchem para o usuário a busca no registro de empresas, e todos os campos referentes à pessoa são ignorados.
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"]
}
Imagem de retrato do rosto do usuário final codificada em Base64 (máx. 2MB; JPEG, PNG, WebP ou TIFF). Usada como imagem de referência para comparação com a captura de prova de vida quando o fluxo é um fluxo Biometric Authentication com a Correspondência facial habilitada, ou qualquer fluxo baseado em grafo em que a Correspondência facial é executada antes da Verificação de identidade (OCR). Opcional quando o usuário de vendor_data já tem uma imagem facial armazenada: a Didit a reutiliza automaticamente, escolhida nesta ordem de prioridade: rosto da prova de vida aprovada, foto do chip do passaporte eletrônico, retrato do documento de identidade, rosto de perfil cadastrado manualmente (somente rostos de sessões aprovadas ou rostos que você mesmo cadastrou são reutilizados). Quando fornecida, portrait_image sempre tem precedência sobre o rosto armazenado. Se for omitida e não houver rosto armazenado (ou se vendor_data não for enviado), a criação da sessão falha com 400. Ignorada para outros tipos de fluxo.
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
Slug de cenário exclusivo do sandbox. É aceito somente quando a chave de API pertence a uma aplicação em modo sandbox e é rejeitado em aplicações em produção. Quando definido, o fluxo de criação aplica os valores mágicos incluídos no cenário aos campos de entrada da sessão (contact_details, expected_details), para que os provedores simulados reproduzam o resultado do cenário por meio do pipeline real do fluxo. Consulte o catálogo de cenários em GET /v1/sandbox/scenarios/ ou em Sandbox e dados de teste. Você também pode armar (ou rearmar) um cenário após a criação via POST /v3/session/{sessionId}/sandbox/arm/, desde que a sessão ainda esteja Not Started. Para consultas sem documento, use lookup_partial_match, lookup_no_match ou lookup_provider_error para testar o limite de tentativas configurado e o fallback. Para carteiras de identidade, use wallet_cancelled, wallet_timeout ou wallet_provider_error; approve simula uma carteira verificada. Todas as carteiras do catálogo podem ser testadas no sandbox, inclusive esquemas indisponíveis em aplicações em produção. Tentativas simuladas não são cobradas.
"decline_document_expired"
Entrada de assinatura eletrônica para esta sessão. documents são os documentos a assinar, para um fluxo de verificação (workflow) cuja etapa de Assinatura eletrônica recebe documentos da sessão (signature_documents_source session ou both): até 20 documentos e 50 MB no total. field_values preenche os campos cujo prefill é api.<key>, tanto nos documentos do fluxo quanto nos da sessão. Criar novamente uma sessão para o mesmo workflow_id e vendor_data retorna a sessão pendente; se essa chamada enviar sign, seus documentos, campos e valores devem ser idênticos aos da primeira, e qualquer diferença retorna 400 com {"sign": "signature_document_changed"}. Consulte Documentos de assinatura eletrônica.
Show child attributes
Show child attributes
Onde a pessoa mora, quando você souber: um código de subdivisão ISO 3166-2 (US-IL, ES-M) ou um código ou nome de estado dos EUA (IL, Illinois). Um estado cuja lei exige consentimento biométrico explícito (Illinois, Texas, Colorado) faz o fluxo de verificação solicitá-lo antes de capturar um rosto, com o gatilho declared_state. Um valor não reconhecido retorna 400. Consulte Consentimento biométrico.
16"US-IL"
Consentimento biométrico explícito que você já coletou da pessoa. Ele atende ao requisito, de modo que o fluxo de verificação não o solicita novamente, e a decisão o registra como status: "given" com o gatilho customer_collected. Uma resposta que a pessoa já deu no fluxo nunca é substituída. Consulte Consentimento biométrico.
Show child attributes
Show child attributes
Resposta
Sessão criada (ou retornada, se já existir uma sessão não concluída com o mesmo vendor_data na versão publicada mais recente do fluxo). A resposta é a sessão serializada, incluindo a url da verificação hospedada para a qual o usuário deve ser redirecionado.
Identificador único da sessão de verificação. Use este id ao chamar GET /v3/session/{sessionId}/decision/.
"11111111-2222-3333-4444-555555555555"
Número sequencial e fácil de ler atribuído à sessão dentro da sua aplicação. Útil para suporte e painéis.
43762
Token seguro para URL de 12 caracteres que autoriza o usuário final a acessar o fluxo de verificação hospedado em url. Válido até a sessão expirar. Trate-o como um segredo: qualquer pessoa que o tenha pode abrir o fluxo de verificação desta sessão.
"3FaJ9wLqX2Mz"
URL de verificação hospedada para a qual o usuário final deve ser redirecionado. A URL incorpora o session_token e, se configurado, usa seu domínio de marca própria. Quando a requisição inclui language, a URL contém um segmento de caminho com o idioma: https://verify.didit.me/{language}/session/{session_token} (por exemplo, /es/session/...); sem language, o segmento é omitido.
"https://verify.didit.me/session/3FaJ9wLqX2Mz"
Identificador que você passou na requisição para vincular a sessão a um usuário ou empresa no seu próprio sistema. Retornado exatamente como enviado. Null quando não informado.
"user-123"
Payload JSON arbitrário que você armazenou com a sessão no momento da criação. Devolvido literalmente — qualquer valor JSON que você enviou (objeto, string, número, array) é retornado como está, embora um objeto JSON seja recomendado. Não é exibido ao usuário final. Sempre presente nas respostas; null quando não fornecido no momento da criação.
{
"user_type": "premium",
"account_id": "ABC123"
}
Status atual da sessão. Sessões recém-criadas retornam Not Started. Se já existia uma sessão não finalizada para o mesmo vendor_data na versão publicada mais recente do fluxo, o status retornado reflete essa sessão existente.
Not Started, In Progress, Approved, Declined, In Review, Expired, Abandoned, Kyc Expired, Resubmitted, Awaiting User "Not Started"
URL de redirecionamento final para a qual o usuário é enviado após concluir o fluxo. A Didit acrescenta ?verificationSessionId={session_id}&status={status} a essa URL. Quando não é informada na requisição, usa a URL de retorno configurada no fluxo de verificação (workflow); null quando nenhuma das duas está definida. Quando a aplicação tem domínios permitidos e essa URL é uma URL web fora deles (por exemplo, um padrão do fluxo definido antes de a lista mudar), o fluxo hospedado não redireciona o usuário para ela.
"https://example.com/verification/callback"
Identificador estável do fluxo em que esta sessão é executada. É sempre o identificador estável de grupo do fluxo: mesmo que você tenha referenciado o UUID de uma versão específica do fluxo na requisição (busca retrocompatível), a resposta traz o workflow_id estável. Use-o para correlacionar a sessão com o fluxo que você configurou no Console.
"11111111-2222-3333-4444-555555555555"
Número da versão publicada do fluxo à qual a sessão foi fixada na criação. A Didit resolve o workflow_id para a versão publicada mais recente do fluxo quando a sessão é criada, e a sessão continua executando essa versão mesmo que o fluxo seja republicado depois.
3
As tags da sessão, por nome.
["VIP", "ONBOARDING Q4"]