API de creació de sessions: iniciar verificació KYC o 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"
}

Compatibilitat amb KYC i KYB

Un únic endpoint crea sessions de Verificació d’usuaris i de Verificació d’empreses. El tipus del flux de treball determina quin tipus de sessió es crea:

Si passes un workflow_id d’un flux de treball KYC, es crea una sessió de Verificació d’usuaris (KYC). Resposta session_kind: "user".
Si passes un workflow_id d’un flux de treball KYB, es crea una sessió de Verificació d’empreses (KYB). Resposta session_kind: "business".

Configura els fluxos de treball a la consola, a Workflows → Create workflow. Un flux de treball és KYC o KYB en el moment de crear-lo; després no es pot canviar el tipus.

Exemples

Verificació d'usuaris (KYC)
Verificació d'empreses (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"
}

Documents de signatura electrònica

Quan el flux de treball té un pas de Signatura electrònica que pren els documents de la sessió (signature_documents_source amb el valor session o both), envia’ls a sign.documents. Cada document és el fitxer en base64, de manera que Didit no l’ha de descarregar mai des d’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" }
  }
}

Camp	Regles
`title`	Es mostra al signant. De 1 a 255 caràcters. Per defecte, és `file_name`.
`file_name`	Obligatori. Acaba en `.pdf` o `.docx`. De 1 a 255 caràcters.
`content_base64`	Obligatori. Un PDF pot tenir fins a 20 MB i 100 pàgines, sense contrasenya, scripts ni fitxers adjunts. Un fitxer Word pot tenir fins a 20 MB i es converteix a PDF mentre dura la sol·licitud, en 25 segons com a màxim; el PDF resultant té els mateixos límits. Fins a 5 fitxers Word per sessió.
`fields`	Opcional. Fins a 200 camps per col·locar al document, amb la forma de camp sense `id`. Cada camp necessita una `key` i un `type`, i una posició (`page`, `x`, `y`, `width` i `height`) o un `anchor`. `role` és per defecte el signant del pas, i `required` i `label` es prenen del tipus. Didit defineix `position` segons on es troba el camp. Les pàgines i les posicions fan referència al PDF, o al PDF convertit en cas d’un fitxer Word.

Sense fields, el signant llegeix el document i hi està d’acord.

Col·locar camps mitjançant text d’ancoratge

En lloc d’una posició, un camp pot portar un anchor: un fragment de text del document que marca on va el camp. Els ancoratges són útils per a documents que generes per a cada sessió, per exemple a partir d’una plantilla Word. Per als documents del flux de treball, col·loca els camps a la consola.

Propietat de `anchor`	Regles
`text`	De 1 a 64 caràcters, cercats al text del document. En un fitxer Word, al PDF convertit.
`occurrence`	`first` (per defecte) col·loca un camp a la primera coincidència. `all` col·loca un camp a cada coincidència, i les claus a partir de la primera reben `_2`, `_3` i així successivament.
`offset_x`, `offset_y`	Fraccions de la pàgina. La cantonada superior esquerra del camp és la cantonada superior esquerra del text d’ancoratge, amb aquests desplaçaments afegits.
`width`, `height`	La mida del camp, com a fraccions de la pàgina.

Si el text no és al document, la crida retorna 400 amb field_anchor_not_found i la clau del camp. Didit no elimina el text d’ancoratge del PDF, de manera que escriu-lo amb el mateix color que el fons de la pàgina.

Valors dels camps

sign.field_values defineix el valor de cada camp el prefill del qual és api.<key>, tant als documents del flux de treball com als de la sessió. És un objecte indexat pels noms <key>. Els valors són cadenes d’1 a 500 caràcters per als camps text i data, i booleans per a 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`)	Quan
`field_value_unknown`	Una clau que cap camp no utilitza.
`field_value_missing`	Un camp obligatori el `api.<key>` del qual no té valor.
`field_value_invalid`	Un valor que no supera la validació del seu camp.

Errors i crides repetides

Una sessió admet fins a 20 documents i 50 MB en total. La crida retorna 400 amb un error de sign quan:

El flux de treball no té cap pas de Signatura electrònica.
Has enviat sign.documents i el pas només accepta documents del flux de treball.
El pas només accepta documents de la sessió i no n’has enviat cap, o no té documents del flux de treball i tampoc n’has enviat cap.
Un document és massa gran, no és base64 vàlid o no és un fitxer admès.
Un fitxer Word és rebutjat amb signature_document_not_supported, o no es pot convertir i retorna signature_document_conversion_failed, cadascun amb el reason que apareix a Fitxers admesos.
Un camp no és vàlid, el seu ancoratge no es troba (field_anchor_not_found), o un valor de camp és rebutjat.

Tornar a crear per al mateix workflow_id i vendor_data retorna la sessió pendent. Si aquesta crida envia sign, els seus documents, camps i valors de camp han de ser idèntics als de la primera (mateix ordre, títols, noms de fitxer, contingut, camps i valors). Qualsevol diferència retorna 400 amb {"sign": "signature_document_changed"}: utilitza un vendor_data diferent o espera que acabi la sessió pendent.

Proves amb escenaris de sandbox

En una aplicació en mode sandbox, passa sandbox_scenario per precarregar un resultat determinista (aprovació, un rebuig concret o un escenari en revisió) sense tocar proveïdors reals ni el teu saldo:

{
  "workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
  "sandbox_scenario": "decline_document_expired"
}

sandbox_scenario és rebutjat amb 400 a les aplicacions en producció. Si encara no coneixes el resultat en el moment de crear la sessió, pots activar-lo (o tornar-lo a activar) més tard mitjançant POST /v3/session/{session_id}/sandbox/arm/, sempre que la sessió encara estigui Not Started: el selector d’escenaris previ al flux allotjat utilitza aquest mateix endpoint. Consulta Sandbox i dades de prova per al catàleg complet d’escenaris, el registre de valors màgics i la forma de la sol·licitud i la resposta de l’endpoint d’activació.

`vendor_data` vincula la sessió a una entitat

En els fluxos de treball KYC, vincula la sessió a una entitat d’usuari. Si l’usuari no existeix, es crea automàticament.
En els fluxos de treball KYB, vincula la sessió a una entitat d’empresa. Es crea automàticament si és nova.

Més informació a vinculació de dades del proveïdor.

Consentiment biomètric a Illinois, Texas i Colorado

El flux allotjat i el SDK natiu 4.10.0 o posterior poden mostrar un pas de consentiment biomètric explícit abans de la primera captura facial, segons el mode de consentiment de l’aplicació i on es troba la persona. Hi ha dos camps opcionals que alimenten aquesta decisió:

user_state: on viu la persona, quan ho saps (US-IL, IL o Illinois). En mode Auto, un estat inclòs en l’àmbit d’aplicació fa que el flux ho demani.
biometric_consent: un objecte amb given_at i text_version, per al consentiment que ja has recollit. El flux no el torna a demanar.

Els SDK natius per sota de 4.10.0 no poden mostrar aquest pas: les seves sessions funcionen com abans i la decisió indica que el consentiment no s’ha recollit. Consulta Consentiment biomètric.

Important: la comunicació de la informació i l’obtenció del consentiment encara tenen lloc al teu producte

Create Session genera una URL de verificació i un token de sessió. Per si mateix, no demostra que hagis mostrat a l’usuari la informació legal ni que hagis obtingut el consentiment que requereix el teu cas d’ús concret. Si inicies una sessió de Didit des de la teva pròpia aplicació, web, embolcall del SDK o flux de marca blanca, hauries de gestionar la capa legal a la teva pròpia UX abans que l’usuari comenci la captura.

Llista de comprovació recomanada abans de la verificació

Digues a l’usuari que la teva empresa sol·licita la verificació i que Didit és el proveïdor de verificació / encarregat del tractament que fa funcionar el flux.
Enllaça al teu avís de privacitat i a qualsevol terme legal del responsable del tractament que sigui aplicable al recorregut.
Enllaça a l’Avís de privacitat de la verificació de Didit i a les Condicions d’ús per a usuaris finals de la verificació d’identitat.
Si el teu flux inclou captura de document, captura de selfie, prova de vida o biometria, recull un consentiment explícit i afirmatiu sempre que la llei aplicable o la teva posició legal ho exigeixin.
Si utilitzes una UI personalitzada, un domini personalitzat o un recorregut només amb API, mostra aquests avisos al teu propi producte abans d’enviar l’usuari al flux de Didit.
Guarda el teu propi registre del text de l’avís o del consentiment, la marca de temps i les metadades relacionades si el teu equip legal exigeix un registre d’auditoria.

Els requisits legals varien segons la jurisdicció. La marca blanca no elimina el paper de Didit en el flux de verificació. Revisa la implementació amb un assessor legal abans de llançar-la si operes en jurisdiccions amb normes específiques sobre biometria.

Autoritzacions

x-api-key

string

header

requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

application/json

workflow_id

string<uuid>

requerit

Identificador estable del flux de treball que defineix quins passos de verificació executarà la sessió. Els fluxos de treball es creen i es gestionen a la pàgina Workflows de la Console. El workflow_id també selecciona implícitament si la sessió és de KYC o de KYB.

Exemple:

"11111111-2222-3333-4444-555555555555"

vendor_data

string

Un identificador únic per a l'usuari que s'està verificant, com ara un UUID, correu electrònic o ID d'usuari intern. Aquest camp s'utilitza per a: (1) Agrupament d'usuaris: les sessions amb el mateix vendor_data s'enllacen al mateix perfil d'usuari a la pestanya Usuaris. (2) Detecció de duplicats entre sessions: quan es cerquen cares, documents, números de telèfon, correus electrònics, adreces IP o empremtes digitals de dispositiu duplicades, les sessions amb el mateix vendor_data es tracten com el mateix usuari i s'exclouen de les coincidències. Sense vendor_data, cada sessió es tracta com un usuari únic i es mostren tots els possibles duplicats. Recomanem fermament proporcionar sempre un vendor_data per reduir el soroll en la detecció de duplicats.

Exemple:

"user-123"

multi_account_segment

string

Àmbit opcional de detecció de duplicats dins de la teva organització. Les comprovacions de cares duplicades comparen aquesta sessió només amb altres sessions que tinguin el mateix segment, de manera que bases de comptes separades (comptes personals i d'empresa, o un per cada subclient B2B) no marquin una persona que legítimament té un compte a cadascuna. Omet-lo per utilitzar l'únic àmbit per defecte, que és el que utilitzen totes les sessions actualment. Les coincidències de llista de bloqueig i de llista d'admesos ignoren aquest camp.

Maximum string length: 64

Exemple:

"business-accounts"

callback

string

URL a la qual redirigir l'usuari un cop completada la verificació. Didit afegeix automàticament verificationSessionId i status (Approved, Declined, In Review) com a paràmetres de consulta. S'admeten esquemes d'URL personalitzats (p. ex., myapp://) per a callbacks mòbils. Si s'omet, s'utilitza la callback_url per defecte del flux de treball. Quan l'aplicació té dominis permesos (allowed_domains a PATCH /v3/webhook/), un callback http o https ha de pertànyer a un d'aquests orígens (mateix esquema, amfitrió i port); en cas contrari, la sol·licitud falla amb un error 400 a callback: callback must be on one of the application's allowed domains: https://app.example.com. Els esquemes d'URL personalitzats sempre s'accepten.

Exemple:

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

callback_method

enum<string>

predeterminat:initiator

Determina quin dispositiu ha de gestionar la redirecció a la URL de callback proporcionada. Utilitza initiator per redirigir només el dispositiu que ha iniciat el flux, completer per al dispositiu que el finalitza o both per permetre que qualsevol dels dos dispositius activi el callback. Si mai observes que el callback no s'activa de manera fiable, et recomanem establir aquest valor a both.

Opcions disponibles:

initiator,

completer,

both

Exemple:

"both"

metadata

any

JSON arbitrari emmagatzemat amb la sessió i retornat en la resposta i als webhooks. S'accepta qualsevol valor JSON (objecte, cadena, número, matriu), però es recomana un objecte JSON de parells clau/valor. No es mostra a l'usuari final. Utilitza'l per passar els teus propis identificadors de correlació, variants A/B o context empresarial.

Exemple:

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

Resposta

Sessió creada (o retornada, si ja existeix una sessió inacabada amb el mateix vendor_data a l'última versió publicada del flux de treball). La resposta és la sessió serialitzada, incloent-hi la url de verificació allotjada a la qual redirigir l'usuari.

session_id

string<uuid>

requerit

Identificador únic de la sessió de verificació. Utilitza aquest id en cridar GET /v3/session/{sessionId}/decision/.

Exemple:

"11111111-2222-3333-4444-555555555555"

session_number

integer

requerit

Número seqüencial i fàcil de llegir assignat a la sessió dins de la teva aplicació. Útil per a suport i taulers.

Exemple:

43762

session_token

string

requerit

Token segur per a URL de 12 caràcters que autoritza l'usuari final a accedir al flux de verificació allotjat a url. Vàlid fins que caduqui la sessió. Tracta'l com un secret: qualsevol persona que el tingui pot obrir el flux de verificació d'aquesta sessió.

Exemple:

"3FaJ9wLqX2Mz"

url

string<uri>

requerit

URL de verificació allotjada a la qual redirigir l'usuari final. L'URL incrusta el session_token i, si està configurat, utilitza el teu domini de marca blanca. Quan la sol·licitud inclou language, l'URL conté un segment de ruta d'idioma — https://verify.didit.me/{language}/session/{session_token} (p. ex. /es/session/...); sense language, el segment s'omet.

Exemple:

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

vendor_data

string | null

requerit

Identificador que has passat a la sol·licitud per vincular la sessió a un usuari o a una empresa del teu propi sistema. Es retorna exactament igual. Null quan no s'ha proporcionat.

Exemple:

"user-123"

metadata

any

requerit

Payload JSON arbitrari que vas emmagatzemar amb la sessió en el moment de la creació. Es retorna literalment: qualsevol valor JSON que hagis enviat (objecte, cadena, número, matriu) es retorna tal qual, tot i que es recomana un objecte JSON. No es mostra a l'usuari final. Sempre present a les respostes; null quan no s'ha proporcionat en crear-la.

Exemple:

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

status

enum<string>

requerit

Estat actual de la sessió. Les sessions acabades de crear retornen Not Started. Si ja existia una sessió no finalitzada per al mateix vendor_data a l'última versió publicada del flux de treball, l'estat retornat reflecteix aquesta sessió existent.

Opcions disponibles:

Not Started,

In Progress,

Approved,

Declined,

In Review,

Expired,

Abandoned,

Kyc Expired,

Resubmitted,

Awaiting User

Exemple:

"Not Started"

callback

string<uri> | null

requerit

URL de redirecció final a la qual s'envia l'usuari després de completar el flux. Didit afegeix ?verificationSessionId={session_id}&status={status} a aquesta URL. Si no s'indica a la sol·licitud, s'utilitza per defecte la URL de callback configurada al flux de treball; serà null si no se n'ha configurat cap de les dues. Si l'aplicació té dominis permesos i aquesta URL és una URL web externa a aquests dominis (per exemple, un valor per defecte del flux de treball configurat abans que canviés la llista), el flux allotjat no hi redirigeix l'usuari.

Exemple:

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

workflow_id

string<uuid>

requerit

Identificador estable del flux de treball en què s'executa aquesta sessió. Sempre és l'identificador de grup estable del flux de treball: fins i tot si has fet referència a un UUID de versió de flux de treball específic a la sol·licitud (cerca compatible amb versions anteriors), la resposta conté el workflow_id estable. Utilitza'l per correlacionar la sessió amb el flux de treball que hagis configurat a la Console.

Exemple:

"11111111-2222-3333-4444-555555555555"

workflow_version

integer

requerit

Número de versió de la versió publicada del flux de treball a la qual es va fixar la sessió en crear-se. Didit resol workflow_id a la darrera versió publicada del flux de treball quan es crea la sessió, i la sessió continua executant aquesta versió encara que el flux de treball es torni a publicar més endavant.

Exemple:

3

​Compatibilitat amb KYC i KYB

​Exemples

​Documents de signatura electrònica

​Col·locar camps mitjançant text d’ancoratge

​Valors dels camps

​Errors i crides repetides

​Proves amb escenaris de sandbox

​vendor_data vincula la sessió a una entitat

​Consentiment biomètric a Illinois, Texas i Colorado

​Important: la comunicació de la informació i l’obtenció del consentiment encara tenen lloc al teu producte

​Llista de comprovació recomanada abans de la verificació

Autoritzacions

Cos

Resposta

Compatibilitat amb KYC i KYB

Exemples

Documents de signatura electrònica

Col·locar camps mitjançant text d’ancoratge

Valors dels camps

Errors i crides repetides

Proves amb escenaris de sandbox

`vendor_data` vincula la sessió a una entitat

Consentiment biomètric a Illinois, Texas i Colorado

Important: la comunicació de la informació i l’obtenció del consentiment encara tenen lloc al teu producte

Llista de comprovació recomanada abans de la verificació