API de criação de sessão: iniciar verificação KYC ou KYB

cURL

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_h

using 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"
}

POST

session

cURL

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_h

using 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 utilizadores e de Verificação de empresas. O tipo do fluxo determina qual delas é criada:

Passe o workflow_id de um fluxo de KYC → é criada uma sessão de Verificação de utilizadores (KYC). Resposta session_kind: "user".
Passe o workflow_id de um fluxo de KYB → é criada uma sessão de Verificação de empresas (KYB). Resposta session_kind: "business".

Configure os fluxos na consola em Workflows → Create workflow. Um fluxo é de KYC ou de KYB no momento da criação; depois não é possível mudar de tipo.

Exemplos

Verificação de utilizadores (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"
  }'

Resposta (201 Created):

{
  "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"
  }'

Resposta (201 Created):

{
  "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 um passo de Assinatura eletrónica que recebe os documentos da sessão (signature_documents_source definido como session ou both), envie-os em sign.documents. Cada documento é o ficheiro em base64, para que a Didit nunca tenha de o obter a partir de um 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`	Apresentado ao signatário. 1 a 255 caracteres. Predefinido como `file_name`.
`file_name`	Obrigatório. Termina em `.pdf` ou `.docx`. 1 a 255 caracteres.
`content_base64`	Obrigatório. Um PDF pode ter até 20 MB e 100 páginas, sem palavra-passe, scripts nem ficheiros anexados. Um ficheiro Word pode ter até 20 MB e é convertido em PDF durante o pedido, em no máximo 25 segundos; o PDF tem depois os mesmos limites. Até 5 ficheiros Word por sessão.
`fields`	Opcional. Até 200 campos a colocar no documento, na estrutura de campo sem `id`. Cada campo precisa de um `key` e de um `type`, e de uma posição (`page`, `x`, `y`, `width` e `height`) ou de uma `anchor`. `role` predefine-se para o signatário do passo, e `required` e `label` predefinem-se a partir do tipo. A Didit define `position` a partir do local onde o campo se encontra. As páginas e as posições referem-se ao PDF, ou ao PDF convertido no caso de um ficheiro Word.

Sem fields, o signatário lê o documento e concorda com ele.

Colocar campos por texto de âncora

Em vez de uma posição, um campo pode ter uma anchor: um trecho de texto no documento que marca onde o campo fica. As âncoras são indicadas para documentos que gera para cada sessão, por exemplo a partir de um modelo Word. Nos documentos do fluxo, coloque os campos na consola.

Propriedade de `anchor`	Regras
`text`	1 a 64 caracteres, pesquisados no texto do documento. No caso de um ficheiro Word, no PDF convertido.
`occurrence`	`first` (predefinido) coloca um campo na primeira correspondência. `all` coloca um campo por correspondência, e as chaves a seguir à 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 da âncora somado a estes deslocamentos.
`width`, `height`	O tamanho do campo, como frações da página.

Quando o texto não existe no documento, a chamada devolve 400 com field_anchor_not_found e a chave do campo. A Didit não remove o texto da âncora do PDF, por isso escreva-o na mesma cor do fundo da página.

Valores dos campos

sign.field_values define o valor de cada campo cujo prefill é api.<key>, tanto nos documentos do fluxo como nos documentos da sessão. É um objeto indexado por esses nomes <key>. Os valores são cadeias de 1 a 500 caracteres para os 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 ocorre
`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 cumpre a validação do seu campo.

Erros e chamadas repetidas

Uma sessão aceita até 20 documentos e 50 MB no total. A chamada devolve 400 com um erro de sign quando:

O fluxo não tem passo de Assinatura eletrónica.
Enviou sign.documents e o passo só aceita documentos do fluxo.
O passo aceita apenas documentos da sessão e não enviou nenhum, ou não tem documentos do fluxo e não enviou nenhum.
Um documento é demasiado grande, não é base64 válido ou não é um ficheiro suportado.
Um ficheiro Word é recusado com signature_document_not_supported, ou não pode ser convertido e devolve signature_document_conversion_failed, cada um com o reason indicado em Ficheiros suportados.
Um campo é inválido, a sua âncora não é encontrada (field_anchor_not_found), ou um valor de campo é recusado.

Voltar a chamar a operação de criação para o mesmo workflow_id e vendor_data devolve a sessão pendente. Se essa chamada enviar sign, os seus documentos, campos e valores de campos têm de ser idênticos aos da primeira (mesma ordem, títulos, nomes de ficheiros, conteúdo, campos e valores). Qualquer diferença devolve 400 com {"sign": "signature_document_changed"}: use um vendor_data diferente ou aguarde até que a sessão pendente termine.

Testes com cenários de sandbox

Numa aplicação em modo sandbox, envie sandbox_scenario para pré-carregar um resultado determinístico (aprovação, uma recusa específica ou um cenário Em análise), sem contactar fornecedores reais nem tocar no 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 ainda não conhecer o resultado no momento da criação, configure (ou volte a configurar) o cenário mais tarde através de POST /v3/session/{session_id}/sandbox/arm/, desde que a sessão ainda esteja no estado Not Started: o seletor de cenários pré-fluxo do fluxo alojado usa este mesmo endpoint. Consulte Sandbox e dados de teste para o catálogo completo de cenários, o registo de valores mágicos e o formato do pedido e da resposta do endpoint de configuração.

O `vendor_data` associa a sessão a uma entidade

Para fluxos de KYC: associa-se a uma entidade de utilizador. Se o utilizador não existir, é criado automaticamente.
Para fluxos de KYB: associa-se a uma entidade empresarial. Criada automaticamente se for nova.

Saiba mais em associação de dados do fornecedor.

Consentimento biométrico em Illinois, no Texas e no Colorado

O fluxo alojado e o SDK nativo 4.10.0 ou posterior podem mostrar um passo de consentimento biométrico explícito antes da primeira captura facial, consoante o modo de consentimento da aplicação e o local onde a pessoa se encontra. Dois campos opcionais alimentam essa decisão:

user_state: onde a pessoa reside, quando o souber (US-IL, IL ou Illinois). No modo Automático, um estado abrangido faz com que o fluxo peça o consentimento.
biometric_consent: um objeto com given_at e text_version, para consentimento que já recolheu. O fluxo não volta a pedir.

Os SDK nativos anteriores à versão 4.10.0 não conseguem mostrar este passo: as respetivas sessões funcionam como antes e a decisão indica que o consentimento não foi recolhido. Consulte Consentimento biométrico.

Importante: a divulgação e o consentimento continuam a ser feitos no seu produto

Create Session gera um URL de verificação e um token de sessão. Por si só, não prova que mostrou ao utilizador as informações fornecidas ao utilizador ou que obteve o consentimento exigido pelo seu caso de utilização específico. Se iniciar uma sessão Didit a partir da sua própria aplicação, website, wrapper de SDK ou fluxo com marca branca, deve tratar da componente jurídica na sua própria experiência de utilização antes de o utilizador iniciar a captura.

Lista de verificação recomendada antes da verificação

Informe o utilizador de que a sua empresa está a pedir a verificação e de que a Didit é o fornecedor de verificação / subcontratante que suporta o fluxo.
Ligue ao seu aviso de privacidade e a quaisquer termos jurídicos do responsável pelo tratamento que se apliquem ao percurso.
Ligue ao Aviso de Privacidade de Verificação da Didit e aos Termos do Utilizador Final para Verificação de Identidade.
Se o seu fluxo incluir captura de documento, captura de selfie, prova de vida ou dados biométricos, recolha consentimento explícito e afirmativo sempre que a lei aplicável ou a sua posição jurídica o exija.
Se utilizar uma interface personalizada, um domínio próprio ou um percurso apenas por API, apresente estas informações no seu próprio produto antes de enviar o utilizador para o fluxo da Didit.
Guarde o seu próprio registo do texto do aviso ou do consentimento, da data e hora e dos metadados relacionados, se a sua equipa jurídica exigir um rasto de auditoria.

As exigências legais variam consoante a jurisdição. A personalização com marca branca não elimina o papel da Didit no fluxo de verificação. Reveja a sua implementação com um advogado antes do lançamento se operar em jurisdições com regras específicas para dados biométricos.

Autorizações

x-api-key

string

header

obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json

workflow_id

string<uuid>

obrigatório

Identificador estável do fluxo que define quais os passos de verificação que a sessão irá executar. Os fluxos são criados e geridos na página Fluxos da Consola. O workflow_id também seleciona implicitamente se a sessão é KYC ou KYB.

Exemplo:

"11111111-2222-3333-4444-555555555555"

vendor_data

string

Um identificador exclusivo para o utilizador a ser verificado, como um UUID, e-mail ou ID de utilizador interno. Este campo é utilizado para: (1) Agrupamento de utilizadores — as sessões com o mesmo vendor_data são associadas ao mesmo perfil de utilizador no separador Utilizadores. (2) Deteção de duplicados entre sessões — ao verificar rostos, documentos, números de telefone, e-mails, endereços IP ou impressões digitais de dispositivos duplicados, as sessões com o mesmo vendor_data são tratadas como o mesmo utilizador e excluídas das correspondências. Sem vendor_data, cada sessão é tratada como um utilizador único e todos os potenciais duplicados são apresentados. Recomendamos vivamente fornecer sempre um vendor_data para reduzir o ruído na deteção de duplicados.

Exemplo:

"user-123"

multi_account_segment

string

Domínio de deteção de duplicados opcional dentro da sua organização. As verificações de rostos duplicados comparam esta sessão apenas com outras sessões que tenham o mesmo segmento, para que bases de contas separadas (contas pessoais e empresariais, ou uma por subcliente B2B) não sinalizem uma pessoa que detenha legitimamente uma conta em cada uma. Omita este campo para utilizar o domínio predefinido único, que é o que todas as sessões utilizam atualmente. A correspondência com a lista de bloqueio e a lista de permissões ignora este campo.

Maximum string length: 64

Exemplo:

"business-accounts"

callback

string

URL para redirecionar o utilizador após a conclusão da verificação. A Didit anexa automaticamente verificationSessionId e status (Approved, Declined, In Review) como parâmetros de consulta. Esquemas de URL personalizados (por exemplo, myapp://) são suportados para callbacks móveis. Se omitido, é utilizado o callback_url predefinido do fluxo. Quando a aplicação tem domínios permitidos (allowed_domains em PATCH /v3/webhook/), um callback http ou https deve pertencer a uma dessas origens (mesmo esquema, anfitrião e porta), caso contrário o pedido 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 aceites.

Exemplo:

"https://example.com/verification/callback"

callback_method

enum<string>

padrão:initiator

Determina que dispositivo deve processar o redirecionamento para o URL de retorno fornecido. Utilize 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 callback. Se alguma vez notar que o callback não está a ser acionado de forma fiável, recomendamos definir este valor como both.

Opções disponíveis:

initiator,

completer,

both

Exemplo:

"both"

metadata

any

JSON arbitrário guardado com a sessão e devolvido na resposta e nos webhooks. Qualquer valor JSON é aceite (objeto, string, número, array), mas recomenda-se um objeto JSON de pares chave/valor. Não visível para o utilizador final. Utilize-o para passar os seus próprios IDs de correlação, variantes A/B ou contexto de negócio.

Exemplo:

{
  "user_type": "premium",
  "account_id": "ABC123"
}

Resposta

Sessão criada (ou devolvida, se já existir uma sessão não finalizada com o mesmo vendor_data na versão publicada mais recente do fluxo). A resposta é a sessão serializada, incluindo o url de verificação alojada para o qual redirecionar o utilizador.

session_id

string<uuid>

obrigatório

Identificador único da sessão de verificação. Utilize este id ao chamar GET /v3/session/{sessionId}/decision/.

Exemplo:

"11111111-2222-3333-4444-555555555555"

session_number

integer

obrigatório

Número sequencial e de fácil leitura atribuído à sessão dentro da sua aplicação. Útil para suporte e painéis.

Exemplo:

43762

session_token

string

obrigatório

Token de 12 carateres seguro para URL que autoriza o utilizador final a aceder ao fluxo de verificação alojado em url. Válido até a sessão expirar. Trate-o como um segredo — qualquer pessoa que o possua pode abrir o fluxo de verificação para esta sessão.

Exemplo:

"3FaJ9wLqX2Mz"

url

string<uri>

obrigatório

URL de verificação alojado para o qual redirecionar o utilizador final. O URL incorpora o session_token e, se configurado, utiliza o seu domínio de marca branca. Quando o pedido inclui language, o URL contém um segmento de caminho de idioma — https://verify.didit.me/{language}/session/{session_token} (ex.: /es/session/...); sem language, o segmento é omitido.

Exemplo:

"https://verify.didit.me/session/3FaJ9wLqX2Mz"

vendor_data

string | null

obrigatório

Identificador transmitido no pedido para associar a sessão a um utilizador ou empresa no seu próprio sistema. Devolvido tal como foi enviado. Nulo quando não fornecido.

Exemplo:

"user-123"

metadata

any

obrigatório

Payload JSON arbitrário que guardou com a sessão no momento da criação. Devolvido tal como enviado — qualquer valor JSON que enviou (objeto, string, número, array) é devolvido inalterado, embora se recomende um objeto JSON. Não visível para o utilizador final. Sempre presente nas respostas; null quando não fornecido no momento da criação.

Exemplo:

{
  "user_type": "premium",
  "account_id": "ABC123"
}

status

enum<string>

obrigatório

Estado atual da sessão. Sessões recém-criadas devolvem Not Started. Se já existia uma sessão não terminada para os mesmos vendor_data na versão mais recente publicada do fluxo, o estado devolvido reflete essa sessão existente.

Opções disponíveis:

Not Started,

In Progress,

Approved,

Declined,

In Review,

Expired,

Abandoned,

Kyc Expired,

Resubmitted,

Awaiting User

Exemplo:

"Not Started"

callback

string<uri> | null

obrigatório

URL de redirecionamento final para onde o utilizador é enviado após concluir o fluxo. O Didit anexa ?verificationSessionId={session_id}&status={status} a este URL. Recai para o URL de retorno configurado no fluxo quando não for fornecido no pedido; null quando nenhum estiver definido. Quando a aplicação tem domínios permitidos e este URL for um URL web fora deles (por exemplo, uma predefinição do fluxo definida antes da alteração da lista), o fluxo alojado não redireciona o utilizador para ele.

Exemplo:

"https://example.com/verification/callback"

workflow_id

string<uuid>

obrigatório

Identificador estável do fluxo em que esta sessão é executada. É sempre o identificador de grupo estável do fluxo — mesmo que tenha referenciado o UUID de uma versão específica do fluxo no pedido (pesquisa compatível com versões anteriores), a resposta contém o workflow_id estável. Utilize-o para correlacionar a sessão com o fluxo configurado na Consola.

Exemplo:

"11111111-2222-3333-4444-555555555555"

workflow_version

integer

obrigatório

Número da versão publicada do fluxo à qual a sessão ficou associada no momento da criação. O Didit resolve o workflow_id para a versão publicada mais recente do fluxo quando a sessão é criada, e a sessão continua a executar essa versão mesmo que o fluxo seja republicado mais tarde.

Exemplo:

3

​Suporte a KYC e KYB

​Exemplos

​Documentos de assinatura eletrónica

​Colocar campos por texto de âncora

​Valores dos campos

​Erros e chamadas repetidas

​Testes com cenários de sandbox

​O vendor_data associa a sessão a uma entidade

​Consentimento biométrico em Illinois, no Texas e no Colorado

​Importante: a divulgação e o consentimento continuam a ser feitos no seu produto

​Lista de verificação recomendada antes da verificação

Autorizações

Corpo

Resposta

Suporte a KYC e KYB

Exemplos

Documentos de assinatura eletrónica

Colocar campos por texto de âncora

Valores dos campos

Erros e chamadas repetidas

Testes com cenários de sandbox

O `vendor_data` associa a sessão a uma entidade

Consentimento biométrico em Illinois, no Texas e no Colorado

Importante: a divulgação e o consentimento continuam a ser feitos no seu produto

Lista de verificação recomendada antes da verificação