{ "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "Didit Verification API", "description": "API de Verificação de identidade. Autentique-se com o cabeçalho x-api-key." }, "servers": [ { "url": "https://verification.didit.me" } ], "tags": [], "paths": { "/system/healthcheck": { "get": { "summary": "Verificação do estado do serviço (público, não autenticado)", "description": "Sonda de liveness pública não autenticada. Devolve `HTTP 200` com `{status: \"ok\", timestamp}` quando o serviço, a base de dados, a cache e o broker estão operacionais.", "operationId": "get_system_healthcheck", "x-didit-sdk": { "resource": "system", "method": "healthcheck", "auth": "public", "server": false }, "tags": [ "System" ], "security": [ {} ], "parameters": [], "responses": { "200": { "description": "O serviço está operacional e a aceitar pedidos. O corpo é sempre `{\"status\": \"ok\", \"timestamp\": \"\"}`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Marcador de prova de vida. Sempre a string literal `\"ok\"` numa resposta 200.", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time", "description": "Hora do servidor em que a verificação do estado foi avaliada, em ISO 8601 com precisão de milissegundos e um sufixo `Z` (UTC).", "example": "2026-04-21T16:42:50.445Z" } } }, "examples": { "Healthy": { "summary": "O serviço está operacional", "value": { "status": "ok", "timestamp": "2026-04-21T16:42:50.445Z" } } } } } }, "503": { "description": "O serviço não está operacional — um dos plugins de verificação de estado configurados (base de dados, cache, broker) está a falhar. O corpo da resposta é intencionalmente mínimo; o estado HTTP é o sinal determinante. Tente novamente com espera exponencial." }, "5XX": { "description": "O serviço de verificação está degradado ou inacessível. Trate qualquer resposta que não seja 2xx como \"com problemas\" e tente novamente com recuo exponencial." } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -i https://verification.didit.me/system/healthcheck" }, { "lang": "Python", "label": "Python (requests)", "source": "import requests\n\nresp = requests.get(\"https://verification.didit.me/system/healthcheck\", timeout=5)\nresp.raise_for_status()\nprint(resp.json()) # {'status': 'ok', 'timestamp': '2026-04-21T16:42:50.445Z'}" }, { "lang": "JavaScript", "label": "Node.js (fetch)", "source": "const res = await fetch(\"https://verification.didit.me/system/healthcheck\");\nif (!res.ok) throw new Error(`Didit unhealthy: ${res.status}`);\nconst body = await res.json();\nconsole.log(body); // { status: 'ok', timestamp: '2026-04-21T16:42:50.445Z' }" } ] } }, "/v3/email/risk/": { "post": { "summary": "Calcular a pontuação de risco de um endereço de e-mail", "description": "Devolve sinais de entregabilidade, endereço descartável, violações de dados, correspondência entre sessões e informações normalizadas de inteligência de risco sem enviar um OTP. O endpoint cria uma sessão de API e devolve o seu id como `request_id`.\n\n**Decisão.** O `status` de nível superior reflete o `email.status`. Normalmente é `Approved`; a avaliação de risco pode produzir `In Review` ou `Declined`.\n\n**Aliases de compatibilidade.** As respostas em produção expõem o objeto de inteligência normalizado tanto como `email.email_intelligence` como `email.enrichment`. Os valores são idênticos. Novas integrações podem ler `email.enrichment`. Ambas as chaves estão ausentes quando não foram devolvidos dados úteis de inteligência.\n\n**Faturação.** As chamadas em produção utilizam os preços da Email Risk API. O pedido é faturável assim que a consulta tem início, mesmo quando alguns campos, obtidos tanto quanto possível, não estão disponíveis.\n\n**Sandbox.** As chaves de sandbox validam o pedido e devolvem dados determinísticos aprovados sem enviar um e-mail, consumir créditos, criar uma sessão ou contribuir para Networks.\n\n**Autenticação.** Envie a chave de API da sua aplicação em `x-api-key`. Credenciais em falta ou inválidas devolvem `403` - esta API nunca devolve `401`.\n\n**Limite de pedidos.** Orçamento de escrita partilhado de 300 pedidos por minuto por chave de API em todos os endpoints POST/PATCH/DELETE (a criação de transações e a ingestão de eventos têm um orçamento separado de 600).\n\n**Presença social.** Defina `enable_social` como `true` para adicionar um bloco `email_social`: as plataformas online onde este endereço está registado, com contagens por categoria e quaisquer detalhes de perfil disponíveis. `profiles_registered: 0` significa que as plataformas foram verificadas e o endereço não foi encontrado em nenhuma delas - uma resposta válida e faturável. O bloco está ausente quando o add-on não foi solicitado ou a verificação não pôde ser concluída, não sendo faturado nesse caso. A faturação adiciona uma unidade `email_social` por pedido ao preço próprio deste endpoint.", "operationId": "post_v3email_risk", "x-didit-sdk": { "resource": "email", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"country_code\": \"US\",\n \"vendor_data\": \"lead-123\",\n \"metadata\": {\"source\": \"signup_prescreen\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.assess_risk(\n email=\"alice@example.com\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.assessRisk({\n email: \"alice@example.com\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{\n\tEmail: \"alice@example.com\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().assessRisk(EmailRiskRequest.builder()\n .email(\"alice@example.com\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->assessRisk([\n 'email' => 'alice@example.com',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.assess_risk(email: \"alice@example.com\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.AssessRiskAsync(new EmailRiskRequest\n{\n Email = \"alice@example.com\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRiskRequest" }, "examples": { "Minimal": { "summary": "Calcular a pontuação de uma morada com valores predefinidos", "value": { "email": "alice@example.com" } }, "Full context": { "summary": "Pontuação com sinais, sugestão de país e IDs de correlação", "value": { "email": "alice@example.com", "country_code": "US", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "web", "os_version": "14.4", "app_version": "1.2.34", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15" }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" } } } } } } }, "responses": { "200": { "description": "A avaliação de risco foi concluída. Inspecione `status` para verificar a decisão; o código HTTP é sempre `200` para pesquisas concluídas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRiskResponse" }, "examples": { "Clean address": { "summary": "Endereço com capacidade de entrega sem exposição a violações de segurança", "value": { "request_id": "82397be9-5921-4970-a979-2d5b43e08b33", "status": "Approved", "email": { "status": "Approved", "email": "alice@example.com", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "email_intelligence": { "score": 4.0, "deliverable": "high", "breach_risk_level": "Low", "breach_risk_index": 4, "is_recent_breach": false, "is_frequent_breached": false, "is_disposable": false, "is_free_domain": false, "is_breached": false, "no_of_breaches": 0, "reason_codes": [] }, "enrichment": { "score": 4.0, "deliverable": "high", "breach_risk_level": "Low", "breach_risk_index": 4, "is_recent_breach": false, "is_frequent_breached": false, "is_disposable": false, "is_free_domain": false, "is_breached": false, "no_of_breaches": 0, "reason_codes": [] } }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" }, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Breached address": { "summary": "Endereço encontrado em violações conhecidas", "value": { "request_id": "d1e5c2a8-6f30-4c1a-8b2d-3e4f5a6b7c8d", "status": "In Review", "email": { "status": "In Review", "email": "bob@example.org", "is_breached": true, "breaches": [ { "name": "ExampleBreach2023", "domain": "example.org", "breach_date": "2023-06-01", "breach_emails_count": 1200000, "description": "A data breach affecting example.org accounts.", "logo_path": "https://logos.example.org/example.png", "data_classes": [ "email_addresses", "passwords" ], "is_verified": true } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "email_intelligence": { "score": 58.0, "deliverable": "high", "breach_risk_level": "High", "breach_risk_index": 72, "is_recent_breach": true, "is_frequent_breached": true, "is_disposable": false, "is_free_domain": true, "is_breached": true, "no_of_breaches": 4, "reason_codes": [ { "code": "IR-F784B630", "direction": "risk", "message": "Email's digital footprint diversity is Very Low", "impact_level": "low" } ] }, "enrichment": { "score": 58.0, "deliverable": "high", "breach_risk_level": "High", "breach_risk_index": 72, "is_recent_breach": true, "is_frequent_breached": true, "is_disposable": false, "is_free_domain": true, "is_breached": true, "no_of_breaches": 4, "reason_codes": [ { "code": "IR-F784B630", "direction": "risk", "message": "Email's digital footprint diversity is Very Low", "impact_level": "low" } ] } }, "vendor_data": "lead-125", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/EmailRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/ip/risk/": { "post": { "summary": "Calcular a pontuação de risco de um endereço IP", "description": "Devolve a geolocalização, propriedade da rede, sinalizadores de VPN/Tor e centros de dados, dados de ameaças e `country_mismatch` para um endereço IP fornecido. O endpoint cria uma sessão de API e devolve o seu id como `request_id`.\n\n**Decisão.** O `status` fica em `In Review` quando o país determinado entra em conflito com `claimed_country` ou quando o endereço está associado a infraestruturas de VPN, Tor ou centros de dados. Caso contrário, é `Approved`.\n\n**Melhor esforço.** O enriquecimento de IP é efetuado tanto quanto possível. Se nenhuma fonte de enriquecimento devolver dados úteis, o endpoint devolve uma resposta aprovada com `ip.ip_address: null`, `ip.country_mismatch: null` e um objeto `ip.threat` vazio.\n\n**Faturação.** As chamadas em produção utilizam os preços da IP Risk API. O pedido é faturável assim que a consulta tem início.\n\n**Sandbox.** As chaves de sandbox validam o pedido e devolvem dados determinísticos aprovados sem consumir créditos, criar uma sessão ou contribuir para Networks.\n\n**Autenticação.** Envie a chave de API da sua aplicação em `x-api-key`. Credenciais em falta ou inválidas devolvem `403` - esta API nunca devolve `401`.\n\n**Limite de pedidos.** Orçamento de escrita partilhado de 300 pedidos por minuto por chave de API em todos os endpoints POST/PATCH/DELETE (a criação de transações e a ingestão de eventos têm um orçamento separado de 600).", "operationId": "post_v3ip_risk", "x-didit-sdk": { "resource": "ip", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/ip/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"ip_address\": \"8.8.8.8\",\n \"claimed_country\": \"ESP\",\n \"user_agent\": \"Mozilla/5.0\",\n \"vendor_data\": \"lead-123\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.ip.assess_risk(\n ip_address=\"8.8.8.8\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.ip.assessRisk({\n ip_address: \"8.8.8.8\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IP.AssessRisk(ctx, didit.IPRiskRequest{\n\tIPAddress: \"8.8.8.8\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.IPRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.ip().assessRisk(IPRiskRequest.builder()\n .ipAddress(\"8.8.8.8\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "ip->assessRisk([\n 'ip_address' => '8.8.8.8',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.ip.assess_risk(ip_address: \"8.8.8.8\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Ip.AssessRiskAsync(new IPRiskRequest\n{\n IpAddress = \"8.8.8.8\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPRiskRequest" }, "examples": { "Minimal": { "summary": "Calcular a pontuação de uma morada com valores predefinidos", "value": { "ip_address": "8.8.8.8" } }, "With claimed country": { "summary": "Pontuação com um país declarado para deteção de discrepâncias", "value": { "ip_address": "8.8.8.8", "claimed_country": "ESP", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15", "vendor_data": "lead-123" } } } } } }, "responses": { "200": { "description": "A avaliação de risco foi concluída. Inspecione `status` para verificar a decisão; o código HTTP é sempre `200` para pesquisas concluídas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPRiskResponse" }, "examples": { "Clean residential IP": { "summary": "Morada de residência, o país declarado corresponde", "value": { "request_id": "9a96ed2a-721e-4b86-8cbf-d61eda529279", "status": "Approved", "ip": { "status": "Approved", "ip_address": "192.0.2.10", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Madrid", "ip_city": "Madrid", "latitude": 40.4168, "longitude": -3.7038, "isp": "Example Telecom", "organization": "Example Telecom SA", "is_vpn_or_tor": false, "is_data_center": false, "time_zone": "Europe/Madrid", "time_zone_offset": "+0200", "asn_number": 3352, "asn_organization": "EXAMPLE-TELECOM", "connection_type": "broadband", "carrier": "Example Telecom", "proxy_type": null, "claimed_country": "ESP", "country_mismatch": false, "threat": {} }, "vendor_data": "lead-123", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Datacenter mismatch": { "summary": "Endereço de centro de dados em conflito com o país indicado", "value": { "request_id": "5b1d4e9a-3c7b-4f8e-9a2d-1b0c9d8e7f6a", "status": "In Review", "ip": { "status": "In Review", "ip_address": "8.8.8.8", "ip_country": "United States", "ip_country_code": "US", "ip_state": "California", "ip_city": "Mountain View", "latitude": 37.386, "longitude": -122.0838, "isp": "Google", "organization": "Google LLC", "is_vpn_or_tor": true, "is_data_center": true, "time_zone": "America/Los_Angeles", "time_zone_offset": "-0700", "asn_number": 15169, "asn_organization": "GOOGLE, US", "connection_type": "hosting", "carrier": null, "proxy_type": "VPN", "claimed_country": "ESP", "country_mismatch": true, "threat": { "is_proxy": true, "is_data_center": true, "is_tor": false } }, "vendor_data": "lead-126", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/IPRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/phone/risk/": { "post": { "summary": "Calcular a pontuação de risco de um número de telefone", "description": "Resolva um número de telefone e obtenha a operadora, o tipo de linha, a portabilidade, a deteção de números descartáveis, a correspondência entre sessões e sinais de inteligência de risco normalizados sem enviar um OTP. O endpoint cria uma sessão de API e devolve o seu id como `request_id`.\n\n**Decisão.** O `status` de nível superior reflete `phone.status`. Normalmente é `Approved`; a avaliação de risco pode produzir `In Review` ou `Declined`.\n\n**Aliases de compatibilidade.** As respostas em ambiente de produção expõem o objeto de inteligência normalizado tanto como `phone.phone_intelligence` como `phone.enrichment`. Os valores são idênticos. Novas integrações podem ler `phone.enrichment`. Ambas as chaves estão ausentes quando não foram devolvidos dados de inteligência utilizáveis.\n\n**Faturação.** As chamadas em ambiente de produção utilizam os preços da Phone Risk API. O pedido é faturável assim que a consulta tem início, mesmo que alguns campos de melhor esforço não estejam disponíveis.\n\n**Sandbox.** As chaves de sandbox validam o pedido e devolvem dados determinísticos aprovados sem enviar um OTP, consumir créditos, criar uma sessão ou contribuir para o Networks.\n\n**Autenticação.** Envie a chave de API da sua aplicação em `x-api-key`. Credenciais ausentes ou inválidas devolvem `403` - esta API nunca devolve `401`.\n\n**Limite de pedidos.** Orçamento de escrita partilhado de 300 pedidos por minuto por chave de API em endpoints POST/PATCH/DELETE (a criação de transações e a ingestão de eventos têm um orçamento separado de 600).\n\n**Pegada social.** Defina `enable_social` como `true` para adicionar um bloco `phone_social`: as plataformas online onde este número está registado, com contagens por categoria e quaisquer detalhes de perfil disponíveis. `profiles_registered: 0` significa que as plataformas foram verificadas e o número não foi encontrado em nenhuma delas - uma resposta válida e faturável. O bloco está ausente quando o add-on não foi solicitado ou a verificação não pôde ser concluída, não sendo faturado nesse caso. A faturação acrescenta uma unidade `phone_social` por pedido ao preço próprio deste endpoint.", "operationId": "post_v3phone_risk", "x-didit-sdk": { "resource": "phone", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"vendor_data\": \"lead-123\",\n \"metadata\": {\"source\": \"signup_prescreen\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.assess_risk(\n phone_number=\"+14155552671\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.assessRisk({\n phone_number: \"+14155552671\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{\n\tPhoneNumber: \"+14155552671\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().assessRisk(PhoneRiskRequest.builder()\n .phoneNumber(\"+14155552671\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->assessRisk([\n 'phone_number' => '+14155552671',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.assess_risk(phone_number: \"+14155552671\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.AssessRiskAsync(new PhoneRiskRequest\n{\n PhoneNumber = \"+14155552671\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneRiskRequest" }, "examples": { "Minimal": { "summary": "Calcular a pontuação de um número com valores predefinidos", "value": { "phone_number": "+14155552671" } }, "Full context": { "summary": "Pontuação com sinais, sugestão de país e IDs de correlação", "value": { "phone_number": "+14155552671", "country_code": "US", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "ios", "device_model": "iPhone17,2", "os_version": "18.0.1", "app_version": "1.2.34", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1" }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" } } } } } } }, "responses": { "200": { "description": "A avaliação de risco foi concluída. Inspecione `status` para verificar a decisão; o código HTTP é sempre `200` para pesquisas concluídas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneRiskResponse" }, "examples": { "Clean mobile number": { "summary": "Número de telemóvel limpo com cobertura de dados de inteligência", "value": { "request_id": "4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62", "status": "Approved", "phone": { "status": "Approved", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "Example Mobile", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": null, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "phone_intelligence": { "score": 3.0, "phone_type_risk": "Low", "phone_trust_index": 97, "network_stability_index": 95, "is_disposable": false, "is_ported": false, "is_recently_ported": false, "carrier_type": "mobile", "reason_codes": [] }, "enrichment": { "score": 3.0, "phone_type_risk": "Low", "phone_trust_index": 97, "network_stability_index": 95, "is_disposable": false, "is_ported": false, "is_recently_ported": false, "carrier_type": "mobile", "reason_codes": [] } }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" }, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Number in review": { "summary": "Número descartável ou virtual sinalizado para revisão", "value": { "request_id": "8c22e1f0-4b3d-4a3a-9d1e-2f6b7c8d9e0f", "status": "In Review", "phone": { "status": "In Review", "phone_number_prefix": "+44", "phone_number": "7700900123", "full_number": "+447700900123", "country_code": "GB", "country_name": "United Kingdom", "carrier": { "name": "Example VoIP", "type": "voip" }, "is_disposable": true, "is_virtual": true, "verification_method": null, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "phone_intelligence": { "score": 72.0, "phone_type_risk": "High", "phone_trust_index": 28, "network_stability_index": 40, "is_disposable": true, "is_ported": true, "is_recently_ported": true, "carrier_type": "voip", "reason_codes": [ { "code": "IR-5AC67A32", "direction": "risk", "message": "Phone type identified as non-mobile", "impact_level": "medium" } ] }, "enrichment": { "score": 72.0, "phone_type_risk": "High", "phone_trust_index": 28, "network_stability_index": 40, "is_disposable": true, "is_ported": true, "is_recently_ported": true, "carrier_type": "voip", "reason_codes": [ { "code": "IR-5AC67A32", "direction": "risk", "message": "Phone type identified as non-mobile", "impact_level": "medium" } ] } }, "vendor_data": "lead-124", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/PhoneRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/": { "post": { "summary": "Criar uma sessão de verificação", "description": "Crie uma sessão de Verificação de utilizadores (KYC) ou de Verificação de empresas (KYB) e receba um `url` de verificação alojado juntamente com um `session_token` para redirecionar o seu utilizador final ou incorporar a página para esse utilizador. O `workflow_id` seleciona quais os passos de verificação a executar e se a sessão é de KYC ou de KYB.\n\nChame este endpoint a partir do seu backend (nunca a partir do navegador — a chave de API é um segredo) sempre que for necessário verificar um utilizador ou empresa: no registo, antes de uma ação sensível ou quando for necessária uma reverificação. Pré-requisitos: um fluxo publicado (criado na página [Workflows](https://docs.didit.me/pt/console/workflows) da Consola) e uma chave de API da aplicação com créditos disponíveis. As aplicações em sandbox ignoram a verificação de créditos.\n\n**Idempotência:** quando `vendor_data` é fornecido e já existe uma sessão não concluída (`Not Started`, `In Progress`, `Resubmitted` ou `Awaiting User`) com o mesmo `vendor_data` na **versão publicada mais recente do fluxo** (e essa sessão já possui um URL de verificação alojado), a sessão existente é devolvida (ainda `201`) em vez de criar uma duplicada — com o seu `callback` e `metadata` atualizados para os novos valores fornecidos. Uma sessão não concluída criada numa versão mais antiga do fluxo (uma que tenha sido entretanto republicada) **não** é reutilizada; em vez disso, é criada uma nova sessão associada à versão publicada mais recente. Sessões em `Approved`, `Declined`, `In Review`, `Expired`, `Abandoned` ou `Kyc Expired` nunca são reutilizadas.\n\n**Efeitos secundários:** o URL de verificação alojado é gerado e armazenado; se `contact_details.send_notification_emails` for `true` e for fornecido um e-mail, é enviado um e-mail de convite para verificação. A sessão expira após o tempo de expiração da sessão configurado no fluxo. Para fluxos de KYB, `contact_details.phone` e `expected_details` são ignorados.", "operationId": "post_v3_session_create", "x-didit-sdk": { "resource": "sessions", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "201": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "session_number", "session_token", "url", "vendor_data", "metadata", "status", "workflow_id", "workflow_version", "callback" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Identificador único da sessão de verificação. Utilize este id ao chamar `GET /v3/session/{sessionId}/decision/`.", "example": "11111111-2222-3333-4444-555555555555" }, "session_number": { "type": "integer", "description": "Número sequencial e de fácil leitura atribuído à sessão dentro da sua aplicação. Útil para suporte e painéis.", "example": 43762 }, "session_token": { "type": "string", "description": "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.", "example": "3FaJ9wLqX2Mz" }, "url": { "type": "string", "format": "uri", "description": "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.", "example": "https://verify.didit.me/session/3FaJ9wLqX2Mz" }, "vendor_data": { "type": "string", "nullable": true, "description": "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.", "example": "user-123" }, "metadata": { "description": "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.", "example": { "user_type": "premium", "account_id": "ABC123" } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "As etiquetas na sessão, por nome.", "example": [ "VIP", "ONBOARDING Q4" ] }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "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.", "example": "Not Started" }, "callback": { "type": "string", "format": "uri", "nullable": true, "description": "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.", "example": "https://example.com/verification/callback" }, "workflow_id": { "type": "string", "format": "uuid", "description": "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.", "example": "11111111-2222-3333-4444-555555555555" }, "workflow_version": { "type": "integer", "description": "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.", "example": 3 } } }, "examples": { "KYC session": { "summary": "Sessão KYC criada", "value": { "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" } }, "KYB session": { "summary": "Sessão KYB criada", "value": { "session_id": "22222222-3333-4444-5555-666666666666", "session_number": 43763, "session_token": "Yk7pQ2vN8aBc", "url": "https://verify.didit.me/en/session/Yk7pQ2vN8aBc", "vendor_data": "company-acme-001", "metadata": { "tier": "enterprise" }, "status": "Not Started", "workflow_id": "33333333-4444-5555-6666-777777777777", "workflow_version": 1, "callback": "https://example.com/kyb/callback" } } } } } }, "400": { "description": "Pedido incorreto — a validação do payload falhou (`workflow_id` em falta ou desconhecido, `language` inválido, `vendor_data` na lista de bloqueio, `portrait_image` malformada, `address` sem `country`/`poa_country`, `sandbox_scenario` inválido, documentos `sign`, campos ou valores recusados pelo passo de Assinatura eletrónica do fluxo, tais como `signature_document_not_supported`, `signature_document_conversion_failed`, `field_anchor_not_found` ou `field_value_missing`, etc.) ou a sua organização não tem créditos suficientes para iniciar a sessão.\n\nO corpo é um objeto cuja chave é o nome do campo com erro (ou `detail` para erros que não são de campos). Os valores são um **array de strings** para falhas de validação de entrada (por exemplo, campo obrigatório em falta, idioma inválido, imagem de retrato demasiado grande) e uma **string simples** para falhas detetadas durante a criação da sessão (`workflow_id` desconhecido, `vendor_data` na lista de bloqueio, nenhuma face de referência disponível para um fluxo de Correspondência facial). Processe ambos os formatos.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível para erros não associados a campos (por exemplo, créditos insuficientes). Em vez disso, as falhas ao nível dos campos utilizam o nome do campo como chave, com um valor de string ou de array de strings.", "example": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } }, "examples": { "Missing workflow_id": { "summary": "Campo obrigatório omitido (formato de array de strings)", "value": { "workflow_id": [ "This field is required." ] } }, "Invalid workflow_id": { "summary": "workflow_id desconhecido (formato plain-string)", "value": { "workflow_id": "Invalid workflow_id." } }, "Insufficient credits": { "summary": "A organização não tem créditos", "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } }, "Blocklisted vendor_data": { "summary": "vendor_data está na lista de bloqueio", "value": { "vendor_data": "This user or business has been blocked and cannot create new verification sessions." } }, "Portrait image too large": { "summary": "portrait_image falha a validação de tamanho", "value": { "portrait_image": [ "Image size exceeds 2MB." ] } }, "No stored face for vendor_data": { "summary": "Fluxo de Correspondência facial sem portrait_image e sem rosto guardado para o utilizador de vendor_data", "value": { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } }, "Portrait image required without vendor_data": { "summary": "Fluxo de Correspondência facial sem portrait_image e sem vendor_data", "value": { "portrait_image": "A portrait image is required to perform face match for this workflow. Send a portrait_image, or provide the vendor_data of a user with a previously stored face image to reuse it." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave incorreta, revogada ou expirada devolve `401`. O endpoint devolve `403` quando o cabeçalho `x-api-key` está em falta ou a chave de API é válida mas o cliente não tem permissão para criar sessões nesta aplicação (por exemplo, a chave de API pertence a uma organização diferente). Estas falhas partilham o corpo `{\"detail\": \"You do not have permission to perform this action.\"}`. Verifique se o cabeçalho `x-api-key` está presente e pertence à aplicação pretendida, obtenha novamente a chave de API da aplicação através da [API de autenticação](/pt/auth-api/get-credentials) se necessário e tente novamente.\n\n**Aplicação eliminada:** durante alguns minutos após a eliminação de uma aplicação, um pedido efetuado com uma das suas chaves de API pode responder `{\"detail\": \"This application was deleted.\", \"code\": \"application_deleted\"}`. Não tente novamente: a aplicação e as suas chaves de API já não existem. Decorridos esses minutos, a chave é recusada como qualquer outra chave inválida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." }, "code": { "type": "string", "description": "Motivo legível por máquina, presente apenas em algumas falhas. `application_deleted`: a chave de API pertence a uma aplicação que foi eliminada.", "example": "application_deleted" } }, "required": [ "detail" ] }, "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key` ou chave de API inválida", "value": { "detail": "You do not have permission to perform this action." } }, "No permission": { "summary": "O cliente não pode criar sessões", "value": { "detail": "You do not have permission to perform this action." } }, "Application deleted": { "summary": "Chave de API de uma aplicação eliminada", "value": { "detail": "This application was deleted.", "code": "application_deleted" } } } } } }, "429": { "description": "Limite de pedidos excedido — mais de 600 pedidos de criação de sessão numa janela de 60 segundos a partir da mesma chave de API / IP. Inspecione o `Retry-After` e aguarde antes de tentar novamente.\n\n**Nota:** O código-fonte também define um `FREE_SESSION_RATE_LIMIT` de 10 chamadas/minuto a par de `PAID_SESSION_RATE_LIMIT=600` (`sessions/serializers/session.py`), mas esse teto do plano gratuito **não é aplicado a este endpoint V3** — o middleware de limite de pedidos aplica o `SESSION_CREATE_RATE_LIMIT` de 600/min independentemente do plano. 600/min é o único limite que pode atingir aqui.", "headers": { "Retry-After": { "description": "Segundos que o autor da chamada deve aguardar antes de tentar novamente o pedido.", "schema": { "type": "integer", "minimum": 1, "example": 42 } }, "X-RateLimit-Limit": { "description": "Número máximo de pedidos permitidos na janela atual de 60 segundos para o limite que foi ultrapassado (600 para session-create). Ausente na variante de quota de sandbox.", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Número de pedidos ainda permitidos na janela atual para o limite ultrapassado. Ausente na variante de quota da sandbox.", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, "X-RateLimit-Reset": { "description": "Segundos da época UTC em que a janela atual de limite de pedidos é reiniciada. Ausente na variante de quota de sandbox.", "schema": { "type": "integer", "minimum": 0, "example": 1747497600 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Explicação legível da violação do limite de pedidos. Utilize esta mensagem para distinguir qual dos três limites foi atingido.", "example": "Session creation rate limit exceeded. You can make up to 600 requests per minute." } } }, "examples": { "Session-create limit": { "summary": "Mais de 600 pedidos de criação de sessão por minuto", "value": { "detail": "Session creation rate limit exceeded. You can make up to 600 requests per minute." } }, "Sandbox session quota": { "summary": "Aplicação em sandbox excedeu 500 sessões em 24 horas", "value": { "detail": "Sandbox session quota exceeded (500 sessions per 24h). Wait for the window to reset. Expected available in 3600 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/session/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"workflow_id\": \"11111111-2222-3333-4444-555555555555\",\n \"vendor_data\": \"user-123\",\n \"callback\": \"https://example.com/verification/callback\",\n \"callback_method\": \"both\",\n \"metadata\": {\"user_type\": \"premium\", \"account_id\": \"ABC123\"},\n \"language\": \"en\",\n \"contact_details\": {\n \"email\": \"john.doe@example.com\",\n \"send_notification_emails\": true,\n \"email_lang\": \"en\",\n \"phone\": \"+14155552671\"\n },\n \"expected_details\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"id_country\": \"USA\",\n \"expected_document_types\": [\"P\", \"ID\"]\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.create(\n workflow_id=\"11111111-2222-3333-4444-555555555555\",\n vendor_data=\"user-123\",\n callback=\"https://example.com/verification/callback\",\n callback_method=\"both\",\n metadata={\"user_type\": \"premium\", \"account_id\": \"ABC123\"},\n language=\"en\",\n contact_details={\n \"email\": \"john.doe@example.com\",\n \"send_notification_emails\": True,\n \"email_lang\": \"en\",\n \"phone\": \"+14155552671\",\n },\n expected_details={\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"nationality\": \"USA\",\n \"id_country\": \"USA\",\n \"expected_document_types\": [\"P\", \"ID\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.create({\n workflow_id: \"11111111-2222-3333-4444-555555555555\",\n vendor_data: \"user-123\",\n callback: \"https://example.com/verification/callback\",\n callback_method: \"both\",\n metadata: { user_type: \"premium\", account_id: \"ABC123\" },\n language: \"en\",\n contact_details: {\n email: \"john.doe@example.com\",\n send_notification_emails: true,\n email_lang: \"en\",\n phone: \"+14155552671\",\n },\n expected_details: {\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1990-05-15\",\n nationality: \"USA\",\n id_country: \"USA\",\n expected_document_types: [\"P\", \"ID\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().create(SessionsCreateParams.builder()\n .workflowId(\"11111111-2222-3333-4444-555555555555\")\n .vendorData(\"user-123\")\n .callback(\"https://example.com/verification/callback\")\n .callbackMethod(SessionsCreateParams.CallbackMethod.of(\"both\"))\n .metadata(Map.of(\"user_type\", \"premium\", \"account_id\", \"ABC123\"))\n .language(SessionsCreateParams.Language.of(\"en\"))\n .contactDetails(SessionsCreateParams.ContactDetails.builder()\n .email(\"john.doe@example.com\")\n .sendNotificationEmails(true)\n .emailLang(SessionsCreateParams.ContactDetails.EmailLang.of(\"en\"))\n .phone(\"+14155552671\")\n .build())\n .expectedDetails(SessionsCreateParams.ExpectedDetails.builder()\n .firstName(\"John\")\n .lastName(\"Doe\")\n .dateOfBirth(LocalDate.parse(\"1990-05-15\"))\n .nationality(\"USA\")\n .idCountry(\"USA\")\n .expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of(\"P\"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of(\"ID\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->create([\n 'workflow_id' => '11111111-2222-3333-4444-555555555555',\n 'vendor_data' => 'user-123',\n 'callback' => 'https://example.com/verification/callback',\n 'callback_method' => 'both',\n 'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],\n 'language' => 'en',\n 'contact_details' => [\n 'email' => 'john.doe@example.com',\n 'send_notification_emails' => true,\n 'email_lang' => 'en',\n 'phone' => '+14155552671',\n ],\n 'expected_details' => [\n 'first_name' => 'John',\n 'last_name' => 'Doe',\n 'date_of_birth' => '1990-05-15',\n 'nationality' => 'USA',\n 'id_country' => 'USA',\n 'expected_document_types' => ['P', 'ID'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.create(\n workflow_id: \"11111111-2222-3333-4444-555555555555\",\n vendor_data: \"user-123\",\n callback: \"https://example.com/verification/callback\",\n callback_method: \"both\",\n metadata: { user_type: \"premium\", account_id: \"ABC123\" },\n language: \"en\",\n contact_details: {\n email: \"john.doe@example.com\",\n send_notification_emails: true,\n email_lang: \"en\",\n phone: \"+14155552671\",\n },\n expected_details: {\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1990-05-15\",\n nationality: \"USA\",\n id_country: \"USA\",\n expected_document_types: [\"P\", \"ID\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CreateAsync(new SessionsCreateParams\n{\n WorkflowId = \"11111111-2222-3333-4444-555555555555\",\n VendorData = \"user-123\",\n Callback = \"https://example.com/verification/callback\",\n CallbackMethod = new SessionsCreateParamsCallbackMethod(\"both\"),\n Metadata = new Dictionary { [\"user_type\"] = \"premium\", [\"account_id\"] = \"ABC123\" },\n Language = new SessionsCreateParamsLanguage(\"en\"),\n ContactDetails = new SessionsCreateParamsContactDetails\n {\n Email = \"john.doe@example.com\",\n SendNotificationEmails = true,\n EmailLang = new SessionsCreateParamsContactDetailsEmailLang(\"en\"),\n Phone = \"+14155552671\",\n },\n ExpectedDetails = new SessionsCreateParamsExpectedDetails\n {\n FirstName = \"John\",\n LastName = \"Doe\",\n DateOfBirth = \"1990-05-15\",\n Nationality = \"USA\",\n IdCountry = \"USA\",\n ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { \"P\", \"ID\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workflow_id" ], "properties": { "workflow_id": { "type": "string", "format": "uuid", "description": "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](/pt/console/workflows) da Consola. O `workflow_id` também seleciona implicitamente se a sessão é KYC ou KYB.", "example": "11111111-2222-3333-4444-555555555555", "x-readme-id": "0.0" }, "vendor_data": { "type": "string", "description": "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.", "example": "user-123", "x-readme-id": "0.1" }, "multi_account_segment": { "type": "string", "maxLength": 64, "description": "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.", "example": "business-accounts" }, "callback": { "type": "string", "description": "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.", "example": "https://example.com/verification/callback", "x-readme-id": "0.2" }, "callback_method": { "type": "string", "description": "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`.", "enum": [ "initiator", "completer", "both" ], "default": "initiator", "example": "both", "x-readme-id": "0.3" }, "metadata": { "description": "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.", "example": { "user_type": "premium", "account_id": "ABC123" }, "x-readme-id": "0.4" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 10, "description": "Etiquetas adicionadas à sessão quando esta é criada, por nome. Até 10, cada uma com até 50 carateres. Os nomes não diferenciam maiúsculas de minúsculas e são guardados em maiúsculas. Um nome que ainda não exista na aplicação é criado como uma nova etiqueta. As etiquetas são apresentadas na sessão na consola, onde pode filtrar por elas.", "example": [ "VIP", "ONBOARDING Q4" ] }, "language": { "type": "string", "description": "Código de idioma (ISO 639-1) para a interface do processo de verificação. Controla o idioma apresentado ao utilizador final durante a verificação. Se não for fornecido, o idioma do navegador será detetado e utilizado automaticamente. Consulte todos os idiomas suportados [aqui](/pt/integration/supported-languages).", "enum": [ "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" ], "example": "en", "x-readme-id": "0.5" }, "contact_details": { "type": "object", "description": "Informações de contacto do utilizador que podem ser utilizadas para notificações, pré-preenchimento de formulários de verificação e verificação de telefone. Isto inclui o endereço de e-mail, o idioma preferido para comunicações e o número de telefone.", "example": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "properties": { "email": { "type": "string", "format": "email", "description": "Endereço de e-mail do utilizador (ex.: \"john.doe@example.com\") que será utilizado durante o passo de [Verificação de e-mail](/pt/core-technology/email-verification/overview). Se não for fornecido, o utilizador terá de o indicar durante o fluxo de verificação.", "example": "john.doe@example.com", "x-readme-id": "1.0" }, "send_notification_emails": { "type": "boolean", "default": false, "description": "Se for verdadeiro e um e-mail for fornecido, a Didit envia o e-mail inicial \"Verifique a sua identidade\" de forma assíncrona quando a sessão de Verificação de utilizadores (KYC) ou Verificação de empresas (KYB) for criada. A Didit também envia notificações sobre o estado da verificação de sessões que necessitam de revisão manual para o endereço de e-mail fornecido (por exemplo, de 'In Review' para 'Approved' ou 'Declined'). Isto ajuda os utilizadores a regressarem à sua aplicação assim que a verificação for concluída. Se tiver a marca branca ativada para a sessão, o e-mail enviado terá marca branca.", "example": true, "x-readme-id": "1.1" }, "email_lang": { "type": "string", "description": "Código de idioma (ISO 639-1) para notificações por e-mail. Controla o idioma de todas as comunicações por e-mail (por exemplo, \"en\", \"es\", \"fr\"). Não existe um valor predefinido guardado — quando omitido, o e-mail de convite de verificação simplesmente reverte para inglês (`en`) no momento do envio. O enum abaixo é um instantâneo; a fonte de referência em tempo real para os valores aceites é o documento de [idiomas suportados](/pt/integration/supported-languages) — consulte-o sempre antes de depender de um código específico.", "enum": [ "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" ], "example": "en", "x-readme-id": "1.2" }, "phone": { "type": "string", "description": "Número de telefone no formato E.164 (por exemplo, \"+14155552671\") que será utilizado durante o passo de [Verificação de telefone](/pt/core-technology/phone-verification/overview). Se não for fornecido, o utilizador tem de o introduzir durante o fluxo de verificação. Ignorado para fluxos de Verificação de empresas (KYB). **Importante:** Este número de telefone só é aplicado se for um número de telefone E.164 válido. Se o número fornecido for inválido ou não puder ser analisado, será ignorado e o utilizador poderá introduzir qualquer número de telefone válido durante o passo de Verificação de telefone.", "example": "+14155552671", "x-readme-id": "1.3" } }, "x-readme-id": "0.4" }, "expected_details": { "type": "object", "description": "Dados esperados do utilizador utilizados para validação cruzada com os dados extraídos do documento de identificação do utilizador, Comprovativo de morada e outros passos de verificação. As discrepâncias são apresentadas como avisos na decisão; alguns campos (por exemplo, `id_country`, `expected_document_types`) também alteram o fluxo apresentado ao utilizador. Para fluxos de Verificação de empresas (KYB), apenas os campos da empresa (`company_name`, `registry_country`, `registration_number`) são utilizados — pré-preenchem a pesquisa no registo de empresas para o utilizador — e todos os campos a nível de pessoa são ignorados.", "example": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "nationality": "USA", "id_country": "USA", "expected_document_types": [ "P", "ID" ] }, "properties": { "first_name": { "type": "string", "description": "Primeiro nome do utilizador. Por exemplo, `John`. A correspondência utiliza comparação difusa (fuzzy) e pode ajustar o nível de exigência configurando o limiar da pontuação de correspondência de nomes na consola para os fluxos de Documento de identificação e Comprovativo de morada.", "example": "John", "x-readme-id": "1.0" }, "last_name": { "type": "string", "description": "Apelido do utilizador. Por exemplo, `Doe`. A correspondência utiliza comparação difusa (fuzzy) e pode ajustar o nível de exigência configurando o limiar da pontuação de correspondência de nomes na consola para os fluxos de Documento de identificação e Comprovativo de morada.", "example": "Doe", "x-readme-id": "1.1" }, "date_of_birth": { "type": "string", "format": "date", "description": "Data de nascimento do utilizador no formato: YYYY-MM-DD. Por exemplo, `1990-05-15`.", "example": "1990-05-15", "x-readme-id": "1.2" }, "gender": { "type": "string", "nullable": true, "enum": [ "M", "F" ], "default": null, "description": "Género do utilizador. Deve ser 'M', 'F' ou null.", "example": "M", "x-readme-id": "1.3" }, "nationality": { "type": "string", "description": "Código de país ISO 3166-1 alfa-3 que representa o país de origem do requerente. Por exemplo, `USA`. Consulte a [lista completa de códigos de país suportados](https://docs.didit.me/pt/core-technology/id-verification/supported-documents-id-verification#documentos-suportados-por-país).", "example": "USA", "x-readme-id": "1.4" }, "country": { "type": "string", "description": "Código de país ISO 3166-1 alfa-3 utilizado como recurso para as verificações de discrepância de país tanto de Verificação de identidade como de Comprovativo de morada. Obrigatório quando `address` é fornecido e nem `id_country` nem `poa_country` estão definidos.", "example": "USA", "x-readme-id": "1.4.1" }, "id_country": { "type": "string", "description": "Código de país ISO 3166-1 alfa-3 que representa o país esperado do documento de identificação do requerente, que pode diferir da nacionalidade. Por exemplo, `GBR`. Tem prioridade sobre `country` para verificações de discrepância de país de verificação de identidade. Consulte a [lista completa de códigos de país suportados](https://docs.didit.me/pt/core-technology/id-verification/supported-documents-id-verification#documentos-suportados-por-país).", "example": "GBR", "x-readme-id": "1.5" }, "poa_country": { "type": "string", "description": "Código de país ISO 3166-1 alfa-3 que representa o país esperado do documento de Comprovativo de morada. Por exemplo, `USA`. Tem prioridade sobre `country` para verificações de discrepância de país de POA. Consulte a [lista completa de códigos de país suportados](https://docs.didit.me/pt/core-technology/id-verification/supported-documents-id-verification#documentos-suportados-por-país).", "example": "USA", "x-readme-id": "1.5.1" }, "address": { "type": "string", "description": "A morada num formato legível por humanos, incluindo o máximo de informação possível. Por exemplo, `123 Main St, San Francisco, CA 94105, USA`. Quando fornecida, também deve passar `country` ou `poa_country`, caso contrário o pedido falha com `400`.", "example": "123 Main St, San Francisco, CA 94105, USA", "x-readme-id": "1.6" }, "identification_number": { "type": "string", "description": "O número de documento, número de identificação pessoal ou número de identificação fiscal do utilizador. Por exemplo, `123456789`.", "example": "123456789", "x-readme-id": "1.7" }, "ip_address": { "type": "string", "description": "Endereço IP previsto para a sessão, no formato IPv4 ou IPv6. Se o endereço IP real diferir deste valor, será registado um aviso. Por exemplo, `192.168.1.100` ou `2001:db8::1`.", "example": "192.168.1.100", "x-readme-id": "1.8" }, "expected_document_types": { "type": "array", "description": "Restringe os tipos de documento que o utilizador pode apresentar durante o passo de verificação de identidade (OCR). Quando definido, o ecrã de seleção de documentos apresenta apenas os tipos solicitados e o `documents_allowed` retornado é filtrado em conformidade. Os valores não diferenciam maiúsculas de minúsculas e são deduplicados; valores desconhecidos são rejeitados com `400`. Códigos permitidos: `P` (passaporte), `ID` (documento de identificação nacional), `DL` (carta de condução), `RP` (título de residência), `HIC` (cartão de saúde), `TC` (cartão fiscal), `SSC` (cartão de segurança social).", "items": { "type": "string", "enum": [ "P", "ID", "DL", "RP", "HIC", "TC", "SSC" ] }, "example": [ "P", "ID" ], "x-readme-id": "1.9" }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome legal esperado da empresa que está a ser verificada. Por exemplo, `Tesco PLC`. Pré-preenche o campo do nome da empresa na pesquisa no registo de empresas em fluxos de Verificação de empresas (KYB); quando `registration_number` também é fornecido, a pesquisa no registo combina ambos os identificadores. Ignorado para fluxos de KYC.", "example": "Tesco PLC", "x-readme-id": "1.10" }, "registry_country": { "type": "string", "maxLength": 10, "description": "Código ISO 3166-1 alpha-2 do país em cujo registo de empresas a empresa está registada. Por exemplo, `GB`. Onde os registos de empresas operam a nível estadual ou provincial, anexe o código de subdivisão ISO 3166-2 como `XX-YY`: `US-CA` visa o registo da Califórnia. Mesmo formato que `country_code` na [KYB Registry Search API](https://docs.didit.me/pt/standalone-apis/kyb-registry-search). Pré-seleciona o país do registo nos fluxos de Verificação de empresas (KYB); ignorado em fluxos de KYC.", "example": "US-CA", "x-readme-id": "1.11" }, "registration_number": { "type": "string", "maxLength": 100, "description": "Número de registo esperado da empresa no registo de empresas. Por exemplo, `00445790`. Pré-preenche o campo do número de registo da pesquisa no registo de empresas em fluxos de Verificação de empresas (KYB); quando `company_name` também é fornecido, a pesquisa no registo de empresas combina ambos os identificadores. Ignorado para fluxos de KYC.", "example": "00445790", "x-readme-id": "1.12" } }, "x-readme-id": "0.5" }, "portrait_image": { "type": "string", "format": "byte", "description": "Imagem de retrato do rosto do utilizador final codificada em base64 (máx. 2MB; JPEG, PNG, WebP ou TIFF). Usada como imagem de referência para comparar com a captura de prova de vida quando o fluxo é um fluxo de `Biometric Authentication` com a Correspondência facial ativada, ou qualquer fluxo em grafo onde a Correspondência facial seja executada antes da Verificação de identidade (OCR). Opcional quando o utilizador em `vendor_data` já possui uma imagem de rosto guardada: a Didit reutiliza-a automaticamente, resolvida pela seguinte ordem de prioridade: rosto de prova de vida aprovado, fotografia do chip de ePassport, retrato do documento de identificação, rosto de perfil registado manualmente (apenas rostos de sessões aprovadas ou rostos registados por si são reutilizados). Quando fornecida, `portrait_image` tem sempre precedência sobre o rosto guardado. Se for omitida e não existir nenhum rosto guardado (ou `vendor_data` não for enviado), a criação da sessão falha com `400`. Ignorado para outros tipos de fluxo.", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "x-readme-id": "0.6" }, "sandbox_scenario": { "type": "string", "description": "Slug de cenário exclusivo da sandbox. Só é aceite quando a chave de API pertence a uma aplicação em modo sandbox; é rejeitado em aplicações de produção. Quando definido, o fluxo de criação expande os valores mágicos incluídos no cenário para os campos de entrada da sessão (contact_details, expected_details) para que os fornecedores simulados reproduzam o resultado do cenário através do pipeline real do fluxo. Consulte o catálogo de cenários em GET /v1/sandbox/scenarios/ ou [Sandbox e dados de teste](/pt/integration/sandbox-testing). Também pode armar (ou rearmar) um cenário após a criação através de POST /v3/session/{sessionId}/sandbox/arm/, desde que a sessão ainda esteja em `Not Started`. Para pesquisas que não sejam de documentos, utilize `lookup_partial_match`, `lookup_no_match` ou `lookup_provider_error` para testar o orçamento de tentativas configurado e o fallback. Para carteiras de identidade, utilize `wallet_cancelled`, `wallet_timeout` ou `wallet_provider_error`; `approve` simula uma carteira verificada. Todas as carteiras do catálogo podem ser testadas na sandbox, incluindo esquemas indisponíveis em aplicações de produção. As tentativas simuladas não são cobradas.", "example": "decline_document_expired" }, "sign": { "type": "object", "description": "Entrada de Assinatura eletrónica para esta sessão. `documents` são os documentos a assinar, para um fluxo cujo passo de Assinatura eletrónica obtém documentos da sessão (`signature_documents_source` como `session` ou `both`): até 20 documentos e 50 MB no total. `field_values` preenche os campos cujo `prefill` seja `api.`, tanto em documentos do fluxo como da sessão. Criar novamente uma sessã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 têm de ser idênticos aos primeiros, e qualquer diferença devolve `400` com `{\"sign\": \"signature_document_changed\"}`. Consulte [Documentos de assinatura eletrónica](/pt/sessions-api/create-session#documentos-de-assinatura-eletrónica).", "properties": { "documents": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/SessionSignDocument" } }, "field_values": { "type": "object", "description": "Valores indexados pela `` de cada fonte de pré-preenchimento `api.`: strings de 1 a 500 carateres para campos `text` e `data`, booleanos para um `checkbox`. `400` com `field_value_unknown` para uma chave que nenhum campo utiliza, `field_value_missing` para um campo obrigatório sem o respetivo valor e `field_value_invalid` para um valor que falhe a validação do respetivo campo.", "additionalProperties": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "boolean" } ] }, "example": { "credit_limit": "3,000 EUR" } } } }, "user_state": { "type": "string", "maxLength": 16, "description": "Onde a pessoa reside, quando for do seu conhecimento: 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 legislação exija consentimento biométrico explícito (Illinois, Texas, Colorado) faz com que o fluxo de verificação o solicite antes de capturar um rosto, com o acionador `declared_state`. Um valor não reconhecido devolve `400`. Consulte [Consentimento biométrico](/pt/getting-started/biometric-consent).", "example": "US-IL" }, "biometric_consent": { "type": "object", "description": "Consentimento biométrico explícito que já recolheu da pessoa. Cumpre o requisito, pelo que o fluxo de verificação não volta a pedir, e a decisão regista-o como `status: \"given\"` com o acionador `customer_collected`. Uma resposta que a pessoa já tenha dado no fluxo nunca é substituída. Consulte [Consentimento biométrico](/pt/getting-started/biometric-consent).", "required": [ "given_at", "text_version" ], "properties": { "given_at": { "type": "string", "format": "date-time", "description": "Quando a pessoa deu consentimento biométrico explícito (ISO 8601). Não pode ser no futuro." }, "text_version": { "type": "string", "maxLength": 64, "description": "ID da versão do texto de consentimento que a pessoa aceitou, nos seus próprios registos." } } } }, "example": { "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" ] } } }, "examples": { "Create KYC session": { "summary": "Payload completo de caso de sucesso para uma sessão de Verificação de utilizadores (KYC)", "description": "Chamada de criação realista que utiliza todos os campos habitualmente definidos: seleção de fluxo, associação a fornecedor, encaminhamento de retorno, metadados, idioma/região, pré-preenchimento de contacto e dados esperados do utilizador. Copie e cole diretamente no exemplo cURL acima.", "value": { "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" ] } } }, "Create KYB session": { "summary": "Payload do cenário ideal para uma sessão de Verificação de empresas (KYB)", "description": "O mesmo formato da chamada KYC — o `workflow_id` é o que torna a sessão KYB. `vendor_data` referencia habitualmente a empresa no seu sistema e `contact_details.email` destina-se ao representante legal que concluirá o fluxo. `expected_details` aceita os campos da empresa (`company_name`, `registry_country`, `registration_number`), que pré-preenchem a pesquisa no registo de empresas; os campos ao nível da pessoa e `contact_details.phone` são ignorados em fluxos KYB.", "value": { "workflow_id": "33333333-4444-5555-6666-777777777777", "vendor_data": "company-acme-001", "callback": "https://example.com/kyb/callback", "callback_method": "both", "metadata": { "tier": "enterprise", "company_id": "ACME-001" }, "expected_details": { "company_name": "Tesco PLC", "registry_country": "GB", "registration_number": "00445790" }, "language": "en", "contact_details": { "email": "legal-rep@acme.example.com", "send_notification_emails": true, "email_lang": "en" } } } } } } } } }, "/v3/session/imports/": { "post": { "summary": "Criar uma tarefa de importação de verificação", "description": "Cria um trabalho de importação assíncrono para sessões históricas de Verificação de utilizadores, sessões de Verificação de empresas (KYB), registos de monitorização de transações ou regras de estado personalizado de fluxos. Defina `source=provider` para migrar a partir de outro fornecedor: a Didit lê Sumsub, Onfido, Persona e ComplyCube com a sua chave só de leitura, lê registos da Veriff, iDenfy e MetaMap através dos IDs que enviar em `file`, e importa um ficheiro de exportação no formato da Didit para os restantes fornecedores. Os IDs dos registos utilizam espaços de nomes por fornecedor (`sumsub:`) para que uma nova execução ignore tudo o que já se encontra na Didit, e um registo importado através de um ficheiro apenas com o ID do fornecedor também é reconhecido, em ambas as direções, para que a alternância entre a importação por ficheiro e a migração por fornecedor nunca importe um registo duas vezes. Uma aplicação pode executar até 4 trabalhos de importação em simultâneo; um trabalho interrompido por uma implementação ou pelo reinício de um processo de trabalho continua autonomamente a partir da última linha importada. As importações estão desativadas por predefinição e têm de ser ativadas por organização pela Didit.", "operationId": "post_v3_session_imports_create", "x-didit-sdk": { "resource": "sessions.imports", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification", "description": "O que importar: sessões históricas de Verificação de utilizadores, sessões históricas de Verificação de empresas, regras de estado personalizadas do fluxo ou registos históricos de monitorização de transações." }, "workflow_id": { "type": "string", "format": "uuid", "description": "UUID do fluxo ao qual as sessões importadas ou as regras de estado devem ser associadas. Obrigatório para user_verification, business_verification e status_rules. Omitir para transações." }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ], "description": "Opcional. Deduzido da extensão do ficheiro carregado quando omitido." }, "file": { "type": "string", "format": "binary", "description": "Ficheiro canónico CSV ou NDJSON. Utilize NDJSON para importações grandes. Tamanho máximo de carregamento de 25 MB (utilize `source_file_url` para ficheiros maiores). Mutuamente exclusivo com `source_file_url`." }, "source_file_url": { "type": "string", "format": "uri", "description": "Alternativa ao carregamento de ficheiro. Deve ser um URL HTTPS que resolva para um endereço público (redes privadas/loopback são rejeitadas). Mutuamente exclusivo com `file`." }, "source": { "type": "string", "enum": [ "file", "provider" ], "description": "`provider` torna isto uma migração a partir de outro fornecedor de verificação de identidade. Omita para uma importação de ficheiro." }, "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "Origem da migração, de `GET /v3/session/imports/providers/`. Obrigatório quando `source` é `provider`." }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A chave apenas de leitura do fornecedor, com os nomes de campos listados por `credential_fields`. Encriptada em repouso, nunca devolvida e apagada quando a importação termina. Envie-a como uma string JSON em multipart." }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "A região do fornecedor, uma das suas `regions` (Onfido: `eu`, `us`, `ca`)." } } }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "Edições ao mapeamento de estado predefinido do fornecedor: estado de origem para estado da Didit. `Not Finished` e `Abandoned` são ignorados e contabilizados, nunca importados." }, "dry_run": { "type": "boolean", "default": false, "description": "Conta o que a migração importaria (por estado, já no Didit, mesma pessoa, não finalizada) e não grava nada. A tarefa termina em `READY`; inicie-a com `POST /v3/session/imports/{importId}/start/`." }, "face_templates": { "type": "boolean", "default": false, "description": "Cria modelos faciais a partir das selfies importadas e pesquisa-os nos rostos e na lista de bloqueio da aplicação. As correspondências são sinalizadas apenas para revisão. Requer `lawful_basis_confirmed`." }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "Confirma que tem uma base legal para partilhar estas selfies com a Didit na qualidade de subcontratante." } } } }, "application/json": { "schema": { "type": "object", "required": [ "source_file_url" ], "properties": { "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification", "description": "O que importar: sessões históricas de Verificação de utilizadores, sessões históricas de Verificação de empresas, regras de estado personalizadas do fluxo ou registos históricos de monitorização de transações." }, "workflow_id": { "type": "string", "format": "uuid", "description": "UUID do fluxo ao qual as sessões importadas ou as regras de estado devem ser associadas. Obrigatório para user_verification, business_verification e status_rules. Omitir para transações." }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ], "description": "Opcional. Deduzido da extensão de ficheiro do URL quando omitido." }, "source_file_url": { "type": "string", "format": "uri", "description": "Alternativa ao carregamento de ficheiro. Deve ser um URL HTTPS que resolva para um endereço público (redes privadas/loopback são rejeitadas). Mutuamente exclusivo com `file`." }, "source": { "type": "string", "enum": [ "file", "provider" ], "description": "`provider` torna isto uma migração a partir de outro fornecedor de verificação de identidade. Omita para uma importação de ficheiro." }, "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "Origem da migração, de `GET /v3/session/imports/providers/`. Obrigatório quando `source` é `provider`." }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A chave apenas de leitura do fornecedor, com os nomes de campos listados por `credential_fields`. Encriptada em repouso, nunca devolvida e apagada quando a importação termina. Envie-a como uma string JSON em multipart." }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "A região do fornecedor, uma das suas `regions` (Onfido: `eu`, `us`, `ca`)." } } }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "Edições ao mapeamento de estado predefinido do fornecedor: estado de origem para estado da Didit. `Not Finished` e `Abandoned` são ignorados e contabilizados, nunca importados." }, "dry_run": { "type": "boolean", "default": false, "description": "Conta o que a migração importaria (por estado, já no Didit, mesma pessoa, não finalizada) e não grava nada. A tarefa termina em `READY`; inicie-a com `POST /v3/session/imports/{importId}/start/`." }, "face_templates": { "type": "boolean", "default": false, "description": "Cria modelos faciais a partir das selfies importadas e pesquisa-os nos rostos e na lista de bloqueio da aplicação. As correspondências são sinalizadas apenas para revisão. Requer `lawful_basis_confirmed`." }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "Confirma que tem uma base legal para partilhar estas selfies com a Didit na qualidade de subcontratante." } } }, "examples": { "URL-based import": { "value": { "import_type": "user_verification", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "source_file_url": "https://files.example.com/exports/sessions.ndjson" } } } } } }, "responses": { "201": { "description": "Tarefa de importação aceite. Consulte periodicamente o `uuid` devolvido até que `status` seja `COMPLETED` ou `FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" }, "examples": { "Job accepted": { "value": { "uuid": "3f9c1a2b-4d5e-4f60-8a7b-9c0d1e2f3a4b", "status": "PENDING", "import_type": "user_verification", "source_format": "ndjson", "source_filename": "sessions.ndjson", "total_rows": 0, "processed_rows": 0, "checkpoint_row": 0, "created_count": 0, "updated_count": 0, "skipped_count": 0, "failed_count": 0, "total_media_bytes": 0, "last_error": null, "created_at": "2026-05-17T08:42:11Z", "updated_at": "2026-05-17T08:42:11Z", "started_at": null, "completed_at": null } } } } } }, "400": { "description": "Fluxo, tipo de ficheiro, tamanho de ficheiro, URL de origem ou combinação de seletores inválidos. Uma migração cuja chave seja recusada pelo fornecedor devolve `code` (`invalid_credentials`, `missing_permission`, `wrong_region`, `provider_unavailable`, `rate_limited`, `ids_required`, `record_not_found`), `missing_permissions` e `suggested_region`.", "content": { "application/json": { "examples": { "Invalid workflow": { "value": { "workflow_id": [ "Invalid workflow_id." ] } }, "Workflow required": { "value": { "workflow_id": [ "This field is required for this import type." ] } }, "Wrong file type": { "value": { "file": [ "Only CSV and NDJSON files are supported." ] } }, "File too large": { "value": { "file": [ "Import file exceeds the maximum allowed size." ] } }, "No source": { "value": { "file": [ "Upload a file or provide source_file_url." ] } }, "Both sources": { "value": { "file": [ "Use either file or source_file_url, not both." ] } } } } } }, "403": { "description": "Importações não ativadas, aplicação de sandbox ou chave de API em falta (uma chave errada, revogada ou expirada recebe `401`). As importações de verificação estão desativadas por predefinição e têm de ser ativadas pela Didit para cada organização.", "content": { "application/json": { "examples": { "Imports not enabled": { "value": { "detail": "Verification imports are not enabled for this organization." } }, "Sandbox": { "value": { "detail": "Verification imports are not enabled for sandbox applications." } }, "Bad API key": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "A aplicação já tem 4 tarefas de importação ativas (PENDING/PROCESSING/PAUSED), o máximo que pode executar em simultâneo. Aguarde que uma termine antes de iniciar outra.", "content": { "application/json": { "examples": { "Active job": { "value": { "detail": "This application already has 4 active import jobs, the most it can run at once. Wait for one to finish before starting another." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.create(\n import_type=\"user_verification\",\n workflow_id=\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url=\"https://files.example.com/exports/sessions.ndjson\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.create({\n import_type: \"user_verification\",\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url: \"https://files.example.com/exports/sessions.ndjson\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Create(ctx, didit.SessionsImportsCreateParams{\n\tImportType: didit.Some(didit.SessionsImportsCreateParamsImportType(\"user_verification\")),\n\tWorkflowID: didit.String(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\"),\n\tSourceFileURL: didit.String(\"https://files.example.com/exports/sessions.ndjson\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsImportsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().create(SessionsImportsCreateParams.builder()\n .importType(SessionsImportsCreateParams.ImportType.of(\"user_verification\"))\n .workflowId(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\")\n .sourceFileUrl(\"https://files.example.com/exports/sessions.ndjson\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->create([\n 'import_type' => 'user_verification',\n 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab',\n 'source_file_url' => 'https://files.example.com/exports/sessions.ndjson',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.create(\n import_type: \"user_verification\",\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url: \"https://files.example.com/exports/sessions.ndjson\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CreateAsync(new SessionsImportsCreateParams\n{\n ImportType = new SessionsImportsCreateParamsImportType(\"user_verification\"),\n WorkflowId = \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n SourceFileUrl = \"https://files.example.com/exports/sessions.ndjson\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/template/": { "get": { "summary": "Descarregar modelo de importação de verificação", "description": "Descarregue o cabeçalho CSV canónico para importações de verificação. O conjunto de colunas é determinado por `import_type`. A primeira coluna dos modelos de sessão é a chave de idempotência `external_id`.", "operationId": "get_v3_session_imports_template", "x-didit-sdk": { "resource": "sessions.imports", "method": "retrieve_template", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "import_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification" } } ], "responses": { "200": { "description": "Ficheiro de modelo CSV.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode descarregar modelos de importação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Chave de API em falta, inválida ou revogada", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.imports.retrieve_template()\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.imports.retrieveTemplate();\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Imports.RetrieveTemplate(ctx, didit.SessionsImportsRetrieveTemplateParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().imports().retrieveTemplate()\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retrieveTemplate();\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.imports.retrieve_template\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Imports.RetrieveTemplateAsync();\nawait content.SaveToAsync(\"download.csv\");" } ] } }, "/v3/session/imports/{importId}/": { "get": { "summary": "Obter uma tarefa de importação de verificações", "description": "Obtenha os contadores de progresso da importação e o estado terminal de uma tarefa. Faça polling até que o `status` seja `COMPLETED` ou `FAILED`; `failed_count` > 0 significa que algumas linhas foram rejeitadas — liste-as através do endpoint de erros.", "operationId": "get_v3_session_imports_retrieve", "x-didit-sdk": { "resource": "sessions.imports", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Estado da tarefa de importação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "404": { "description": "Tarefa de importação não encontrada para esta aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode ler tarefas de importação para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Chave de API em falta, inválida ou revogada", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/errors/": { "get": { "summary": "Listar erros de linha de importação de verificação", "description": "Listar erros ao nível da linha para uma tarefa de importação de verificações, ordenados por `row_number`. Utilize este endpoint para gerar um ficheiro corrigido para nova tentativa que contenha apenas as linhas que falharam.", "operationId": "get_v3_session_imports_errors", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_errors", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Tamanho da página. A predefinição é 50 quando omitido." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Offset de base zero do primeiro registo a devolver." } ], "responses": { "200": { "description": "Erros de linha paginados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número de linhas com erro — exato até 100, limitado a 100 acima disso. Confie no facto de `next` ser `null` para detetar a última página." }, "next": { "type": "string", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SessionImportError" } } } }, "examples": { "Row errors": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "row_number": 17, "external_id": "ext-000017", "error": "status: invalid value 'unknown_status'", "raw_row": { "external_id": "ext-000017", "status": "unknown_status", "first_name": "Jane" }, "created_at": "2026-05-17T08:44:02Z" } ] } } } } } }, "404": { "description": "Tarefa de importação não encontrada para esta aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode ler tarefas de importação para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Chave de API em falta, inválida ou revogada", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.imports.list_errors(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.imports.listErrors(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.Imports.ListErrorsAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsListErrorsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().imports().listErrors(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listErrors('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.imports.list_errors(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.Imports.ListErrorsAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/decision/": { "get": { "summary": "Obter a decisão completa para uma sessão de verificação", "description": "Obtenha o relatório de decisão completo para uma sessão de verificação — o `status` consolidado da sessão mais um relatório por funcionalidade de verificação que o fluxo executou. Este é o endpoint canónico de leitura para sessões de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB): o mesmo caminho serve ambas, e o discriminador de nível superior `session_kind` indica que estrutura recebeu (`\"user\"` ou `\"business\"`).\n\n**Cada relatório de funcionalidade é um array no plural.** Os fluxos V3 são grafos que podem executar a mesma funcionalidade mais do que uma vez, pelo que cada bloco (`id_verifications`, `nfc_verifications`, `liveness_checks`, `face_matches`, `poa_verifications`, `document_ai_documents`, `phone_verifications`, `email_verifications`, `aml_screenings`, `ip_analyses`, `database_validations`, `questionnaire_responses`) é um array JSON cujos itens contêm, cada um, um `node_id` que identifica o nó do grafo do fluxo que os gerou. Leia o NFC como `response.nfc_verifications[0]` — nunca como um campo `nfc` no singular. Um bloco é `null` até que o fluxo tenha executado essa funcionalidade pelo menos uma vez; as funcionalidades que o fluxo não inclui nunca aparecem com dados. Os resultados da Assinatura eletrónica estão em `signatures`, que só está presente quando o fluxo tem um passo de Assinatura eletrónica.\n\n**Quando chamar.** O padrão recomendado é orientado a eventos: aguarde pelo webhook `status.updated` emitido quando a sessão atinge uma decisão (`Approved`, `Declined`, `In Review`) e, em seguida, chame este endpoint uma vez para obter o relatório completo. O polling também funciona — o endpoint pode ser chamado em qualquer ponto do ciclo de vida da sessão e devolve os dados gerados até ao momento —, mas a abordagem de webhook seguido de obtenção é mais económica e rápida. Os URLs de multimédia na resposta (imagens de documentos, vídeos, PDFs) são ligações pré-assinadas de curta duração: obtenha-os prontamente ou volte a pedir a decisão para obter novos URLs, e não os persista como referências de longo prazo.\n\n**Estados.** O `status` de nível superior é o estado do ciclo de vida da sessão (`Not Started`, `In Progress`, `Awaiting User`, `In Review`, `Approved`, `Declined`, `Resubmitted`, `Expired`, `Kyc Expired`, `Abandoned`). Cada item de funcionalidade contém adicionalmente o seu próprio `status` ao nível da funcionalidade (`Not Finished`, `Approved`, `Declined`, `In Review`, ...). Uma sessão pode estar globalmente `Approved` enquanto uma funcionalidade individual está `In Review`, dependendo das regras de decisão do fluxo.\n\n**Autenticação e visibilidade.** Autentique-se com a chave de API da aplicação no cabeçalho `x-api-key` (um token Bearer de utilizador da consola com a permissão `read:sessions` também funciona). Apenas as sessões que pertencem à aplicação autenticada estão visíveis. Se o seu fluxo restringir atributos de resposta, os campos não permitidos dentro dos itens de funcionalidade são devolvidos como `null`, enquanto `status`, `warnings` e `node_id` são sempre preservados.\n\n**Limites de pedidos.** Os pedidos GET estão limitados a 600 por minuto por chave de API. Exceder o limite devolve `429` com os cabeçalhos `Retry-After` e `X-RateLimit-*`.", "operationId": "get_v3_session_decision", "x-didit-sdk": { "resource": "sessions", "method": "retrieve_decision", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "Relatório completo de decisão. `session_kind` distingue as duas estruturas: sessões `user` contêm os arrays de funcionalidades de KYC apresentados abaixo; sessões `business` contêm, em vez disso, `registry_checks`, `document_verifications` e `key_people_checks` juntamente com os arrays partilhados. Os arrays de funcionalidades são `null` até que o fluxo tenha executado essa funcionalidade; os URLs dos ficheiros multimédia são ligações pré-assinadas de curta duração.", "content": { "application/json": { "examples": { "Example": { "summary": "Exemplo completo", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "session_kind": "user", "session_number": 43762, "session_url": "https://verify.didit.me/session/11111111-2222-3333-4444-555555555555", "status": "In Review", "environment": "live", "workflow_id": "11111111-2222-3333-4444-555555555555", "features": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACE_MATCH", "POA", "PHONE", "DATABASE_VALIDATION", "AML", "IP_ANALYSIS" ], "vendor_data": "11111111-1111-1111-1111-111111111111", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "expected_details": { "first_name": "Carmen", "last_name": "Española Española" }, "contact_details": { "email": "carmen@example.com", "email_lang": "es", "send_notification_emails": false, "phone": null }, "callback": "https://verify.didit.me/", "id_verifications": [ { "node_id": "feature_ocr_1", "status": "Approved", "document_type": "Identity Card", "document_subtype": "ID_CARD_GENERIC", "document_number": "CAA000000", "personal_number": "99999999R", "portrait_image": "https:///portrait.jpg", "front_image": "https:///front.jpg", "front_video": "https:///front.mp4", "back_image": "https:///back.jpg", "back_video": "https:///back.mp4", "full_front_image": "https:///full_front.jpg", "full_back_image": "https:///full_back.jpg", "front_image_camera_front": "https:///front_camera_front.jpg", "back_image_camera_front": "https:///back_camera_front.jpg", "date_of_birth": "1980-01-01", "age": 45, "expiration_date": "2031-06-02", "date_of_issue": "2021-06-02", "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Carmen", "last_name": "Española Española", "full_name": "Carmen Española Española", "gender": "F", "address": "Avda de Madrid 34, Madrid, Madrid", "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain", "place_of_birth": "Madrid", "marital_status": "Single", "nationality": "ESP", "extra_fields": { "dl_categories": [], "blood_group": null }, "mrz": { "surname": "ESPANOLA ESPANOLA", "name": "CARMEN", "country": "ESP", "nationality": "ESP", "birth_date": "800101", "expiry_date": "310602", "sex": "F", "document_type": "ID", "document_number": "CAA000000", "optional_data": "99999999R", "optional_data_2": "", "birth_date_hash": "4", "expiry_date_hash": "8", "document_number_hash": "4", "final_hash": "1", "personal_number": "99999999R", "warnings": [], "errors": [], "mrz_type": "TD1", "mrz_string": "IDESPCAA000000499999999R<<<<<<\n8001014F3106028ESP<<<<<<<<<<<1\nESPANOLA/match_face.jpg", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null, "source": "session" } ], "front_image_quality_score": { "focus_score": 85.3, "brightness_score": 92.1, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 72.4, "overall_score": 88.7 }, "back_image_quality_score": { "focus_score": 79.1, "brightness_score": 90.5, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 72.4, "overall_score": 85.2 }, "extra_files": [ "https:///extra_id_verification.jpg" ], "matches": [ { "session_id": "7d4f1f60-9c2e-4b8a-8f3d-2a1b5c6d7e8f", "session_number": 1234, "vendor_data": "user_ref_001", "verification_date": "2024-06-15T10:30:00Z", "user_details": { "name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Approved", "is_blocklisted": false, "api_service": null, "front_image_url": "https:///document_front.jpg" }, { "session_id": "b2c8e4d1-6a3f-4e7b-95c0-1d8f2a6b4c9e", "session_number": 1235, "vendor_data": null, "verification_date": "2024-05-20T14:45:00Z", "user_details": { "name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Declined", "is_blocklisted": true, "api_service": "ID_VERIFICATION", "front_image_url": "https:///document_front_2.jpg" } ], "warnings": [ { "feature": "ID_VERIFICATION", "risk": "QR_NOT_DETECTED", "additional_data": null, "log_type": "information", "short_description": "QR not detected", "long_description": "The system couldn't find or read the QR code on the document, which is necessary for document verification. This could be due to poor image quality or an unsupported document type.", "node_id": "feature_ocr_1" } ], "verification_method": "document", "assurance": "documentary", "wallet_provider": null, "fallback_from": null, "id_lookup": null, "wallet_verification": null, "document_liveness": { "portrait_replace": { "score": 96.46, "front": 96.46, "back": 98.2, "decline_threshold": 35, "review_threshold": 70, "bucket": "approve" }, "printed_copy": { "score": 91.2, "front": 91.2, "back": 93.7, "decline_threshold": 35, "review_threshold": 77, "bucket": "approve" }, "screen_replay": { "score": 99.9, "front": 99.9, "back": 99.5, "decline_threshold": 30, "review_threshold": 70, "bucket": "approve" } } }, { "node_id": "feature_ocr_2", "status": "Approved", "issuing_state": "ZAF", "issuing_state_name": "South Africa", "first_name": "Thabo", "last_name": "Mokoena", "full_name": "Thabo Mokoena", "date_of_birth": "1991-06-15", "personal_number": "9106155043088", "verification_method": "id_lookup", "assurance": "data_match", "wallet_provider": null, "fallback_from": null, "id_lookup": { "source": "Department of Home Affairs", "checked_at": "2026-09-04T09:12:44Z", "attempts": 1, "max_attempts": 2, "outcome": "match", "comparison": [ { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" }, { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" }, { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" } ], "registry_portrait": "https:///registry_portrait.jpg", "face_match_score": 96.4, "source_errors": [] }, "wallet_verification": null, "warnings": [] }, { "node_id": "feature_ocr_3", "status": "Approved", "issuing_state": "DNK", "issuing_state_name": "Denmark", "first_name": "Freja", "last_name": "Nielsen", "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "verification_method": "wallet", "assurance": "cryptographic", "wallet_provider": "mitid", "fallback_from": null, "id_lookup": null, "wallet_verification": { "provider": "mitid", "provider_name": "MitID", "issuing_authority": "Danish Agency for Digital Government", "issuing_country": "DNK", "credential_type": "person_identification", "level_of_assurance": "substantial", "verified_at": "2026-09-04T09:12:44Z", "signature_valid": true, "attributes": { "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678" }, "portrait": null, "face_match_score": null }, "warnings": [] } ], "nfc_verifications": [ { "node_id": "feature_nfc_1", "status": "In Review", "is_nfc_skipped": false, "skip_reason": null, "chip_protocol": "icao", "jpki": null, "portrait_image": "https:///portrait.jpg", "signature_image": "https:///signature.jpg", "chip_data": { "document_type": "ID", "issuing_country": "ESP", "document_number": "123456789", "expiration_date": "2030-01-01", "first_name": "John", "last_name": "Smith", "birth_date": "1990-05-15", "gender": "M", "nationality": "ESP", "address": "CALLE MAYOR 123 4B, MADRID, MADRID", "place_of_birth": "MADRID, MADRID" }, "authenticity": { "sod_integrity": true, "dg_integrity": true }, "certificate_summary": { "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES", "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES", "serial_number": "118120836164494130086420187336801405660", "not_valid_after": "2031-02-18 10:21:11", "not_valid_before": "2020-11-18 10:21:11" }, "warnings": [ { "feature": "NFC", "risk": "DATA_INCONSISTENT", "additional_data": null, "log_type": "warning", "short_description": "OCR and NFC mrz code extracted are not the same", "long_description": "The Optical Character Recognition (OCR) data and the NFC chip data don't match, indicating potential document tampering or data inconsistency.", "node_id": "feature_nfc_1" } ] } ], "liveness_checks": [ { "node_id": "feature_liveness_1", "status": "Approved", "method": "ACTIVE_3D", "score": 89.92, "reference_image": "https:///reference.jpg", "video_url": "https:///video.mp4", "age_estimation": 24.3, "matches": [ { "session_id": "7d4f1f60-9c2e-4b8a-8f3d-2a1b5c6d7e8f", "session_number": 1234, "vendor_data": "user_ref_001", "verification_date": "2024-06-15T10:30:00Z", "user_details": { "full_name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null, "source": "session", "match_image_url": "https:///face_match.jpg", "similarity_percentage": 98.5 }, { "session_id": "3e9a7c21-5b48-4f0e-9c6a-8d2f4b1e0a35", "session_number": 1100, "vendor_data": "customer_xyz", "verification_date": "2024-04-10T09:15:00Z", "user_details": { "full_name": "John Smith", "document_type": "P", "document_number": "DZ8375806" }, "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": "PASSIVE_LIVENESS", "source": "session", "match_image_url": "https:///face_match_2.jpg", "similarity_percentage": 95.2 } ], "warnings": [ { "feature": "LIVENESS", "risk": "LOW_LIVENESS_SCORE", "additional_data": null, "log_type": "information", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.", "node_id": "feature_liveness_1" } ], "face_quality": null, "face_luminance": null } ], "face_matches": [ { "node_id": "feature_face_match_1", "status": "In Review", "score": 65.43, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "LOW_FACE_MATCH_SIMILARITY", "additional_data": null, "log_type": "warning", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.", "node_id": "feature_face_match_1" } ] } ], "phone_verifications": [ { "node_id": "feature_phone_1", "status": "Approved", "phone_number_prefix": "+34", "phone_number": "600600600", "full_number": "+34600600600", "country_code": "ES", "country_name": "Spain", "carrier": { "name": "Orange", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "sms", "verification_attempts": 1, "verified_at": "2024-07-28T06:47:35.654321Z", "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-08-24T09:12:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" }, "fee": 0.1 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-08-24T09:12:39.662157+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2025-08-24T09:12:39.684292+00:00", "details": null, "fee": 0 } ], "warnings": [], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "phone_number": "+34600000000", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ] } ], "email_verifications": [ { "node_id": "feature_email_1", "status": "Approved", "email": "test@example.com", "is_breached": true, "breaches": [ { "name": "TAPAirPortugal", "domain": "flytap.com", "logo_path": "https://logos.example.com/TAPAirPortugal.png", "breach_date": "2022-08-25", "description": "In August 2022, the Portuguese airline TAP Air Portugal was the target of a ransomware attack perpetrated by the Ragnar Locker gang who later leaked the compromised data via a public dark web site. Over 5M unique email addresses were exposed alongside other personal data including names, genders, DoBs, phone numbers and physical addresses.", "is_verified": true, "data_classes": [ "dates_of_birth", "email_addresses", "genders", "names", "nationalities", "phone_numbers", "physical_addresses", "salutations", "spoken_languages" ], "breach_emails_count": 6083479 } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2025-09-15T17:36:19.963451Z", "warnings": [ { "feature": "EMAIL", "risk": "BREACHED_EMAIL_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Breached email detected", "long_description": "This email address was found in one or more known data breaches.", "node_id": "feature_email_1" } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-09-15T17:36:19.792684+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-09-15T17:36:19.963427+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_DECLINED", "timestamp": "2025-09-15T17:36:20.081471+00:00", "details": { "reason": "BREACHED_EMAIL_DETECTED" }, "fee": 0 } ], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "email": "test@example.com", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ] } ], "poa_verifications": [ { "node_id": "feature_poa_1", "status": "Declined", "document_file": "https:///poa_document.pdf", "issuing_state": "AR", "document_type": "UTILITY_BILL", "document_subtype": null, "document_language": "es", "document_metadata": { "file_size": 1000, "content_type": "application/pdf", "creation_date": "2021-01-01", "modified_date": "2021-01-01", "overlay_manipulation": null, "creator": null, "producer": "PDF Generator", "software": null, "encryption": null, "is_signed": false, "is_tampered": false, "signature_info": null, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": true }, "issuer": "Aguas del Norte", "issue_date": "2021-02-01", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 3396, SALTA", "poa_formatted_address": "Av. Monseñor Tavella 3396, A4400 Salta, Argentina", "poa_parsed_address": { "address_type": "Avenida", "street_1": "Avenida Monseñor Tavella 3396", "street_2": null, "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208664, "longitude": -65.4131 } }, "name_on_document": "Fernando De Lima", "name_match_score_expected_details": null, "name_match_score_id_verification": 38.5, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": {}, "extra_fields": { "bank_account_number": "1234567890", "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": "+5491112345678", "additional_names": [] }, "extra_files": [ "https:///extra_poa.pdf" ], "detected_codes": [ { "type": "QR_CODE", "page_number": 1, "position": [ [ 820, 1120 ], [ 1002, 1120 ], [ 1002, 1302 ], [ 820, 1302 ] ], "x": 820, "y": 1120, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==", "parsed_payload": "https://aguasdelnorte.com/factura/998811" }, { "type": "CODE_128", "page_number": 1, "position": [ [ 112, 1480 ], [ 560, 1480 ], [ 560, 1540 ], [ 112, 1540 ] ], "x": 112, "y": 1480, "width": 448, "height": 60, "page_width": 1190, "page_height": 1684, "raw_payload": "MDA5OTg4MTEwMDA0Mg==", "parsed_payload": "0099881100042" } ], "warnings": [] } ], "document_ai_documents": [ { "status": "Approved", "node_id": "feature_document_ai_1", "items": [ { "uuid": "c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071", "node_id": "feature_document_ai_1", "document_key": "proof_of_funds", "original_filename": "bank_statement.pdf", "file_size": 184320, "file_url": "https:///document_ai/proof_of_funds.pdf", "status": "Approved", "extracted_data": { "account_holder": "John Doe", "balance": 15230.55, "currency": "EUR", "statement_date": "2026-05-31" }, "detected_codes": [ { "type": "QR_CODE", "page_number": 2, "position": [ [ 124, 86 ], [ 306, 86 ], [ 306, 268 ], [ 124, 268 ] ], "x": 124, "y": 86, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "SU5WLTIwMjYtMDA0Mg==", "parsed_payload": "INV-2026-0042" } ], "fields": [ { "key": "account_holder", "name": "Account holder", "instruction": "Extract the full name of the account holder.", "type": "text", "required": true }, { "key": "balance", "name": "Closing balance", "instruction": "Extract the closing balance amount.", "type": "number", "required": true } ], "document_metadata": { "is_tampered": false }, "cross_check_result": null, "created_at": "2026-06-01T12:34:56Z" } ], "warnings": [] } ], "questionnaire_responses": [ { "node_id": "feature_questionnaire_1", "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213", "title": "Source of Funds", "description": "Reply to this questionnaire to help us understand the source of funds.", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60", "version": 1, "published_at": "2025-11-02T09:14:55.000000Z", "sections": [ { "title": null, "description": null, "items": [ { "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db", "value": "question_1", "element_type": "DROPDOWN", "is_required": true, "title": "What is your primary source of funds?", "description": null, "placeholder": null, "choices": [ { "label": "Salary", "value": "salary" }, { "label": "Business Income", "value": "business_income" }, { "label": "Savings", "value": "savings" }, { "label": "Investments", "value": "investments" }, { "label": "Sale of Asset", "value": "sale_of_asset" }, { "label": "Inheritance/Gift", "value": "inheritance_gift" }, { "label": "Pension", "value": "pension" }, { "label": "Crypto Proceeds", "value": "crypto_proceeds" }, { "label": "Other", "value": "other", "requires_text_input": true } ], "max_files": 1, "answer": { "value": "salary" }, "required_if": null, "repeatable_config": null }, { "uuid": "2d16b527-72be-42e0-8e96-b164b818386c", "value": "question_2", "element_type": "LONG_TEXT", "is_required": true, "title": "Provide details of the primary source.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "a9239b7c-fbfb-4ea7-b7e4-c835cd4016e0", "value": "question_3", "element_type": "DROPDOWN", "is_required": true, "title": "What is your annual income range (pre-tax)?", "description": null, "placeholder": null, "choices": [ { "label": "Less than $25,000", "value": "<25k" }, { "label": "$25,000 - $50,000", "value": "25k-50k" }, { "label": "$50,001 - $100,000", "value": "50k-100k" }, { "label": "$100,001 - $250,000", "value": "100k-250k" }, { "label": "More than $250,000", "value": ">250k" } ], "max_files": 1, "answer": { "value": "<25k" }, "required_if": null, "repeatable_config": null }, { "uuid": "93dede62-6d0c-4a7f-934d-42175eb94011", "value": "question_4", "element_type": "DROPDOWN", "is_required": true, "title": "What is your approximate net worth (range)?", "description": null, "placeholder": null, "choices": [ { "label": "Less than $50,000", "value": "<50k" }, { "label": "$50,000 - $250,000", "value": "50k-250k" }, { "label": "$250,001 - $1,000,000", "value": "250k-1m" }, { "label": "$1,000,001 - $5,000,000", "value": "1m-5m" }, { "label": "More than $5,000,000", "value": ">5m" } ], "max_files": 1, "answer": { "value": "<50k" }, "required_if": null, "repeatable_config": null }, { "uuid": "2af60d6f-6961-4692-9ee7-24b3033610a6", "value": "question_5", "element_type": "LONG_TEXT", "is_required": true, "title": "For your initial deposit/funding, indicate the exact source and amount.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "0ad9d1aa-736f-46cf-947b-9e1241b53e40", "value": "question_6", "element_type": "LONG_TEXT", "is_required": true, "title": "Breakdown of sources by percentage.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "1bf8a2a3-14ee-48a8-bb3d-175481aae4aa", "value": "question_7", "element_type": "SINGLE_CHOICE", "is_required": true, "title": "Will any funds originate from third parties? If yes, please provide details.", "description": null, "placeholder": null, "choices": [ { "label": "Yes", "value": "yes", "requires_text_input": true }, { "label": "No", "value": "no" } ], "max_files": 1, "answer": { "text": "Additional details", "value": "yes" }, "required_if": null, "repeatable_config": null }, { "uuid": "e18d4dd3-b7bf-4883-ba18-d6046adbe313", "value": "question_8", "element_type": "SINGLE_CHOICE", "is_required": true, "title": "Do you hold or plan to use virtual assets (e.g., crypto) to fund this account? If yes, please provide details.", "description": null, "placeholder": null, "choices": [ { "label": "Yes", "value": "yes", "requires_text_input": true }, { "label": "No", "value": "no" } ], "max_files": 1, "answer": { "text": "Additional details", "value": "yes" }, "required_if": null, "repeatable_config": null }, { "uuid": "a90a073d-e098-404c-bbce-5130d8b12a13", "value": "question_9", "element_type": "FILE_UPLOAD", "is_required": true, "title": "Upload a proof of funds document", "description": "You can upload your three (3) most recent bank statements, three (3) most recent payslips, your most recent tax return, proof of company ownership, trading exchange statement, sale of property, or proof of inheritance.", "placeholder": null, "choices": null, "max_files": 3, "answer": { "files": [ "/media/ocr/", "/media/ocr/" ] }, "required_if": null, "repeatable_config": null }, { "uuid": "9503b486-7cb8-4c3b-a97d-4b64926a5a47", "value": "question_10", "element_type": "LONG_TEXT", "is_required": false, "title": "Would you like to add any details to help us expedite our review of the documents you submitted?", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null } ] } ], "status": "Approved" } ], "aml_screenings": [ { "node_id": "feature_aml_1", "status": "In Review", "total_hits": 1, "entity_type": "person", "hits": [ { "id": "hit_7c1e9a40b2d35f86e0a4c912", "url": "https://news.example.org/articles/sample", "match": false, "score": 0.73, "target": null, "caption": "Javier Ejemplo Modelo", "datasets": [ "PEP" ], "features": null, "rca_name": "", "last_seen": "2025-06-13T00:00:00", "risk_view": { "crimes": { "score": 0, "weightage": 20, "risk_level": "Low", "risk_scores": {} }, "countries": { "score": 0, "weightage": 30, "risk_level": "Low", "risk_scores": {} }, "categories": { "score": 100, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100 } }, "custom_list": {} }, "first_seen": "2025-01-18T00:00:00", "properties": { "name": [ "Javier Ejemplo Modelo" ], "alias": [ "Javier Ejemplo Modelo", "David Azagra" ], "notes": [ "Spanish orchestra conductor" ], "title": null, "gender": [ "male" ], "height": null, "topics": null, "weight": null, "address": null, "country": null, "website": null, "eyeColor": null, "keywords": null, "lastName": [ "Ejemplo", "Modelo" ], "position": null, "religion": null, "birthDate": [ "1974" ], "education": [ "Tokyo Arts and Space (2012-2012)", "Saint Petersburg Conservatory (-2010)", "Comillas Pontifical University" ], "ethnicity": null, "firstName": [ "David" ], "hairColor": null, "weakAlias": null, "birthPlace": [ "Madrid" ], "modifiedAt": null, "wikidataId": null, "citizenship": null, "nationality": null }, "match_score": 98, "risk_score": 73, "review_status": "Unreviewed", "score_breakdown": { "name_score": 95, "name_weight": 60, "name_weight_normalized": 70.59, "name_contribution": 67.06, "dob_score": 100, "dob_weight": 25, "dob_weight_normalized": 29.41, "dob_contribution": 29.41, "country_score": 0, "country_weight": 15, "country_weight_normalized": 0, "country_contribution": 0, "document_number_match_type": "NEUTRAL", "document_number_effect": "No document number provided for screening", "total_score": 98 }, "pep_matches": [ { "aliases": [ "Javier Ejemplo Modelo", "David Azagra" ], "education": [ "Tokyo Arts and Space (2012-2012)", "Saint Petersburg Conservatory (-2010)", "Comillas Pontifical University" ], "list_name": "Wikidata", "publisher": "Wikidata", "source_url": "https://news.example.org/articles/sample", "description": "Wikidata is the structured data project of the Wikipedia community, providing fact-based information edited by humans and machines", "matched_name": "Javier Ejemplo Modelo", "pep_position": "", "date_of_birth": "1974", "other_sources": [], "place_of_birth": "Madrid" } ], "linked_entities": [ { "name": [ "Antonio Ejemplo" ], "active": [], "status": [], "details": [], "relation": [] } ], "warning_matches": [], "sanction_matches": [], "adverse_media_details": { "sentiment": "Moderately Negative", "entity_type": "person", "sentiment_score": -2, "adverse_keywords": { "fraud": 3, "juicio": 1, "delitos": 2, "imputado": 1, "impunidad": 1, "corruption": 2, "favoritism": 2, "privilegio": 1, "corrupción": 1, "persecution": 2, "desconfianza": 1, "desprestigio": 1, "fraude de ley": 2, "manipulación": 1, "investigación": 3, "prevaricación": 8, "trato de favor": 1, "irregularidades": 2, "crisis de confianza": 1, "tráfico de influencias": 8 } }, "adverse_media_matches": [ { "country": "spain", "summary": "Javier Ejemplo is implicated in legal violations related to favoritism and influence trafficking, leading to a negative portrayal in the article.", "headline": "La Diputación de Villaejemplo consolida la plaza a medida para el ex asesor de Moncloa amigo del \"hermanito\" de Ejemplo", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "prevaricación", "tráfico de influencias", "irregularidades", "imputado" ], "sentiment_score": -2, "publication_date": "2025-06-10T20:46:38" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in legal issues regarding favoritism and corruption, leading to a negative portrayal in the article.", "headline": "La Diputación de Villaejemplo consolida la plaza a medida para el ex asesor de Moncloa amigo del \"hermanito\" de Ejemplo", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "prevaricación", "tráfico de influencias", "irregularidades", "trato de favor" ], "sentiment_score": -2, "publication_date": "2025-06-10T20:46:38" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is mentioned in connection with Carlos Ficticio's corruption case, indicating his involvement in alleged influence peddling.", "headline": "España, paraíso del aforado", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "corrupción", "impunidad", "privilegio", "desconfianza", "manipulación", "fraude de ley" ], "sentiment_score": -2, "publication_date": "2025-06-10T05:05:34" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, which raises questions about his conduct and political ethics.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación", "juicio", "fraude de ley", "desprestigio", "crisis de confianza", "delitos" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:01:00" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a legal investigation regarding irregularities in his hiring, which raises serious concerns about his conduct.", "headline": "La jueza del 'caso Javier Ejemplo' denuncia un «fraude de ley» en el aforamiento de Ficticio (Partido Ejemplo)", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "irregularities", "prevaricación", "tráfico de influencias" ], "sentiment_score": -2, "publication_date": "2025-06-09T10:19:10" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is mentioned in connection with legal allegations of corruption, contributing to a negative perception.", "headline": "'Caso aforamiento': la letrada mayor de la Asamblea certifica a la juez que Ficticio es diputado desde antes de prometer su cargo en el Pleno", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias" ], "sentiment_score": -2, "publication_date": "2025-06-09T08:08:30" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, raising concerns about political corruption and influence.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:01:00" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, which raises concerns about political misconduct.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación", "delitos" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:00:59" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a case of favoritism and corruption, which casts a negative light on his character and actions.", "headline": "'Caso Javier Ejemplo': las asociaciones judiciales salen en defensa de la juez Luisa Inventada ante las \"presiones externas\" que sufre", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "favoritism", "corruption", "persecution" ], "sentiment_score": -2, "publication_date": "2025-06-06T10:08:15" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a case of alleged favoritism and corruption, which casts a negative light on his character and actions.", "headline": "'Caso Javier Ejemplo': las asociaciones judiciales salen en defensa de la juez Luisa Inventada ante las \"presiones externas\" que sufre", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "favoritism", "corruption", "persecution" ], "sentiment_score": -2, "publication_date": "2025-06-06T08:08:15" } ], "additional_information": {} } ], "score": 80, "screened_data": { "full_name": "Javier Ejemplo Modelo", "nationality": "ES", "date_of_birth": "1974-01-01", "document_number": null }, "is_ongoing_monitoring_enabled": true, "next_ongoing_monitoring_bill_date": "2026-07-24", "last_ongoing_screening_at": "2026-09-12T04:03:11Z", "last_ongoing_screening_datasets_updated_at": "2026-09-11T06:00:00Z", "warnings": [ { "feature": "AML", "risk": "POSSIBLE_MATCH_FOUND", "additional_data": null, "log_type": "warning", "short_description": "Possible match found in AML screening", "long_description": "The Anti-Money Laundering (AML) screening process identified potential matches with watchlists or high-risk databases, requiring further review.", "node_id": "feature_aml_1" } ] } ], "ip_analyses": [ { "node_id": "feature_ip_1", "status": "Approved", "device_brand": "Apple", "device_model": "iPhone", "browser_family": "Mobile Safari", "os_family": "iOS", "platform": "mobile", "device_fingerprint": "didit-fp-a1b2c3d4e5f6g7h8", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Barcelona", "ip_city": "Barcelona", "latitude": 41.4022, "longitude": 2.1407, "ip_address": "83.50.226.71", "isp": null, "organization": null, "is_vpn_or_tor": false, "is_data_center": false, "time_zone": "Europe/Madrid", "time_zone_offset": "+0100", "ip": { "location": { "latitude": 40.2206327, "longitude": 1.5770097 }, "distance_from_id_document": 23.4, "distance_from_poa_document": 12.3 }, "id_document": { "location": { "latitude": 41.2706327, "longitude": 1.9770097 }, "distance_from_ip": 23.4, "distance_from_poa_document": 18.7 }, "poa_document": { "location": { "latitude": 41.2706327, "longitude": 1.9770097 }, "distance_from_ip": 12.3, "distance_from_id_document": 18.7 }, "warnings": [], "matches": [ { "session_id": "99999999-8888-7777-6666-555555555555", "session_number": 41205, "vendor_data": "22222222-2222-2222-2222-222222222222", "verification_date": "2024-07-20T10:15:30Z", "match_type": "ip_address", "match_source": "ip_address", "matched_value": "83.50.226.71", "status": "Approved", "is_blocklisted": false, "api_service": null, "source": "session", "device_info": { "device_brand": "Apple", "device_model": "iPhone", "browser_family": "Mobile Safari", "os_family": "iOS", "platform": "mobile", "device_fingerprint": "didit-fp-f9e8d7c6b5a40312" }, "location_info": { "ip_address": "83.50.226.71", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Barcelona", "ip_city": "Barcelona", "is_vpn_or_tor": false, "is_data_center": false }, "confidence": 0.0, "match_mode": "co_occurrence" }, { "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_number": 42830, "vendor_data": "33333333-3333-3333-3333-333333333333", "verification_date": "2024-06-30T18:22:05Z", "match_type": "device_fingerprint", "match_source": "recovered_high", "matched_value": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "Declined", "is_blocklisted": false, "api_service": null, "source": "session", "device_info": { "device_brand": "Samsung", "device_model": "SM-G991B", "browser_family": "Chrome Mobile", "os_family": "Android", "platform": "mobile", "device_fingerprint": null }, "location_info": { "ip_address": "83.50.231.18", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Madrid", "ip_city": "Madrid", "is_vpn_or_tor": false, "is_data_center": false }, "confidence": 1.0, "match_mode": "deterministic", "recovery_similarity": 0.9874, "tls_ja4_corroborated": true, "recovery_gate_reason": "hardware_root_match" } ] } ], "database_validations": [ { "node_id": "feature_db_validation_1", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "last_name": "De Lima", "first_name": "Fernando", "tax_number": "01234567890", "date_of_birth": "1980-01-01", "document_type": "ID", "expiration_date": "2030-01-01" }, "validations": [ { "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "outcome_code": "MATCH", "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "source_data": { "identification_number": "01234567890", "first_name": "FERNANDO", "last_name": "DE LIMA", "date_of_birth": "1980-01-01", "gender": "M", "nationality": "BRA" } } ], "match_type": "full_match", "status": "Approved", "warnings": [] } ], "reviews": [ { "user": "compliance@example.com", "new_status": "Declined", "comment": "Possible match found in AML screening", "created_at": "2024-07-18T13:29:00.366811Z" } ], "created_at": "2024-07-24T08:54:25.443172Z", "expires_at": "2025-07-24T08:54:25.443172Z", "biometric_consent": { "required": false, "trigger": null, "status": "not_required", "given_at": null, "declined_at": null, "text_version": null, "text_hash": null, "locale": null, "policy_url": null, "step": null, "node_id": null, "ip_address": null, "ip_country_code": null, "ip_state": null, "ip_city": null, "user_agent": null, "detected_ip_address": "83.50.226.71", "detected_country_code": "ES", "detected_state": "ES-B", "detected_city": "Barcelona", "declared_state": null, "document_state": null, "jurisdictions": [], "retention_months": null, "reason": null, "decline_reason": null, "face_data_deleted_at": null } } }, "BusinessExample": { "summary": "Exemplo de sessão de empresa (KYB)", "description": "Uma decisão de `session_kind = \"business\"`: as sessões de KYB substituem os arrays de funcionalidades de KYC por `registry_checks`, `document_verifications` e `key_people_checks`, partilhando simultaneamente `aml_screenings`, `phone_verifications`, `email_verifications`, `questionnaire_responses`, `ip_analyses`, `reviews` e o envelope da sessão.", "value": { "session_id": "66666666-7777-8888-9999-000000000000", "session_kind": "business", "session_number": 31415, "session_url": "https://verify.didit.me/session/business123", "status": "In Review", "environment": "live", "workflow_id": "abababab-cdcd-efef-0101-232323232323", "features": [ "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE" ], "vendor_data": "merchant-001234", "metadata": null, "callback": "https://example.com/verification/callback", "registry_checks": [ { "status": "Approved", "node_id": "feature_kyb_registry_1", "data_resolved": true, "company": { "uuid": "dddd4444-eeee-5555-ffff-666677778888", "node_id": "feature_kyb_registry_1", "status": "Approved", "registry_status": "active", "data_resolved": true, "company_name": "ACME HOLDINGS LTD", "registration_number": "12345678", "country_code": "GB", "region": null, "company_type": "Private Limited Company", "incorporation_date": "2015-03-12", "registered_address": "1 Example Street, London, EC1A 1AA", "tax_number": null, "risk_level": null, "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": null, "nature_of_business": "62012 - Business and domestic software development", "registered_capital": "100 GBP", "registered_capital_amount": "100.00", "registered_capital_currency": "GBP", "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": "England and Wales", "financial_summary": null, "officers": [ { "uuid": "aaaa1111-bbbb-2222-cccc-333344445555", "name": "Jane Smith", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/session/abc123def456" } ], "beneficial_owners": [ { "uuid": "bbbb2222-cccc-3333-dddd-444455556666", "name": "John Doe", "first_name": "John", "last_name": "Doe", "entity_type": "person", "roles": [ "ubo", "shareholder" ], "ownership_min_shares": "50", "ownership_max_shares": "75", "is_active": true, "kyc_status": "Pending", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "effective_ownership_percent": 75.0 } ], "addresses": [ { "type": "registered", "address": "1 Example Street, London, EC1A 1AA", "country": "GB" } ], "industries": [ { "code": "62012", "description": "Business and domestic software development" } ], "accounts": null, "registry_data": {}, "user_provided_data": { "company_name": "ACME HOLDINGS", "registration_number": "12345678" }, "confirmed_by_user_at": "2026-06-10T12:01:30.000000Z", "last_console_edit_at": null, "is_editable": false }, "ownership_structure": { "shareholders": [ { "name": "John Doe", "first_name": "John", "last_name": "Doe", "date_of_birth": null, "country_of_birth": null, "company_name": null, "registration_number": null, "entity_type": "person", "nationality": null, "designation": null, "roles": [ "shareholder" ], "ownership_min_shares": "75", "ownership_max_shares": "75", "voting_min_shares": null, "voting_max_shares": null, "appointment_date": null, "is_active": true, "shareholding": { "share_class": "ORDINARY", "number_of_shares": 750.0, "currency": "GBP", "nominal_value": 1.0, "total_value": null, "percentage": 75.0 } } ], "beneficial_owners": [] }, "warnings": [] } ], "aml_screenings": null, "document_verifications": [ { "status": "In Review", "node_id": "feature_kyb_documents_1", "items": [ { "uuid": "eeee5555-ffff-6666-0000-777788889999", "document_type": "LEGAL_PRESENCE", "document_subtype": "CERTIFICATE_OF_INCORPORATION", "document_group": "LEGAL_PRESENCE", "file_url": "https:///kyb/certificate-of-incorporation.pdf", "original_filename": "certificate_of_incorporation.pdf", "file_size": 482133, "status": "Approved", "created_at": "2026-06-10T12:03:11.000000Z", "cross_check_result": { "critical": { "company_name": { "document": "ACME HOLDINGS LTD", "registry": "ACME HOLDINGS LTD", "score": 1.0, "match": true }, "registration_number": { "document": "12345678", "registry": "12345678", "match": true } }, "non_critical": {}, "people": {} }, "document_metadata": { "file_size": 482133, "content_type": "application/pdf", "creation_date": "2015-03-12T09:00:00", "modified_date": "2015-03-12T09:00:00", "creator": null, "producer": null, "software": null, "encryption": null, "is_signed": true, "is_tampered": false, "signature_info": null, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": false, "overlay_manipulation": null }, "description": null, "is_requested": false, "ocr_data": { "company_name": "ACME HOLDINGS LTD", "registration_number": "12345678", "incorporation_date": "2015-03-12" }, "is_console_upload": false, "is_confirmed": true }, { "uuid": "ffff6666-0000-7777-1111-888899990000", "document_type": "OWNERSHIP_STRUCTURE", "document_subtype": null, "document_group": "OWNERSHIP_STRUCTURE", "file_url": null, "original_filename": null, "file_size": null, "status": "Not Finished", "created_at": "2026-06-10T15:40:02.000000Z", "cross_check_result": null, "document_metadata": null, "description": "Please upload an up-to-date shareholder registry", "is_requested": true, "ocr_data": null, "is_console_upload": false, "is_confirmed": true } ], "groups": { "LEGAL_PRESENCE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }, "OWNERSHIP_STRUCTURE": { "total": 1, "approved": 0, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 1 } }, "required_groups": [ "LEGAL_PRESENCE", "OWNERSHIP_STRUCTURE" ], "warnings": [] } ], "key_people_checks": [ { "status": "In Review", "node_id": "feature_kyb_key_people_1", "registry": { "officers": [ { "uuid": "aaaa1111-bbbb-2222-cccc-333344445555", "name": "Jane Smith", "designation": "Director", "role": "director", "nationality": "British", "appointment_date": "2015-03-12", "termination_date": null, "is_active": true, "address": "1 Example Street, London, EC1A 1AA", "aml_status": "Approved", "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/session/abc123def456", "kyc_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "didit_internal_id": "99999999-0000-1111-2222-333333333333", "kyc_document_type": "P", "kyc_nationality": "GBR", "kyc_liveness_passed": true, "kyc_verified_at": "2026-06-10T14:22:31.123456Z", "kyc_aml_categories": { "sanctions": "clear", "pep": "clear", "adverse_media": "clear", "warnings": "clear" }, "kyc_notification_sent_at": "2026-06-09T09:00:00.000000Z" } ], "beneficial_owners": [ { "uuid": "bbbb2222-cccc-3333-dddd-444455556666", "name": "John Doe", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-05-04", "country_of_birth": null, "email": null, "company_name": null, "registration_number": null, "entity_type": "person", "nationality": "British", "designation": null, "roles": [ "ubo", "shareholder" ], "ownership_min_shares": "50", "ownership_max_shares": "75", "is_active": true, "aml_status": null, "kyc_status": "In Progress", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "kyc_session_id": "88888888-9999-aaaa-bbbb-cccccccccccc", "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null, "kyc_document_type": null, "kyc_nationality": null, "kyc_liveness_passed": null, "kyc_verified_at": null, "kyc_aml_categories": null, "kyc_notification_sent_at": null, "child_beneficial_owners": [], "effective_ownership_percent": 75.0 } ] }, "submitted": { "parties": [ { "uuid": "cccc3333-dddd-4444-eeee-555566667777", "entity_type": "person", "source": "USER", "name": "John Doe", "first_name": "John", "last_name": "Doe", "company_name": null, "registration_number": null, "email": "john.doe@example.com", "nationality": "GBR", "phone_number": "+447700900123", "date_of_birth": "1980-05-04", "position": "Chief Executive Officer", "custom_fields": {}, "is_active": true, "is_skipped": false, "requires_verification": true, "roles": [ { "role": "ubo", "ownership_percent": 75.0, "voting_percent": 75.0 }, { "role": "director", "ownership_percent": null, "voting_percent": null } ], "kyc_session_id": "88888888-9999-aaaa-bbbb-cccccccccccc", "kyc_session_status": "In Progress", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "kyb_sub_session_id": null, "kyb_sub_session_status": null, "kyb_sub_session_url": null, "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null } ] }, "ubo_kyc_summary": { "total": 1, "approved": 0, "flagged": 0, "pending": 1 }, "warnings": [] } ], "phone_verifications": null, "email_verifications": null, "questionnaire_responses": null, "ip_analyses": null, "reviews": [], "contact_details": null, "expected_details": { "company_name": "Tesco PLC", "registry_country": "GB", "registration_number": "00445790" }, "created_at": "2026-06-10T11:58:04.000000Z", "expires_at": "2026-06-24T11:58:04.000000Z" } } }, "schema": { "$ref": "#/components/schemas/SessionDecision" } } } }, "403": { "description": "Falha na autenticação ou autorização. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`. Duas cadeias de carateres em `detail` distinguem os modos de falha:\n\n- `\"Authentication credentials were not provided or are invalid.\"` — nenhum cabeçalho `x-api-key` (e nenhum token `Authorization: Bearer`), ou a credencial fornecida falhou a introspeção (revogada, expirada ou mal formatada).\n- `\"You do not have permission to perform this action.\"` — a credencial é válida, mas não tem permissão para ler esta sessão: um token Bearer de um utilizador da consola carece da permissão `read:sessions` ou não consegue aceder à aplicação proprietária, ou uma chave de API pertence a uma organização diferente da sessão.\n\nTenha em atenção que, para um `sessionId` completamente desconhecido, o endpoint resolve a aplicação proprietária antes de validar as credenciais; logo, uma sessão em falta devolve `404` mesmo quando a credencial está em falta ou é inválida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Authentication credentials were not provided or are invalid." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a introspeção", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permissions": { "summary": "Credencial válida sem read:sessions ou sem acesso à aplicação à qual pertence", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Sessão não encontrada. Retornado quando nenhuma sessão ativa corresponde ao `sessionId` fornecido como uma sessão de Verificação de utilizadores (KYC) ou de Verificação de empresas (KYB) — uma sessão que tenha sido eliminada também vai parar aqui. O corpo é o invólucro padrão `{\"detail\": ...}`.\n\n**Duas strings `detail` distintas.** Se o `sessionId` for desconhecido tanto como sessão KYC como KYB, a pesquisa de proprietário pré-autenticação falha e recebe `{\"detail\": \"Not found.\"}` — isto acontece antes da validação de credenciais, pelo que é retornado mesmo para chamadas não autenticadas. Se a sessão existir mas não puder ser obtida sob a aplicação autenticada (por exemplo, um registo obsoleto ou acabado de eliminar), a vista retorna `{\"detail\": \"Session not found.\"}`. Ambas indicam o mesmo resultado — a sessão não está acessível — portanto, compare pelo código de estado `404` em vez da string.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Not found." } } }, "examples": { "Unknown session id": { "summary": "sessionId é desconhecido para esta aplicação", "value": { "detail": "Not found." } }, "Session not retrievable": { "summary": "A sessão existe, mas não pode ser obtida para esta aplicação", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. Os pedidos GET estão limitados a **600 por minuto por credencial** (chave de API, token Bearer ou IP de origem quando não autenticado). Inspecione `Retry-After` / `X-RateLimit-Reset` e aguarde antes de tentar novamente. Se atingir este limite enquanto faz polling por decisões, mude para o webhook `status.updated` e obtenha a decisão uma vez por alteração de estado.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente o pedido.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Número máximo de pedidos permitidos na janela atual (600 para pedidos GET).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Carimbo de data/hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Explicação legível da violação do limite de pedidos.", "example": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } }, "examples": { "Throttled": { "summary": "Mais de 600 pedidos GET num minuto a partir da mesma credencial", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação cuja decisão pretende obter. Este é o `session_id` retornado por `POST /v3/session/`. O mesmo caminho funciona para sessões de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB) — o servidor resolve o ID em ambos os tipos de sessão.\n\n**Deve ser um UUID válido.** A rota apenas faz correspondência com UUIDs bem formatados, pelo que um valor mal formatado é rejeitado pelo router de URL antes da execução de qualquer código da aplicação e a resposta é uma página **HTML** de `404` em vez do envelope JSON `{\"detail\": ...}` apresentado abaixo. Valide o formato do UUID no lado do cliente para que possa distinguir um erro de introdução de dados de um verdadeiro `404` de sessão em falta.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "include", "in": "query", "required": false, "description": "Lista separada por vírgulas de secções adicionais do payload. Valores suportados: `events` e `resubmissions`, isolados ou em conjunto (`events,resubmissions`). Quando `include=events` é transmitido, a resposta contém adicionalmente a cronologia de eventos da sessão (`events`, incluindo os eventos de encaminhamento `WORKFLOW_BRANCH_EVALUATED` / `WORKFLOW_STATUS_NODE_REACHED` descritos na página Obter sessão), o registo de atividade completo (`activity_reviews`), indicadores de lista de bloqueio (`blocklisted`), um `cost_breakdown` por sessão, metadados do fluxo (`workflow_type`, `workflow_version`, `workflow_version_id` e `workflow_terminal_node_id` - o último nó de estado do fluxo registado que definiu um estado de sessão, ou `null` se nenhum tiver sido registado; proveniência histórica que não é limpa por aprovações manuais, recusas ou novos envios, sendo substituída por um nó de estado do fluxo posterior) e metadados da sessão (`api_service` — string ou `null`, definido apenas para sessões de API autónoma; `session_type` — `API`, `HOSTED` ou `MIGRATED`; `has_device_nfc_support` — booleano). Dois campos mudam em relação à estrutura simples: o discriminador `session_kind` de nível superior é **omitido** (a estrutura de eventos existe apenas para sessões de utilizador) e o array `features` passa de strings simples para objetos `{feature, node_id}` — onde a funcionalidade de e-mail é comunicada como `EMAIL` em vez de `EMAIL_VERIFICATION`. Esta estrutura expandida é utilizada principalmente pela consola da Didit; a maioria das integrações de API deve omitir o parâmetro. **Limitação de KYB:** `include=events` aplica-se apenas a sessões de utilizador (KYC). As sessões de empresas (`session_kind = \"business\"`) devolvem sempre a estrutura normal de decisão de empresa — `events`, `activity_reviews`, `blocklisted`, `cost_breakdown` e os metadados adicionais de `workflow_*`/sessão nunca são devolvidos para sessões de empresas, e o respetivo array `features` permanece um array simples de strings. Com `include=resubmissions` (tanto em sessões de utilizador como de empresas), a resposta também contém `resubmissions`: uma entrada por pedido de novo envio, do mais antigo para o mais recente, cada uma com `number`, `created_at`, `previous_status`, `nodes`, `reasons`, `requested_by` e `results` (o que os passos reenviados devolveram antes do pedido, sob as mesmas chaves e com a mesma estrutura dos resultados atuais). Cada item de `cost_breakdown` contém `usage_type`, `price`, `details` e `created_at`: um passo reenviado que seja executado novamente é faturado como um novo item.", "schema": { "type": "string", "enum": [ "events", "resubmissions", "events,resubmissions" ], "example": "events" } } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/decision/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Accept: application/json'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.retrieve_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.retrieveDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RetrieveDecision(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsRetrieveDecisionParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().retrieveDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->retrieveDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.retrieve_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RetrieveDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/delete/": { "delete": { "summary": "Eliminar uma sessão de verificação (KYC ou KYB)", "description": "Elimine uma única sessão de verificação, Verificação de utilizadores (KYC) ou Verificação de empresas (KYB), através do respetivo `session_id`. O id é resolvido primeiro em relação a sessões de KYC e, em seguida, a sessões de KYB, pelo que ambos os tipos são eliminados através deste único URL.\n\n**O que é eliminado:**\n- A sessão e todas as tentativas de verificação que esta contém, incluindo os resultados substituídos por um novo envio: a decisão, os dados extraídos, todos os registos de funcionalidades relacionados (verificação de identidade, rosto, prova de vida, correspondência facial, AML, verificações de registos, análise de IP, entre outros), as suas revisões e o respetivo registo de atividade.\n- Todos os ficheiros armazenados pertencentes à sessão: fotografias da frente/verso do documento (versões completas, recortadas e com desfocagem para privacidade), vídeos de captura de documentos, recortes de retrato, imagens de retrato e de assinatura do chip NFC, imagens de referência facial, vídeos de prova de vida, imagens de origem/destino de correspondência facial, documentos de Comprovativo de morada e quaisquer ficheiros adicionais carregados (KYC); documentos da empresa carregados e ficheiros adicionais (KYB). Documentos de Assinatura eletrónica, PDFs assinados, PDFs de prova e imagens de assinatura (KYC e KYB): os respetivos caminhos de transferência deixam de funcionar. URLs de multimédia emitidos anteriormente (`https:///...`) deixam de resolver.\n- Os dados faciais da sessão. O respetivo embedding facial também é eliminado, a menos que opte por manter um template sem imagem (consulte **Dados biométricos faciais**).\n- Envios de webhooks ainda em fila para a sessão e as respetivas tentativas de repetição. Os webhooks já entregues não são afetados.\n- Para uma sessão de Verificação de empresas (KYB): as verificações criadas para as suas pessoas-chave (KYC) e para as suas empresas proprietárias (KYB), de forma recursiva, comunicadas como `deleted_child_verifications`. Uma verificação à qual apenas esteja associada, como um KYC aprovado existente que tenha reutilizado, não é eliminada.\n\nA sessão desaparece imediatamente de todos os endpoints de leitura: `GET /v3/session/{sessionId}/decision/` devolve `404` e `GET /v3/sessions/` deixa de a listar. A monitorização AML contínua e a monitorização de registos de KYB iniciadas pelas verificações eliminadas são interrompidas.\n\n**O que não é afetado:** as entradas na lista de bloqueio criadas a partir desta sessão (rosto ou documento) **não** são removidas; faça a gestão das mesmas com os endpoints da lista de bloqueio. Os tokens de partilha emitidos para a sessão não são revogados, mas já não existe nada para importarem: uma importação com um deles devolve `400` com `{\"share_token\": [\"Original session does not exist.\"]}`. Os créditos já consumidos **não** são reembolsados. A entidade Utilizador ou Empresa-mãe **não** é eliminada; utilize `POST /v3/users/delete/` ou `POST /v3/businesses/delete/` para esse efeito. Se o retrato de perfil do Utilizador tiver tido origem nesta sessão, o retrato é removido juntamente com ela.\n\n**Dados biométricos faciais:** por predefinição, o embedding facial da sessão é eliminado juntamente com a sessão (`face_retention_outcome: deleted`). Uma aplicação que tenha optado pela retenção de templates biométricos (`face_retention_policy: retain_until_user_deleted` no `PATCH /v3/webhook/`), ou um pedido com `retain_face_embeddings: true`, mantém um template biométrico facial sem imagem, gerido separadamente e associado ao Utilizador da sessão (`retained_with_user`), para que a deteção de duplicados, a Pesquisa facial e a autenticação biométrica continuem a funcionar. O template nunca contém a imagem facial, multimédia, campos de identidade, a decisão ou o id da sessão eliminada; trata-se de dados biométricos eliminados em `biometric_template_expires_at`, ou antes disso em caso de eliminação do Utilizador, eliminação por motivos de privacidade ou uma purga explícita através de `/v3/biometric-templates/`. Uma sessão sem um Utilizador associado não pode reter um template (`ineligible_no_vendor_user`). Envie `deletion_instruction: privacy_erasure` para pedidos de titulares de dados: isto purga todos os templates retidos para esse Utilizador e nunca retém um novo.\n\n**Irreversível:** a eliminação é permanente e não existe nenhum endpoint de restauro. Exporte tudo o que precisar (por exemplo, um PDF da decisão) antes de chamar o endpoint.\n\n**Efeitos secundários:** nenhum webhook é emitido para eliminações.\n\n**Resposta:** `200 OK` assim que a eliminação estiver concluída, com um corpo JSON que reporta o `face_retention_outcome`, a expiração do template retido e, para uma sessão de KYB, `deleted_child_verifications`. Versões anteriores deste endpoint devolviam `204 No Content`; atualize os clientes que validam o código `204`. Mantenha o seu `instruction_id` no seu próprio registo de eliminações.\n\n**Idempotência:** não é idempotente ao nível do HTTP: a primeira chamada devolve `200`; repeti-la devolve `404` porque a sessão já não resolve. Após um `503`, a sessão continua ativa; repita o mesmo pedido para concluir a respetiva eliminação.\n\n**Autenticação:** envie a chave de API da sua aplicação no cabeçalho `x-api-key`; a sessão tem de pertencer a essa aplicação. Os tokens de acesso de utilizadores da consola (`Authorization: Bearer ...`) também podem chamar este endpoint se tiverem a permissão `delete:sessions`. As falhas de autenticação e de permissão devolvem ambas `403`; esta API nunca devolve `401`.\n\n**Limite de pedidos:** quota de escrita partilhada de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; exceder este valor devolve `429`.\n\nPara eliminar sessões de KYC em massa através do respetivo `session_number` numérico, utilize `POST /v3/sessions/delete/`.\n\n**Relatórios regulamentares submetidos:** se os dados selecionados constarem de um relatório regulamentar finalizado, todo o pedido é recusado com `409` e nada é eliminado. O corpo utiliza `code: in_filed_report` e identifica cada relatório com `uuid`, `report_number`, `report_type` e `case_uuid`. Elimine os relatórios e, em seguida, repita o pedido.", "operationId": "delete_v3_session_by_id", "x-didit-sdk": { "resource": "sessions", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID (`session_id`) da sessão de Verificação de utilizadores (KYC) ou de Verificação de empresas (KYB) a eliminar, conforme retornado aquando da criação da sessão. Tem de ser um UUID canónico com hífenes — um valor que não seja UUID não corresponde à rota e devolve `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "responses": { "200": { "description": "Sessão eliminada. O corpo indica o que aconteceu aos dados biométricos faciais da sessão e, para uma sessão KYB, quantas verificações criadas por esta foram eliminadas em conjunto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "A sessão eliminada." }, "session_number": { "type": "integer", "nullable": true, "description": "O número da sessão eliminada." }, "face_retention_outcome": { "type": "string", "enum": [ "retained_with_user", "deleted", "none", "ineligible_no_vendor_user" ], "description": "O que aconteceu aos dados biométricos faciais da sessão. `deleted`: o embedding facial foi eliminado com a sessão (predefinição). `retained_with_user`: a sessão é eliminada e um template biométrico sem imagem permanece associado ao Utilizador; consulte `biometric_template_uuid`. `none`: a sessão não tinha nenhum embedding facial (por exemplo, uma sessão de KYB ou uma sessão de KYC sem selfie de prova de vida). `ineligible_no_vendor_user`: a conservação foi solicitada, mas a sessão não tem nenhum Utilizador associado, pelo que o embedding foi eliminado com a sessão. Uma falha no armazenamento biométrico nunca é comunicada através deste campo neste endpoint: devolve `503` e a sessão não é eliminada." }, "biometric_template_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "ID do template biométrico retido quando `face_retention_outcome` é `retained_with_user`; `null` caso contrário. Faça a sua gestão através de `/v3/biometric-templates/{template_uuid}/`." }, "biometric_template_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o template biométrico retido é eliminado, quando `face_retention_outcome` é `retained_with_user`; `null` quando nenhum template é retido." }, "deleted_child_verifications": { "type": "integer", "description": "Para uma sessão de Verificação de empresas (KYB): quantas verificações que ela criou (as sessões de KYC das suas pessoas-chave e as sessões de KYB dos seus proprietários empresariais, recursivamente) foram eliminadas juntamente com ela. Sempre `0` para uma sessão de KYC." } } }, "examples": { "Deleted (default)": { "value": { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1024, "face_retention_outcome": "deleted", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } }, "Retained with User": { "value": { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1024, "face_retention_outcome": "retained_with_user", "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "biometric_template_expires_at": "2027-10-09T10:15:00Z", "deleted_child_verifications": 0 } }, "Ineligible: no User": { "summary": "Conservação solicitada numa sessão criada sem vendor_data", "value": { "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c", "session_number": 1031, "face_retention_outcome": "ineligible_no_vendor_user", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } }, "KYB session": { "value": { "session_id": "0f3c9b7e-2d1a-4e5f-8c6b-7a9d8e1f2c3b", "session_number": 88, "face_retention_outcome": "none", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 3 }, "summary": "Uma verificação de empresas eliminada com as três verificações que criou para as suas pessoas-chave" } } } } }, "400": { "description": "Erro de validação — nada é eliminado.", "content": { "application/json": { "examples": { "Privacy erasure cannot retain": { "value": { "retain_face_embeddings": [ "Privacy erasure cannot retain biometric templates." ] } }, "No finite retention duration": { "summary": "Conservação solicitada sem face_retention_days no pedido ou na aplicação", "value": { "detail": "A finite biometric-template retention duration is required." } } } } } }, "403": { "description": "Falha de autenticação ou permissão. Uma chave em falta também devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`. Exceção: quando o `sessionId` não corresponde a uma sessão ativa, a consulta prévia de proprietário devolve `404` primeiro, mesmo com credenciais em falta ou inválidas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho x-api-key ou a chave é inválida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permission": { "summary": "Token de utilizador sem delete:sessions, ou credenciais de uma aplicação que não é proprietária da sessão", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhuma sessão ativa de KYC ou KYB com este `session_id` — o ID é desconhecido ou a sessão já foi eliminada (repetir uma eliminação bem-sucedida resulta nesta resposta).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not Found": { "summary": "Sessão desconhecida ou já eliminada", "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos de escrita partilhado excedido (300 pedidos POST/PATCH/DELETE por minuto por chave de API). Inspecione o cabeçalho `Retry-After` e os cabeçalhos de resposta `X-RateLimit-*` antes de tentar novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Orçamento de escrita esgotado", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } }, "503": { "description": "A eliminação não pôde ser concluída porque um serviço de armazenamento, um repositório biométrico ou um fornecedor de monitorização estava indisponível. A sessão continua a existir; repita o mesmo pedido até que devolva `200`. Alguns dos seus ficheiros guardados ou o seu embedding facial podem já ter sido eliminados, pelo que não deve confiar neles após um `503`. As tentativas convergem para um modelo único.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Session deletion unavailable": { "summary": "Um serviço de armazenamento ou um fornecedor de monitorização esteve indisponível", "value": { "detail": "The session could not be deleted because a storage service or a monitoring provider is unavailable. The session is still in place; repeat the request to finish deleting it." } }, "Biometric store unavailable": { "summary": "Um armazenamento biométrico estava indisponível durante a retenção ou eliminação de um modelo biométrico", "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } }, "409": { "description": "A sessão faz parte de um relatório regulatório finalizado. Nada é eliminado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl (default policy)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (retain template)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"retain_face_embeddings\": true, \"face_retention_days\": 365}'" }, { "lang": "curl", "label": "curl (privacy erasure)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"deletion_instruction\": \"privacy_erasure\", \"instruction_id\": \"dsar-2026-0142\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.delete(\n \"11111111-2222-3333-4444-555555555555\",\n retain_face_embeddings=True,\n face_retention_days=365,\n instruction_id=\"post-approval-cleanup-2026-08\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.delete(\"11111111-2222-3333-4444-555555555555\", {\n retain_face_embeddings: true,\n face_retention_days: 365,\n instruction_id: \"post-approval-cleanup-2026-08\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsDeleteParams{\n\tRetainFaceEmbeddings: didit.Bool(true),\n\tFaceRetentionDays: didit.Int(365),\n\tInstructionID: didit.String(\"post-approval-cleanup-2026-08\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().delete(\"11111111-2222-3333-4444-555555555555\", SessionsDeleteParams.builder()\n .retainFaceEmbeddings(true)\n .faceRetentionDays(365L)\n .instructionId(\"post-approval-cleanup-2026-08\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->delete('11111111-2222-3333-4444-555555555555', [\n 'retain_face_embeddings' => true,\n 'face_retention_days' => 365,\n 'instruction_id' => 'post-approval-cleanup-2026-08',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.delete(\n \"11111111-2222-3333-4444-555555555555\",\n retain_face_embeddings: true,\n face_retention_days: 365,\n instruction_id: \"post-approval-cleanup-2026-08\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsDeleteParams\n{\n RetainFaceEmbeddings = true,\n FaceRetentionDays = 365,\n InstructionId = \"post-approval-cleanup-2026-08\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": false, "description": "Opcional. Omita totalmente o corpo para seguir a política de conservação da aplicação com uma eliminação operacional.", "content": { "application/json": { "schema": { "type": "object", "properties": { "retain_face_embeddings": { "type": "boolean", "nullable": true, "description": "Substitui a `face_retention_policy` da aplicação para esta eliminação. `true` mantém um template biométrico facial sem imagem associado ao utilizador da sessão após a sessão ser eliminada; `false` elimina o embedding facial com a sessão; omita ou use `null` para seguir a política da aplicação. Ignorado para sessões KYB e para sessões sem embedding facial.", "example": true }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Duração finita de conservação, em dias, para um modelo conservado. Obrigatória quando um modelo é conservado, a menos que a aplicação já defina `face_retention_days`. O `expires_at` do modelo é determinado pelo limite mais cedo entre esta duração, a janela geral de conservação de dados da aplicação e `face_retention_deadline`.", "example": 365 }, "face_retention_deadline": { "type": "string", "format": "date-time", "description": "Data de expiração definitiva opcional para um modelo retido. Tem de ser no futuro.", "example": "2027-08-28T00:00:00Z" }, "deletion_instruction": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ], "default": "operational_session_delete", "description": "A classe de instrução que está a fornecer. `operational_session_delete` elimina a sessão e retém um modelo apenas quando a política ou `retain_face_embeddings` o determinar. `privacy_erasure` elimina permanentemente todos os templates biométricos retidos associados ao utilizador da sessão antes de eliminar a sessão, não pode ser substituído pela política da aplicação e não pode ser combinado com `retain_face_embeddings: true` (`400`).", "example": "operational_session_delete" }, "instruction_id": { "type": "string", "maxLength": 255, "description": "A sua referência duradoura para esta instrução de eliminação (por exemplo, o id de um pedido de eliminação). Registada no registo de auditoria e em qualquer modelo retido. Gerada pela Didit quando omitida.", "example": "dsar-2026-0142" } } }, "examples": { "Retain a biometric template": { "summary": "Eliminar a sessão, mantendo um modelo sem imagem durante 365 dias", "value": { "retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "post-approval-cleanup-2026-08" } }, "Force deletion on an opted-in application": { "summary": "Eliminar o embedding facial independentemente da política da aplicação", "value": { "retain_face_embeddings": false } }, "Privacy erasure": { "summary": "Pedido do titular dos dados: eliminar a sessão e purgar todos os modelos retidos dessa pessoa", "value": { "deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142" } } } } } } } }, "/v3/session/{sessionId}/generate-pdf/": { "get": { "summary": "Descarregar um relatório PDF de uma sessão de verificação", "description": "Renderize e descarregue um relatório em PDF pronto para conformidade de uma sessão de verificação terminada. O mesmo caminho serve tanto sessões de Verificação de utilizadores (KYC) como de Verificação de empresas (KYB) — o servidor resolve o `sessionId` para ambos os tipos de sessão e escolhe o modelo de relatório correspondente.\n\n**Estados elegíveis.** A sessão já deve ter um estado final ou passível de revisão:\n\n- Sessões de KYC: `Approved`, `Declined`, `In Review` ou `Kyc Expired`.\n- Sessões de KYB: `Approved`, `Declined` ou `In Review`.\n\nQualquer outro estado (`Not Started`, `In Progress`, `Expired`, `Abandoned`, …) devolve `403` com uma cadeia explicativa `detail` — consulte a resposta `403` abaixo.\n\n**O que o relatório contém.** O PDF reflete a vista da sessão na consola no momento do pedido:\n\n- **KYC** — o estado agregado da sessão, a lista de avisos e uma secção por funcionalidade executada: Verificação de identidade (imagens do documento e campos extraídos), NFC, Prova de vida, Correspondência facial, Verificação de e-mail, Verificação de telefone, Comprovativo de morada, respostas aos Questionários, Validação de base de dados, Triagem AML e Análise de IP — seguidos pelas etiquetas da sessão, atividade de revisão na consola (comentários e alterações de estado) e cronologia de eventos da sessão.\n- **KYB** — verificações no registo de empresas (dados da empresa), triagens AML, verificações de documentos da empresa, verificações de pessoas-chave, respostas a questionários, verificações de telefone/e-mail, análises de IP e a cronologia de eventos da sessão, seguidas pelas etiquetas e atividade de revisão.\n\n**Marca.** Se a sua aplicação tiver personalização de marca branca, o relatório é renderizado com o seu logótipo e ligações para o URL da sua política de privacidade; caso contrário, inclui a marca Didit. Os relatórios são renderizados em inglês — não existe parâmetro de idioma.\n\n**Sem colocação em cache.** Cada chamada volta a renderizar o PDF a partir dos dados atuais da sessão, pelo que um relatório gerado após uma revisão manual reflete a decisão do revisor. Duas chamadas para a mesma sessão podem produzir ficheiros com bytes diferentes — arquive o ficheiro descarregado se precisar de uma cópia imutável.\n\n**Latência.** A renderização descarrega todas as imagens armazenadas (frentes e versos de documentos, selfies, ficheiros adicionais) antes de compor o PDF, pelo que sessões com muitos ficheiros multimédia podem demorar vários segundos. Utilize um tempo limite de leitura no cliente generoso (60 s recomendado) e faça o streaming do corpo para o disco.\n\n**Barra final.** O caminho canónico termina com uma barra final (`…/generate-pdf/`). Um pedido sem ela é processado diretamente com a mesma resposta — não há redirecionamento `301`, pelo que nenhum cliente precisa de seguir redirecionamentos e o `curl` não necessita de `-L`. Utilize o URL com barra como nos exemplos.\n\nSe precisar dos dados subjacentes em JSON em vez de um relatório renderizado, utilize `GET /v3/session/{sessionId}/decision/`. Para obter todas as sessões passíveis de relatório de um utilizador num único documento, utilize `GET /v3/users/{vendor_data}/generate-pdf/`.", "operationId": "get_v3_session_generate_pdf", "x-didit-sdk": { "resource": "sessions", "method": "generate_pdf", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de utilizadores (KYC) ou de Verificação de empresas (KYB) a gerar — o `session_id` devolvido por `POST /v3/session/`. O mesmo caminho funciona para ambos os tipos de sessão; utilize o nome de ficheiro em `Content-Disposition` na resposta para saber que tipo de relatório recebeu.\n\n**Tem de ser um UUID bem formatado e em minúsculas.** A rota apenas aceita UUIDs válidos, pelo que um valor mal formatado é rejeitado pelo router de URLs antes de qualquer código da aplicação ser executado, e a resposta é uma página **HTML** de `404` em vez do formato JSON `{\"detail\": ...}` apresentado abaixo. O conversor de UUID da rota apenas aceita o formato canónico em minúsculas — UUIDs com carateres hexadecimais em maiúsculas são rejeitados com o 404 em HTML.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "responses": { "200": { "description": "O documento PDF renderizado, devolvido diretamente como binário `application/pdf` — não há invólucro JSON nem redirecionamento por URL de descarregamento. O corpo começa com os bytes mágicos `%PDF` (PDF 1.7). Guarde-o num ficheiro `.pdf` ou transmita-o diretamente para o chamador.", "headers": { "Content-Disposition": { "description": "`attachment; filename=session_{sessionId}.pdf` para sessões de KYC, `attachment; filename=business_{sessionId}.pdf` para sessões de KYB — o prefixo indica qual modelo de relatório foi gerado.", "schema": { "type": "string", "example": "attachment; filename=session_11111111-2222-3333-4444-555555555555.pdf" } }, "Content-Length": { "description": "Tamanho total do PDF em bytes; o corpo não é fragmentado.", "schema": { "type": "integer", "example": 25191 } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Falha de autenticação, autorização ou estado da sessão. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`. Distinga os modos de falha pela string `detail`:\n\n- `\"Authentication credentials were not provided or are invalid.\"` — nenhum cabeçalho `x-api-key` (e nenhum token `Authorization: Bearer`), ou a credencial fornecida falhou a introspeção (revogada, expirada ou mal formatada).\n- `\"You do not have permission to perform this action.\"` — a credencial é válida mas não pode ler esta sessão: um token Bearer de utilizador da consola não tem a permissão `read:sessions` ou não pode aceder à aplicação proprietária, ou uma chave de API pertence a uma organização diferente da sessão.\n- `\"You can only generate a PDF for sessions in review, declined, approved or kyc expired\"` — a sessão de KYC existe mas ainda não está num estado elegível (por exemplo, `Not Started` ou `In Progress`). Aguarde pelo webhook `status.updated` antes de solicitar o relatório.\n- `\"You can only generate a PDF for sessions in review, declined or approved\"` — mesma condição para sessões de KYB.\n\nTenha em atenção que, para um `sessionId` completamente desconhecido, o endpoint resolve a aplicação proprietária antes de validar as credenciais, pelo que uma sessão em falta devolve `404` mesmo quando a credencial está em falta ou é inválida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You can only generate a PDF for sessions in review, declined, approved or kyc expired" } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a introspeção", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permissions": { "summary": "Credencial válida sem read:sessions ou sem acesso à aplicação à qual pertence", "value": { "detail": "You do not have permission to perform this action." } }, "KYC session not finished": { "summary": "Sessão KYC ainda Não Iniciada / Em Curso", "value": { "detail": "You can only generate a PDF for sessions in review, declined, approved or kyc expired" } }, "KYB session not finished": { "summary": "Sessão KYB ainda Não Iniciada / Em Curso", "value": { "detail": "You can only generate a PDF for sessions in review, declined or approved" } } } } } }, "404": { "description": "Não existe nenhuma sessão ativa com este `sessionId` — nunca foi criada ou foi eliminada. A resolução do proprietário ocorre antes da validação das credenciais, pelo que este `404` é retornado mesmo para pedidos não autenticados. Consoante a pesquisa que falhar, a string `detail` será `\"Not found.\"` (o caso mais comum) ou `\"Session not found.\"`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Not found." } } }, "examples": { "Unknown session": { "summary": "sessionId não corresponde a nenhuma sessão de KYC ou KYB", "value": { "detail": "Not found." } }, "Recently deleted session": { "summary": "A sessão foi eliminada entre pesquisas", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. A geração de PDF tem um limite dedicado de **50 pedidos por minuto por credencial** (chave de API, Bearer token ou IP de origem quando não autenticado), além do limite global de pedidos GET de 600/min. Aguarde `Retry-After` segundos (também refletido nos cabeçalhos `X-RateLimit-*`) e tente novamente. Os relatórios não são guardados em cache no servidor, portanto transfira cada relatório uma vez e armazene o ficheiro em vez de o voltar a obter.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente o pedido.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Número máximo de gerações de PDF permitidas na janela atual (50).", "schema": { "type": "integer", "example": 50 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Carimbo de data/hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Explicação legível da violação do limite de pedidos.", "example": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } }, "examples": { "Throttled": { "summary": "Mais de 50 gerações de PDF num minuto a partir da mesma credencial", "value": { "detail": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --fail \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/generate-pdf/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.generate_pdf(\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.generatePdf(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.GeneratePDF(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().generatePdf(\"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->generatePdf('11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.generate_pdf(\"11111111-2222-3333-4444-555555555555\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.GeneratePdfAsync(\"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/sandbox/arm/": { "post": { "summary": "Ativar um cenário de sandbox numa sessão", "description": "Persista um cenário de sandbox numa sessão `Not Started` e expanda os respetivos valores mágicos incluídos (campos de e-mail, telefone ou `expected_details`) na sessão, para que os fornecedores simulados reproduzam o resultado do cenário assim que o fluxo for executado. Este é o endpoint que o seletor de cenários pré-fluxo na UI de verificação alojada da Didit chama quando um testador escolhe um resultado antes de iniciar a recolha. Crie o seu próprio seletor com base nele ou chame-o diretamente a partir de um ambiente de testes de sandbox.\n\nAutentique-se com o próprio `Session-Token` da sessão (devolvido em `session_token` por [Create Session](/pt/sessions-api/create-session)), e não com a `x-api-key` da sua aplicação: este endpoint destina-se a ser chamado a partir do cliente, não do seu backend. Um cenário só é aceite enquanto o `status` for `Not Started`. Chamá-lo novamente enquanto ainda estiver em `Not Started` reativa a sessão: substitui os valores mágicos pelo novo cenário e limpa apenas os valores que o cenário *anterior* escreveu, pelo que qualquer valor já introduzido manualmente pelo utilizador (e-mail, primeiro nome, etc.) sobrevive à reativação. Ativar uma sessão que já tenha passado de `Not Started`, ou que pertença a uma aplicação de produção (não-sandbox), é rejeitado.\n\nConsulte [Sandbox & Test Data](/pt/integration/sandbox-testing) para obter o catálogo completo de cenários e as outras duas formas de conduzir um resultado: `sandbox_scenario` na criação da sessão e a introdução direta de valores mágicos.", "operationId": "post_v3_session_sandbox_arm", "x-didit-sdk": { "resource": "sessions", "method": "arm_sandbox", "auth": "device_token", "server": false }, "tags": [ "Sessions" ], "security": [ { "SessionTokenAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação em sandbox a ativar. Deve coincidir com a sessão codificada no Session-Token utilizado para autenticar.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scenario" ], "properties": { "scenario": { "type": "string", "description": "Slug do cenário a ativar. Consulte o catálogo em GET /v1/sandbox/scenarios/ ou a tabela de cenários em [Sandbox e dados de teste](/pt/integration/sandbox-testing).", "example": "decline_document_expired" } } }, "examples": { "Arm": { "summary": "Ativar o cenário de correspondência PEP em AML", "value": { "scenario": "decline_aml_hit" } } } } } }, "responses": { "200": { "description": "Cenário armado. Os respetivos valores mágicos estão agora na sessão. O campo `status` reflete o estado atual da sessão, o qual esta chamada nunca altera: é sempre `Not Started` em caso de sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "scenario": { "type": "string", "description": "O slug do cenário armado (ecoa o pedido)." }, "status": { "type": "string", "example": "Not Started" } } }, "examples": { "Armed": { "summary": "Cenário armado numa sessão Not Started", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "scenario": "decline_aml_hit", "status": "Not Started" } } } } } }, "400": { "description": "Erro de validação: um slug de cenário desconhecido ou a sessão já progrediu além de `Not Started`.", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "o cenário não está no catálogo", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-real-scenario'." ] } }, "Already Started": { "summary": "A sessão avançou além de Not Started", "value": [ "Scenario can only be armed before the verification starts." ] } } } } }, "404": { "description": "O Session-Token não resolve para este `session_id` ou a sessão pertence a uma aplicação de produção (não sandbox).", "content": { "application/json": { "examples": { "Not Found": { "summary": "Sessão ativa, ou discrepância entre session_id / token", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/ \\\n -H 'Session-Token: YOUR_SESSION_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"scenario\": \"decline_aml_hit\"\n }'" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/\",\n headers={\n \"Session-Token\": \"YOUR_SESSION_TOKEN\",\n \"Content-Type\": \"application/json\",\n },\n json={\"scenario\": \"decline_aml_hit\"},\n)\nresponse.raise_for_status()\nprint(response.json()) # {'session_id': '...', 'scenario': 'decline_aml_hit', 'status': 'Not Started'}" }, { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(\n 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/',\n {\n method: 'POST',\n headers: {\n 'Session-Token': sessionToken,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ scenario: 'decline_aml_hit' }),\n },\n);\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst { session_id, scenario, status } = await response.json();" } ] } }, "/v3/session/{sessionId}/update-status/": { "patch": { "summary": "Aprovar, recusar ou solicitar novo envio para uma sessão de verificação", "description": "Substitua manualmente a decisão final de uma sessão de verificação KYC ou KYB. Defina `new_status` como `Approved` ou `Declined` para registar uma decisão manual, ou como `Resubmitted` para limpar passos de verificação específicos e permitir que o utilizador os repita através do mesmo URL de verificação. O endpoint aceita tanto IDs de sessão de utilizador (KYC) como de empresa (KYB).\n\nChame-o quando uma sessão tiver atingido um estado passível de revisão: o estado atual deve ser `Approved`, `Declined`, `In Review`, `Kyc Expired`, `Abandoned` ou `Resubmitted`. As sessões que ainda estejam em `Not Started`, `In Progress` ou `Awaiting User`, ou que tenham terminado como `Expired`, devolvem `400`. A sua chave de API necessita da permissão `write:sessions` (uma chave de API com âmbito necessita de acesso de escrita a decisões). A verificação de estado elegível é executada antes da validação do corpo, pelo que uma sessão inelegível devolve o erro `Wrong Current Status`, mesmo quando o payload também é inválido.\n\nPara `Resubmitted`, passe `nodes_to_resubmit` para escolher quais os passos do fluxo que o utilizador deve repetir, ou omita-o para selecionar automaticamente tentativas de funcionalidades existentes num estado ressubmissível (`Declined`, `In Review`, `Not Finished`, `Expired`). As funcionalidades nunca tentadas não são selecionadas automaticamente: liste-as explicitamente em `nodes_to_resubmit`, caso contrário o pedido devolve `400` quando nenhuma tentativa registada necessitar de ressubmissão. Os resultados anteriores dos passos selecionados passam para o histórico da ressubmissão (devolvido por Get Decision com `include=resubmissions`), os passos são reordenados para corresponder ao grafo do fluxo, a janela de expiração da sessão é reiniciada e o URL de verificação original volta a ficar utilizável. Os passos exclusivos de backend (`AML`, `DATABASE_VALIDATION`, `IP_ANALYSIS`) no início da lista são executados imediatamente sem interação do utilizador; se todos os passos ressubmetidos forem exclusivos de backend, a sessão volta a ser finalizada no âmbito do mesmo pedido. `KYB_REGISTRY` e `KYB_KEY_PEOPLE` não podem ser ressubmetidos diretamente: em alternativa, ressubmeta as sessões KYC subordinadas relevantes e a sessão da empresa principal será recalculada automaticamente.\n\nCada chamada que altere o estado dispara o [webhook](/pt/integration/webhooks) `status.updated` assim que a alteração for confirmada e adiciona uma entrada de atividade (com atribuição do autor e o seu `comment`) às `reviews` da sessão, visível em [Get Decision](#get-/v3/session/-sessionId-/decision/) e na cronologia de atividade da consola. Os agregados do perfil de utilizador associados a `vendor_data` da sessão também são atualizados. A recusa desativa a monitorização AML contínua para a sessão; a reaprovação reativa-a (a partir de `Resubmitted`, `Declined` ou `Kyc Expired`) se o fluxo tiver a monitorização ativada. A aprovação ou recusa de um KYC subordinado pertencente a uma verificação de pessoas-chave de KYB recalcula o estado da sessão da empresa principal. Defina `send_email: true` (com `email_address`) para notificar o utilizador: um aviso de estado para `Approved`/`Declined`, ou um e-mail de ressubmissão contendo a ligação de verificação e os motivos por passo para `Resubmitted`. Para verificar o e-mail primeiro, pré-visualize-o com [Preview Decision Email](/pt/sessions-api/preview-decision-email) (`Approved`, `Declined`) ou [Preview Resubmission Email](/pt/sessions-api/preview-resubmission) (`Resubmitted`) e passe o respetivo `preview_token` como `email_preview_token`: a atualização envia então exatamente o e-mail pré-visualizado, ou devolve `409` antes de alterar qualquer elemento se o e-mail ou a sessão tiverem mudado desde a pré-visualização ou se o recibo tiver mais de 15 minutos.\n\nRepetir `Approved` ou `Declined` numa sessão que já tenha esse estado não altera nada e devolve `200`: nenhum webhook, nenhuma entrada de atividade e nenhum e-mail. Repetir `Resubmitted` devolve `400` (`The new status is the same as the current status.`). Credenciais em falta ou inválidas e permissões em falta devolvem `403`; uma chave de API com âmbito expirada devolve `401`.", "operationId": "patch_v3_session_update_status", "x-didit-sdk": { "resource": "sessions", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação a atualizar. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB) — o serviço resolve o ID em ambos os tipos de sessão.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "description": "Estado de destino. `Approved` e `Declined` registam uma decisão manual final (cada uma também pode revogar a outra). `Resubmitted` limpa os passos selecionados e envia a sessão de volta ao utilizador. Qualquer outro valor devolve `400`.", "enum": [ "Approved", "Declined", "Resubmitted" ], "example": "Approved" }, "comment": { "type": "string", "description": "Motivo em texto livre para a alteração, guardado no histórico de revisão da sessão e devolvido no array `reviews` de [Get Decision](#get-/v3/session/-sessionId-/decision/). Por exemplo, `Duplicated user`.", "example": "All checks passed manual review" }, "nodes_to_resubmit": { "type": "array", "description": "Passos do fluxo que o utilizador deve repetir. Apenas considerados quando `new_status` é `Resubmitted`. Para `Approved`/`Declined`, as entradas continuam a ser validadas pelo schema (um valor inválido de `feature` devolve `400`), mas as entradas válidas no schema são semanticamente ignoradas. Se for omitido, o servidor seleciona automaticamente tentativas existentes de OCR, Prova de vida, Correspondência facial, Comprovativo de morada, Telefone, E-mail, AML, Validação de base de dados e Questionário cujo estado seja `Declined`, `In Review`, `Not Finished` ou `Expired` (tentativas de NFC, análise de IP, estimativa de idade, pesquisa facial e documentos KYB nunca são selecionadas automaticamente; tentativas faciais que não sejam de correspondência facial são selecionadas como `LIVENESS`) — funcionalidades que o utilizador nunca tentou (sem tentativa registada) NÃO são selecionadas, pelo que uma sessão com zero tentativas devolve `400` (\"No features found that need resubmission\"), mesmo que nada tenha sido aprovado; passe `nodes_to_resubmit` explicitamente nesse caso. Os passos são executados na ordem do grafo do fluxo, independentemente da ordem em que os envia. `KYB_REGISTRY`, `KYB_KEY_PEOPLE` e o alias `KYB` são rejeitados com `400` — essas verificações principais são recalculadas a partir das respetivas sessões KYC filhas.", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "Identificador do nó tal como aparece na definição do fluxo da sessão (por exemplo `feature_ocr`, `feature_liveness`).", "example": "feature_ocr" }, "feature": { "type": "string", "description": "Tipo de funcionalidade do nó. Os aliases `ID_VERIFICATION`, `POA`, `PHONE` e `EMAIL` são normalizados do lado do servidor para `OCR`, `PROOF_OF_ADDRESS`, `PHONE_VERIFICATION` e `EMAIL_VERIFICATION`. `KYB_REGISTRY`, `KYB_KEY_PEOPLE` e `KYB` passam na validação do esquema, mas são sempre rejeitados com a regra de negócio `400` mostrada nos exemplos.", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "send_email": { "type": "boolean", "description": "Se deve ser enviado um e-mail ao utilizador sobre a alteração. Requer `email_address`. Para `Approved`/`Declined`, o utilizador recebe um aviso de estado; para `Resubmitted`, o e-mail inclui a ligação de verificação e os motivos de reenvio por passo.", "default": false, "example": false }, "email_address": { "type": "string", "format": "email", "description": "Destinatário do e-mail de notificação. **Obrigatório quando `send_email` for `true`** — omiti-lo devolve `400`.", "example": "user@example.com" }, "email_language": { "type": "string", "description": "Idioma do e-mail de notificação. Aceita qualquer cadeia de caracteres ao nível do esquema; códigos não suportados revertem silenciosamente para inglês (`en`).", "default": "en", "example": "en" }, "email_preview_token": { "type": "string", "writeOnly": true, "minLength": 1, "maxLength": 512, "description": "Recibo opcional de [Pré-visualizar e-mail de decisão](/pt/sessions-api/preview-decision-email) (para `Approved` e `Declined`) ou [Pré-visualizar e-mail de nova submissão](/pt/sessions-api/preview-resubmission) (para `Resubmitted`): o respetivo `preview_token`. Válido apenas com `send_email: true`; sem este, o pedido devolve `400`. O destinatário, idioma, estado da sessão, remetente e e-mail (e, para uma nova submissão, os passos selecionados) têm de continuar a coincidir com a pré-visualização, e o recibo expira após 15 minutos. Caso contrário, o pedido devolve `409` antes de a sessão ser alterada ou de ser enviado um e-mail. As integrações existentes podem omitir este campo." } } }, "examples": { "Approve Session": { "summary": "Aprovar uma sessão após revisão manual", "value": { "new_status": "Approved", "comment": "All checks passed manual review" } }, "Decline Session": { "summary": "Recusar uma sessão", "value": { "new_status": "Declined", "comment": "Suspected fraud" } }, "Resubmit Specific Steps": { "summary": "Pedir reenvio dos passos selecionados, com e-mail", "value": { "new_status": "Resubmitted", "nodes_to_resubmit": [ { "node_id": "feature_ocr", "feature": "OCR" }, { "node_id": "feature_liveness", "feature": "LIVENESS" } ], "send_email": true, "email_address": "user@example.com", "email_language": "en" } }, "Resubmit Auto-select": { "summary": "Pedir reenvio (selecionar automaticamente os passos não aprovados)", "value": { "new_status": "Resubmitted" } }, "Approve With Previewed Email": { "summary": "Aprovar e enviar o e-mail devolvido por Pré-visualizar e-mail de decisão", "value": { "new_status": "Approved", "send_email": true, "email_address": "person@example.com", "email_language": "en", "email_preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } } } } }, "responses": { "200": { "description": "Estado atualizado. A resposta contém apenas o `session_id`; obtenha a sessão atualizada através de [Get Decision](#get-/v3/session/-sessionId-/decision/). O webhook `status.updated` é disparado assim que a alteração for confirmada. Repetir `Approved` ou `Declined` devolve o mesmo corpo e não altera nada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "UUID da sessão atualizada." } } }, "examples": { "Updated": { "summary": "Devolvido da mesma forma para Aprovada, Recusada e Reenviada", "value": { "session_id": "3472fb7c-8f7c-4d1a-9cf4-cf3d74ce1a60" } } } } } }, "400": { "description": "Erro de validação. Os erros de campo chegam como `{\"\": [\"\"]}` (algumas recusas de regras de negócio utilizam um valor de string: `{\"nodes_to_resubmit\": \"\"}`), erros entre estados como `{\"detail\": \"\"}` e o erro de mesmo estado como um array JSON simples.", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "A sessão não está num estado atualizável", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Invalid Status Value": { "summary": "new_status é um estado de sessão real, mas não é um de Approved/Declined/Resubmitted", "value": { "new_status": [ "You can only update the status to 'Approved', 'Declined', or 'Resubmitted'." ] } }, "Missing new_status": { "summary": "Campo obrigatório omitido", "value": { "new_status": [ "This field is required." ] } }, "Same Status": { "summary": "Reenvio solicitado numa sessão que já se encontra reenviada", "value": [ "The new status is the same as the current status." ] }, "Email Address Required": { "summary": "send_email true sem email_address", "value": { "email_address": [ "Email address is required when send_email is true." ] } }, "Non-resubmittable Feature": { "summary": "O reenvio tem como alvo uma verificação-pai de KYB", "value": { "nodes_to_resubmit": "The following features cannot be resubmitted directly: KYB_REGISTRY. Resubmit the relevant child KYC sessions instead; the parent will recompute automatically." } }, "Nothing To Resubmit": { "summary": "A seleção automática não encontrou funcionalidades não aprovadas", "value": { "nodes_to_resubmit": "No features found that need resubmission. All features are already approved." } }, "Invalid Feature Choice": { "summary": "Funcionalidade desconhecida em nodes_to_resubmit", "value": { "nodes_to_resubmit": [ { "feature": [ "\"BOGUS\" is not a valid choice. Valid choices are: OCR, OCR_BACK, NFC, AML, FACE, LIVENESS, FACE_MATCH, IP_ANALYSIS, AGE_ESTIMATION, PROOF_OF_ADDRESS, PHONE_VERIFICATION, EMAIL_VERIFICATION, FACE_SEARCH, DATABASE_VALIDATION, QUESTIONNAIRE, KYB_REGISTRY, KYB_DOCUMENTS, KYB_KEY_PEOPLE, ID_VERIFICATION, POA, PHONE, EMAIL, KYB" ] } ] } }, "Invalid Status Value (not a status at all)": { "summary": "new_status não é um valor de StatusChoices válido", "value": { "new_status": [ "\"Bogus\" is not a valid choice." ] } }, "Preview Receipt Without Email": { "summary": "email_preview_token enviado sem send_email: true", "value": { "email_preview_token": [ "A preview receipt is only valid when the email is sent." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chave de API com âmbito cuja data de validade já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenciais em falta ou permissões insuficientes, ou um `session_id` que pertence a outra aplicação.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "A chave de API não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhuma sessão de KYC ou KYB com este `session_id` (sessões eliminadas também devolvem `404`).", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id desconhecido", "value": { "detail": "Not found." } } } } } }, "429": { "description": "Um reenvio focado apenas em funcionalidades de backend (AML, DATABASE_VALIDATION, IP_ANALYSIS) foi repetido dentro do intervalo de espera de 30 segundos; uma repetição imediata não altera o resultado. Aguarde e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Backend-only resubmit throttled": { "value": { "detail": "This session was already resubmitted for backend-only features within the last 30 seconds; repeating it cannot change the outcome. Wait before resubmitting again." } } } } } }, "409": { "description": "A pré-visualização do e-mail foi alterada ou expirou. Gere uma nova pré-visualização antes de confirmar; não ocorre nenhuma alteração de sessão nem entrega de e-mail.", "content": { "application/json": { "examples": { "Preview Changed": { "summary": "O recibo já não corresponde ou tem mais de 15 minutos", "value": { "detail": "This email preview changed or expired. Preview the message again before confirming." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"Approved\",\n \"comment\": \"All checks passed manual review\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_status(\n \"11111111-2222-3333-4444-555555555555\",\n new_status=\"Approved\",\n comment=\"All checks passed manual review\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateStatus(\"11111111-2222-3333-4444-555555555555\", {\n new_status: \"Approved\",\n comment: \"All checks passed manual review\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateStatusParams{\n\tNewStatus: \"Approved\",\n\tComment: didit.String(\"All checks passed manual review\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateStatusParams.builder()\n .newStatus(SessionsUpdateStatusParams.NewStatus.of(\"Approved\"))\n .comment(\"All checks passed manual review\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateStatus('11111111-2222-3333-4444-555555555555', [\n 'new_status' => 'Approved',\n 'comment' => 'All checks passed manual review',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_status(\n \"11111111-2222-3333-4444-555555555555\",\n new_status: \"Approved\",\n comment: \"All checks passed manual review\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateStatusParams\n{\n NewStatus = \"Approved\",\n Comment = \"All checks passed manual review\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/": { "post": { "summary": "Verificação de identidade (OCR de documentos + verificações de fraude)", "description": "Efetue o OCR de um documento de identidade e execute verificações de fraude documental numa única chamada — devolve os campos extraídos do titular, a MRZ processada, um `status` `Approved`/`Declined`/`In Review` e uma lista `warnings` que explica cada problema detetado. Suporta 14,000+ tipos de documentos de 220+ países e territórios.\n\n**Como funciona.** Envie a `front_image` do documento (obrigatória) e, para documentos com dois lados, a `back_image`. Carregue fotos não recortadas com os quatro cantos do documento visíveis — o serviço deteta, alinha e recorta o documento autonomamente, pelo que não deve recortar previamente. O documento é classificado automaticamente (nunca declara o país ou o tipo de documento), a zona visual é lida por OCR e a MRZ e quaisquer códigos de barras são descodificados. As verificações cruzadas validam depois as datas, os formatos numéricos e os dígitos de controlo da MRZ, e comparam a zona visual com a MRZ. Com `perform_document_liveness=true`, as imagens são adicionalmente analisadas quanto a reproduções em ecrã, cópias impressas e manipulação de retrato.\n\n**Lógica de decisão.** O `status` é `Approved`, a menos que pelo menos um aviso resulte numa recusa. Os riscos de fraude e falha crítica recusam sempre: `DOCUMENT_EXPIRED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, além de falhas de extração (`NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`). (`PORTRAIT_IMAGE_NOT_DETECTED`, `INVALID_DATE` e `MRZ_NOT_DETECTED` existem em sessões de fluxo, mas nunca são produzidos por este endpoint autónomo. `COULD_NOT_DETECT_DOCUMENT_TYPE` é devolvido aqui quando a imagem frontal não corresponde com elevada confiança a um modelo de documento oficial conhecido, recusando o pedido.) Três grupos de risco são configuráveis por pedido através de `invalid_mrz_action`, `inconsistent_data_action` e `expiration_date_not_detected_action` (`DECLINE` ou `NO_ACTION`). Todos os outros avisos (por exemplo, `POSSIBLE_DUPLICATED_USER`) são informativos e nunca recusam por si próprios. Quando `perform_document_liveness=true` (a predefinição) e a verificação de falsificação não devolve uma pontuação utilizável — o fornecedor falhou, respondeu com um código diferente de 200 ou respondeu com HTTP 200 e `status=\"ERR\"` - a chamada devolve `200` com `status: \"In Review\"` e um aviso `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: \"warning\"`) em vez de `Approved`: uma verificação que não foi executada não constitui prova de que o documento seja genuíno. Este escalonamento não é configurável e nunca se sobrepõe a `Declined`; com `perform_document_liveness=false`, a verificação é ignorada e o estado segue os restantes avisos como anteriormente. Um documento que não possa de todo ser processado devolve `400` com `{\"error\": \"COULD_NOT_RECOGNIZE_DOCUMENT\"}`; um documento legível mas com problemas devolve `200` com `status: \"Declined\"` — inspecione sempre `id_verification.status` e `id_verification.warnings`, e não apenas o código HTTP.\n\n**Faturação.** Cada resposta `200` consome um crédito da API de Verificação de identidade (pago a partir do crédito do seu plano ou do saldo carregado). Quando o saldo da organização não cobre a chamada, o endpoint devolve `403` com o erro de créditos insuficientes antes de qualquer processamento de imagem.\n\n**Persistência da sessão (`save_api_request`, predefinição `true`).** Quando for `true`, a chamada é persistida como uma sessão do tipo API: aparece na Business Console, o `request_id` devolvido é um ID de sessão real que pode passar a `GET /v3/session/{sessionId}/decision/`, as imagens recortadas do documento/retrato são armazenadas e devolvidas como URLs de multimédia de curta duração (`https:///ocr/...`), e um webhook `status.updated` é emitido para os seus endpoints de webhook configurados. Quando for `false`, nada é armazenado, `request_id` é um UUID de correlação pontual e `portrait_image`/`front_image`/`back_image` são devolvidos diretamente como strings JPEG codificadas em base64.\n\n**Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada malformados continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved` (um documento de identidade fictício dos EUA do utilizador \"Sandbox User\"), nenhuma sessão é persistida e nenhum crédito é consumido.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limite de pedidos.** Limite de pedidos de escrita partilhado de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; exceder este limite devolve `429`.", "operationId": "post_v3id-verification", "x-didit-sdk": { "resource": "id_verification", "method": "verify", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "front_image" ], "properties": { "front_image": { "type": "string", "format": "binary", "description": "Frente do documento de identificação. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`, `pdf`. Tamanho máximo de carregamento: **10 MB** (ficheiros maiores são rejeitados com `400`). Os PDFs são convertidos numa imagem antes do OCR; PDFs encriptados requerem `front_image_password`. As imagens são comprimidas automaticamente para ~0.5 MB e a orientação EXIF é aplicada. Carregue a captura completa e sem cortes com os quatro cantos do documento visíveis." }, "front_image_password": { "type": "string", "description": "Palavra-passe para desencriptar `front_image` quando for um PDF encriptado. O envio de um PDF encriptado sem palavra-passe (ou com uma incorreta) devolve `400`.", "writeOnly": true }, "back_image": { "type": "string", "format": "binary", "description": "Verso do documento — envie-o sempre que o documento tiver um (muitos cartões de identificação contêm o MRZ ou um código de barras no verso; omiti-lo apenas deixa o MRZ e os campos do verso vazios na resposta — este endpoint não gera um aviso de MRZ em falta). Mesmos limites de formato e tamanho que `front_image`. Quando omitido, `back_image` e os campos do verso ficam a `null` na resposta." }, "back_image_password": { "type": "string", "description": "Palavra-passe para desencriptar `back_image` quando for um PDF encriptado.", "writeOnly": true }, "perform_document_liveness": { "type": "boolean", "default": true, "description": "Analisa ambas as imagens à procura de fraude de apresentação: reproduções de ecrã (`SCREEN_CAPTURE_DETECTED`), cópias impressas (`PRINTED_COPY_DETECTED`) e manipulação de retrato (`PORTRAIT_MANIPULATION_DETECTED`). Qualquer uma destas situações causa recusa automática. Ativado por predefinição; defina como `false` para ignorar a triagem de fraude e reduzir a latência. Quando ativado e o fornecedor não devolve uma pontuação utilizável, a resposta é `In Review` com um aviso `DOCUMENT_LIVENESS_NOT_COMPUTED` em vez de `Approved`.", "example": true }, "minimum_age": { "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 120, "description": "Aceite e validado (1–120), mas **atualmente não aplicado** por este endpoint — nunca produz um aviso `MINIMUM_AGE_NOT_MET` a partir deste campo. Aplique regras de idade a partir de `date_of_birth`/`age` devolvidos, ou utilize um fluxo de sessão de verificação com restrições de idade." }, "expiration_date_not_detected_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "O que fazer quando não for possível ler qualquer data de validade (`EXPIRATION_DATE_NOT_DETECTED`). Predefinição `NO_ACTION`, pois muitos documentos de identidade não imprimem a data de validade. Nota: uma data de validade *detetada e ultrapassada* resulta sempre numa recusa (`DOCUMENT_EXPIRED`), independentemente desta opção." }, "invalid_mrz_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "O que fazer quando a MRZ extraída falha na validação do dígito de controlo (`MRZ_VALIDATION_FAILED`). Uma MRZ em falta não gera qualquer aviso neste endpoint. Relevante apenas para documentos que possuem uma MRZ. `REVIEW` não é suportado neste endpoint e devolve `400`." }, "inconsistent_data_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "O que fazer quando os dados extraídos forem internamente inconsistentes: `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` (a zona visual não coincide com a MRZ) ou `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`." }, "critical_field_occlusion_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "O que fazer quando um campo impresso crítico foi fisicamente tapado na captura (`CRITICAL_FIELD_OCCLUSION_DETECTED`) - um número de identificação, um nome, a data de nascimento ou a data de validade. Recusa por predefinição, tal como outros riscos de integridade do documento deste endpoint: tapar os números face aos quais um relatório é reconciliado é o aspeto típico de um documento rasurado. O valor lido para um campo tapado é descartado da extração de qualquer forma, pelo que o aviso `*_NOT_DETECTED` correspondente costuma acompanhá-lo. O valor `REVIEW` não é suportado neste endpoint e devolve `400`." }, "document_or_personal_number_format_mismatch_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "O que fazer quando um número não corresponder ao formato que a sua autoridade emissora utiliza para esse tipo de documento (`DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`). Predefinição `NO_ACTION`, que comunica o aviso sem alterar o estado. O valor `REVIEW` não é suportado neste endpoint e devolve `400`." }, "preferred_characters": { "type": "string", "enum": [ "latin", "non_latin" ], "default": "latin", "description": "Sistema de escrita preferencial para os campos de nome/morada em documentos que imprimem texto latino e não latino (árabe, cirílico, CJK, …). `latin` devolve valores transliterados/latinos; `non_latin` prefere o sistema de escrita nativo." }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido, anunciada através de um webhook `status.updated` e com imagens de documentos devolvidas como URLs de multimédia. Quando for `false`, nada é armazenado, `request_id` é um UUID transitório e as imagens são devolvidas em linha como strings JPEG em base64.", "example": true }, "vendor_data": { "type": "string", "description": "String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={\"flow\":\"onboarding\"}`) — é convertido num objeto.", "example": { "flow": "onboarding" } } } }, "example": { "front_image": "(binary JPEG/PNG/PDF of the document front)", "back_image": "(binary JPEG/PNG/PDF of the document back)", "perform_document_liveness": true, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "onboarding" } } } } }, "responses": { "200": { "description": "Documento processado. `id_verification.status` é `Approved`, `Declined` ou `In Review`; cada problema detetado é discriminado em `id_verification.warnings`. `In Review` é devolvido quando uma verificação de prova de vida no documento solicitada não produziu nenhum resultado utilizável (`DOCUMENT_LIVENESS_NOT_COMPUTED`). Um documento com problemas continua a devolver `200` com `status: \"Declined\"` — inspecione o corpo, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id da sessão persistida e os campos de imagem são URLs de multimédia de curta duração; com `save_api_request=false`, são strings JPEG base64 inline.", "content": { "application/json": { "examples": { "Approved": { "summary": "Cartão de cidadão/identidade frente e verso lido com sucesso (guardado — imagens como URLs de multimédia)", "value": { "request_id": "11d219ed-d59c-4b1d-8d65-9b933f12d5b8", "id_verification": { "status": "Approved", "document_type": "Identity Card", "document_subtype": "ID_CARD_GENERIC", "document_number": "CBX164224", "personal_number": "20446581H", "portrait_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=...", "front_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=...", "back_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=...", "front_image_camera_front": null, "back_image_camera_front": null, "front_image_camera_front_face_match_score": null, "back_image_camera_front_face_match_score": null, "front_image_quality_score": { "focus_score": 78.0, "brightness_score": 83.2, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 40.7, "overall_score": 70.2 }, "back_image_quality_score": { "focus_score": 100.0, "brightness_score": 95.6, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 43.0, "overall_score": 84.4 }, "date_of_birth": "1980-01-13", "age": 46, "expiration_date": "2032-03-31", "date_of_issue": "2022-03-31", "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Julio Francisco", "last_name": "Fores Sena", "full_name": "Julio Francisco Fores Sena", "gender": "M", "address": "Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife", "formatted_address": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain", "place_of_birth": "Valencia, Valencia", "marital_status": "UNKNOWN", "nationality": "ESP", "extra_fields": { "first_surname": "Fores", "second_surname": "Sena" }, "mrz": { "surname": "FORES SENA", "name": "JULIO FRANCISCO", "country": "ESP", "nationality": "ESP", "birth_date": "800113", "expiry_date": "320331", "sex": "M", "document_type": "ID", "document_number": "CBX164224", "optional_data": "20446581H", "optional_data_2": "", "birth_date_hash": "9", "expiry_date_hash": "8", "document_number_hash": "3", "final_hash": "3", "personal_number": "20446581H", "warnings": [], "errors": [], "mrz_type": "TD1", "mrz_string": "IDESPCBX164224320446581H<<<<<<\n8001139M3203318ESP<<<<<<<<<<<3\nFORES/ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=...", "front_image": "https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=...", "back_image": null, "front_image_camera_front": null, "back_image_camera_front": null, "front_image_camera_front_face_match_score": null, "back_image_camera_front_face_match_score": null, "front_image_quality_score": { "focus_score": 100.0, "brightness_score": 95.7, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 22.2, "overall_score": 79.3 }, "back_image_quality_score": null, "date_of_birth": "1997-01-30", "age": 29, "expiration_date": "2025-11-26", "date_of_issue": null, "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Lucia", "last_name": "Marin Castro", "full_name": "Lucia Marin Castro", "gender": "F", "address": null, "formatted_address": null, "place_of_birth": null, "marital_status": "UNKNOWN", "nationality": "ESP", "extra_fields": { "first_surname": "Marin", "second_surname": "Castro" }, "mrz": {}, "parsed_address": null, "warnings": [ { "risk": "DOCUMENT_EXPIRED", "feature": "ID_VERIFICATION", "additional_data": null, "log_type": "error", "short_description": "Document expired", "long_description": "The document's expiration date has passed, rendering it no longer valid for use." } ], "barcodes": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:25:48.117204+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "id_verification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "`Approved` quando nenhum aviso resultar numa recusa e a verificação de prova de vida do documento solicitada tiver produzido um resultado utilizável; `In Review` quando essa verificação solicitada não tiver produzido nenhum resultado utilizável (`DOCUMENT_LIVENESS_NOT_COMPUTED`); `Declined` quando um aviso resultar numa recusa — a lista `warnings` explica o motivo." }, "document_type": { "type": "string", "nullable": true, "description": "Nome de apresentação do tipo de documento detetado: `Identity Card`, `Passport`, `Driver's License`, `Residence Permit`, `Health Insurance Card` ou `Tax Card`. `null` quando o documento não pôde ser classificado.", "example": "Identity Card" }, "document_subtype": { "type": "string", "nullable": true, "description": "Subtipo mais detalhado quando disponível (ex.: `ID_CARD_GENERIC`, `EPASSPORT`).", "example": "ID_CARD_GENERIC" }, "document_number": { "type": "string", "nullable": true, "example": "CBX164224" }, "personal_number": { "type": "string", "nullable": true, "description": "Número pessoal/nacional secundário impresso em alguns documentos.", "example": "20446581H" }, "portrait_image": { "type": "string", "nullable": true, "description": "Foto de retrato recortada do documento. Um URL de multimédia de curta duração (`https:///ocr/...`) quando `save_api_request=true` (predefinição); uma string JPEG em base64 inline quando `save_api_request=false`. `null` se nenhum retrato tiver sido detetado." }, "front_image": { "type": "string", "nullable": true, "description": "Recorte alinhado da frente do documento. URL de multimédia quando guardado, JPEG inline em base64 caso contrário." }, "back_image": { "type": "string", "nullable": true, "description": "Recorte alinhado do verso do documento. `null` quando não foi carregada nenhuma `back_image`." }, "front_image_camera_front": { "type": "string", "nullable": true, "description": "Sempre `null` neste endpoint (preenchido apenas em sessões de verificação com captura por câmara)." }, "back_image_camera_front": { "type": "string", "nullable": true, "description": "Sempre `null` neste endpoint." }, "front_image_camera_front_face_match_score": { "type": "number", "nullable": true, "description": "Sempre `null` neste endpoint." }, "back_image_camera_front_face_match_score": { "type": "number", "nullable": true, "description": "Sempre `null` neste endpoint." }, "front_image_quality_score": { "type": "object", "nullable": true, "description": "Diagnósticos de qualidade de captura para a imagem carregada (`null` quando o lado não foi fornecido ou a pontuação falhou). Todas as pontuações são de 0 a 100.", "properties": { "focus_score": { "type": "number", "format": "float", "description": "Nitidez do recorte do documento (quanto maior, mais nítido)." }, "brightness_score": { "type": "number", "format": "float", "description": "Qualidade da exposição (quanto maior, melhor)." }, "brightness_issue": { "type": "string", "nullable": true, "description": "`ok` quando a exposição está adequada; caso contrário, o problema detetado (por exemplo, demasiado escuro / demasiado claro)." }, "is_document_fully_visible": { "type": "boolean", "nullable": true, "description": "Se os quatro cantos do documento estão dentro do enquadramento." }, "resolution_score": { "type": "number", "format": "float", "description": "Resolução efetiva da área do documento." }, "overall_score": { "type": "number", "format": "float", "description": "Pontuação de qualidade agregada." } } }, "back_image_quality_score": { "type": "object", "nullable": true, "description": "Diagnósticos de qualidade de captura para a imagem carregada (`null` quando o lado não foi fornecido ou a pontuação falhou). Todas as pontuações são de 0 a 100.", "properties": { "focus_score": { "type": "number", "format": "float", "description": "Nitidez do recorte do documento (quanto maior, mais nítido)." }, "brightness_score": { "type": "number", "format": "float", "description": "Qualidade da exposição (quanto maior, melhor)." }, "brightness_issue": { "type": "string", "nullable": true, "description": "`ok` quando a exposição está adequada; caso contrário, o problema detetado (por exemplo, demasiado escuro / demasiado claro)." }, "is_document_fully_visible": { "type": "boolean", "nullable": true, "description": "Se os quatro cantos do documento estão dentro do enquadramento." }, "resolution_score": { "type": "number", "format": "float", "description": "Resolução efetiva da área do documento." }, "overall_score": { "type": "number", "format": "float", "description": "Pontuação de qualidade agregada." } } }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "example": "1980-01-13" }, "age": { "type": "integer", "nullable": true, "description": "Idade do titular em anos, calculada a partir de `date_of_birth`.", "example": 46 }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "example": "2032-03-31" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "example": "2022-03-31" }, "issuing_state": { "type": "string", "nullable": true, "description": "País emissor (ISO 3166-1 alfa-3).", "example": "ESP" }, "issuing_state_name": { "type": "string", "nullable": true, "example": "Spain" }, "first_name": { "type": "string", "nullable": true, "example": "Julio Francisco" }, "last_name": { "type": "string", "nullable": true, "example": "Fores Sena" }, "full_name": { "type": "string", "nullable": true, "example": "Julio Francisco Fores Sena" }, "gender": { "type": "string", "nullable": true, "description": "`M`, `F`, ou `null` quando não impresso/detetado.", "example": "M" }, "address": { "type": "string", "nullable": true, "description": "Morada exatamente como impressa no documento." }, "formatted_address": { "type": "string", "nullable": true, "description": "Versão geocodificada e normalizada de `address`." }, "place_of_birth": { "type": "string", "nullable": true, "example": "Valencia, Valencia" }, "marital_status": { "type": "string", "nullable": true, "description": "`UNKNOWN`, a menos que o documento tenha o estado civil impresso.", "example": "UNKNOWN" }, "nationality": { "type": "string", "nullable": true, "description": "Nacionalidade do titular (ISO 3166-1 alfa-3).", "example": "ESP" }, "extra_fields": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Dados adicionais específicos do documento que não têm uma coluna dedicada (por exemplo, `first_surname`/`second_surname` em documentos de identificação espanhóis, categorias de carta de condução em cartas de condução)." }, "mrz": { "type": "object", "description": "Zona de leitura ótica analisada. Um **objeto vazio** (`{}`) quando o documento não tem MRZ ou ela não pôde ser lida — consulte também a lista `warnings` nesse caso. As datas no interior da MRZ utilizam o formato em bruto `YYMMDD`.", "properties": { "surname": { "type": "string", "example": "FORES SENA" }, "name": { "type": "string", "example": "JULIO FRANCISCO" }, "country": { "type": "string", "description": "País emissor (ISO 3166-1 alfa-3).", "example": "ESP" }, "nationality": { "type": "string", "description": "Nacionalidade do titular (ISO 3166-1 alfa-3).", "example": "ESP" }, "birth_date": { "type": "string", "description": "Data de nascimento em bruto da MRZ (`YYMMDD`).", "example": "800113" }, "expiry_date": { "type": "string", "description": "Data de validade em bruto da MRZ (`YYMMDD`).", "example": "320331" }, "sex": { "type": "string", "example": "M" }, "document_type": { "type": "string", "description": "Código do tipo de documento do MRZ (por exemplo `ID`, `P`).", "example": "ID" }, "document_number": { "type": "string", "example": "CBX164224" }, "optional_data": { "type": "string", "nullable": true, "example": "20446581H" }, "optional_data_2": { "type": "string", "nullable": true, "example": "" }, "birth_date_hash": { "type": "string", "description": "Dígito de controlo do MRZ para a data de nascimento.", "example": "9" }, "expiry_date_hash": { "type": "string", "description": "Dígito de controlo do MRZ para a data de validade.", "example": "8" }, "document_number_hash": { "type": "string", "description": "Dígito de controlo do MRZ para o número do documento.", "example": "3" }, "final_hash": { "type": "string", "description": "Dígito de controlo MRZ composto.", "example": "3" }, "personal_number": { "type": "string", "nullable": true, "example": "20446581H" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Avisos não fatais de análise do MRZ." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Erros de dígito de controlo/análise do MRZ. Os erros que não estejam vazios surgem como um aviso `MRZ_VALIDATION_FAILED`." }, "mrz_type": { "type": "string", "description": "Esquema do MRZ: `TD1` (cartões de cidadão/identidade, 3 linhas), `TD2` ou `TD3` (passaportes, 2 linhas).", "example": "TD1" }, "mrz_string": { "type": "string", "description": "Texto em bruto da MRZ conforme lido, linhas separadas por `\\n`." }, "mrz_key": { "type": "string", "description": "Chave composta (número do documento + dígitos de controlo) utilizada para verificações cruzadas." } } }, "parsed_address": { "type": "object", "nullable": true, "description": "Detalhes estruturados e geocodificados de `address`. `null` quando o documento não tem morada ou esta não pôde ser analisada.", "properties": { "street_1": { "type": "string", "nullable": true, "example": "Avenida el Cardonal 52" }, "street_2": { "type": "string", "nullable": true, "example": "b" }, "city": { "type": "string", "nullable": true, "example": "La Laguna" }, "region": { "type": "string", "nullable": true, "example": "Canarias" }, "country": { "type": "string", "nullable": true, "description": "Código de país ISO 3166-1 alpha-2.", "example": "ES" }, "postal_code": { "type": "string", "nullable": true, "example": "38108" }, "address_type": { "type": "string", "nullable": true, "example": "Avenida" }, "formatted_address": { "type": "string", "nullable": true, "description": "Cadeia de caracteres de morada geocodificada canónica.", "example": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain" }, "raw_results": { "type": "object", "additionalProperties": true, "description": "Payload de geocodificação em bruto (`address_components`, `geometry.location`, `place_id`, …) para consumidores avançados." }, "document_location": { "type": "object", "nullable": true, "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "description": "Coordenadas geocodificadas da morada do documento." }, "label": { "type": "string", "nullable": true, "description": "De que campo do documento a morada foi lida.", "example": "Spain Identity Card Address" }, "is_verified": { "type": "boolean", "description": "Se a geocodificação confirmou que a morada existe." }, "category": { "type": "string", "nullable": true, "description": "Categoria de morada (por exemplo, `Residential`, `Commercial`).", "example": "Residential" } } }, "warnings": { "type": "array", "description": "Vazio numa aprovação limpa. Cada entrada explica um risco detetado; entradas com `log_type: \"error\"` definem `status` como `Declined`, e `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: \"warning\"`) define-o como `In Review`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "Código de risco legível por máquina. Riscos de recusa obrigatória: `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT` (apenas 400, nunca um aviso), `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`. Determinados pelas opções do pedido: `MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED` (`invalid_mrz_action`), `DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` (`inconsistent_data_action`), `EXPIRATION_DATE_NOT_DETECTED` (`expiration_date_not_detected_action`). Outros riscos (p. ex. `POSSIBLE_DUPLICATED_USER`) são informativos. `DOCUMENT_LIVENESS_NOT_COMPUTED` é acionado quando `perform_document_liveness=true`, mas a verificação de falsificação não devolveu uma pontuação utilizável; define `status` para `In Review`. `COULD_NOT_DETECT_DOCUMENT_TYPE` também é devolvido quando a frente do documento não coincide com um modelo de documento oficial conhecido com elevada confiança, por exemplo, um documento editado ou gerado por computador, ou um modelo que ainda não é suportado.", "example": "DOCUMENT_EXPIRED" }, "feature": { "type": "string", "enum": [ "ID_VERIFICATION" ], "description": "Funcionalidade que gerou o aviso. Sempre `ID_VERIFICATION` neste endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contexto adicional para alguns riscos (por exemplo, `POSSIBLE_DUPLICATED_USER` inclui `duplicated_session_id`); `null` para a maioria." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravidade. Os avisos `error` alteram o `status` para `Declined`; `warning` (apenas `DOCUMENT_LIVENESS_NOT_COMPUTED`, quando a verificação de falsificação solicitada não produziu nenhuma pontuação utilizável) altera o `status` para `In Review`; as entradas `information` são informativas e nunca alteram o estado." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos sobre o risco." }, "long_description": { "type": "string", "description": "Explicação legível do risco." } } } }, "barcodes": { "type": "array", "description": "Códigos de barras descodificados do documento (PDF417, QR, …). Vazio quando o documento não tem nenhum ou nenhum pôde ser lido.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo de código de barras (por exemplo, `PDF417`, `QR_CODE`, `UNKNOWN`)." }, "position": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Localização do código de barras na imagem, quando disponível." }, "data": { "type": "string", "description": "Payload descodificado." }, "data_raw": { "type": "string", "description": "Payload em bruto (não descodificado), quando diferente." }, "side": { "type": "string", "nullable": true, "description": "`front` ou `back`." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, ou `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, ou `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada." } } } } } }, "400": { "description": "Erro de validação ou de processamento. Problemas ao nível do campo devolvem o envelope padrão do DRF (um array de mensagens por campo afetado). Problemas com PDF encriptado devolvem `{\"detail\": ...}`. Uma imagem de documento na qual nenhum documento possa ser reconhecido devolve `{\"error\": \"COULD_NOT_RECOGNIZE_DOCUMENT\"}`. Os carregamentos de PDF também podem falhar com \"The submitted PDF file is corrupted or invalid.\" ou um erro de ausência de páginas.", "content": { "application/json": { "examples": { "Missing front image": { "summary": "`front_image` não incluído nos dados do formulário", "value": { "front_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Extensão de ficheiro fora de tiff/jpg/jpeg/png/webp/pdf", "value": { "front_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf." ] } }, "File too large": { "summary": "O carregamento excede o limite de 10 MB", "value": { "front_image": [ "File size should not exceed 10 MB" ] } }, "Invalid option value": { "summary": "As opções apenas aceitam DECLINE ou NO_ACTION", "value": { "invalid_mrz_action": [ "\"REVIEW\" is not a valid choice." ] } }, "Encrypted PDF": { "summary": "PDF carregado sem a palavra-passe obrigatória", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "`front_image_password` / `back_image_password` não desencripta o PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } }, "Document not recognized": { "summary": "Nenhum documento de identificação pôde ser detetado na imagem", "value": { "error": "COULD_NOT_RECOGNIZE_DOCUMENT" } }, "PDF conversion failure": { "summary": "O PDF carregado não pôde ser convertido numa imagem", "value": { "error": "Failed to convert front image PDF." } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer processamento de imagens ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/id-verification/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'front_image=@./id_front.jpg' \\\n -F 'back_image=@./id_back.jpg' \\\n -F 'perform_document_liveness=true' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_verification.verify(\n front_image=open(\"front_image.jpg\", \"rb\"),\n back_image=open(\"back_image.jpg\", \"rb\"),\n perform_document_liveness=True,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"onboarding\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idVerification.verify({\n front_image: await fileFromPath(\"front_image.jpg\"),\n back_image: await fileFromPath(\"back_image.jpg\"),\n perform_document_liveness: true,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"onboarding\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.IdVerificationVerifyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idVerification().verify(IdVerificationVerifyParams.builder()\n .frontImage(Path.of(\"front_image.jpg\"))\n .backImage(Path.of(\"back_image.jpg\"))\n .performDocumentLiveness(true)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"onboarding\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idVerification->verify([\n 'front_image' => File::fromPath('front_image.jpg'),\n 'back_image' => File::fromPath('back_image.jpg'),\n 'perform_document_liveness' => true,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'onboarding'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_verification.verify(\n front_image: Pathname(\"front_image.jpg\"),\n back_image: Pathname(\"back_image.jpg\"),\n perform_document_liveness: true,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"onboarding\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams\n{\n FrontImage = FileUpload.FromPath(\"front_image.jpg\"),\n BackImage = FileUpload.FromPath(\"back_image.jpg\"),\n PerformDocumentLiveness = true,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"onboarding\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/face-match/": { "post": { "summary": "Correspondência facial", "description": "Compare duas imagens faciais (1:1) e obtenha uma pontuação (`score`) de similaridade (0–100), bem como um `status` `Approved`/`Declined`.\n\n**Como funciona.** Ambas as imagens são descodificadas e analisadas por um modelo biométrico (defina `rotate_image=true` se as capturas puderem estar de lado ou de cabeça para baixo); em seguida, é calculada uma pontuação de similaridade entre os dois rostos. Uma pontuação **estritamente superior** a `face_match_score_decline_threshold` (por predefinição `30`) devolve `status: \"Approved\"`; uma pontuação igual ou inferior devolve `Declined` com um aviso `LOW_FACE_MATCH_SIMILARITY`. Se não for de todo possível pontuar um par de rostos, a chamada continua a devolver `200` com `status: \"Declined\"` e um aviso `NO_REFERENCE_IMAGE` — `score` é `null` no caminho predefinido de gravação ou `0` com `save_api_request=false`. Envie um rosto nítido e virado para a frente por imagem para obter os melhores resultados.\n\n**Faturação.** Cada resposta `200` consome um crédito de API de Correspondência facial (pago a partir do crédito do seu plano ou do saldo de carregamento). Quando o saldo da organização não for suficiente para cobrir a chamada, o endpoint devolve `403` com o erro de créditos insuficientes antes de qualquer processamento de imagem.\n\n**Persistência de sessão (`save_api_request`, por predefinição `true`).** Quando for `true`, a chamada é persistida como uma sessão do tipo API: surge na Business Console, o `request_id` devolvido é um ID de sessão real que pode transmitir a `GET /v3/session/{sessionId}/decision/`, ambas as imagens são guardadas como as imagens de origem/destino de correspondência facial da sessão e é emitido um webhook `status.updated` para os endpoints de webhook que configurou. Quando for `false`, nada é guardado e `request_id` é um UUID de correlação único que não pode ser consultado mais tarde.\n\n**Índice de pesquisa facial.** Este endpoint nunca regista rostos no seu índice de pesquisa facial e nunca executa triagem de lista de bloqueio ou de duplicados — utilize `POST /v3/passive-liveness/` ou `POST /v3/face-search/` para essas operações.\n\n**Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada mal formatados continuam a devolver `400`), o endpoint devolve um payload simulado estático com `Approved`, nenhuma sessão é persistida e não são consumidos créditos.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limite de pedidos.** Limite partilhado de escrita de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; exceder este limite devolve `429`.", "operationId": "post_v3face-match", "x-didit-sdk": { "resource": "face_match", "method": "compare", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image", "ref_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "Imagem facial ao vivo ou candidata a verificar (por exemplo, uma selfie). Envie uma única fotografia frontal com o rosto do sujeito claramente visível e bem iluminado. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamanho máximo de carregamento: **5 MB** (ficheiros maiores são rejeitados com `400`). As imagens são comprimidas automaticamente para ~0.5 MB antes do processamento, pelo que resoluções muito elevadas não melhoram a precisão." }, "ref_image": { "type": "string", "format": "binary", "description": "Imagem facial de referência para comparação (por exemplo, a fotografia de um documento de identificação ou uma fotografia registada anteriormente). O mesmo formato e limites de tamanho que `user_image`." }, "face_match_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "Limiar de semelhança (0–100) que orienta o `status` da resposta. Uma pontuação calculada **igual ou inferior** a este valor define o `status` como `Declined` e adiciona um aviso `LOW_FACE_MATCH_SIMILARITY`; uma pontuação estritamente superior devolve `Approved`. O valor predefinido de `30` é permissivo — aumente-o (por exemplo, `50`–`60`) para uma verificação mais rigorosa. Valores fora de 0–100 devolvem `400`.", "example": 50 }, "rotate_image": { "type": "boolean", "default": false, "description": "Quando `true`, o serviço testa as imagens de entrada em incrementos de 90 graus (0, 90, 180, 270) e utiliza a orientação que produzir a melhor deteção facial — útil para capturas móveis sem orientação EXIF. Adiciona latência, pelo que só deve ativá-lo se não puder garantir imagens na orientação correta.", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido e anunciada através de um webhook `status.updated`. Quando for `false`, nada é armazenado e `request_id` é um UUID transitório apenas para correlação de respostas.", "example": true }, "vendor_data": { "type": "string", "description": "String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={\"flow\":\"login\"}`) — é convertido num objeto.", "example": { "flow": "login", "device_id": "abc123" } } } }, "example": { "user_image": "(binary JPEG/PNG of the live selfie)", "ref_image": "(binary JPEG/PNG of the reference photo)", "face_match_score_decline_threshold": 50, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "login" } } } } }, "responses": { "200": { "description": "Correspondência facial calculada. `face_match.score` é um número de ponto flutuante de 0–100 (duas casas decimais); `status` é `Approved` quando a pontuação está estritamente acima de `face_match_score_decline_threshold`, caso contrário é `Declined` com um aviso explicativo. Um par de baixa semelhança ou sem pontuação ainda devolve `200` — inspecione `face_match.status` e `face_match.warnings`, e não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id de sessão persistido.", "content": { "application/json": { "examples": { "Approved": { "summary": "Mesma pessoa — pontuação acima do limiar", "value": { "request_id": "f9f5a777-8002-44c6-baaf-128bcfd6e226", "face_match": { "status": "Approved", "score": 99.41, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "ref_image": { "entities": [ { "bbox": [ 653, 745, 1691, 2185 ], "confidence": 0.722082, "age": 27.0, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "login" }, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - low similarity": { "summary": "Pontuação igual ou inferior ao limiar de recusa", "value": { "request_id": "7cdda24e-311a-46d3-a3bb-e5d9b564ce73", "face_match": { "status": "Declined", "score": 24.87, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "ref_image": { "entities": [ { "bbox": [ 156, 234, 679, 898 ], "confidence": 0.717775, "age": 41.2, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "LOW_FACE_MATCH_SIMILARITY", "feature": "FACEMATCH", "additional_data": null, "log_type": "error", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:08:19.859116+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "face_match": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Approved` quando a pontuação de similaridade for estritamente superior a `face_match_score_decline_threshold` e tenha sido possível calcular uma pontuação; caso contrário, `Declined` (um aviso explica o motivo)." }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Pontuação de semelhança de 0 a 100 — a confiança do modelo de que ambas as imagens representam a mesma pessoa. Arredondada a duas casas decimais apenas quando `save_api_request` for true; com `save_api_request=false`, é devolvido o float não formatado. `null` quando nenhum par de rostos pôde ser pontuado (com a predefinição `save_api_request=true`); com `save_api_request=false`, a mesma condição pode surgir como `score: 0`. Em qualquer dos casos, um aviso `NO_REFERENCE_IMAGE` está presente e o `status` é `Declined`.", "example": 99.41 }, "user_image": { "type": "object", "description": "Resultados da deteção facial para as imagens analisadas.", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Caixa delimitadora do rosto detetado como coordenadas de píxeis `[x_min, y_min, x_max, y_max]` na imagem processada.", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Confiança da deteção facial (0–1).", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "Idade estimada pelo modelo para o rosto detetado, em anos. Apenas informativa — não afeta a decisão de correspondência facial.", "example": 26.91 }, "gender": { "type": "string", "description": "Género previsto pelo modelo para o rosto detetado (`male` ou `female`). Apenas informativo.", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "Campo reservado — sempre `null` nas respostas deste endpoint.", "example": null } } }, "description": "Uma entrada por rosto detetado." }, "best_angle": { "type": "integer", "description": "Rotação (graus: 0, 90, 180 ou 270) que produziu a melhor deteção facial. Diferente de zero apenas quando `rotate_image=true` corrigiu a orientação.", "example": 0 } } }, "ref_image": { "type": "object", "description": "Resultados da deteção facial para a imagem de referência, com o mesmo formato que `user_image`.", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Caixa delimitadora do rosto detetado como coordenadas de píxeis `[x_min, y_min, x_max, y_max]` na imagem processada.", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Confiança da deteção facial (0–1).", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "Idade estimada pelo modelo para o rosto detetado, em anos. Apenas informativa — não afeta a decisão de correspondência facial.", "example": 26.91 }, "gender": { "type": "string", "description": "Género previsto pelo modelo para o rosto detetado (`male` ou `female`). Apenas informativo.", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "Campo reservado — sempre `null` nas respostas deste endpoint.", "example": null } } }, "description": "Uma entrada por rosto detetado." }, "best_angle": { "type": "integer", "example": 0 } } }, "warnings": { "type": "array", "description": "Vazio numa aprovação limpa. `NO_REFERENCE_IMAGE` (`error`) — não foi possível pontuar nenhum par de faces; `LOW_FACE_MATCH_SIMILARITY` (`error`) — pontuação igual ou inferior ao limiar de recusa. Qualquer um destes define `status` como `Declined`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_REFERENCE_IMAGE", "LOW_FACE_MATCH_SIMILARITY" ], "description": "Código de risco legível por máquina." }, "feature": { "type": "string", "enum": [ "FACEMATCH" ], "description": "Funcionalidade que gerou o aviso. Sempre `FACEMATCH` neste endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Sempre `null` para avisos de correspondência facial." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravidade. Os avisos `error` alteram o `status` para `Declined`; as entradas `warning` e `information` são informativas e nunca recusam por si sós." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos sobre o risco." }, "long_description": { "type": "string", "description": "Explicação legível do risco." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, ou `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, ou `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada, por exemplo `2026-06-12T01:04:42.763237+00:00`." } } } } } }, "400": { "description": "Erro de validação. Devolvido quando uma imagem obrigatória está em falta, excede 5 MB, tem uma extensão não suportada ou quando uma opção está fora do intervalo. O corpo é o envelope padrão de erro de campo do DRF: um array de mensagens por campo afetado.", "content": { "application/json": { "examples": { "Missing required image": { "summary": "`ref_image` (ou `user_image`) não incluído nos dados do formulário", "value": { "ref_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Extensão de ficheiro fora de tiff/jpg/jpeg/png/webp", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "O carregamento excede o limite de 5 MB", "value": { "user_image": [ "File size should not exceed 5 MB" ] } }, "Threshold out of range": { "summary": "`face_match_score_decline_threshold` fora de 0–100", "value": { "face_match_score_decline_threshold": [ "Ensure this value is less than or equal to 100." ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer processamento de imagens ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/face-match/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'ref_image=@./id_portrait.jpg' \\\n -F 'face_match_score_decline_threshold=50' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.face_match.compare(\n user_image=open(\"user_image.jpg\", \"rb\"),\n ref_image=open(\"ref_image.jpg\", \"rb\"),\n face_match_score_decline_threshold=50.0,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"login\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.faceMatch.compare({\n user_image: await fileFromPath(\"user_image.jpg\"),\n ref_image: await fileFromPath(\"ref_image.jpg\"),\n face_match_score_decline_threshold: 50.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"login\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.FaceMatchCompareParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.faceMatch().compare(FaceMatchCompareParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .refImage(Path.of(\"ref_image.jpg\"))\n .faceMatchScoreDeclineThreshold(50.0)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"login\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "faceMatch->compare([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'ref_image' => File::fromPath('ref_image.jpg'),\n 'face_match_score_decline_threshold' => 50.0,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'login'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.face_match.compare(\n user_image: Pathname(\"user_image.jpg\"),\n ref_image: Pathname(\"ref_image.jpg\"),\n face_match_score_decline_threshold: 50.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"login\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n RefImage = FileUpload.FromPath(\"ref_image.jpg\"),\n FaceMatchScoreDeclineThreshold = 50.0,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"login\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/age-estimation/": { "post": { "summary": "Estimativa de idade (idade facial + prova de vida passiva)", "description": "Estime a idade de uma pessoa a partir de uma única fotografia do rosto e execute uma verificação de prova de vida passiva na mesma chamada — devolve o `age_estimation` previsto pelo modelo (em anos), um `score` de prova de vida (0–100) e um `status` `Approved`/`Declined`. A idade é **prevista pelo modelo a partir do rosto, não verificada contra um documento** — utilize-a para limites de idade e verificações de baixa fricção, não como prova legal de idade.\n\n**Como funciona.** A imagem é analisada para detetar rostos (defina `rotate_image=true` se as capturas puderem estar de lado ou invertidas); cada rosto detetado obtém uma idade estimada, e o maior rosto no enquadramento determina o `age_estimation`. Em paralelo, um modelo de prova de vida passiva avalia se a fotografia mostra uma pessoa viva (sem necessidade de desafio ao utilizador) e deteta ataques de apresentação (fotografias de fotografias, ecrãs, máscaras). Envie um rosto nítido, de frente e bem iluminado por imagem para obter os melhores resultados.\n\n**Lógica de decisão.** Qualquer aviso resulta numa recusa: o `status` é `Approved` apenas quando o array `warnings` está vazio. Um `score` de prova de vida igual ou inferior a `face_liveness_score_decline_threshold` (predefinição `30`) adiciona `LOW_LIVENESS_SCORE`; um ataque detetado adiciona `LIVENESS_FACE_ATTACK`; nenhum rosto encontrado pelo modelo de prova de vida adiciona `NO_FACE_DETECTED`; quando não for possível estimar a idade de um rosto, é adicionado `AGE_NOT_DETECTED` (`age_estimation` é `null`); uma idade estimada abaixo de `age_estimation_decline_threshold` (predefinição `18`) adiciona `AGE_BELOW_MINIMUM`. Idades limítrofes próximas do seu limiar justificam uma alternativa baseada em verificação por documento — o erro do modelo aumenta para rostos próximos do limite.\n\n**Faturação.** Cada resposta `200` consome um crédito da API de Estimativa de idade (pago a partir do crédito do seu plano ou do saldo carregado). Quando o saldo da organização não consegue cobrir a chamada, o endpoint devolve `403` com o erro de créditos insuficientes antes de qualquer processamento de imagem.\n\n**Persistência da sessão (`save_api_request`, predefinição `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API: aparece na Business Console, o `request_id` devolvido é um id de sessão real que pode passar para `GET /v3/session/{sessionId}/decision/` (o resultado é aí exposto em `liveness_checks[]`, com `features: [\"AGE_ESTIMATION\"]`), o recorte do rosto e a imagem de referência são armazenados, o embedding facial é adicionado ao índice de rostos da sua aplicação (utilizado pela pesquisa facial e deteção de duplicados) e é emitido um webhook `status.updated`. Quando `false`, nada é armazenado e `request_id` é um UUID de correlação pontual que não pode ser consultado mais tarde.\n\n**Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada mal formatados continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved` (`age_estimation: 30`, sem avisos), nenhuma sessão é persistida e não são consumidos créditos.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limite de pedidos.** Orçamento de escrita partilhado de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-lo devolve `429`.", "operationId": "post_v3age-estimation", "x-didit-sdk": { "resource": "age_estimation", "method": "estimate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "Foto de rosto a analisar (por exemplo, uma selfie). Envie uma única foto virada para a frente com o rosto do titular claramente visível e bem iluminado. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp` (sem PDF). Tamanho máximo de carregamento: **5 MB** (ficheiros maiores são rejeitados com `400`). As imagens são automaticamente comprimidas para ~0.3 MB antes do processamento, pelo que resoluções muito altas não melhoram a precisão." }, "face_liveness_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "Limiar de prova de vida (0–100). Um `score` de prova de vida **igual ou inferior** a este valor adiciona um aviso `LOW_LIVENESS_SCORE` e recusa. Aumente-o para um antispoofing mais rigoroso; valores fora de 0–100 devolvem `400`.", "example": 30 }, "age_estimation_decline_threshold": { "type": "integer", "default": 18, "minimum": 0, "maximum": 100, "description": "Idade estimada mínima aceitável em anos. Uma idade estimada **inferior** a este valor adiciona um aviso `AGE_BELOW_MINIMUM` e recusa. Defina `0` para desativar a verificação de idade (a chamada executará apenas a prova de vida + estimativa de idade sem uma decisão baseada na idade).", "example": 18 }, "rotate_image": { "type": "boolean", "default": false, "description": "Quando `true`, o serviço testa a imagem de entrada em incrementos de 90 graus (0, 90, 180, 270) e utiliza a orientação que produzir a melhor deteção facial — útil para capturas móveis sem orientação EXIF. Adiciona latência, pelo que só deve ativá-lo se não puder garantir imagens na orientação correta.", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido, anunciada através de um webhook `status.updated` e com o rosto detetado adicionado ao índice facial da sua aplicação. Quando for `false`, nada é armazenado e `request_id` é um UUID transitório apenas para correlação de respostas.", "example": true }, "vendor_data": { "type": "string", "description": "String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={\"flow\":\"age-gate\"}`) — é convertido num objeto.", "example": { "flow": "age-gate" } } } }, "example": { "user_image": "(binary JPEG/PNG of the selfie)", "face_liveness_score_decline_threshold": 30, "age_estimation_decline_threshold": 18, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "age-gate" } } } } }, "responses": { "200": { "description": "Estimativa de idade e prova de vida passiva concluídas. `age_estimation.age_estimation` é a idade prevista pelo modelo em anos para o maior rosto detetado (`null` se não houver nenhum); `age_estimation.score` é a pontuação de prova de vida passiva (0–100); `status` é `Approved` apenas quando `warnings` está vazio. Uma captura de um menor ou com spoofing continua a devolver `200` com `status: \"Declined\"` — inspecione o corpo, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id da sessão persistida.", "content": { "application/json": { "examples": { "Approved": { "summary": "Rosto adulto com prova de vida — ambas as verificações foram aprovadas", "value": { "request_id": "0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1", "age_estimation": { "status": "Approved", "method": "PASSIVE", "score": 97.5, "user_image": { "entities": [ { "age": 27.33, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "male" } ], "best_angle": 0 }, "age_estimation": 27.33, "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "age-gate" }, "created_at": "2026-06-12T02:24:11.512941+00:00" } }, "Declined - age below threshold": { "summary": "Idade estimada abaixo de `age_estimation_decline_threshold`", "value": { "request_id": "9be41a6f-2f4e-4f57-92f4-b3a4f6f0a1c2", "age_estimation": { "status": "Declined", "method": "PASSIVE", "score": 95.0, "user_image": { "entities": [ { "age": 16.5, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "female" } ], "best_angle": 0 }, "age_estimation": 16.5, "warnings": [ { "risk": "AGE_BELOW_MINIMUM", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Age below minimum", "long_description": "The age of the face is below the minimum age threshold for the application." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:26:40.118332+00:00" } }, "Declined - liveness too low": { "summary": "Pontuação de prova de vida igual ou inferior ao limiar de recusa (possível spoofing)", "value": { "request_id": "5f6f2f1f-7c4f-43b9-8d62-0a8f4c2d9e77", "age_estimation": { "status": "Declined", "method": "PASSIVE", "score": 5.0, "user_image": { "entities": [ { "age": 25.0, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "male" } ], "best_angle": 0 }, "age_estimation": 25.0, "warnings": [ { "risk": "LOW_LIVENESS_SCORE", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:27:02.901547+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "age_estimation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Approved` quando nenhum aviso tiver sido emitido; `Declined` caso contrário (todos os avisos gerados por este endpoint resultam em recusa)." }, "method": { "type": "string", "enum": [ "PASSIVE" ], "description": "Método de prova de vida. Sempre `PASSIVE` neste endpoint (imagem única, sem desafio ao utilizador)." }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Pontuação de prova de vida passiva de 0 a 100 — a confiança do modelo de que a fotografia mostra uma pessoa viva. Comparada com `face_liveness_score_decline_threshold`; com valor igual ou inferior, a chamada é recusada com `LOW_LIVENESS_SCORE`. `null` quando o modelo de prova de vida não devolve qualquer confiança — a chamada continua a ser recusada com `LOW_LIVENESS_SCORE`, pois null é tratado como 0 para a comparação com o limiar.", "example": 97.5 }, "user_image": { "type": "object", "description": "Resultados da deteção facial para a imagem analisada.", "properties": { "entities": { "type": "array", "description": "Uma entrada por rosto detetado. Vazio quando nenhum rosto foi encontrado (nesse caso, `age_estimation` é `null` e é adicionado um aviso `AGE_NOT_DETECTED`).", "items": { "type": "object", "properties": { "age": { "type": "number", "format": "float", "description": "Idade estimada pelo modelo para este rosto, em anos.", "example": 27.33 }, "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Caixa delimitadora do rosto detetado como coordenadas de píxeis `[x_min, y_min, x_max, y_max]` na imagem processada.", "example": [ 40, 40, 100, 100 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Confiança da deteção facial (0–1).", "example": 0.7177750468254089 }, "gender": { "type": "string", "description": "Género previsto pelo modelo para o rosto detetado (`male` ou `female`). Apenas informativo.", "example": "male" } } } }, "best_angle": { "type": "integer", "nullable": true, "description": "Rotação (graus: 0, 90, 180 ou 270) que produziu a melhor deteção facial. Diferente de zero apenas quando `rotate_image=true` corrigiu a orientação.", "example": 0 } } }, "age_estimation": { "type": "number", "format": "float", "nullable": true, "description": "Idade prevista pelo modelo, em anos, para o **maior** rosto detetado. `null` quando não foi possível estimar a idade do rosto (é adicionado um aviso `AGE_NOT_DETECTED` e a chamada é recusada).", "example": 27.33 }, "warnings": { "type": "array", "description": "Vazio numa aprovação limpa. Qualquer entrada define `status` como `Declined`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_FACE_DETECTED", "LOW_LIVENESS_SCORE", "LIVENESS_FACE_ATTACK", "AGE_NOT_DETECTED", "AGE_BELOW_MINIMUM" ], "description": "Código de risco legível por máquina. `NO_FACE_DETECTED` — o modelo de prova de vida não encontrou nenhum rosto; `LOW_LIVENESS_SCORE` — `score` de prova de vida igual ou inferior a `face_liveness_score_decline_threshold`; `LIVENESS_FACE_ATTACK` — foi detetado um ataque de apresentação (fotografia/ecrã/máscara); `AGE_NOT_DETECTED` — não foi possível estimar a idade do rosto; `AGE_BELOW_MINIMUM` — idade estimada abaixo de `age_estimation_decline_threshold`. `NO_FACE_DETECTED` e `LOW_LIVENESS_SCORE` são mutuamente exclusivos — quando nenhum rosto é encontrado, apenas `NO_FACE_DETECTED` é emitido." }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "Funcionalidade que gerou o aviso. Sempre `LIVENESS` neste endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Sempre `null` para avisos de estimativa de idade." }, "log_type": { "type": "string", "enum": [ "error" ], "description": "Gravidade. Todos os avisos produzidos por este endpoint são um `error` e definem o `status` como `Declined`." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos sobre o risco." }, "long_description": { "type": "string", "description": "Explicação legível do risco." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, ou `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, ou `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada." } } } } } }, "400": { "description": "Erro de validação. Devolvido quando `user_image` está em falta, excede 5 MB, tem uma extensão não suportada ou quando um limiar está fora do intervalo. O corpo é o envelope padrão de erro de campo do DRF: um array de mensagens por campo afetado.", "content": { "application/json": { "examples": { "Missing user image": { "summary": "`user_image` não incluído nos dados do formulário", "value": { "user_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Extensão de ficheiro fora de tiff/jpg/jpeg/png/webp", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "O carregamento excede o limite de 5 MB", "value": { "user_image": [ "File size should not exceed 5 MB" ] } }, "Threshold out of range": { "summary": "`face_liveness_score_decline_threshold` fora de 0–100", "value": { "face_liveness_score_decline_threshold": [ "Ensure this value is less than or equal to 100." ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer processamento de imagens ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/age-estimation/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'age_estimation_decline_threshold=18' \\\n -F 'face_liveness_score_decline_threshold=30' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.age_estimation.estimate(\n user_image=open(\"user_image.jpg\", \"rb\"),\n face_liveness_score_decline_threshold=30.0,\n age_estimation_decline_threshold=18,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"age-gate\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.ageEstimation.estimate({\n user_image: await fileFromPath(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n age_estimation_decline_threshold: 18,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"age-gate\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AgeEstimation.Estimate(ctx, didit.AgeEstimationEstimateParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tAgeEstimationDeclineThreshold: didit.Int(18),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"age-gate\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.AgeEstimationEstimateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.ageEstimation().estimate(AgeEstimationEstimateParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .faceLivenessScoreDeclineThreshold(30.0)\n .ageEstimationDeclineThreshold(18L)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"age-gate\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "ageEstimation->estimate([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'face_liveness_score_decline_threshold' => 30.0,\n 'age_estimation_decline_threshold' => 18,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'age-gate'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.age_estimation.estimate(\n user_image: Pathname(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n age_estimation_decline_threshold: 18,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"age-gate\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AgeEstimation.EstimateAsync(new AgeEstimationEstimateParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n FaceLivenessScoreDeclineThreshold = 30.0,\n AgeEstimationDeclineThreshold = 18,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"age-gate\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/poa/": { "post": { "summary": "Comprovativo de morada (OCR do documento + verificações de morada)", "description": "Extraia e valide um documento de Comprovativo de morada — faturas de serviços públicos, extratos bancários e documentos emitidos pelo governo — numa única chamada. Devolve o emissor, as datas de emissão/validade, o nome do titular, a morada bruta e processada/geocodificada, um `status` `Approved`/`Declined`, e uma lista de `warnings` que explica cada problema encontrado.\n\n**Latência.** A extração é baseada em LLM: as chamadas típicas demoram **5–15 segundos**, e PDFs de várias páginas até **~30 segundos**. Configure um tempo limite do cliente de **pelo menos 45 segundos** e não tente novamente antes de a chamada ser concluída.\n\n**Como funciona.** O documento (imagem ou PDF, até 15 MB; PDFs encriptados requerem `document_password`) é classificado num tipo e subtipo de documento (por exemplo, `UTILITY_BILL` / `WATER_BILL`), e o emissor, as datas, o nome do titular e a morada são extraídos através de extração baseada em LLM. A morada é processada e geocodificada em `poa_parsed_address`. A análise forense de PDF/EXIF verifica adulterações — modificação após assinatura digital, editores de PDF conhecidos, manipulação de texto sobreposto, reexportações suspeitas — apresentando `SUSPECTED_DOCUMENT_MANIPULATION` ou `DOCUMENT_METADATA_MISMATCH`. Um campo de texto que foi apagado e reescrito noutro tipo de letra, em que o próprio ficheiro não permite determinar se o seu conteúdo foi alterado, apresenta `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. A antiguidade do documento é validada em relação a `poa_document_age_months`, e o idioma em relação a `poa_languages_allowed`. Se transmitir `expected_address`, `expected_country` ou `expected_first_name`/`expected_last_name`, os valores extraídos são cruzados e as discrepâncias são sinalizadas.\n\n**Lógica de decisão.** O `status` é `Approved`, a menos que pelo menos um aviso resulte numa recusa. Falhas graves resultam sempre em recusa: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, além de `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` (não configuráveis neste endpoint). Cinco grupos de risco são configuráveis por pedido através das opções `poa_*_action` (`DECLINE` ou `NO_ACTION`, todas com predefinição `DECLINE`). `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` e `UNPARSABLE_OR_INVALID_ADDRESS` são informativos neste endpoint e nunca recusam. Um documento que não possa de todo ser processado devolve `400`; um documento legível mas problemático devolve `200` com `status: \"Declined\"` — inspecione sempre `poa.status` e `poa.warnings`, e não apenas o código HTTP.\n\n**Faturação.** Cada resposta `200` consome um crédito da API de Comprovativo de morada (pago a partir do crédito do seu plano ou do saldo de carregamento). Quando o saldo da organização não consegue cobrir a chamada, o endpoint devolve `403` com o erro de créditos insuficientes antes de qualquer processamento do documento.\n\n**Persistência da sessão (`save_api_request`, predefinição `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API: aparece na Business Console, o documento carregado é armazenado, o `request_id` devolvido é um ID de sessão real que pode passar para `GET /v3/session/{sessionId}/decision/` (a decisão expõe adicionalmente `document_file` e a análise forense em `document_metadata`, que esta resposta omite), e é emitido um webhook `status.updated`. Quando `false`, nada é armazenado e `request_id` é um UUID de correlação único que não pode ser consultado posteriormente.\n\n**Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada com formato incorreto continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved` (uma fatura de eletricidade fictícia da \"Sandbox Power Co.\"), nenhuma sessão é persistida e não são consumidos créditos.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limite de pedidos.** Limite partilhado de escrita de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-lo devolve `429`.\n\nNota: `FUTURE_ISSUE_DATE` e `POOR_DOCUMENT_QUALITY` existem em sessões de fluxo, mas nunca são gerados por este endpoint autónomo — um documento com data futura não é recusado automaticamente aqui.", "operationId": "post_v3poa", "x-didit-sdk": { "resource": "proof_of_address", "method": "verify", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "document" ], "properties": { "document": { "type": "string", "format": "binary", "description": "O documento de Comprovativo de morada. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. Tamanho máximo de carregamento: **15 MB** (ficheiros maiores são rejeitados com `400`). São suportados PDFs de várias páginas (espere uma latência mais elevada); PDFs encriptados exigem `document_password`. As imagens são comprimidas automaticamente antes do processamento." }, "document_password": { "type": "string", "description": "Palavra-passe para desencriptar `document` quando for um PDF encriptado. O envio de um PDF encriptado sem palavra-passe (ou com uma incorreta) devolve `400`.", "writeOnly": true }, "expected_address": { "type": "string", "description": "Morada a verificar contra o documento. É geocodificada e comparada com a morada extraída; uma divergência (ou uma morada esperada que não possa ser geocodificada/verificada) adiciona `ADDRESS_MISMATCH_WITH_PROVIDED`, regido por `poa_address_mismatch_action`. A forma geocodificada é devolvida em `expected_details_formatted_address` / `expected_details_parsed_address`.", "example": "Av. Monseñor Tavella 1291, Salta, Argentina" }, "expected_country": { "type": "string", "description": "País a verificar em relação ao documento (código ISO 3166-1, por ex., `ARG` ou `AR`). Uma discrepância com o país do documento adiciona `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, o que é regido por `poa_address_mismatch_action`.", "example": "ARG" }, "expected_first_name": { "type": "string", "description": "Primeiro nome a verificar contra `name_on_document` (correspondência difusa, sensível a transliteração). Uma pontuação abaixo do limiar de correspondência adiciona `NAME_MISMATCH_WITH_PROVIDED`, regido por `poa_address_mismatch_action`.", "example": "Sophia" }, "expected_last_name": { "type": "string", "description": "Apelido a verificar face a `name_on_document`, combinado com `expected_first_name` para a pontuação de correspondência.", "example": "Martinez" }, "poa_languages_allowed": { "type": "string", "description": "Lista separada por vírgulas de idiomas de documentos aceites como códigos ISO 639-1 (por exemplo, `en,es,fr`). Quando omitida ou em branco, são aceites **todos os 51 idiomas suportados**. Um documento num idioma fora da lista adiciona `UNSUPPORTED_DOCUMENT_LANGUAGE` (regulado por `poa_unsupported_language_action`); um código desconhecido na lista devolve `400` com o conjunto completo de códigos suportados.", "example": "en,es" }, "poa_document_age_months": { "type": "string", "description": "Pares `key:value` separados por vírgulas que definem a idade máxima do documento em meses por tipo de documento — chaves: `utility_bill`, `bank_statement`, `government_issued_document`, `other_poa_document`; valores: `1`–`120`, ou `-1` para ilimitado (sem verificação da idade). Valores predefinidos se omitido: `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. Um documento mais antigo do que o seu limite é recusado com `POA_DOCUMENT_EXPIRED`. **Atenção:** ao fornecer este campo, liste *todos* os tipos que aceita — os tipos omitidos são tratados como não aceites (informativo `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`) e a respetiva verificação da idade é ignorada.", "example": "utility_bill:3,bank_statement:6" }, "poa_name_mismatch_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Aceite, mas **atualmente não aplicado** — os avisos de não correspondência de nome (`NAME_MISMATCH_WITH_PROVIDED`) seguem `poa_address_mismatch_action`. Defina `poa_address_mismatch_action` para controlar o comportamento de não correspondência tanto de nome como de morada." }, "poa_document_issues_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "O que fazer perante problemas de integridade do ficheiro — na prática, apenas `DOCUMENT_METADATA_MISMATCH` é gerado por este endpoint." }, "poa_document_authenticity_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "O que fazer quando houver suspeita de manipulação do documento (`SUSPECTED_DOCUMENT_MANIPULATION`) — por ex., o PDF foi modificado após assinatura digital, processado por um editor de PDF conhecido, apresenta manipulação de texto sobreposto ou tem datas EXIF inconsistentes. Também rege `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (um campo de texto redigitado que o ficheiro não consegue comprovar se foi alterado ou não): `DECLINE` também o recusa, `NO_ACTION` mantém-no como aviso." }, "poa_unsupported_language_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "O que fazer quando o idioma do documento está fora de `poa_languages_allowed` (`UNSUPPORTED_DOCUMENT_LANGUAGE`)." }, "poa_address_mismatch_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "O que fazer quando os detalhes extraídos não coincidem com os campos `expected_*`: `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED` e `POA_COUNTRY_MISMATCH_WITH_PROVIDED` seguem todos esta ação." }, "poa_issuer_not_identified_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "O que fazer quando não for possível identificar nenhuma empresa/organização emissora no documento (`ISSUER_NOT_IDENTIFIED`)." }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido, anunciada através de um webhook `status.updated` e com o documento carregado armazenado. Quando for `false`, nada é armazenado e `request_id` é um UUID transitório apenas para correlação de respostas.", "example": true }, "vendor_data": { "type": "string", "description": "String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={\"flow\":\"onboarding\"}`) — é convertido num objeto.", "example": { "flow": "onboarding" } } } }, "example": { "document": "(binary JPEG/PNG/PDF of the utility bill or bank statement)", "expected_address": "Av. Monseñor Tavella 1291, Salta, Argentina", "expected_country": "ARG", "expected_first_name": "Sophia", "expected_last_name": "Martinez", "poa_languages_allowed": "en,es", "save_api_request": true, "vendor_data": "user-123" } } } }, "responses": { "200": { "description": "Documento processado. `poa.status` é `Approved` ou `Declined`; cada problema detetado é discriminado em `poa.warnings`. Um documento expirado, que não corresponde ou suspeito continua a devolver `200` com `status: \"Declined\"` — inspecione o corpo, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id da sessão persistida.", "content": { "application/json": { "examples": { "Approved": { "summary": "Fatura de serviços públicos lida sem problemas, sem verificações dos detalhes esperados", "value": { "request_id": "4b523a8d-ed32-45e4-8aa8-a89eda459d88", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2026-04-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "detected_codes": [ { "type": "QR_CODE", "page_number": 1, "position": [ [ 820, 1120 ], [ 1002, 1120 ], [ 1002, 1302 ], [ 820, 1302 ] ], "x": 820, "y": 1120, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==", "parsed_payload": "https://aguasdelnorte.com/factura/998811" }, { "type": "CODE_128", "page_number": 1, "position": [ [ 112, 1480 ], [ 560, 1480 ], [ 560, 1540 ], [ 112, 1540 ] ], "x": 112, "y": 1480, "width": 448, "height": 60, "page_width": 1190, "page_height": 1684, "raw_payload": "MDA5OTg4MTEwMDA0Mg==", "parsed_payload": "0099881100042" } ], "status": "Approved", "warnings": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:29:02.439655+00:00" } }, "Declined - document too old": { "summary": "Data de emissão anterior ao limite permitido por `poa_document_age_months`", "value": { "request_id": "f61681b8-9422-4378-ac3e-04c6a247fb45", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2021-02-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "status": "Declined", "warnings": [ { "risk": "POA_DOCUMENT_EXPIRED", "feature": "PROOF_OF_ADDRESS", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "WATER_BILL", "document_type": "UTILITY_BILL", "issue_date": "2021-02-10" }, "log_type": "error", "short_description": "Document expired", "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:23:02.165493+00:00" } }, "Declined - name mismatch": { "summary": "`expected_first_name`/`expected_last_name` não correspondem a `name_on_document`", "value": { "request_id": "0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2021-02-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "status": "Declined", "warnings": [ { "risk": "NAME_MISMATCH_WITH_PROVIDED", "feature": "PROOF_OF_ADDRESS", "additional_data": null, "log_type": "error", "short_description": "Name mismatch with provided information", "long_description": "The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:27:21.330172+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "poa": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Approved` quando nenhum aviso resultar numa recusa; `Declined` caso contrário — a lista `warnings` explica o motivo." }, "issuing_state": { "type": "string", "nullable": true, "description": "País onde o documento foi emitido, conforme extraído do documento — normalmente ISO 3166-1 alpha-3 (por ex., `ARG`).", "example": "ARG" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "Categoria de documento detetada. `UNKNOWN` significa que o documento não pôde ser classificado como um Comprovativo de morada aceitável e é automaticamente recusado com `INVALID_DOCUMENT_TYPE`. Nunca é nulo — falhas de classificação revertem para `UNKNOWN`." }, "document_subtype": { "type": "string", "description": "Classificação mais detalhada dentro de `document_type` — ex.: `ELECTRICITY_BILL`, `WATER_BILL`, `GAS_BILL`, `INTERNET_BILL`, `PHONE_BILL` (faturas de serviços públicos); `ACCOUNT_STATEMENT`, `CREDIT_CARD_STATEMENT` (extratos bancários); `TAX_ASSESSMENT`, `RESIDENCY_CERTIFICATE` (documentos governamentais). `UNKNOWN` quando não foi possível determinar o subtipo. Nunca é nulo — falhas de classificação recaem para `UNKNOWN`.", "example": "WATER_BILL" }, "document_language": { "type": "string", "nullable": true, "description": "Idioma do documento detetado (ISO 639-1).", "example": "es" }, "issuer": { "type": "string", "nullable": true, "description": "Empresa ou organização que emitiu o documento. `null` adiciona `ISSUER_NOT_IDENTIFIED`.", "example": "Aguas del Norte" }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "Data de emissão do documento (`YYYY-MM-DD`). `null` quando não foi possível extrair — o pedido é recusado com `UNABLE_TO_EXTRACT_ISSUE_DATE` neste endpoint.", "example": "2021-02-10" }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade explícita impressa no documento, quando presente. Independente da verificação de idade `poa_document_age_months`." }, "poa_address": { "type": "string", "nullable": true, "description": "Morada exatamente como impressa no documento. `null` recusa automaticamente com `MISSING_ADDRESS_INFORMATION`." }, "poa_formatted_address": { "type": "string", "nullable": true, "description": "Versão geocodificada e normalizada de `poa_address`.", "example": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina" }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "Detalhes estruturados e geocodificados da morada do documento. `null` quando a morada não pôde ser analisada.", "properties": { "street_1": { "type": "string", "nullable": true, "example": "Avenida Monseñor Tavella 1291" }, "street_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true, "example": "Salta" }, "region": { "type": "string", "nullable": true, "example": "Salta" }, "country": { "type": "string", "nullable": true, "description": "Código de país ISO 3166-1 alpha-2.", "example": "AR" }, "postal_code": { "type": "string", "nullable": true, "example": "A4400" }, "document_location": { "type": "object", "nullable": true, "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "description": "Coordenadas geocodificadas da morada do documento." } } }, "expected_details_address": { "type": "string", "nullable": true, "description": "Eco do `expected_address` que enviou, ou `null`." }, "expected_details_formatted_address": { "type": "string", "nullable": true, "description": "Versão geocodificada e normalizada de `expected_address`; `null` quando não fornecida ou não passível de geocodificação." }, "expected_details_parsed_address": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Resultado completo de geocodificação para `expected_address` (rua/cidade/região/país/código postal mais a saída bruta do geocodificador e um indicador `is_verified`). `null` quando `expected_address` não foi fornecido." }, "name_on_document": { "type": "string", "nullable": true, "description": "Nome do titular principal extraído do documento; comparado com `expected_first_name`/`expected_last_name` quando fornecido. `null` indica uma recusa com `POA_NAME_NOT_DETECTED` neste endpoint.", "example": "OESTE EMBOTELLADORA S.A." }, "extra_fields": { "type": "object", "description": "Dados adicionais específicos do documento. Os campos bancários são preenchidos para extratos bancários quando impressos no documento; `null` caso contrário.", "properties": { "bank_account_number": { "type": "string", "nullable": true }, "bank_iban": { "type": "string", "nullable": true }, "bank_sort_code": { "type": "string", "nullable": true }, "bank_routing_number": { "type": "string", "nullable": true }, "bank_swift_bic": { "type": "string", "nullable": true }, "bank_branch_name": { "type": "string", "nullable": true }, "bank_branch_address": { "type": "string", "nullable": true }, "document_phone_number": { "type": "string", "nullable": true, "description": "Número de telefone de contacto impresso no documento." }, "additional_names": { "type": "array", "items": { "type": "string" }, "description": "Outros nomes de titulares encontrados no documento (por exemplo, cotitulares de conta, nomes de conta anteriores)." } } }, "warnings": { "type": "array", "description": "Vazio numa aprovação limpa. Cada entrada explica um risco detetado; entradas com `log_type: \"error\"` definem `status` como `Declined`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "Código de risco legível por máquina. Recusa obrigatória: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, mais `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` (definidos para recusar neste endpoint). Determinados pelas opções do pedido: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED` (`poa_address_mismatch_action`), `POOR_DOCUMENT_QUALITY` (nunca gerado por este endpoint) / `DOCUMENT_METADATA_MISMATCH` (`poa_document_issues_action`), `SUSPECTED_DOCUMENT_MANIPULATION` e `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (`poa_document_authenticity_action`), `UNSUPPORTED_DOCUMENT_LANGUAGE` (`poa_unsupported_language_action`), `ISSUER_NOT_IDENTIFIED` (`poa_issuer_not_identified_action`). Informativos neste endpoint: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNPARSABLE_OR_INVALID_ADDRESS`.", "example": "POA_DOCUMENT_EXPIRED" }, "feature": { "type": "string", "enum": [ "PROOF_OF_ADDRESS" ], "description": "Funcionalidade que gerou o aviso. Sempre `PROOF_OF_ADDRESS` neste endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contexto adicional para alguns riscos — por exemplo, `POA_DOCUMENT_EXPIRED` inclui `expiration_reason` (`printed_expiration` ou `age_window`), `document_type`, `document_subtype` e `issue_date`, além de `expiration_date` no caminho `printed_expiration` ou `max_age_months` no caminho `age_window`; `SUSPECTED_DOCUMENT_MANIPULATION` inclui `reason` e `detection_method`; `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` inclui `reason`, `detection_method` (`unproven_text_replacement`), `replaced_text`, `manipulated_regions` e `manipulated_blocks`. `null` para a maioria dos riscos." }, "log_type": { "type": "string", "enum": [ "error", "information" ], "description": "Gravidade. Os avisos `error` alteram o `status` para `Declined`; as entradas `information` são informativas e nunca recusam por si sós. (`warning` não é produzido por este endpoint — as suas opções só aceitam `DECLINE` ou `NO_ACTION`.)" }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos sobre o risco." }, "long_description": { "type": "string", "description": "Explicação legível do risco." } } } }, "detected_codes": { "type": "array", "description": "Códigos QR e códigos de barras detetados em todas as páginas processadas do documento. Vazio quando nenhum é encontrado. Um código QR localizado mas não descodificável tem `parsed_payload: null`.", "items": { "$ref": "#/components/schemas/DocumentAIDetectedCode" } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, ou `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, ou `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada." } } } } } }, "400": { "description": "Erro de validação ou de processamento. Problemas ao nível do campo devolvem o envelope padrão do DRF (um array de mensagens por campo afetado). Problemas com PDF encriptado devolvem `{\"detail\": ...}`. Um documento que o pipeline de extração não consiga processar devolve `{\"error\": [\"Error extracting POA information\"]}`.", "content": { "application/json": { "examples": { "Missing document": { "summary": "`document` não incluído nos dados do formulário", "value": { "document": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Extensão de ficheiro fora de tiff/jpg/jpeg/png/pdf/webp", "value": { "document": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp." ] } }, "File too large": { "summary": "O carregamento excede o limite de 15 MB", "value": { "document": [ "File size should not exceed 15 MB" ] } }, "Encrypted PDF": { "summary": "PDF carregado sem a palavra-passe obrigatória", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "`document_password` não desencripta o PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } }, "Invalid language code": { "summary": "`poa_languages_allowed` contém um código não suportado", "value": { "poa_languages_allowed": [ "Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']." ] } }, "Invalid document age value": { "summary": "valor de `poa_document_age_months` fora do intervalo 1–120 / -1", "value": { "poa_document_age_months": [ "Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120." ] } }, "Extraction failure": { "summary": "Não foi possível processar o documento através do pipeline de extração", "value": { "error": [ "Error extracting POA information" ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer processamento de documentos ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/poa/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'document=@./utility-bill.pdf' \\\n -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \\\n -F 'expected_country=ARG' \\\n -F 'expected_first_name=Sophia' \\\n -F 'expected_last_name=Martinez' \\\n -F 'poa_languages_allowed=en,es' \\\n -F 'vendor_data=user-123' \\\n --max-time 45" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.proof_of_address.verify(\n document=open(\"document.pdf\", \"rb\"),\n expected_address=\"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country=\"ARG\",\n expected_first_name=\"Sophia\",\n expected_last_name=\"Martinez\",\n poa_languages_allowed=\"en,es\",\n save_api_request=True,\n vendor_data=\"user-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.proofOfAddress.verify({\n document: await fileFromPath(\"document.pdf\"),\n expected_address: \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country: \"ARG\",\n expected_first_name: \"Sophia\",\n expected_last_name: \"Martinez\",\n poa_languages_allowed: \"en,es\",\n save_api_request: true,\n vendor_data: \"user-123\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.ProofOfAddressVerifyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder()\n .document(Path.of(\"document.pdf\"))\n .expectedAddress(\"Av. Monseñor Tavella 1291, Salta, Argentina\")\n .expectedCountry(\"ARG\")\n .expectedFirstName(\"Sophia\")\n .expectedLastName(\"Martinez\")\n .poaLanguagesAllowed(\"en,es\")\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "proofOfAddress->verify([\n 'document' => File::fromPath('document.pdf'),\n 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina',\n 'expected_country' => 'ARG',\n 'expected_first_name' => 'Sophia',\n 'expected_last_name' => 'Martinez',\n 'poa_languages_allowed' => 'en,es',\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.proof_of_address.verify(\n document: Pathname(\"document.pdf\"),\n expected_address: \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country: \"ARG\",\n expected_first_name: \"Sophia\",\n expected_last_name: \"Martinez\",\n poa_languages_allowed: \"en,es\",\n save_api_request: true,\n vendor_data: \"user-123\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams\n{\n Document = FileUpload.FromPath(\"document.pdf\"),\n ExpectedAddress = \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n ExpectedCountry = \"ARG\",\n ExpectedFirstName = \"Sophia\",\n ExpectedLastName = \"Martinez\",\n PoaLanguagesAllowed = \"en,es\",\n SaveApiRequest = true,\n VendorData = \"user-123\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/document-ai/": { "post": { "summary": "Document AI (extração de campos personalizados + verificações de adulteração)", "description": "Extraia os campos que **você** definir de qualquer documento comprovativo — recibos de vencimento, comprovativo de fundos, cartas sobre a origem do património, declarações fiscais, contratos, faturas — numa única chamada. Envie o ficheiro juntamente com uma definição de `fields` (chave, nome, instrução de extração, tipo) e receba valores tipados (`text`, `number`, `date` como `YYYY-MM-DD`), uma pontuação opcional de correspondência de nome com a pessoa ou empresa esperada, sinais de adulteração de PDF/EXIF, um `status` `Approved`/`Declined`/`In Review`, e uma lista de `warnings` a explicar cada problema encontrado. Esta é a contrapartida servidor a servidor do passo do fluxo Document AI alojado (consulte `/core-technology/document-ai/overview`); utiliza o modelo de extração predefinido da Didit e não expõe a seleção de fornecedor.\n\n**Latência.** A extração é baseada em LLM: as chamadas típicas demoram **5–15 segundos**, PDFs de várias páginas até **~30 segundos**. Configure um tempo limite do cliente de **pelo menos 45 segundos** e não tente novamente antes de a chamada ser concluída.\n\n**Formato do pedido.** Apenas `multipart/form-data`. `fields` é **uma string de array codificada em JSON** (1–30 itens, no máximo 16 KB); arrays de formulário no formato de parênteses retos são rejeitados com `400`. Cada item é `{key, name, instruction, type, required, is_full_name}` — `key` é a chave JSON devolvida (`^[a-z0-9_]{1,64}$`, única), `instruction` indica ao modelo o que ler, `type` é `text` (predefinição) | `number` | `date`, `required` gera `DOCUMENT_AI_MISSING_REQUIRED_FIELDS` quando o valor não pode ser lido, e no máximo um campo pode definir `is_full_name: true` para marcar o valor comparado com o nome esperado.\n\n**Correspondência de nomes.** Passe `expected_first_name` + `expected_last_name` (pessoa) **ou** `expected_company_name` (+ opcionalmente `expected_company_country`) — não ambos. O valor do campo `is_full_name` (ou, quando nenhum estiver marcado, o primeiro campo de texto cuja chave se assemelhe a um nome) é comparado de forma aproximada; `name_match_score` (0–100) e `name_on_document` são sempre devolvidos quando ambos os lados existirem, e uma pontuação abaixo de `document_ai_name_match_score_threshold` (predefinição 80) adiciona `DOCUMENT_AI_NAME_MISMATCH`, controlado por `document_ai_name_mismatch_action`.\n\n**Lógica de decisão.** Cada risco mapeia para uma ação configurável: `DECLINE` → `status: \"Declined\"`, `REVIEW` → `status: \"In Review\"`, `NO_ACTION` → apenas informativo. As predefinições refletem o passo do fluxo: documento ilegível `REVIEW`, campos obrigatórios em falta `REVIEW`, suspeita de manipulação `DECLINE`, discrepância de nome `NO_ACTION`, ficheiro não suportado `REVIEW`. Um documento que não possa de todo ser processado devolve `400`; um documento legível mas com problemas devolve `200` com `Declined`/`In Review` — inspecione sempre `document_ai.status` e `document_ai.warnings`, e não apenas o código HTTP.\n\n**Faturação.** Cada resposta `200` consome um crédito da API de Document AI — **$0.20 por documento** ao preço de tabela, pagos a partir do crédito do seu plano ou do saldo de carregamento. Quando o saldo da organização não cobrir a chamada, o endpoint devolve `403` antes de qualquer processamento. As chaves de API da sandbox devolvem uma resposta simulada determinística e não são cobradas.\n\n**Persistência.** Com `save_api_request=true` (predefinição), a chamada é armazenada como uma sessão do tipo API: o documento, os valores extraídos, as definições de campos e o instantâneo da correspondência de nomes são guardados, a sessão aparece na Business Console e o `request_id` funciona com `GET /v3/session/{sessionId}/decision/`.", "operationId": "post_v3document-ai", "x-didit-sdk": { "resource": "document_ai", "method": "analyze", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "document", "fields" ], "properties": { "document": { "type": "string", "format": "binary", "description": "O documento a ler. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`, `zip`. Tamanho máximo de carregamento: **30 MB** (ficheiros maiores são rejeitados com `400`). São suportados PDFs de várias páginas (espere uma latência superior); PDFs encriptados são rejeitados com `400`. As imagens são comprimidas automaticamente antes do processamento." }, "fields": { "type": "string", "description": "Uma cadeia de caracteres que representa um array codificado em JSON com **1–30** definições de campos (máximo de 16 KB). Cada item: `key` (obrigatório, `^[a-z0-9_]{1,64}$`, exclusivo — a chave devolvida em `extracted_data`), `name` (≤100 caracteres, apresentado nas mensagens), `instruction` (≤500 caracteres, o que o modelo deve ler), `type` (`text` predefinido | `number` | `date`), `required` (booleano, predefinição `false`), `is_full_name` (booleano, predefinição `false`, no máximo um por pedido). Arrays de formulário com estilo de parênteses retos, JSON inválido, chaves duplicadas ou mais do que um `is_full_name` devolvem `400` antes de qualquer processamento ou faturação.", "example": "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]" }, "expected_first_name": { "type": "string", "description": "Primeiro nome a verificar contra o campo do nome do documento (correspondência difusa, sensível a transliteração). Utilize em conjunto com `expected_last_name`; não pode ser combinado com `expected_company_name`.", "example": "Sophia" }, "expected_last_name": { "type": "string", "description": "Apelido a verificar face ao campo de nome do documento, combinado com `expected_first_name` para `name_match_score`.", "example": "Martinez" }, "expected_company_name": { "type": "string", "description": "Nome da empresa a verificar contra o campo de nome do documento (para documentos de empresas). Não pode ser combinado com `expected_first_name` / `expected_last_name` (intencionalmente sem valor de exemplo — a amostra de pedido gerada utiliza os campos de pessoa; substitua-os por este ao verificar um documento de empresa)." }, "expected_company_country": { "type": "string", "description": "Código de país ISO 3166-1 alpha-2 opcional (duas letras ASCII, por exemplo, `FR`) que ajusta a normalização do nome da empresa para `expected_company_name`. Utilizado apenas com `expected_company_name`." }, "document_ai_name_match_score_threshold": { "type": "integer", "minimum": 0, "maximum": 100, "default": 80, "description": "Valor mínimo de `name_match_score` (0–100) para considerar que o nome coincide. Uma pontuação inferior adiciona `DOCUMENT_AI_NAME_MISMATCH`, regulado por `document_ai_name_mismatch_action`.", "example": 80 }, "document_ai_unreadable_document_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "O que fazer quando nenhum campo puder ser lido do documento (`DOCUMENT_AI_UNREADABLE_DOCUMENT`)." }, "document_ai_missing_required_fields_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "O que fazer quando não for possível ler pelo menos um campo `required` (`DOCUMENT_AI_MISSING_REQUIRED_FIELDS`; `additional_data.missing_fields` lista-os)." }, "document_ai_document_tampering_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "DECLINE", "description": "O que fazer quando a análise forense de PDF/EXIF suspeitar de manipulação — modificado após assinatura digital, editor de PDF conhecido, manipulação de texto sobreposto, reexportação suspeita, anomalias na imagem (`DOCUMENT_AI_SUSPECTED_MANIPULATION`)." }, "document_ai_name_mismatch_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "NO_ACTION", "description": "O que fazer quando `name_match_score` estiver abaixo do limiar (`DOCUMENT_AI_NAME_MISMATCH`)." }, "document_ai_unsupported_file_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "O que fazer quando o carregamento está vazio ou não é um ficheiro processável (`DOCUMENT_AI_UNSUPPORTED_FILE`)." }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido, com o documento carregado, os valores extraídos, as definições de campos e o instantâneo da correspondência de nomes armazenados. Quando for `false`, nada é armazenado e `request_id` é um UUID transitório apenas para correlação de respostas; a chamada continua a ser faturada.", "example": true }, "vendor_data": { "type": "string", "description": "String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={\"flow\":\"onboarding\"}`) — é convertido num objeto.", "example": { "flow": "onboarding" } } } } } } }, "responses": { "200": { "description": "Documento processado. `document_ai.status` é `Approved`, `Declined` ou `In Review`; cada problema detetado é discriminado em `document_ai.warnings`. Um documento com problemas continua a devolver `200` — inspecione o corpo, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id da sessão persistida.", "content": { "application/json": { "examples": { "Approved": { "summary": "Recibo de vencimento lido com sucesso, nome correspondente", "value": { "request_id": "9d6a3b1e-2f0c-4a8e-9b7d-1c2e3f4a5b6c", "document_ai": { "status": "Approved", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" }, "detected_codes": [ { "type": "CODE_128", "page_number": 1, "position": [ [ 96, 456 ], [ 96, 616 ], [ 1012, 611 ], [ 1015, 456 ] ], "x": 96, "y": 456, "width": 919, "height": 160, "page_width": 1200, "page_height": 1700, "raw_payload": "SU5WLTIwMjYtMDA0Mg==", "parsed_payload": "INV-2026-0042" } ], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": 100.0, "name_on_document": "Sophia Martinez", "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "onboarding" }, "created_at": "2026-08-19T16:40:12.318Z" } }, "In Review — missing required field": { "summary": "não foi possível ler `net_pay`; ação predefinida REVIEW", "value": { "request_id": "3f2a9c7b-5d4e-4b1a-8c6f-0e9d8c7b6a5f", "document_ai": { "status": "In Review", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": null, "pay_date": "2026-07-31" }, "detected_codes": [], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": 100.0, "name_on_document": "Sophia Martinez", "warnings": [ { "risk": "DOCUMENT_AI_MISSING_REQUIRED_FIELDS", "feature": "DOCUMENT_AI", "additional_data": { "missing_fields": [ "Net pay" ] }, "log_type": "warning", "short_description": "Required fields could not be extracted", "long_description": "One or more fields configured as required could not be extracted from the uploaded document." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-08-19T16:41:05.002Z" } }, "Declined — suspected manipulation": { "summary": "A análise forense de PDF sinalizou um editor conhecido; ação predefinida DECLINE", "value": { "request_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "document_ai": { "status": "Declined", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" }, "detected_codes": [], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": null, "name_on_document": "Sophia Martinez", "warnings": [ { "risk": "DOCUMENT_AI_SUSPECTED_MANIPULATION", "feature": "DOCUMENT_AI", "additional_data": { "detection_method": "known_editor", "processed_by_known_editor": "ilovepdf" }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential manipulation or editing in the uploaded document." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-08-19T16:42:40.771Z" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "document_ai": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "`Approved` quando nenhum aviso resultar numa recusa ou revisão; `Declined` quando pelo menos um risco mapear para `DECLINE`; caso contrário, `In Review` quando pelo menos um mapear para `REVIEW`. A lista `warnings` explica o motivo." }, "extracted_data": { "type": "object", "additionalProperties": true, "description": "Uma entrada por chave de campo solicitada. Os valores são tipados de acordo com o `type` do campo — strings para `text`, números para `number`, strings `YYYY-MM-DD` para `date` — ou `null` quando o valor não pôde ser lido.", "example": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" } }, "detected_codes": { "type": "array", "description": "Códigos QR e códigos de barras detetados em todas as páginas processadas. Vazio quando nenhum é encontrado. Um código QR localizado mas não descodificável tem `parsed_payload: null`.", "items": { "$ref": "#/components/schemas/DocumentAIDetectedCode" } }, "fields": { "type": "array", "description": "As definições normalizadas dos campos utilizadas para esta extração, devolvidas na resposta (também armazenadas com a sessão quando `save_api_request=true`).", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "instruction": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date" ] }, "required": { "type": "boolean" }, "is_full_name": { "type": "boolean" } } } }, "name_match_score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "description": "Semelhança difusa (0–100) entre `name_on_document` e o nome esperado da pessoa/empresa. Devolvido sempre que existirem tanto um valor de nome como um nome esperado — em correspondências **e** não correspondências; `null` caso contrário.", "example": 96.0 }, "name_on_document": { "type": "string", "nullable": true, "description": "O valor do nome extraído do documento (o campo `is_full_name`, ou o primeiro campo de texto semelhante a um nome) que foi comparado com o nome esperado. `null` quando nenhum valor de nome estava disponível.", "example": "Sophia Martinez" }, "warnings": { "type": "array", "description": "Vazio numa aprovação limpa. Cada entrada explica um risco detetado; entradas com `log_type: \"error\"` definem `status` como `Declined`, entradas com `log_type: \"warning\"` definem-no como `In Review`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "DOCUMENT_AI_UNREADABLE_DOCUMENT", "DOCUMENT_AI_MISSING_REQUIRED_FIELDS", "DOCUMENT_AI_SUSPECTED_MANIPULATION", "DOCUMENT_AI_NAME_MISMATCH", "DOCUMENT_AI_UNSUPPORTED_FILE" ], "description": "Código de risco legível por máquina. Cada um é determinado pela opção correspondente no pedido `document_ai_*_action`.", "example": "DOCUMENT_AI_MISSING_REQUIRED_FIELDS" }, "feature": { "type": "string", "enum": [ "DOCUMENT_AI" ], "description": "Funcionalidade que gerou o aviso. Sempre `DOCUMENT_AI` neste endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contexto adicional para o risco: `{\"missing_fields\": [\"Net pay\"]}` para campos obrigatórios em falta, `{\"name_on_document\", \"score\", \"threshold\"}` para uma discrepância de nome e a conclusão forense (`detection_method`, detalhes do produtor/editor) para suspeita de manipulação. `null` quando não houver nada a acrescentar.", "example": { "missing_fields": [ "Net pay" ] } }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravidade derivada da ação configurada: `error` (DECLINE), `warning` (REVIEW), `information` (NO_ACTION)." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos para o risco.", "example": "Required fields could not be extracted" }, "long_description": { "type": "string", "description": "Explicação legível, interpolada com `additional_data` quando relevante." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, ou `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, ou `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando o pedido foi processado (UTC, ISO 8601)." } } } } } }, "400": { "description": "Erro de validação ou de processamento. Problemas ao nível do campo devolvem o envelope padrão do DRF (um array de mensagens por campo afetado). Documentos encriptados ou ilegíveis e falhas de extração devolvem `{\"error\": ...}`.", "content": { "application/json": { "examples": { "Missing document": { "summary": "`document` não incluído nos dados do formulário", "value": { "document": [ "No file was submitted." ] } }, "Invalid fields payload": { "summary": "`fields` não é uma string de array codificada em JSON", "value": { "fields": [ "fields must be a valid JSON array string." ] } }, "Duplicate field keys": { "summary": "Dois itens partilham a mesma `key`", "value": { "fields": [ "Every fields item must have a unique key." ] } }, "Conflicting expectations": { "summary": "Valores esperados de pessoa e empresa enviados em conjunto", "value": { "non_field_errors": [ "Provide either person expected-name fields or expected_company_name, not both." ] } }, "Invalid metadata": { "summary": "`metadata` não é um objeto JSON (ou contém um caráter NUL)", "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Oversized vendor_data": { "summary": "`vendor_data` acima do limite de 2.000 bytes", "value": { "vendor_data": [ "vendor_data is too long (maximum 2000 bytes)." ] } }, "Encrypted PDF": { "summary": "PDF protegido por palavra-passe", "value": { "error": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Extraction failed": { "summary": "O pipeline de extração não conseguiu processar o documento", "value": { "error": [ "Error extracting Document AI information" ] } } }, "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos — e organizações com faturação por contrato cuja tabela de preços não tenha uma entrada para a Document AI API — devolvem `403` com `{\"error\": ...}` antes de qualquer processamento de documentos ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } }, "Contract rate missing": { "summary": "Organização faturada por contrato cuja tabela de preços não tem entrada para a API do Document AI", "value": { "error": "Document AI API is not included in your contract rate card. Contact support@didit.me to enable it." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "error": { "type": "string" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.document_ai.analyze(\n document=open(\"document.pdf\", \"rb\"),\n fields=\"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.documentAi.analyze({\n document: await fileFromPath(\"document.pdf\"),\n fields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DocumentAi.Analyze(ctx, didit.DocumentAiAnalyzeParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tFields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.DocumentAiAnalyzeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.documentAi().analyze(DocumentAiAnalyzeParams.builder()\n .document(Path.of(\"document.pdf\"))\n .fields(\"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "documentAi->analyze([\n 'document' => File::fromPath('document.pdf'),\n 'fields' => '[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.document_ai.analyze(\n document: Pathname(\"document.pdf\"),\n fields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.DocumentAi.AnalyzeAsync(new DocumentAiAnalyzeParams\n{\n Document = FileUpload.FromPath(\"document.pdf\"),\n Fields = \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/aml/": { "post": { "summary": "Triagem AML (independente)", "operationId": "post_v3aml", "x-didit-sdk": { "resource": "aml", "method": "screen", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave opcional de proteção contra repetições, até 255 carateres. Reutilizar a mesma chave com o mesmo corpo do pedido devolve a resposta original sem executar nem faturar uma segunda triagem. Reutilizar a chave com um corpo diferente devolve `409`.", "schema": { "type": "string", "maxLength": 255 } } ], "description": "Faça a triagem de uma pessoa ou empresa em conjuntos de dados de PEP, sanções, listas de aviso/vigilância e notícias adversas numa única chamada.\n\n**Modelo de duas pontuações.** Cada resultado inclui um `match_score` (0–100, confiança na identidade) e um `risk_score` (0–100, risco da entidade). Os resultados cujo `match_score` seja inferior a `aml_match_score_threshold` (por predefinição **93**) são marcados como `review_status: \"False Positive\"` e ignorados para efeitos de risco; o `risk_score` mais elevado entre os restantes resultados torna-se `aml.score`. O `aml.status` final segue os seus limiares: `score` > `aml_score_review_threshold` (por predefinição **100**) → `Declined`; `score` > `aml_score_approve_threshold` (por predefinição **80**) → `In Review`; caso contrário, `Approved`. Sempre que `score` for diferente de zero e ≥ ao limiar de aprovação, é adicionado um aviso `POSSIBLE_MATCH_FOUND` (uma pontuação exatamente de 0 nunca emite aviso).\n\n**Pesos da pontuação de correspondência.** `aml_name_weight` + `aml_dob_weight` + `aml_country_weight` devem somar exatamente 100 (valores predefinidos: 60/25/15). Os componentes omissos no pedido são excluídos e os pesos dos restantes são renormalizados; um `document_number` correspondente atua como chave de ouro que sobrepõe o `match_score` para 100.\n\n**Latência.** As triagens simples demoram normalmente alguns segundos a concluir. Com `include_adverse_media=true`, a API aguarda pelo enriquecimento de notícias adversas (uma pausa inicial de ~5 s mais até ~25 s de consultas periódicas) — configure um timeout do cliente de **pelo menos 60 segundos**.\n\n**Persistência.** `save_api_request` tem o valor predefinido **true**: a triagem é guardada como uma sessão (`request_id` funciona com `GET /v3/session/{sessionId}/decision/`), surge na consola, o webhook `status.updated` é disparado e os estados de revisão dos resultados podem ser atualizados posteriormente. Com `save_api_request=false`, nada é armazenado e `request_id` é um ID de correlação transitório. `include_ongoing_monitoring=true` continua a realizar novas triagens ao perfil e requer `save_api_request=true` (imposto com um `400`).\n\n**Idempotência.** Envie um cabeçalho `Idempotency-Key` ao tentar novamente após um timeout ou erro transitório. A chave está associada à sua aplicação e ao corpo exato do pedido. O primeiro pedido concluído armazena a sua resposta; tentativas posteriores idênticas devolvem essa mesma resposta e não executam nem faturam outra triagem AML. Se o pedido original ainda estiver em execução, tente novamente mais tarde com a mesma chave. Se a mesma chave for reutilizada com um corpo diferente, a API devolve `409`.\n\n**Faturação.** É debitado um crédito de API AML após a primeira triagem bem-sucedida. Respostas idempotentes reproduzidas não são cobradas novamente; saldo insuficiente devolve `403` antes de ocorrer qualquer nova triagem.\n\n**Sandbox.** As chaves de aplicações sandbox ignoram totalmente a triagem e a faturação e devolvem um resultado simulado — `Approved` sem qualquer resultado, a menos que passe `sandbox_scenario`. `save_api_request` funciona do mesmo modo que nas chaves de produção, pelo que uma triagem sandbox guardada pode ser consultada através de `GET /v3/session/{sessionId}/decision/` e `GET /v3/session/{sessionId}/generate-pdf/`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "full_name" ], "properties": { "full_name": { "type": "string", "minLength": 2, "description": "Nome completo da pessoa ou empresa a analisar na triagem. Mínimo de **2 caracteres** - o limite mínimo do próprio fornecedor de triagem. Um nome mais curto ou em branco retorna `400` neste campo antes de qualquer triagem ser executada, pelo que nada é faturado.", "example": "Antonio Ejemplo Modelo" }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "default": "person", "description": "Tipo de entidade a analisar. O valor predefinido é `person`." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data de nascimento (pessoas) ou data de constituição (empresas), `YYYY-MM-DD`. Melhora a precisão da correspondência através do peso da data de nascimento.", "example": "1972-02-29" }, "nationality": { "type": "string", "description": "Código de país ISO 3166-1 **alpha-2** (ex.: `ES`). Códigos inválidos retornam `400`. Melhora a precisão da correspondência através do peso do país.", "example": "ES" }, "document_number": { "type": "string", "description": "Número do documento de identidade. Sem ponderação — funciona como chave mestre: uma correspondência exata substitui a `match_score` da ocorrência por 100, uma divergência estrita penaliza-a. Enviado ao fornecedor de triagem como filtro de pesquisa apenas se tiver entre **2 e 50 carateres**; um valor fora desse intervalo é aceite e armazenado, e a triagem é executada e faturada, apenas sem refinamento pelo número de documento." }, "aml_score_approve_threshold": { "type": "number", "minimum": 0, "maximum": 100, "default": 80, "description": "Limiar de pontuação de risco igual ou inferior ao qual o resultado é `Approved`. Deve ser ≤ `aml_score_review_threshold` (caso contrário, `400`)." }, "aml_score_review_threshold": { "type": "number", "minimum": 0, "maximum": 100, "default": 100, "description": "Limiar de pontuação de risco acima do qual o resultado é `Declined`. Pontuações entre os dois limiares produzem `In Review`." }, "aml_name_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 60, "description": "Ponderação da semelhança do nome na pontuação de correspondência por ocorrência. O somatório das três ponderações tem de ser exatamente 100 (caso contrário, `400`)." }, "aml_dob_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 25, "description": "Ponderação da data de nascimento na pontuação de correspondência por ocorrência." }, "aml_country_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 15, "description": "Ponderação do país/nacionalidade na pontuação de correspondência por ocorrência." }, "aml_match_score_threshold": { "type": "integer", "minimum": 0, "maximum": 100, "default": 93, "description": "Ponto de corte por ocorrência: as ocorrências com `match_score` abaixo deste valor são `False Positive` (excluídas da avaliação de risco); no valor ou acima são possíveis correspondências `Unreviewed`." }, "include_adverse_media": { "type": "boolean", "default": false, "description": "Pesquisar também em notícias por cobertura negativa. Adiciona até ~30 s de latência enquanto os resultados são recolhidos — utilize um tempo limite de cliente de ≥60 s." }, "include_ongoing_monitoring": { "type": "boolean", "default": false, "description": "Continuar a fazer a nova triagem deste perfil e enviar alterações via webhook. Requer `save_api_request=true` (caso contrário, `400`)." }, "save_api_request": { "type": "boolean", "default": true, "description": "Persistir a triagem como uma sessão (visibilidade na consola, endpoint de decisão, webhooks, revisão de ocorrências). Defina como `false` para uma verificação sem estado." }, "vendor_data": { "type": "string", "description": "O seu identificador para o utilizador submetido a triagem; devolvido e armazenado com a sessão." }, "metadata": { "type": "object", "nullable": true, "description": "JSON de formato livre armazenado com o pedido e devolvido na resposta." }, "sandbox_scenario": { "type": "string", "description": "Slug de cenário exclusivo de sandbox. Apenas aceite quando a chave de API pertence a uma aplicação em modo sandbox; rejeitado em aplicações em produção. Uma triagem autónoma não tem sessão para armar, pelo que o slug é incluído no próprio pedido de triagem: `decline_aml_hit` devolve uma correspondência com formato de produção e define a triagem como `Declined`, `review_aml_possible_match` define-a como `In Review`, e um cenário que não arme qualquer resultado de AML mantém a triagem limpa. Consulte o catálogo de cenários em GET /v1/sandbox/scenarios/ ou em [Sandbox & Test Data](/pt/integration/sandbox-testing).", "example": "decline_aml_hit" } } }, "example": { "full_name": "Antonio Ejemplo Modelo", "entity_type": "person", "date_of_birth": "1972-02-29", "nationality": "ES", "include_adverse_media": false, "vendor_data": "user-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/aml/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: aml-user-1234-2026-08-20' \\\n -d '{\n \"full_name\": \"Antonio Ejemplo Modelo\",\n \"entity_type\": \"person\",\n \"date_of_birth\": \"1972-02-29\",\n \"nationality\": \"ES\",\n \"include_adverse_media\": false,\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml.screen(\n full_name=\"Antonio Ejemplo Modelo\",\n entity_type=\"person\",\n date_of_birth=\"1972-02-29\",\n nationality=\"ES\",\n include_adverse_media=False,\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.aml.screen({\n full_name: \"Antonio Ejemplo Modelo\",\n entity_type: \"person\",\n date_of_birth: \"1972-02-29\",\n nationality: \"ES\",\n include_adverse_media: false,\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AML.Screen(ctx, didit.AMLScreenParams{\n\tFullName: \"Antonio Ejemplo Modelo\",\n\tEntityType: didit.Some(didit.AMLScreenParamsEntityType(\"person\")),\n\tDateOfBirth: didit.String(\"1972-02-29\"),\n\tNationality: didit.String(\"ES\"),\n\tIncludeAdverseMedia: didit.Bool(false),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport me.didit.Didit;\nimport me.didit.types.AmlScreenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.aml().screen(AmlScreenParams.builder()\n .fullName(\"Antonio Ejemplo Modelo\")\n .entityType(AmlScreenParams.EntityType.of(\"person\"))\n .dateOfBirth(LocalDate.parse(\"1972-02-29\"))\n .nationality(\"ES\")\n .includeAdverseMedia(false)\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "aml->screen([\n 'full_name' => 'Antonio Ejemplo Modelo',\n 'entity_type' => 'person',\n 'date_of_birth' => '1972-02-29',\n 'nationality' => 'ES',\n 'include_adverse_media' => false,\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml.screen(\n full_name: \"Antonio Ejemplo Modelo\",\n entity_type: \"person\",\n date_of_birth: \"1972-02-29\",\n nationality: \"ES\",\n include_adverse_media: false,\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Aml.ScreenAsync(new AmlScreenParams\n{\n FullName = \"Antonio Ejemplo Modelo\",\n EntityType = new AmlScreenParamsEntityType(\"person\"),\n DateOfBirth = \"1972-02-29\",\n Nationality = \"ES\",\n IncludeAdverseMedia = false,\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Triagem concluída. `aml.status` reflete os seus limiares; cada resultado igual ou superior ao piso interno de inclusão é listado em `aml.hits` com o seu `match_score` de identidade, o `risk_score` da entidade e um `score_breakdown` que explica a correspondência.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "aml": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "`Declined` quando `score` > `aml_score_review_threshold`; `In Review` quando `score` > `aml_score_approve_threshold`; caso contrário, `Approved` (incluindo quando não existe pontuação disponível)." }, "total_hits": { "type": "integer", "description": "Número de entradas em `hits`." }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Eco do tipo de entidade submetida a triagem." }, "hits": { "type": "array", "items": { "type": "object", "description": "Uma ocorrência de triagem. O `match_score` (0–100) mede a confiança na identidade — as ocorrências abaixo de `aml_match_score_threshold` são marcadas com `review_status: \"False Positive\"` e excluídas da avaliação de risco; as ocorrências iguais ou superiores a esse limiar são possíveis correspondências `\"Unreviewed\"`. O `risk_score` (0–100) mede o nível de risco da entidade correspondente e determina o `aml.score` de nível superior.", "properties": { "id": { "type": "string", "nullable": true, "description": "Identificador estável da Didit para o resultado (hit): `hit_` seguido de 24 carateres hexadecimais. A mesma entidade correspondente mantém o mesmo `id` quando o sujeito é novamente analisado. Transmita-o como `hit_id` para os endpoints de revisão de resultados AML." }, "url": { "type": "string", "nullable": true, "description": "URL de origem para a entidade correspondente, quando disponível." }, "match": { "type": "boolean", "nullable": true, "description": "Flag legada de correspondência exata. Prefira `match_score` + `review_status`." }, "score": { "type": "number", "nullable": true, "description": "OBSOLETO: pontuação de correspondência ponderada no intervalo de 0–1. Utilize `match_score` em alternativa." }, "match_score": { "type": "number", "nullable": true, "description": "Confiança da identidade (0–100). Comparada com `aml_match_score_threshold` para separar Falsos Positivos de Correspondências Possíveis." }, "risk_score": { "type": "number", "nullable": true, "description": "Pontuação de risco da entidade (0–100). O `risk_score` mais elevado entre os resultados que não sejam falsos positivos torna-se o `aml.score` de nível superior." }, "target": { "type": "boolean", "nullable": true }, "caption": { "type": "string", "nullable": true, "description": "Nome de apresentação da entidade correspondente." }, "datasets": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "PEP", "PEP Level 1", "PEP Level 2", "PEP Level 3", "PEP Level 4", "Sanctions", "Adverse Media", "Warnings and Regulatory Enforcement", "Fitness and Probity", "SIP", "SIE", "Insolvency", "Other Lists" ] }, "description": "Categorias de risco sob as quais a entidade está listada: `PEP` (com o respetivo nível, `PEP Level 1` a `PEP Level 4`), `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`, `SIP`, `SIE` ou `Insolvency`. `Other Lists` quando a fonte da entidade não indica nenhuma destas categorias." }, "features": { "type": "object", "nullable": true }, "properties": { "type": "object", "nullable": true, "description": "Perfil da entidade: `name`, `alias`, `notes`, `gender`, `birthDate`, `birthPlace`, `nationality`, `position` e outras matrizes biográficas (cada uma anulável)." }, "rca_name": { "type": "string", "nullable": true, "description": "Nome do associado próximo relacionado que deu origem à correspondência com a entidade, quando o resultado for um RCA." }, "pep_matches": { "type": "array", "description": "Entradas da lista PEP que fundamentam esta correspondência.", "items": { "type": "object", "properties": { "list_name": { "type": "string" }, "publisher": { "type": "string" }, "source_url": { "type": "string" }, "description": { "type": "string" }, "matched_name": { "type": "string" }, "pep_position": { "type": "string" }, "date_of_birth": { "type": "string" }, "place_of_birth": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "other_sources": { "type": "array", "items": { "type": "string" } } } } }, "sanction_matches": { "type": "array", "items": { "type": "object" }, "description": "Entradas da lista de sanções que fundamentam esta correspondência (o mesmo formato de lista de suporte que `pep_matches`, acrescido de campos específicos de sanções)." }, "warning_matches": { "type": "array", "items": { "type": "object" }, "description": "Entradas de aviso/lista de vigilância que fundamentam este alerta." }, "adverse_media_matches": { "type": "array", "description": "Artigos de notícias adversas. Preenchido apenas quando `include_adverse_media=true`.", "items": { "type": "object", "properties": { "headline": { "type": "string" }, "summary": { "type": "string" }, "sentiment": { "type": "string" }, "sentiment_score": { "type": "number" }, "source_url": { "type": "string" }, "thumbnail": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "author_name": { "type": "string", "nullable": true }, "publication_date": { "type": "string", "nullable": true }, "adverse_keywords": { "type": "array", "items": { "type": "string" } }, "other_sources": { "type": "array", "items": { "type": "string" } } } } }, "adverse_media_details": { "type": "object", "nullable": true, "description": "Sentimento agregado de notícias adversas para a entidade (`sentiment`, `sentiment_score`, mapa de frequência de `adverse_keywords`). Preenchido apenas quando `include_adverse_media=true`." }, "first_seen": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a entidade apareceu pela primeira vez nos conjuntos de dados." }, "last_seen": { "type": "string", "format": "date-time", "nullable": true, "description": "Atualização mais recente do conjunto de dados que incluiu a entidade." }, "linked_entities": { "type": "array", "description": "Relações conhecidas da entidade correspondente (família, associados, empresas).", "items": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "relation": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "details": { "type": "array", "items": { "type": "string" } }, "active": { "type": "array", "items": { "type": "string" } } } } }, "risk_view": { "type": "object", "nullable": true, "description": "Discriminação de risco por dimensão (`crimes`, `countries`, `categories`, `custom_list`), cada uma com `score`, `weightage`, `risk_level` e um mapa `risk_scores`." }, "additional_information": { "type": "object", "nullable": true, "description": "Contexto adicional em formato livre, por exemplo, um array `flag_summary` a explicar por que motivo a entidade foi sinalizada." }, "review_status": { "type": "string", "nullable": true, "enum": [ "False Positive", "Unreviewed", "Confirmed Match", "Inconclusive" ], "description": "`False Positive` — `match_score` abaixo de `aml_match_score_threshold`, excluído da avaliação de risco. `Unreviewed` — possível correspondência a aguardar revisão. `Confirmed Match` / `Inconclusive` — definido manualmente por um revisor (através da Business Console) em sessões guardadas; essa capacidade de revisão não faz parte desta especificação." }, "score_breakdown": { "type": "object", "nullable": true, "description": "Como `match_score` foi calculado. Nome, data de nascimento e país contribuem cada um com `_score` × `_weight_normalized` pontos; os pesos são renormalizados quando um componente está em falta nos dados analisados. O número do documento não tem peso — funciona como uma 'chave mestra': `MATCH` define a pontuação como 100, `NEUTRAL` mantém-na inalterada, `HARD_MISMATCH` aplica uma penalização.", "properties": { "name_score": { "type": "integer", "nullable": true, "description": "Semelhança de nome em bruto (0–100)." }, "name_weight": { "type": "integer", "nullable": true, "description": "Ponderação de nome configurada (`aml_name_weight`)." }, "name_weight_normalized": { "type": "number", "nullable": true, "description": "Peso do nome após renormalização (0–100)." }, "name_contribution": { "type": "number", "nullable": true, "description": "Pontos com que o nome contribuiu para `total_score`." }, "dob_score": { "type": "integer", "nullable": true, "description": "Pontuação da data de nascimento como uma percentagem do seu peso (−100 a 100)." }, "dob_weight": { "type": "integer", "nullable": true, "description": "Ponderação de data de nascimento configurada (`aml_dob_weight`)." }, "dob_weight_normalized": { "type": "number", "nullable": true, "description": "Peso da data de nascimento após renormalização (0–100)." }, "dob_contribution": { "type": "number", "nullable": true, "description": "Pontos com que a data de nascimento contribuiu para `total_score`." }, "country_score": { "type": "integer", "nullable": true, "description": "Pontuação do país como uma percentagem do seu peso (−100 a 100)." }, "country_weight": { "type": "integer", "nullable": true, "description": "Ponderação de país configurada (`aml_country_weight`)." }, "country_weight_normalized": { "type": "number", "nullable": true, "description": "Peso do país após renormalização (0–100)." }, "country_contribution": { "type": "number", "nullable": true, "description": "Pontos com que o país contribuiu para `total_score`." }, "document_number_match_type": { "type": "string", "nullable": true, "enum": [ "MATCH", "NEUTRAL", "HARD_MISMATCH" ], "description": "Resultado de referência («golden-key») para a comparação do número do documento." }, "document_number_effect": { "type": "string", "nullable": true, "description": "Descrição legível do efeito do número do documento." }, "total_score": { "type": "integer", "nullable": true, "description": "Pontuação de correspondência ponderada final (0–100) — reflete `match_score`." } } } } } }, "score": { "type": "number", "nullable": true, "description": "Pontuação de risco AML global (0–100): o `risk_score` mais elevado entre as correspondências que não são falsos positivos. Determina o `status` através dos dois limiares." }, "screened_data": { "type": "object", "description": "Eco do que foi submetido a triagem: `full_name`, `date_of_birth`, `nationality`, `document_number` (campos ausentes são `null`).", "properties": { "full_name": { "type": "string" }, "date_of_birth": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Funcionalidade que gerou o aviso." }, "risk": { "type": "string", "description": "Identificador de risco legível por máquina." }, "additional_data": { "type": "object", "nullable": true, "description": "Contexto adicional para o aviso, quando disponível." }, "log_type": { "type": "string", "description": "`warning`, `information` ou `error` — como o risco afetou o resultado." }, "short_description": { "type": "string", "description": "Resumo legível por humanos numa única linha." }, "long_description": { "type": "string", "description": "Explicação completa e legível por humanos." } } }, "description": "Contém um aviso `POSSIBLE_MATCH_FOUND` sempre que `score` não for zero e ≥ `aml_score_approve_threshold` (uma pontuação exatamente de 0 nunca gera aviso); vazio caso contrário." } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou." }, "metadata": { "type": "object", "nullable": true, "description": "Eco do objeto `metadata` que enviou." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "No hits (Approved)": { "summary": "Triagem limpa — zero correspondências", "value": { "request_id": "d27c5509-7a66-45a9-b05e-d69d9f4c336a", "aml": { "status": "Approved", "total_hits": 0, "entity_type": "person", "hits": [], "score": 0, "screened_data": { "full_name": "Maximilian Mustermann-Doe", "date_of_birth": "1992-03-14", "nationality": "DE", "document_number": null }, "warnings": [] }, "vendor_data": "user-1234", "metadata": { "internal_ref": "abc-123" }, "created_at": "2026-06-11T10:21:07.013938+00:00" } }, "PEP hit (Approved — risk below approve threshold)": { "summary": "Uma possível correspondência de PEP; a pontuação de risco 73 mantém-se abaixo do limiar de aprovação predefinido de 80", "value": { "request_id": "0b7e7a3e-65a1-4f3d-9c7a-1de2f9a40111", "aml": { "status": "Approved", "total_hits": 1, "entity_type": "person", "hits": [ { "id": "hit_7c1e9a40b2d35f86e0a4c912", "url": "https://news.example.org/articles/sample", "match": false, "score": 0.93, "match_score": 93.0, "risk_score": 73.0, "target": null, "caption": "Antonio Ejemplo Modelo", "datasets": [ "PEP Level 1", "PEP" ], "features": null, "rca_name": "", "first_seen": "2026-01-07T00:00:00", "last_seen": "2026-01-07T00:00:00", "review_status": "Unreviewed", "properties": { "name": [ "Antonio Ejemplo Modelo", "Antonio Ejemplo" ], "alias": [ "Antonio Ejemplo Modelo", "Ejemplo Modelo, Pedro" ], "notes": [ "Prime Minister of Spain" ], "gender": [ "male" ], "birthDate": [ "1972-02-29" ], "birthPlace": [ "Madrid, Spain" ], "nationality": null, "position": null }, "risk_view": { "crimes": { "score": 0.0, "weightage": 20, "risk_level": "Low", "risk_scores": {} }, "countries": { "score": 9.64, "weightage": 30, "risk_level": "Low", "risk_scores": { "Spain": 25.71 } }, "categories": { "score": 62.5, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100.0, "PEP Level 1": 100.0 } }, "custom_list": {} }, "score_breakdown": { "name_score": 89, "name_weight": 60, "name_weight_normalized": 60.0, "name_contribution": 53.4, "dob_score": 100, "dob_weight": 25, "dob_weight_normalized": 25.0, "dob_contribution": 25.0, "country_score": 100, "country_weight": 15, "country_weight_normalized": 15.0, "country_contribution": 15.0, "document_number_match_type": "NEUTRAL", "document_number_effect": "No document number provided for screening", "total_score": 93 }, "pep_matches": [ { "aliases": [], "education": [], "list_name": "Presidency of the Government of Spain", "publisher": "Presidency of the Government of Spain", "source_url": "https://news.example.org/articles/sample", "description": "The Presidency of the Government is the central institutional body in Spain that supports the Prime Minister and coordinates the general action of the central government.", "matched_name": "Antonio Ejemplo Modelo", "pep_position": "", "date_of_birth": "1972-02-29", "other_sources": [], "place_of_birth": "Madrid, Spain" } ], "sanction_matches": [], "warning_matches": [], "adverse_media_matches": [], "adverse_media_details": null, "linked_entities": [ { "name": [ "Maria Begona Gomez Fernandez" ], "active": [], "status": [], "details": [], "relation": [ "spouse" ] } ], "additional_information": { "flag_summary": [ "Antonio Ejemplo Modelo has been flagged as a Level 1 Politically Exposed Person (PEP) from Spain, serving as the President of the Government of Spain." ] } } ], "score": 73.0, "screened_data": { "full_name": "Pedro Sanchez Perez-Castejon", "date_of_birth": "1972-02-29", "nationality": "ES", "document_number": null }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:23:44.812000+00:00" } } } } } }, "400": { "description": "Erro de validação. Problemas ao nível do campo devolvem o envelope padrão do DRF (um array de mensagens por campo afetado); regras entre campos (soma dos pesos, ordenação dos limiares, monitorização sem guardar) devolvem `{\"error\": [...]}`.", "content": { "application/json": { "examples": { "Missing full_name": { "summary": "`full_name` é o único campo obrigatório", "value": { "full_name": [ "This field is required." ] } }, "Short full_name": { "summary": "`full_name` tem de ter pelo menos 2 carateres", "value": { "full_name": [ "Ensure this field has at least 2 characters." ] } }, "Invalid nationality": { "summary": "`nationality` deve ser ISO 3166-1 alpha-2", "value": { "nationality": [ "Invalid ISO 3166-1 alpha-2 country code." ] } }, "Weights do not sum to 100": { "summary": "`aml_name_weight` + `aml_dob_weight` + `aml_country_weight` ≠ 100", "value": { "error": [ "AML weights must sum to 100. Current sum: 90 (name: 50, dob: 25, country: 15)" ] } }, "Thresholds out of order": { "summary": "Limiar de aprovação superior ao limiar de revisão", "value": { "error": [ "Approve threshold (90.0) cannot be greater than review threshold (80.0)" ] } }, "Monitoring without saving": { "summary": "`include_ongoing_monitoring=true` com `save_api_request=false`", "value": { "error": [ "Ongoing monitoring can only be enabled when the API request is saved." ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer triagem ou chamada ao fornecedor ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/face-search/": { "post": { "summary": "Pesquisa facial", "description": "Pesquise uma imagem de rosto (1:N) no índice de pesquisa facial da sua aplicação — rostos registados a partir de sessões de verificação, chamadas de API autónomas guardadas, carregamentos diretos de rostos de perfis de utilizador e as suas listas de bloqueio/permissão — e obtenha correspondências de similaridade classificadas, além de avisos de lista de bloqueio e duplicados.\n\n**Como funciona.** O maior rosto detetado em `user_image` tem o seu embedding gerado e é pesquisado no índice, circunscrito à sua aplicação. São devolvidas até **5 correspondências** acima do limiar de similaridade em `matches`, cada uma com `similarity_percentage`, a sessão de origem (`session_id`, `session_number`, `status`, `vendor_data`), os `user_details` extraídos durante a verificação de documentos dessa sessão, os sinalizadores `is_blocklisted` / `is_allowlisted` e um discriminador `source` (`session`, `imported` ou `list_entry`).\n\n- `search_type=most_similar` (predefinição) classifica todos os rostos registados por similaridade — utilize-o para desduplicação e investigação de redes de fraude.\n- `search_type=blocklisted_or_approved` restringe os candidatos a rostos em listas de bloqueio, rostos em listas de permissão, rostos de sessões aprovadas e rostos de perfis de utilizador importados, classificando primeiro as entradas da lista de bloqueio — utilize-o quando o objetivo principal for a triagem em listas de bloqueio.\n\nO `status` é `Declined` apenas quando é acionado um aviso `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST`; `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) e `MULTIPLE_FACES_DETECTED` (`warning`) nunca recusam. Ao contrário da Prova de vida passiva, este endpoint **não** exclui da correspondência sessões anteriores com os mesmos `vendor_data`. Uma análise de prova de vida passiva também é executada internamente e armazenada com a sessão persistida, mas o seu resultado não faz parte desta resposta.\n\n**Faturação.** Cada resposta `200` consome um crédito da API de Pesquisa facial (pago a partir do crédito do seu plano ou do saldo carregado). Um saldo insuficiente devolve `403` antes de qualquer processamento de imagem.\n\n**Persistência da sessão e registo facial (`save_api_request`, predefinição `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API (Business Console, `GET /v3/session/{sessionId}/decision/` através do `request_id` devolvido, webhook `status.updated`) e o rosto pesquisado é registado no seu índice de pesquisa facial. Os rostos registados por chamadas de Pesquisa facial são excluídos de resultados futuros da Pesquisa facial, para que pesquisas repetidas nunca correspondam entre si. Quando `false`, a chamada é pontual: nada é armazenado, o rosto não é registado e os valores de `match_image_url` são caminhos de armazenamento interno em vez de URLs para transferência.\n\n**Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada com formato incorreto continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved`, nenhuma sessão é persistida e nenhum crédito é consumido.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limite de pedidos.** Limite partilhado de 300 pedidos de escrita por minuto, por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-lo devolve `429`.", "operationId": "post_v3face-search", "x-didit-sdk": { "resource": "face_search", "method": "search", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "Imagem facial frontal para efetuar a pesquisa. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamanho máximo de carregamento: **5 MB** (ficheiros maiores são rejeitados com `400`). As imagens são comprimidas automaticamente para ~0.5 MB antes do processamento, pelo que resoluções muito altas não melhoram a precisão. A imagem deve conter pelo menos um rosto detetável — caso contrário, o endpoint devolve `400`. Quando vários rostos estão presentes, o maior é pesquisado e um aviso `MULTIPLE_FACES_DETECTED` é adicionado." }, "search_type": { "type": "string", "default": "most_similar", "enum": [ "most_similar", "blocklisted_or_approved" ], "description": "Política de pesquisa. `most_similar` (predefinição) classifica cada rosto registado na sua aplicação por similaridade. `blocklisted_or_approved` restringe os candidatos a rostos em lista de bloqueio, rostos em lista de permissões, rostos de sessões aprovadas e rostos importados de perfis de utilizador — com as entradas na lista de bloqueio classificadas primeiro.", "example": "most_similar" }, "rotate_image": { "type": "boolean", "default": false, "description": "Quando `true`, o serviço tenta rotações de 90 graus da entrada e utiliza a orientação que produzir a melhor deteção facial. Útil quando a orientação EXIF está ausente. Adiciona latência.", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando `true` (padrão), persiste a chamada como uma sessão do tipo API, emite um webhook `status.updated`, pré-assina os valores de `match_image_url` e regista o rosto pesquisado no seu índice de Pesquisa facial (os registos de Pesquisa facial são excluídos de pesquisas futuras). Quando `false`, a pesquisa é de execução única — nenhuma sessão é armazenada e o rosto não é registado.", "example": true }, "vendor_data": { "type": "string", "description": "Identificador opaco opcional (o seu ID de utilizador, e-mail, UUID...) guardado na sessão persistida e devolvido. Não exclui rostos do mesmo utilizador dos resultados de pesquisa.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido. Em pedidos multipart, envie-o como um campo de texto codificado em JSON — é convertido num objeto.", "example": { "flow": "dedup_check" } } } }, "example": { "user_image": "(binary JPEG/PNG selfie)", "search_type": "most_similar", "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "dedup_check" } } } } }, "responses": { "200": { "description": "Pesquisa facial concluída. `face_search.matches` contém até 5 rostos semelhantes ordenados por semelhança; uma matriz vazia significa que nenhum rosto registado excedeu o limiar mínimo de semelhança. `status` é `Declined` apenas em correspondências na lista de bloqueio — correspondências duplicadas por si só devolvem `Approved`, portanto inspecione `matches` e `warnings`, não apenas `status`. Quando `save_api_request=true`, `request_id` é o id de sessão persistido. Cada correspondência contém `source` (`session`, `imported`, `list_entry` ou `retained_template`), `vendor_user_id` e `biometric_template_id`; uma correspondência `retained_template` provém de um template biométrico sem imagem mantido após a sessão de origem ter sido eliminada e tem os campos de sessão, `match_image_url` e `user_details` como `null`.", "content": { "application/json": { "examples": { "Blocklist hit (Declined)": { "summary": "O rosto coincide com um rosto na lista de bloqueio", "value": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "face_search": { "status": "Declined", "total_matches": 1, "matches": [ { "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "session_number": 323442, "similarity_percentage": 99.99, "source": "session", "vendor_data": "user-1", "verification_date": "2025-01-01T00:00:00Z", "user_details": { "full_name": "Jane Marie Doe", "document_type": "ID", "document_number": "X1234567" }, "match_image_url": "https:///face/3f6a1c2e/reference.jpg", "status": "Approved", "is_blocklisted": true, "is_allowlisted": false, "api_service": null, "vendor_user_id": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "biometric_template_id": null } ], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [ { "risk": "FACE_IN_BLOCKLIST", "feature": "LIVENESS", "additional_data": { "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "blocklisted_session_number": 323442, "api_service": null }, "log_type": "error", "short_description": "Face in blocklist", "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Duplicate found (Approved)": { "summary": "O rosto já apareceu noutra sessão aprovada — informativo, sem recusa", "value": { "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f", "face_search": { "status": "Approved", "total_matches": 1, "matches": [ { "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788", "session_number": 1024, "similarity_percentage": 87.42, "source": "session", "vendor_data": "user-9", "verification_date": "2025-11-20T09:15:00Z", "user_details": null, "match_image_url": "https:///face/9c8b7a6d/reference.jpg", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": "PASSIVE_LIVENESS", "vendor_user_id": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "biometric_template_id": null } ], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [ { "risk": "DUPLICATED_FACE", "feature": "LIVENESS", "additional_data": { "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788", "duplicated_session_number": 1024, "api_service": "PASSIVE_LIVENESS" }, "log_type": "information", "short_description": "Duplicated face from other approved session", "long_description": "The system identified a duplicated face from another approved session, requiring further investigation." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "No matches (Approved)": { "summary": "Nenhum rosto registado ultrapassou o limiar mínimo de similaridade", "value": { "request_id": "9d8c7b6a-5f4e-3d2c-1b0a-998877665544", "face_search": { "status": "Approved", "total_matches": 0, "matches": [], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "face_search": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Declined` apenas quando for acionado um aviso `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST`. As correspondências duplicadas e os avisos de múltiplos rostos nunca causam uma recusa." }, "total_matches": { "type": "integer", "description": "Número de entradas em `matches` (0–5).", "example": 1 }, "matches": { "type": "array", "maxItems": 5, "description": "Até 5 rostos do seu índice de pesquisa facial que excedem o limiar de similaridade, ordenados por similaridade (com entradas na lista de bloqueio classificadas primeiro quando `search_type=blocklisted_or_approved`). Vazio quando nenhum rosto registado for suficientemente semelhante.", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID da sessão de verificação à qual pertence a face correspondente. `null` quando `source` é `imported`, `list_entry` ou `retained_template`.", "example": "882c42d5-8a4d-4d20-8080-a22f57822c86" }, "session_number": { "type": "integer", "nullable": true, "description": "Número de sessão legível apresentado na Business Console. `null` para correspondências que não sejam de sessão.", "example": 323442 }, "similarity_percentage": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Semelhança entre o rosto submetido e o rosto correspondente (0–100).", "example": 99.99 }, "source": { "type": "string", "enum": [ "session", "imported", "list_entry", "retained_template" ], "description": "Onde o rosto correspondente foi registado: `session` — uma sessão de verificação ou uma chamada de API autónoma guardada; `imported` — um rosto carregado diretamente para um perfil de Utilizador; `list_entry` — um rosto associado a uma das suas listas; `retained_template` — um template biométrico sem imagem armazenado num Utilizador, listado em `/v3/biometric-templates/`." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` da sessão correspondente ou utilizador associado para rostos importados e com modelo retido.", "example": "user-1" }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID do utilizador vinculado. `null` para entradas de lista e correspondências de sessão sem utilizador.", "example": "2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4" }, "biometric_template_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID do template biométrico retido. Definido apenas quando `source` é `retained_template`; `null` caso contrário.", "example": null }, "verification_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o rosto correspondente foi originalmente capturado ou quando um modelo retido foi criado (`YYYY-MM-DDThh:mm:ssZ`). `null` para correspondências de `list_entry`.", "example": "2025-01-01T00:00:00Z" }, "user_details": { "type": "object", "nullable": true, "description": "Dados de identidade extraídos durante a verificação de documentos da sessão correspondente. `null` quando a sessão correspondente não tem dados de documentos (p. ex., sessões apenas com prova de vida) e sempre `null` para correspondências com `retained_template`. Para correspondências com `source: imported`, é preenchido a partir do perfil de Utilizador: `full_name` definido, `document_type`/`document_number` nulos.", "properties": { "full_name": { "type": "string", "nullable": true, "example": "Jane Marie Doe" }, "document_type": { "type": "string", "nullable": true, "example": "ID" }, "document_number": { "type": "string", "nullable": true, "example": "X1234567" } } }, "match_image_url": { "type": "string", "nullable": true, "description": "URL com limite temporal (`https:///...`) da imagem de referência do rosto correspondente quando `save_api_request=true`. Com `save_api_request=false`, este é um caminho de armazenamento interno que não pode ser descarregado diretamente. Sempre `null` para correspondências de `retained_template`, pois os modelos retidos não contêm qualquer imagem.", "example": "https:///face/3f6a1c2e/reference.jpg" }, "status": { "type": "string", "nullable": true, "description": "Estado da sessão correspondente (`Approved`, `Declined`, `In Review`, …). `null` para correspondências `imported`/`list_entry`.", "example": "Approved" }, "is_blocklisted": { "type": "boolean", "description": "`true` quando o rosto correspondente está na sua lista de bloqueio facial. Qualquer correspondência na lista de bloqueio suficientemente semelhante recusa a pesquisa." }, "is_allowlisted": { "type": "boolean", "description": "`true` quando o rosto correspondente está numa das suas listas de permissões. As correspondências em listas de permissões suprimem avisos de duplicados." }, "api_service": { "type": "string", "nullable": true, "description": "Definido quando a face correspondente foi registada através de uma chamada de API autónoma (ex.: `PASSIVE_LIVENESS`); `null` para sessões de verificação normais e faces importadas.", "example": null } } } }, "user_image": { "type": "object", "description": "Resultados da deteção facial para a imagem submetida. As entradas aqui contêm apenas `bbox` e `confidence`.", "properties": { "entities": { "type": "array", "description": "Uma entrada por rosto detetado. O maior rosto é o pesquisado.", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Caixa delimitadora `[x_min, y_min, x_max, y_max]` em píxeis.", "example": [ 40, 40, 120, 120 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Confiança da deteção facial (0–1).", "example": 0.732973 } } } }, "best_angle": { "type": "integer", "description": "Rotação (graus) que produziu a melhor deteção facial; diferente de zero apenas quando `rotate_image=true` corrigiu a orientação. Nunca é null neste endpoint (assume 0 por predefinição quando o modelo a omite).", "example": 0 } } }, "warnings": { "type": "array", "description": "Sinais de risco. `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` (`error`) recusam a pesquisa; `MULTIPLE_FACES_DETECTED` (`warning`) e `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) são meramente indicativos.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "MULTIPLE_FACES_DETECTED", "FACE_IN_BLOCKLIST", "POSSIBLE_FACE_IN_BLOCKLIST", "DUPLICATED_FACE", "POSSIBLE_DUPLICATED_FACE" ], "description": "Código de risco legível por máquina." }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "Funcionalidade que gerou o aviso. Sempre `LIVENESS` neste endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`null` para `MULTIPLE_FACES_DETECTED`. As correspondências na lista de bloqueio contêm `{blocklisted_session_id, blocklisted_session_number, api_service}`; as correspondências duplicadas contêm `{duplicated_session_id, duplicated_session_number, api_service}` a apontar para a primeira sessão correspondente." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravidade. Os avisos `error` alteram o `status` para `Declined`; as entradas `warning` e `information` são informativas e nunca recusam por si sós." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos sobre o risco." }, "long_description": { "type": "string", "description": "Explicação legível do risco." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, ou `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, ou `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada, por exemplo `2026-06-12T01:04:42.763237+00:00`." } } } } } }, "400": { "description": "Erro de validação. Devolvido quando `user_image` está em falta, excede 5 MB, tem uma extensão não suportada ou quando **nenhum rosto é detetado** na imagem enviada. Os erros de campo utilizam o envelope `{field: [messages]}` do DRF; as falhas de deteção facial utilizam `{\"error\": ...}`.", "content": { "application/json": { "examples": { "No face detected": { "summary": "A imagem descodifica-se corretamente, mas não contém nenhum rosto detetável", "value": { "error": "No face detected in the image" } }, "Missing image": { "summary": "`user_image` não incluído nos dados do formulário", "value": { "user_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Extensão de ficheiro fora de tiff/jpg/jpeg/png/webp", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "O carregamento excede o limite de 5 MB", "value": { "user_image": [ "File size should not exceed 5 MB" ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer processamento de imagens ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/face-search/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'search_type=most_similar' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.face_search.search(\n user_image=open(\"user_image.jpg\", \"rb\"),\n search_type=\"most_similar\",\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"dedup_check\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.faceSearch.search({\n user_image: await fileFromPath(\"user_image.jpg\"),\n search_type: \"most_similar\",\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"dedup_check\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceSearch.Search(ctx, didit.FaceSearchSearchParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tSearchType: didit.Some(didit.FaceSearchSearchParamsSearchType(\"most_similar\")),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"dedup_check\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.FaceSearchSearchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.faceSearch().search(FaceSearchSearchParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .searchType(FaceSearchSearchParams.SearchType.of(\"most_similar\"))\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"dedup_check\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "faceSearch->search([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'search_type' => 'most_similar',\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'dedup_check'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.face_search.search(\n user_image: Pathname(\"user_image.jpg\"),\n search_type: \"most_similar\",\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"dedup_check\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FaceSearch.SearchAsync(new FaceSearchSearchParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n SearchType = new FaceSearchSearchParamsSearchType(\"most_similar\"),\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"dedup_check\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/sessions/": { "get": { "summary": "Listar sessões de verificação (KYC e/ou KYB) com filtros e paginação", "description": "Devolve uma lista paginada de sessões de verificação para a aplicação identificada pela sua chave de API, as mais recentes primeiro (`session_number` descendente).\n\n**URL canónico:** a rota é `/v3/sessions/` (barra final). Os pedidos para `/v3/sessions` sem a barra recebem um redirecionamento `301` para o URL com barra preservando a cadeia de consulta; a maioria dos clientes HTTP segue-o de forma transparente em GET.\n\n**Quando utilizar este endpoint vs webhooks.** Utilize este endpoint para painéis, pesquisa de back-office, reconciliação e exportações em lote. Não faça polling deste endpoint para acompanhar o progresso de verificações individuais - em vez disso, configure [webhooks](/pt/integration/webhooks), que enviam eventos `status.updated` no momento em que uma sessão é alterada. Para obter o resultado completo de uma sessão, chame `GET /v3/session/{sessionId}/decision/`.\n\n**Sessões de KYC e KYB.** `session_kind` seleciona quais os tipos listados:\n- `user` (predefinição) - apenas sessões de Verificação de utilizadores (KYC). Comportamento retrocompatível.\n- `business` - apenas sessões de Verificação de empresas (KYB). As linhas têm uma estrutura diferente e menor (consulte o esquema da resposta).\n- `all` - ambos os tipos numa única resposta: a página de KYC e a página de KYB para os mesmos `limit`/`offset` são concatenadas em `results` (linhas de KYC primeiro), pelo que uma página pode conter até `2 x limit` linhas. `count` é a soma de ambos os tipos e `next`/`previous` refletem a paginação do lado do KYC. Para uma paginação estrita de dados mistos, chame `user` e `business` separadamente.\n\nCada linha inclui um discriminador `session_kind` (`\"user\"` ou `\"business\"`).\n\n**Paginação.** Paginação padrão limit/offset: `limit` (predefinição 50) e `offset` (predefinição 0), com URLs de páginas pré-construídas `next`/`previous`. Para linhas de KYC, `count` é exato. Para linhas de KYB, `count` é calculado com uma análise delimitada e está limitado a 100 - quando houver mais de 100 correspondências, mantém-se em 100, pelo que deve iterar utilizando `next` (ou verificando se foi devolvida uma página completa) em vez de calcular o total de páginas a partir de `count`.\n\n**Semântica dos filtros.** Todos os filtros combinam-se com AND e aplicam-se a linhas de KYC. Quando `session_kind` for `business` ou `all`, o lado de KYB respeita os parâmetros partilhados `vendor_data`, `status`, `workflow_id`, `country` (código do país do registo da empresa), `date_from`, `date_to`, `search` (nome da empresa, número de registo — introduza números de registo sem separadores, por exemplo `DPC001` e não `DPC-001` —, vendor_data, número de sessão ou UUID da sessão), `warning` e `organization_name`; os restantes filtros exclusivos de KYC são ignorados para linhas de KYB. Parâmetros separados por vírgulas (`status`, `country`, `document_type`, `region`, `workflow_id`, `document_name`, `warning`, `organization_name`, `session_type`) correspondem a qualquer um dos valores listados (OR dentro do parâmetro). `vendor_data` é uma correspondência exata - utilize `search` para correspondência parcial. Valores desconhecidos em filtros de lista simplesmente não devolvem linhas (sem erro); valores tipados malformados (`date_from`, `date_to`, `didit_internal_id`, `api_service`, `session_kind`) devolvem `400` com um objeto de erro por campo.\n\n**Pesquisa.** `search` adapta-se à entrada: um UUID completo procura por `session_id`; dígitos (com `+ - . space` opcionais) correspondem ao prefixo do número da sessão, números de documento/identificação pessoal, prefixo de número de telefone ou `vendor_data`; valores contendo `@` correspondem a prefixos de e-mail; qualquer outro texto corresponde a nomes (insensível a acentos) e `vendor_data`.\n\nNão é aplicado nenhum limite de pedidos fixo por endpoint, mas mantenha o polling de listas pouco frequente e confie em webhooks para atualizações em tempo real.", "operationId": "get_v3_sessions", "x-didit-sdk": { "resource": "sessions", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "session_kind", "in": "query", "required": false, "description": "Qual o tipo de sessões a listar: `user` (apenas KYC, predefinição), `business` (apenas KYB) ou `all` (ambas, concatenadas - consulte a descrição para a semântica de paginação combinada). A correspondência não diferencia maiúsculas de minúsculas (`BUSINESS` funciona); qualquer valor que não seja uma variante de maiúsculas/minúsculas de `user`/`business`/`all` devolve `400`.", "schema": { "type": "string", "enum": [ "user", "business", "all" ], "default": "user" }, "example": "all" }, { "name": "limit", "in": "query", "required": false, "description": "Número máximo de linhas por página (por tipo quando `session_kind=all`). O valor predefinido é 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 20 }, { "name": "offset", "in": "query", "required": false, "description": "Número de linhas a ignorar antes da primeira linha devolvida. O valor predefinido é 0. Prefira seguir os URLs `next`/`previous` da resposta.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 20 }, { "name": "status", "in": "query", "required": false, "description": "Lista separada por vírgulas de estados de sessão a incluir, por exemplo, `Approved,In Review`. Os valores são sensíveis a maiúsculas e minúsculas; consulte [Estados de verificação](/pt/integration/verification-statuses). Valores desconhecidos não correspondem a nada.", "schema": { "type": "string" }, "example": "Approved,In Review" }, { "name": "vendor_data", "in": "query", "required": false, "description": "Filtro de correspondência exata no `vendor_data` que enviou na criação da sessão (o seu próprio identificador de utilizador/empresa). Para correspondências parciais, utilize `search` em alternativa.", "schema": { "type": "string" }, "example": "your-user-id-123" }, { "name": "search", "in": "query", "required": false, "description": "Uma referência completa apresentada, como `S-0001` (utilizador) ou `B-0001` (empresa), corresponde apenas a esse número e tipo de sessão; os zeros à esquerda e maiúsculas/minúsculas não afetam a correspondência. Pesquisa inteligente de texto livre. Um UUID completo corresponde a `session_id`; uma entrada numérica corresponde ao prefixo do número da sessão, números de documento/pessoais, prefixo de telefone ou `vendor_data`; entradas que contenham `@` correspondem a prefixos de e-mail; outro texto corresponde a nomes (não sensível a acentos) e a `vendor_data`. O texto livre que contenha dígitos corresponde adicionalmente a campos de pesquisa de número de documento/pessoal e a prefixos de número de sessão.", "schema": { "type": "string" }, "example": "jane doe" }, { "name": "workflow_id", "in": "query", "required": false, "description": "UUIDs de fluxos separados por vírgulas (encontre-os na página Fluxos na Consola). UUIDs malformados na lista são ignorados; se nenhum for válido, o resultado fica vazio.", "schema": { "type": "string" }, "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, { "name": "date_from", "in": "query", "required": false, "description": "Apenas sessões criadas nesta data ou após a mesma (UTC), formato `YYYY-MM-DD`. Datas malformadas devolvem `400`.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-01" }, { "name": "date_to", "in": "query", "required": false, "description": "Apenas sessões criadas até esta data (UTC), formato `YYYY-MM-DD`. Para linhas de KYC, o dia inteiro é incluído; para linhas de KYB, a comparação é `created_at <= date_to` (meia-noite), pelo que deve utilizar a data do dia seguinte para incluir um dia completo de sessões de KYB.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-30" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IDs de etiquetas separados por vírgulas (`tags` da sua aplicação). Devolve as sessões que contenham qualquer uma delas. Os IDs que não sejam UUIDs válidos são ignorados e, quando nenhum for válido, a lista fica vazia." }, { "name": "decided_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Data e hora ISO 8601. Devolve as sessões cujo estado mudou pela última vez nesse momento ou depois. Filtra pela hora da última alteração de estado, não pela hora de criação." }, { "name": "decided_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Data e hora ISO 8601. Devolve as sessões cujo estado mudou pela última vez antes dessa data. Combine com `decided_from` para um intervalo semiaberto." }, { "name": "country", "in": "query", "required": false, "description": "Filtro de países separados por vírgulas. Para linhas KYC: códigos ISO 3166-1 alfa-3 do país emissor do documento de identificação (por exemplo, `ESP,USA`), que podem diferir da nacionalidade. Para linhas KYB: o código de país do registo comercial da empresa.", "schema": { "type": "string" }, "example": "ESP,USA" }, { "name": "document_type", "in": "query", "required": false, "description": "Códigos de tipo de documento de identificação verificados na sessão, separados por vírgulas (apenas linhas KYC): `P` (Passaporte), `ID` (Cartão de Cidadão / Bilhete de Identidade), `DL` (Carta de Condução), `RP` (Título de Residência), `SSC` (Cartão de Segurança Social), `HIC` (Cartão de Seguro de Saúde), `WP` (Autorização de Trabalho), `TC` (Cartão de Contribuinte), `VISA`, `PSC` (Cartão de Serviços Públicos), `BC` (Certidão de Nascimento), `OTHER`. Tenha em atenção que o campo de resposta `document_type` contém o nome de apresentação, não o código.", "schema": { "type": "string" }, "example": "P,ID" }, { "name": "document_name", "in": "query", "required": false, "description": "Nomes exatos de documentos; podem ser transmitidos vários nomes separados por vírgulas, mas o valor só é dividido por vírgulas quando contém mais do que um separador ` - ` (um nome isolado com uma vírgula incorporada é correspondido por inteiro). Os nomes são conforme reconhecidos pela verificação de documentos (frente ou verso), por ex., `Spain - Id Card (2021)`. Apenas linhas de KYC.", "schema": { "type": "string" }, "example": "Spain - Id Card (2021)" }, { "name": "region", "in": "query", "required": false, "description": "Valores de região/estado do documento separados por vírgulas (para documentos emitidos por região, como cartas de condução dos EUA). Apenas linhas KYC.", "schema": { "type": "string" }, "example": "CA,TX" }, { "name": "didit_internal_id", "in": "query", "required": false, "description": "Filtrar pelo identificador interno de utilizador da Didit (o campo de resposta `didit_internal_id`) para listar todas as sessões de um utilizador verificado. Tem de ser um UUID válido; valores malformados devolvem `400`. Apenas linhas de KYC.", "schema": { "type": "string", "format": "uuid" }, "example": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147" }, { "name": "session_type", "in": "query", "required": false, "description": "Canais de criação de sessão separados por vírgulas: `API`, `HOSTED`, `MIGRATED`. O valor especial `ALL` (ou omitir o parâmetro) desativa o filtro. Apenas linhas de KYC.", "schema": { "type": "string" }, "example": "HOSTED" }, { "name": "api_service", "in": "query", "required": false, "description": "Filtrar sessões da API autónoma por serviço. Valores inválidos devolvem `400`. Apenas linhas de KYC.", "schema": { "type": "string", "enum": [ "ID_VERIFICATION", "FACE_MATCH", "AGE_ESTIMATION", "FACE_SEARCH", "POA", "AML", "KYB_REGISTRY", "PASSIVE_LIVENESS", "DATABASE_VALIDATION", "PHONE_VERIFICATION", "EMAIL_VERIFICATION" ] }, "example": "AML" }, { "name": "screened_full_name", "in": "query", "required": false, "description": "Pesquisa de nomes insensível a acentos nos dados analisados por AML e validação de base de dados. Quando combinada com `api_service=AML` ou `api_service=DATABASE_VALIDATION`, a pesquisa fica restrita aos dados analisados dessa funcionalidade. Apenas linhas de KYC.", "schema": { "type": "string" }, "example": "Jane Doe" }, { "name": "warning", "in": "query", "required": false, "description": "Códigos de risco de aviso separados por vírgulas; devolve as sessões que geraram qualquer um deles (por exemplo, `POSSIBLE_FRAUD`). Os códigos de risco estão listados por funcionalidade na [documentação de avisos](/pt/integration/webhooks). Aplica-se a linhas de KYC e, com códigos de aviso empresariais, a linhas de KYB.", "schema": { "type": "string" }, "example": "POSSIBLE_FRAUD" }, { "name": "status_initialized_as_in_review", "in": "query", "required": false, "description": "Quando `true`, apenas as sessões cuja decisão inicialmente terminou em `In Review` (útil para auditar o volume de revisão manual). Apenas linhas de KYC.", "schema": { "type": "boolean" }, "example": true }, { "name": "is_kyc_to_be_reviewed", "in": "query", "required": false, "description": "`true` devolve sessões cuja verificação de documentos está sinalizada para revisão manual; `false` devolve sessões com verificação de documentos explicitamente não sinalizada. Omita para desativar. Apenas linhas de KYC.", "schema": { "type": "boolean" }, "example": true }, { "name": "euuid", "in": "query", "required": false, "description": "Filtrar pelo euuid do utilizador final (UUID atribuído ao utilizador em verificação, utilizado pelas ligações diretas da Console). Tem de ser um UUID válido; valores mal formatados devolvem um erro de campo 400. Apenas linhas de KYC.", "schema": { "type": "string", "format": "uuid" }, "example": "0f8fad5b-d9cb-469f-a165-70867728950e" }, { "name": "organization_name", "in": "query", "required": false, "description": "Nomes de organizações separados por vírgulas. Orientado para a consola; com uma chave de API (já restrita a uma aplicação), corresponde apenas ao nome da sua própria organização.", "schema": { "type": "string" }, "example": "Acme Inc" } ], "responses": { "200": { "description": "Lista de sessões paginada. Os itens de `results` são linhas de KYC, linhas de KYB, ou ambos, dependendo de `session_kind`; diferencie através do campo `session_kind` de cada linha.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Número de sessões que correspondem aos filtros: exato até 100 e limitado a 100 além disso, pelo que não deve ser usado como total. Use `next` para saber se existem mais páginas. Para `session_kind=all`, é a soma de ambos os tipos, cada um limitado a 100.", "example": 2 }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página.", "example": "https://verification.didit.me/v3/sessions/?limit=20&offset=20" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página.", "example": null }, "results": { "type": "array", "description": "Linhas de sessão, as mais recentes primeiro. Com `session_kind=all`, as linhas KYC surgem primeiro, seguidas pelas linhas KYB.", "items": { "oneOf": [ { "$ref": "#/components/schemas/UserSessionListItem" }, { "$ref": "#/components/schemas/BusinessSessionListItem" } ], "discriminator": { "propertyName": "session_kind", "mapping": { "user": "#/components/schemas/UserSessionListItem", "business": "#/components/schemas/BusinessSessionListItem" } } } } } }, "examples": { "KYC sessions (default)": { "summary": "session_kind=user - uma sessão concluída e uma sessão não iniciada", "value": { "count": 2, "next": null, "previous": null, "results": [ { "session_id": "5b3720ed-d429-42ef-b67f-37ea805f48ee", "session_kind": "user", "session_number": 720, "session_url": "https://verify.didit.me/session/CuXoBYCYVO5Y", "portrait_image": "https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=...", "document_type": "Passport", "full_name": "Jane Marie Doe", "country": "ESP", "status": "Approved", "vendor_data": "your-user-id-123", "didit_internal_id": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147", "created_at": "2026-06-09T12:26:54.328364Z", "features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" }, { "feature": "IP_ANALYSIS", "status": "Approved" } ], "phone_number": { "number": "+14155552671", "is_verified": true }, "email_address": { "email": "jane@example.com", "is_verified": true }, "additional_details": { "aml": { "total_hits": 0, "entity_type": "person", "is_adverse_media_fetched": false }, "liveness": { "method": "PASSIVE", "score": 0.98 }, "face_match": { "score": 0.95 } } }, { "session_id": "038ad62f-5ebd-46c2-afe9-4b2956bf687f", "session_kind": "user", "session_number": 719, "session_url": "https://verify.didit.me/session/7RGKiO6ioGH6", "portrait_image": null, "document_type": null, "full_name": null, "country": null, "status": "Not Started", "vendor_data": "your-user-id-124", "didit_internal_id": "eb4e679d-ca4b-461f-9685-687bac29ebdb", "created_at": "2026-06-09T08:02:23.343053Z", "features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "FACE_MATCH", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" }, { "feature": "IP_ANALYSIS", "status": "Not Finished" } ], "phone_number": null, "email_address": null, "additional_details": null } ] } }, "Mixed KYC + KYB (session_kind=all)": { "summary": "session_kind=all - linha de KYC seguida por uma linha de KYB", "value": { "count": 2, "next": null, "previous": null, "results": [ { "session_id": "5b3720ed-d429-42ef-b67f-37ea805f48ee", "session_kind": "user", "session_number": 720, "session_url": "https://verify.didit.me/session/CuXoBYCYVO5Y", "portrait_image": null, "document_type": "Identity Card", "full_name": "Jane Marie Doe", "country": "ESP", "status": "In Review", "vendor_data": "your-user-id-123", "didit_internal_id": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147", "created_at": "2026-06-09T12:26:54.328364Z", "features": [ { "feature": "ID_VERIFICATION", "status": "In Review" }, { "feature": "LIVENESS", "status": "Approved" } ], "phone_number": null, "email_address": null, "additional_details": { "liveness": { "method": "PASSIVE", "score": 0.98 } } }, { "session_id": "8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52", "session_kind": "business", "session_number": 42, "status": "Approved", "vendor_data": "your-company-id-77", "created_at": "2026-06-08T09:14:02.118450Z", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "workflow_type": "kyb", "workflow_label": "Standard KYB", "company_name": "Acme Holdings S.L.", "registration_number": "B12345678", "country": "ES" } ] } } } } } }, "301": { "description": "Redirecionamento para o URL canónico com barra final. Devolvido quando o caminho do pedido é `/v3/sessions` (sem barra final); o cabeçalho `Location` aponta para `/v3/sessions/` preservando a cadeia de consulta. Os clientes GET normalmente seguem-no automaticamente." }, "400": { "description": "Parâmetro de consulta inválido. O corpo é um objeto com uma chave correspondente ao parâmetro problemático.", "content": { "application/json": { "examples": { "Invalid session_kind": { "summary": "session_kind não é um dos valores user/business/all", "value": { "session_kind": "Must be \"user\", \"business\", or \"all\"." } }, "Invalid date": { "summary": "date_from/date_to mal formatados", "value": { "date_from": [ "Enter a valid date." ] } }, "Invalid didit_internal_id": { "summary": "didit_internal_id não é um UUID", "value": { "didit_internal_id": [ "Enter a valid UUID." ] } }, "Invalid api_service": { "summary": "api_service não está entre as opções permitidas", "value": { "api_service": [ "Select a valid choice. FOO is not one of the available choices." ] } } } } } }, "403": { "description": "Chave de API em falta, malformada ou revogada. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.\n\n**Aplicação eliminada:** durante alguns minutos após uma aplicação ser eliminada, um pedido efetuado com uma das suas chaves de API pode responder `{\"detail\": \"This application was deleted.\", \"code\": \"application_deleted\"}`. Não tente novamente: a aplicação e as suas chaves de API já não existem. Decorridos esses minutos, a chave é recusada como qualquer outra chave inválida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." }, "code": { "type": "string", "description": "Motivo legível por máquina, presente apenas em algumas falhas. `application_deleted`: a chave de API pertence a uma aplicação que foi eliminada.", "example": "application_deleted" } }, "required": [ "detail" ] }, "examples": { "Forbidden": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "You do not have permission to perform this action." } }, "ApplicationDeleted": { "summary": "Chave de API de uma aplicação eliminada", "value": { "detail": "This application was deleted.", "code": "application_deleted" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s 'https://verification.didit.me/v3/sessions/?status=Approved,In%20Review&date_from=2026-06-01&limit=20' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->list() as $item) {\n print_r($item);\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/share/": { "post": { "summary": "Gerar um token de partilha para uma sessão de verificação concluída", "description": "Gerar um JWT de curta duração que permite a uma aplicação Didit específica importar esta sessão concluída. Combine com `POST /v3/session/import-shared/`.", "operationId": "post_v3_session_share", "x-didit-sdk": { "resource": "sessions", "method": "share", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "Token de partilha gerado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "share_token": { "type": "string", "description": "JWT assinado com HS256. Passe este valor textualmente como `share_token` para [`POST /v3/session/import-shared/`](/sessions-api/import-shared-session) na aplicação de destino.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "for_application_id": { "type": "string", "format": "uuid", "description": "Repete o UUID da aplicação de destino à qual o token está vinculado.", "example": "a5f3bca2-46e2-411e-90ef-a580900a57ee" }, "session_kind": { "type": "string", "enum": [ "user", "business" ], "description": "Se a sessão de origem é uma sessão de Verificação de utilizadores (KYC) ou de Verificação de empresas (KYB)." } } }, "examples": { "User session": { "summary": "Partilhar uma sessão de KYC", "value": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiMjBiYjNjM2ItNjE0Ni00MzlmLTg0YTQtYmQzMGQwMGFjNmEyIiwiZnJvbV9hcHBsaWNhdGlvbl9pZCI6ImRiZDIwZTM0LTQyZTktNGYyYy1iYTkxLWNmMDc2MjAxNmY2NCIsImZvcl9hcHBsaWNhdGlvbl9pZCI6ImE1ZjNiY2EyLTQ2ZTItNDExZS05MGVmLWE1ODA5MDBhNTdlZSIsImlhdCI6MTc1MzYzMDY2NiwiZXhwIjoxNzUzNjM0MjY2fQ.JJ9pNE_hqZsOtbR0XYZIWw4JzidjdEl279iUrsIkhGE", "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "session_kind": "user" } }, "Business session": { "summary": "Partilhar uma sessão de KYB", "value": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "session_kind": "business" } } } } } }, "401": { "description": "Credenciais em falta ou inválidas. Ao contrário da maioria dos endpoints v3, este endpoint autentica através do decorador de permissões e devolve `401` quando nenhum token/chave válido é apresentado.", "content": { "application/json": { "examples": { "Unauthorized": { "summary": "Não autorizado", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "404": { "description": "Não existe nenhuma sessão com o `session_id` fornecido na sua aplicação.", "content": { "application/json": { "examples": { "Not Found": { "summary": "Sessão não encontrada", "value": { "detail": "Not found." } } } } } }, "400": { "description": "Erro de validação. Os erros de campo são indexados pelo nome do campo; o erro de não concluído surge sob a chave `detail` (como um array).", "content": { "application/json": { "examples": { "Wrong status": { "summary": "A sessão de origem não está finalizada", "value": { "detail": [ "Only finished sessions (\"Approved\", \"Declined\", \"In Review\") can be shared." ] } }, "Target missing": { "summary": "A aplicação de destino não existe", "value": { "for_application_id": [ "Target application does not exist." ] } }, "Self-share": { "summary": "O destino é a aplicação chamadora", "value": { "for_application_id": [ "Cannot share a session with the same application." ] } }, "TTL bounds": { "summary": "ttl_in_seconds fora dos limites", "value": { "ttl_in_seconds": [ "Ensure this value is greater than or equal to 60." ] } } } } } }, "403": { "description": "As credenciais são válidas, mas não possuem a permissão `write:sessions` para esta aplicação.", "content": { "application/json": { "examples": { "No Permission": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Sem permissão" } } } } } }, "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação de origem para a qual gerar um token.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "for_application_id" ], "properties": { "for_application_id": { "type": "string", "format": "uuid", "description": "UUID da aplicação Didit que irá resgatar o token. Deve existir, não pode estar eliminada e tem de ser diferente da aplicação que efetuou a chamada. Encontre-o na Business Console em **Definições → Aplicação**.", "example": "a5f3bca2-46e2-411e-90ef-a580900a57ee" }, "ttl_in_seconds": { "type": "integer", "description": "Tempo de vida útil do token, em segundos. Mínimo `60`, máximo `86400` (24 h). O valor predefinido é `3600` (1 h).", "minimum": 60, "maximum": 86400, "default": 3600, "example": 3600 } } }, "example": { "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "ttl_in_seconds": 7200 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/share/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"for_application_id\": \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n \"ttl_in_seconds\": 7200\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.share(\n \"11111111-2222-3333-4444-555555555555\",\n for_application_id=\"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds=7200,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.share(\"11111111-2222-3333-4444-555555555555\", {\n for_application_id: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds: 7200,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Share(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsShareParams{\n\tForApplicationID: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n\tTTLInSeconds: didit.Int(7200),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsShareParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().share(\"11111111-2222-3333-4444-555555555555\", SessionsShareParams.builder()\n .forApplicationId(\"a5f3bca2-46e2-411e-90ef-a580900a57ee\")\n .ttlInSeconds(7200L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->share('11111111-2222-3333-4444-555555555555', [\n 'for_application_id' => 'a5f3bca2-46e2-411e-90ef-a580900a57ee',\n 'ttl_in_seconds' => 7200,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.share(\n \"11111111-2222-3333-4444-555555555555\",\n for_application_id: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds: 7200\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ShareAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsShareParams\n{\n ForApplicationId = \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n TtlInSeconds = 7200,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/import-shared/": { "post": { "summary": "Resgatar um token de partilha para clonar uma sessão de verificação para a sua aplicação", "description": "Resgatar um token de partilha para clonar uma sessão de KYC ou KYB para a aplicação chamadora com um novo `session_id`. Não idempotente — um token é resgatado uma única vez por destinatário.", "operationId": "post_v3_session_import_shared", "x-didit-sdk": { "resource": "sessions", "method": "import_shared", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "201": { "description": "Sessão clonada. O corpo é o payload de decisão V3 para ambos os tipos, diferenciados por `session_kind`: `\"user\"` (KYC) com blocos de funcionalidades baseados em listas, tais como `id_verifications`, `liveness_checks`, `aml_screenings`; `\"business\"` (KYB) com blocos como `registry_checks` e `key_people_checks`. Ambos incluem `shared_from_session` — o `session_id` da sessão original na aplicação de origem. Com `trust_review: false`, o `status` da sessão clonada é forçado para `In Review`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDecision" }, "examples": { "User session imported": { "summary": "Sessão KYC clonada (truncada — payload completo de decisão V3 na realidade)", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "session_kind": "user", "shared_from_session": "99999999-8888-7777-6666-555555555555", "session_number": 43762, "session_url": null, "status": "In Review", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "user-1", "created_at": "2026-05-17T08:42:11Z", "expires_at": "2026-05-24T08:42:11Z" } }, "Business session imported": { "summary": "Sessão KYB clonada (truncada — payload completo de decisão KYB V3 na realidade)", "value": { "session_id": "22222222-3333-4444-5555-666666666666", "session_kind": "business", "shared_from_session": "88888888-7777-6666-5555-444444444444", "session_number": 982, "session_url": null, "status": "Approved", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "company-1" } } } } } }, "400": { "description": "Erro de validação (token inválido, expirado, destino incorreto ou que referencia uma sessão que já não existe).", "content": { "application/json": { "examples": { "Invalid Share Token": { "summary": "JWT inválido", "value": { "share_token": [ "Invalid share token." ] } }, "Expired Share Token": { "summary": "Token expirado (`exp` ultrapassado)", "value": { "share_token": [ "Share token has expired." ] } }, "Wrong audience": { "summary": "Token não associado a esta aplicação", "value": { "share_token": [ "This token is not valid for this application." ] } }, "Original missing": { "summary": "A sessão de origem foi eliminada", "value": { "share_token": [ "Original session does not exist." ] } } } } } }, "403": { "description": "Chave de API em falta (uma chave incorreta, revogada ou expirada recebe `401`), ou esta sessão de origem já foi importada para a aplicação chamadora (um resgate por recetor).", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Proibido", "value": { "detail": "You do not have permission to perform this action." } }, "Already imported": { "summary": "Origem já importada uma vez", "value": { "detail": "This session has already been shared with your application." } } } } } }, "404": { "description": "`workflow_id` não pertence à aplicação que efetuou a chamada.", "content": { "application/json": { "examples": { "Workflow not found": { "summary": "Fluxo desconhecido", "value": { "detail": "Workflow does not exist for this application." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "share_token", "trust_review", "workflow_id" ], "properties": { "share_token": { "type": "string", "description": "Token JWT de partilha emitido por [`POST /v3/session/{sessionId}/share/`](/sessions-api/share-session).", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "trust_review": { "type": "boolean", "description": "Se `true`, a sessão clonada mantém o `status` final da origem. Se `false`, é forçada para `In Review`.", "example": false }, "workflow_id": { "type": "string", "format": "uuid", "description": "UUID de um fluxo na aplicação que fez a chamada. Os IDs entre aplicações são rejeitados com `404`.", "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, "vendor_data": { "type": "string", "nullable": true, "description": "Substituição opcional para o `vendor_data` da sessão clonada.", "example": "user-1" } } }, "example": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "trust_review": false, "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "user-1" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/import-shared/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"trust_review\": false,\n \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n \"vendor_data\": \"user-1\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.import_shared(\n share_token=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review=False,\n workflow_id=\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data=\"user-1\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.importShared({\n share_token: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review: false,\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data: \"user-1\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ImportShared(ctx, didit.SessionsImportSharedParams{\n\tShareToken: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n\tTrustReview: false,\n\tWorkflowID: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n\tVendorData: didit.String(\"user-1\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsImportSharedParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().importShared(SessionsImportSharedParams.builder()\n .shareToken(\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\")\n .trustReview(false)\n .workflowId(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\")\n .vendorData(\"user-1\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->importShared([\n 'share_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',\n 'trust_review' => false,\n 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab',\n 'vendor_data' => 'user-1',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.import_shared(\n share_token: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review: false,\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data: \"user-1\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ImportSharedAsync(new SessionsImportSharedParams\n{\n ShareToken = \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n TrustReview = false,\n WorkflowId = \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n VendorData = \"user-1\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/kyb/search/": { "post": { "summary": "Pesquisa de empresa no registo KYB (autónoma)", "operationId": "post_v3_kyb_search", "x-didit-sdk": { "resource": "kyb", "method": "search", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Pesquise registos de empresas oficiais para encontrar empresas candidatas por nome e/ou número de registo. Este é o passo 1 do fluxo de registo de dois passos: a **pesquisa** devolve candidatos simplificados e, em seguida, o `POST /v3/kyb/select/` obtém o perfil completo de um candidato.\n\n**Faturação de pesquisas.** Pesquisas bem-sucedidas que utilizem uma fonte de dados empresariais paga custam USD 0.50 por pedido, independentemente do número de candidatos. Resultados vazios, falhas e resultados fornecidos apenas por outras fontes não são cobrados. O preço aplicável é reservado antes de pesquisar; saldo insuficiente devolve 403 com o código `insufficient_credits`. As tarifas contratuais aplicam-se quando acordadas, e uma tarifa contratual de pesquisa não configurada devolve 403. As pesquisas em sandbox são gratuitas. Repetir uma pesquisa bem-sucedida pode implicar uma nova cobrança; a entrega do callback não adiciona qualquer cobrança. A obtenção do perfil é faturada separadamente. Esta taxa de pesquisa também se aplica à v2. Os candidatos são sempre devolvidos com `fetch_status: \"pending\"`: os dados completos da empresa só são obtidos (e faturados) na seleção.\n\n**`kyb_response_id` é efémero.** É um identificador por pesquisa, não um ID de empresa estável. Selecione prontamente após pesquisar e pesquise novamente para obter um identificador recente em vez de o armazenar.\n\n**`tier` escolhe a cadeia de fornecedores.** `tier` indica o nível de registo no qual a pesquisa é executada: `basic` (a predefinição, a cadeia Lite), `shareholders` ou `ubo`. A pesquisa utiliza a cadeia de fornecedores que serve esse nível, e nem sempre é a mesma cadeia que a pesquisa Lite consulta, pelo que uma pesquisa Lite vazia não é prova de que o registo não contenha a empresa — pesquise novamente no nível de que necessita. Um país que não disponibilize o nível indicado é pesquisado no nível mais elevado que disponibilizar até esse. Obtenha o candidato a partir do endpoint que fornece esse nível: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` ou `POST /v3/kyb/ubo/`.\n\n**Autenticação.** `POST /v3/kyb/search/` (e `/v2/`) recebe a chave de API da sua aplicação no cabeçalho `x-api-key`. O endpoint alojado `POST /v1/kyb/search/` é a rota autenticada por sessão que um fluxo de verificação alojado chama: responde com `403` a uma chave de API e não aceita `tier` — a configuração do registo KYB do fluxo escolhe a cadeia.\n\n**Dois modos.**\n- *Síncrono (predefinição):* a API consulta o registo até que a pesquisa seja resolvida e devolve a lista final de candidatos (`search_resolved: true`).\n- *Assíncrono:* passe `webhook_url` e a API responde imediatamente — normalmente com `search_status: \"pending\"` e uma lista de candidatos vazia — e, em seguida, envia um pedido POST com o callback `kyb.registry_search.resolved` para o seu URL quando o registo terminar. O corpo do callback é `{\"event_id\", \"event_type\": \"kyb.registry_search.resolved\", \"request_id\", \"vendor_data\", \"metadata\", \"search_status\", \"search_resolved\", \"kyb_registry\", \"timestamp\", \"created_at\"}` — note que `timestamp` e `created_at` no callback são números inteiros epoch, ao contrário do `created_at` em formato ISO deste endpoint — e é enviado **não assinado** (cabeçalho `X-Didit-Unsigned-Callback: true`, sem `X-Signature`).\n\n**Códigos de país.** ISO 3166-1 alpha-2 (`GB`, `DE`), além de códigos de subdivisão `XX-YY` onde os registos são regionais — por exemplo, `US-CA` para a Califórnia.\n\n**Sandbox.** Chaves de aplicações em sandbox devolvem um candidato estático sem contactar nenhum registo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country_code" ], "properties": { "country_code": { "type": "string", "maxLength": 10, "description": "Código ISO 3166-1 alpha-2 do país cujo registo de empresas deve ser pesquisado. Por exemplo, `GB`. Onde os registos de empresas operam a nível estadual ou provincial, anexe o código de subdivisão ISO 3166-2 como `XX-YY`: `US-CA` pesquisa o registo da Califórnia. As pesquisas nos Estados Unidos requerem sempre a subdivisão — um simples `US` é rejeitado. Insensível a maiúsculas e minúsculas; normalizado para maiúsculas.", "example": "GB" }, "name": { "type": "string", "maxLength": 255, "description": "Nome da empresa a pesquisar. É obrigatório indicar `name` ou `registration_number`.", "example": "Tesco" }, "registration_number": { "type": "string", "maxLength": 100, "description": "Número de registo a pesquisar. É obrigatório indicar `name` ou `registration_number`." }, "tier": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "default": "basic", "description": "Nível do registo de empresas cuja cadeia de fornecedores executa esta pesquisa. `basic` (predefinição) pesquisa a cadeia Lite do país; `shareholders` e `ubo` pesquisam a cadeia de propriedade desse nível, que pode ser uma fonte diferente, pelo que uma pesquisa Lite vazia não prova que a empresa não conste do registo de empresas. Um país que não disponibilize o nível indicado é pesquisado no nível mais elevado disponível até esse. Obtenha o candidato a partir do endpoint que comercializa o nível pesquisado: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` ou `POST /v3/kyb/ubo/`.", "example": "basic" }, "search_type": { "type": "string", "enum": [ "contains" ], "default": "contains", "description": "Estratégia de correspondência de nomes aplicada pela pesquisa no registo. `contains` é o único valor aceite: nenhuma fonte de registo por detrás da pesquisa disponibiliza um modo de prefixo ou aproximado (fuzzy), pelo que `start_with` e `fuzzy` são rejeitados com `400` (`not a valid choice`)." }, "vendor_data": { "type": "string", "description": "O seu identificador para esta consulta; devolvido e incluído no callback do webhook." }, "metadata": { "type": "object", "nullable": true, "description": "JSON de formato livre; devolvido na resposta e incluído no callback do webhook." }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 500, "description": "Muda a pesquisa para o modo assíncrono: a API responde imediatamente e envia um callback POST não assinado `kyb.registry_search.resolved` para este URL quando a lista de candidatos estiver pronta." } } }, "example": { "country_code": "GB", "name": "Tesco", "search_type": "contains", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/search/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"country_code\": \"GB\",\n \"name\": \"Tesco\",\n \"search_type\": \"contains\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.search(\n country_code=\"GB\",\n name=\"Tesco\",\n search_type=\"contains\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.search({\n country_code: \"GB\",\n name: \"Tesco\",\n search_type: \"contains\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Search(ctx, didit.KYBSearchParams{\n\tCountryCode: \"GB\",\n\tName: didit.String(\"Tesco\"),\n\tSearchType: didit.Some(didit.KYBSearchParamsSearchType(\"contains\")),\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KybSearchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().search(KybSearchParams.builder()\n .countryCode(\"GB\")\n .name(\"Tesco\")\n .searchType(KybSearchParams.SearchType.of(\"contains\"))\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->search([\n 'country_code' => 'GB',\n 'name' => 'Tesco',\n 'search_type' => 'contains',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.search(\n country_code: \"GB\",\n name: \"Tesco\",\n search_type: \"contains\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.SearchAsync(new KybSearchParams\n{\n CountryCode = \"GB\",\n Name = \"Tesco\",\n SearchType = new KybSearchParamsSearchType(\"contains\"),\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Pesquisa aceite. O modo síncrono devolve a lista final de candidatos; o modo webhook devolve imediatamente (frequentemente `search_status: \"pending\"`) e entrega a lista final através do callback `kyb.registry_search.resolved`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Com `webhook_url`: o id persistido do pedido de pesquisa, devolvido como `request_id` no callback `kyb.registry_search.resolved`. Sem `webhook_url`: um UUID de correlação transitório (a pesquisa não é armazenada)." }, "kyb_registry": { "$ref": "#/components/schemas/KYBRegistrySearchResults" }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou." }, "metadata": { "type": "object", "nullable": true, "description": "Eco do objeto `metadata` que enviou." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved search": { "summary": "Modo síncrono — lista final de candidatos", "value": { "request_id": "0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a", "kyb_registry": { "companies": [ { "kyb_response_id": "69aeeb95febb0f1704042259", "name": "Tesco PLC", "registration_number": "00445790", "status": "active", "type": "Public Limited Company", "risk_level": null, "fetch_status": "pending" }, { "kyb_response_id": "69aeeb95febb0f170404225a", "name": "E-TESCO LTD", "registration_number": "15168476", "status": "active", "type": "Private Limited Company", "risk_level": null, "fetch_status": "pending" } ], "pagination": { "total": 2, "page": 1, "per_page": 25 }, "search_status": "resolved", "search_resolved": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:40:00.000000+00:00" } }, "Pending search (webhook mode)": { "summary": "`webhook_url` fornecido — os candidatos chegam através do callback kyb.registry_search.resolved", "value": { "request_id": "5f2d8c1b-7e4a-4b9c-9f0d-3a6e8c2b1d4f", "kyb_registry": { "companies": [], "pagination": { "total": 0, "page": 1, "per_page": 25 }, "search_status": "pending", "search_resolved": false }, "vendor_data": "company-1234", "metadata": { "source": "onboarding" }, "created_at": "2026-06-11T10:41:00.000000+00:00" } } } } } }, "400": { "description": "Erro de validação. Problemas ao nível do campo utilizam o envelope padrão do DRF; a regra de nome/número de registo é reportada sob `non_field_errors`. Um país não abrangido pelos registos responde com `400` e `code: kyb_registry_country_unsupported`.", "content": { "application/json": { "examples": { "Missing search criteria": { "summary": "Nem `name` nem `registration_number` foram fornecidos", "value": { "non_field_errors": [ "Either 'name' or 'registration_number' is required." ] } }, "Invalid country_code": { "summary": "Tem de ser `XX` (alfa-2) ou subdivisão `XX-YY`", "value": { "country_code": [ "country_code must be a 2-letter ISO code." ] } }, "Invalid search_type": { "summary": "Apenas `contains` é aceite", "value": { "search_type": [ "\"start_with\" is not a valid choice." ] } }, "Invalid webhook_url": { "summary": "`webhook_url` tem de ser um URL válido", "value": { "webhook_url": [ "Enter a valid URL." ] } }, "Country not covered": { "summary": "Nenhum registo de empresas abrange o país", "value": { "detail": "Company registry search is not available for this country. Enter the company details manually to continue.", "code": "kyb_registry_country_unsupported" } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. Também é devolvido antes de pesquisar quando a taxa de pesquisa aplicável não pode ser coberta (`code: \"insufficient_credits\"`), ou quando falta uma taxa de pesquisa por contrato.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido, ou o limite de pesquisas foi esgotado. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600), com cabeçalhos `X-RateLimit-*` e `Retry-After`. Separadamente, as pesquisas pagas no registo estão limitadas a 600 por aplicação por hora: acima disso, a resposta é `429` com `code: kyb_registry_search_limit_reached`, e as pesquisas disponibilizadas apenas por fontes gratuitas continuam a funcionar. Aguarde e pesquise novamente mais tarde.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } }, "Search allowance spent": { "summary": "Mais de 600 pesquisas pagas na última hora", "value": { "detail": "The maximum number of company registry searches for this session has been reached. Enter the company details manually to continue.", "code": "kyb_registry_search_limit_reached" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "502": { "description": "O fornecedor de registo de KYB está temporariamente indisponível - uma resposta 5xx, tempo limite esgotado ou falha de ligação do registo a montante. A pesquisa não é faturada. Tente novamente mais tarde ou, no fluxo de verificação alojado da Didit, é oferecida automaticamente ao utilizador a introdução manual da empresa em vez de um erro que apenas permite tentar novamente.", "content": { "application/json": { "examples": { "Registry provider outage": { "summary": "O fornecedor do registo de empresas não respondeu à pesquisa", "value": { "detail": "The KYB registry provider is temporarily unavailable. Please try again shortly.", "code": "kyb_registry_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/v3/kyb/select/": { "post": { "summary": "Seleção de empresa no registo KYB — nível Lite (autónoma)", "operationId": "post_v3_kyb_select", "x-didit-sdk": { "resource": "kyb", "method": "select", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Obtenha o perfil de registo **Lite** de um candidato retornado por `POST /v3/kyb/search/` — dados da empresa, morada registada, identificadores, estado, atividade e os administradores, além do payload em bruto do registo. Os acionistas e beneficiários efetivos são comercializados através de `POST /v3/kyb/shareholders/` e `POST /v3/kyb/ubo/`.\n\n**Associação à pesquisa.** Forneça o `kyb_response_id` do candidato exatamente como retornado por uma pesquisa da mesma aplicação. O identificador é efémero e restrito a essa pesquisa — selecione prontamente e efetue uma nova pesquisa para obter um novo identificador em vez de o armazenar.\n\n**Faturação.** Cada seleção é faturada ao preço Lite do país (qualquer taxa de pesquisa é cobrada em separado); consulte os [preços do registo KYB](/pt/getting-started/kyb-registry-pricing). O saldo é verificado antes de qualquer chamada ao registo (`403` quando insuficiente) e o débito é registado na sessão de empresa criada.\n\n**A persistência é obrigatória.** Cada seleção cria uma sessão de empresa (o seu id é o `request_id`) para que a faturação e a recuperação possam ser acompanhadas; fica visível na consola. `save_api_request` é aceite por simetria, mas tem de ser `true` (a predefinição) — o envio de `false` retorna `400`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/select/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.select(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.select({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Select(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().select(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->select([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.select(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.SelectAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Empresa obtida e faturada. O campo `kyb_registry` contém o perfil completo; verifique `data_resolved` — quando for `false`, o registo de empresas ainda estava em processamento e o registo guardado é concluído automaticamente assim que for resolvido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão de empresa criada para esta consulta. O registo guardado (visível na consola) continua a ser atualizado se a consulta ao registo for concluída após a resposta." }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "O nível que este endpoint comercializa: `basic` (Lite) para select, `shareholders`, `ubo`." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "O nível efetivamente entregue e faturado. Inferior ao solicitado quando os registos do país não contêm dados de propriedade ou quando o registo não tem qualquer registo de propriedade para esta empresa." }, "kyb_registry": { "type": "object", "description": "Perfil completo da empresa no registo de empresas.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID da Didit para este registo de empresa." }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Avaliação da Didit sobre a verificação do registo (por exemplo, `In Review` quando a empresa não está ativa no registo ou não foi possível obter os dados de propriedade)." }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off" ], "description": "Estado normalizado da empresa conforme reportado pelo registo de empresas." }, "data_resolved": { "type": "boolean", "description": "`true` assim que o registo tiver devolvido o perfil completo. `false` quando o registo ainda estava a processar após o polling — o registo guardado é concluído automaticamente assim que o registo ficar resolvido." }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alfa-2.", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "Código de subdivisão quando o registo é regional (p. ex., `CA` para `US-CA`); vazio caso contrário." }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "Nível de risco reportado pelo registo de empresas, quando disponível." }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "Estado de verificação entre jurisdições: `verified` quando o estado do registo estabelece a regularidade da situação (`active`), `failed` quando indica que a empresa já não está em atividade (por exemplo `dissolved`), caso contrário `unknown`. `null` para uma empresa que não provenha de um registo e enquanto uma seleção estiver ainda `pending`." }, "is_from_registry": { "type": "boolean", "description": "Sempre `true` para este endpoint — o perfil foi obtido a partir de um registo oficial." }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "Ciclo de vida de obtenção do registo de empresas. Espelhado por `data_resolved`." }, "alternative_names": { "type": "string", "nullable": true, "description": "Nomes alternativos, comerciais, anteriores ou no idioma original da empresa em texto, quando comunicados." }, "nature_of_business": { "type": "string", "nullable": true, "description": "Descrição da atividade ou código de classificação, quando comunicado." }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "Montante decimal como string, quando reportado." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Código ISO 4217, quando comunicado." }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI, quando comunicado." }, "location_of_registration": { "type": "string", "nullable": true, "description": "Registo de empresas/jurisdição onde a empresa está registada, quando reportado." }, "vat_number": { "type": "string", "nullable": true, "description": "Número de IVA da UE, quando recolhido durante o passo de registo alojado ou editado posteriormente. No momento da seleção, normalmente ainda não está definido — a validação de IVA e do número de identificação fiscal é executada quando o utilizador final envia o passo de registo no fluxo alojado." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Resultado da validação do número de IVA ou, quando inexistente, do `tax_number`, no envio do registo. `valid` / `invalid`: decidido pelo registo oficial do país (VIES da UE, Noruega, Suíça, Brasil, Colômbia, Costa Rica, Equador, Paraguai; Polónia também pelo seu registo doméstico de IVA). `format_valid` / `invalid_format`: decidido pelas regras de formato e de dígito de controlo do país quando nenhum registo pode ser consultado. `could_not_validate`: o registo estava indisponível. `not_applicable`: sem número, um país sem registo ou regras, ou uma sessão de sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "O número que foi verificado, tal como a fonte o conhece (por exemplo, o número de IVA derivado de um SIREN francês ou de um RSIN neerlandês). `null` quando nenhuma verificação foi executada." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "A origem que determinou o `vat_validation_status`: um registo oficial ou `format_rules`. `null` quando nenhuma verificação foi executada." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registado na fonte que validou o número, quando esta o divulga. Apenas definido quando o estado for `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Morada registada junto da fonte que validou o número, quando esta a divulga. Apenas definida quando o estado é `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da verificação. `null` quando nenhuma verificação foi executada." }, "financial_summary": { "type": "object", "nullable": true, "description": "Detalhes das ações/capital reportados pelo registo de empresas (moeda, total de ações, classes de ações), quando disponíveis." }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "Designação no registo em bruto (por ex., `Director`, `Secretary`)." }, "role": { "type": "string", "description": "Função normalizada derivada da designação. Conjunto completo de 17 valores do modelo; a análise do registo de empresas neste endpoint emite tipicamente director, non_executive_director, secretary, chairman ou company_officer.", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "`false` quando o registo marca a nomeação como tendo cessado." }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending" ], "description": "Estado de uma sessão KYC associada, caso tenha sido iniciada uma para este administrador. Caso contrário, `null`." }, "kyc_session_url": { "type": "string", "nullable": true, "description": "URL de verificação da sessão de KYC associada, quando existir." }, "first_name": { "type": "string", "nullable": true, "description": "Nome próprio quando explicitamente indicado pelo registo; não deduzido a partir do nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Apelido quando explicitamente comunicado pelo registo." }, "address": { "type": "string", "nullable": true, "description": "Morada do administrador indicada pelo registo." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data em que o administrador foi nomeado.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data em que a nomeação terminou, quando reportada.", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa comunicada pelo registo de empresas. Nulo quando apenas o ano ou mês de nascimento é conhecido.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Ano de nascimento reportado pelo registo de empresas, incluindo quando a data completa não está disponível." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mês de nascimento reportado pelo registo de empresas. Nulo quando apenas o ano é conhecido." } } }, "description": "Administradores, secretários e outros responsáveis extraídos do registo." }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se o proprietário é uma pessoa singular ou uma entidade coletiva." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Funções normalizadas (por exemplo, `ubo`, `shareholder`)." }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferior da faixa de propriedade reportada pelo registo (por exemplo, `25%`)." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superior do intervalo de propriedade reportado pelo registo." }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending" ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem de propriedade analisada (limite máximo, recorrendo ao limite mínimo como alternativa)." }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa quando comunicada.", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "Data de nomeação quando comunicada.", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "Beneficiários efetivos / pessoas com controlo significativo extraídos do registo. Pode estar vazio quando o registo não divulga a propriedade." }, "addresses": { "type": "array", "nullable": true, "description": "Todas as moradas indicadas pelo registo, num formato canónico. Nulo quando este não indicar nenhuma.", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "As atividades sob as quais o registo classifica a empresa, num formato canónico. Null quando não indica nenhuma.", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Datas de submissão no registo de empresas, quando disponíveis. As declarações anuais e assembleias gerais utilizam last_annual_return_date e last_agm_date; são distintas das contas financeiras." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "Sempre `null` neste endpoint (utilizado pelo fluxo alojado de KYB quando os utilizadores finais editam dados do registo)." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Sempre `null` neste endpoint." }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Definido quando um revisor da consola edita o registo posteriormente." }, "is_editable": { "type": "boolean", "description": "Se os dados provenientes do registo ainda podem ser editados no fluxo alojado/consola." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "Igual ao `registry_tier_delivered` de nível superior." }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable" ], "description": "`delivered` quando os dados de propriedade foram devolvidos, `not_held` quando o registo de propriedade respondeu e não lista esta empresa (consulte `registry_data.ownership_error`), `unavailable` quando um nível de propriedade foi solicitado mas o registo não tinha nenhum para esta empresa ou não pôde ser consultado (consulte `registry_data.ownership_error`), `not_requested` no nível Lite." }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "O nível de registo encomendado pelo fluxo: `basic`, `shareholders` ou `ubo`. Também em `ownership.tier_requested`." }, "registry_monitoring": { "type": "object", "nullable": true, "description": "A monitorização mais recente do registo para a empresa, ou `null` quando não existir nenhuma.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "Os campos da empresa que o monitor acompanha." } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou." }, "metadata": { "type": "object", "nullable": true, "description": "Eco do objeto `metadata` que enviou." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "Perfil completo do registo de empresas (lista de administradores truncada para brevidade)", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } }, "Pending (registry still resolving)": { "summary": "A seleção permaneceu pendente após sondagem — campos esparsos, conclusão automática do lado do servidor", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "Erro de validação. Problemas ao nível do campo utilizam o envelope padrão do DRF. Um país não abrangido pelos registos responde com `400` e `code: kyb_registry_country_unsupported`.", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` é obrigatório", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "As seleções são sempre persistidas", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } }, "Country not covered": { "summary": "Nenhum registo de empresas abrange o país", "value": { "detail": "Company registry search is not available for this country. Enter the company details manually to continue.", "code": "kyb_registry_country_unsupported" } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer triagem ou chamada ao fornecedor ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/passive-liveness/": { "post": { "summary": "Prova de vida passiva", "description": "Detete ataques de apresentação — fotos impressas, reproduções em ecrã, máscaras, deepfakes — a partir de uma única imagem de rosto. Não requer vídeo, movimento nem interação do utilizador.\n\n**Como funciona.** A imagem é analisada por um modelo biométrico; o maior rosto detetado é avaliado e é calculado um `score` de prova de vida (0–100). O `status` é `Declined` quando qualquer aviso de gravidade `error` é acionado:\n- `NO_FACE_DETECTED` — o modelo de prova de vida não encontrou nenhum rosto,\n- `LOW_LIVENESS_SCORE` — pontuação igual ou inferior a `face_liveness_score_decline_threshold` (predefinição `30`),\n- `LIVENESS_FACE_ATTACK` — o modelo detetou um ataque de apresentação,\n- `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` — o rosto corresponde a uma entrada na sua lista de bloqueio de rostos.\n\n`MULTIPLE_FACES_DETECTED` é um sinal de gravidade `warning` (não recusa), e `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` são sinais de gravidade `information` que indicam que o mesmo rosto já apareceu noutra sessão aprovada (nunca recusam). `face_quality` e `face_luminance` (0–100, anulável) descrevem a qualidade da captura.\n\n**Triagem de lista de bloqueio e duplicados.** É executada em **todas** as chamadas — com ou sem `save_api_request` — comparando o rosto detetado com o índice de pesquisa facial da sua aplicação. Rostos anteriores com o mesmo `vendor_data` são excluídos de toda a pesquisa no índice — logo, voltar a executar a prova de vida para o mesmo utilizador não aciona `DUPLICATED_FACE`, e um rosto na lista de bloqueio proveniente de uma sessão com o próprio `vendor_data` do chamador também NÃO é assinalado (a triagem de `FACE_IN_BLOCKLIST` é ignorada para rostos com o mesmo `vendor_data`).\n\n**Faturação.** Cada resposta `200` consome um crédito da Passive Liveness API (pago a partir do crédito do seu plano ou do saldo de carregamento). Saldo insuficiente devolve `403` antes de qualquer processamento de imagem.\n\n**Persistência da sessão e inscrição facial (`save_api_request`, predefinição `true`).** Quando for `true`, a chamada é persistida como uma sessão do tipo API (Business Console, `GET /v3/session/{sessionId}/decision/` através do `request_id` devolvido, webhook `status.updated`), a imagem de referência e o recorte do rosto são armazenados, e o rosto detetado é **inscrito no seu índice de pesquisa facial** para que chamadas posteriores de Pesquisa facial e verificações de duplicados possam corresponder-lhe. Quando for `false`, a chamada é pontual: nada é armazenado e o rosto não é inscrito (a triagem de lista de bloqueio/duplicados continua a ser executada).\n\n**Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada mal formatados continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved`, nenhuma sessão é persistida e não são consumidos créditos.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limite de pedidos.** Quota de escrita partilhada de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-la devolve `429`.", "operationId": "post_v3passive-liveness", "x-didit-sdk": { "resource": "passive_liveness", "method": "check", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "Imagem facial frontal (por exemplo, uma selfie). Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamanho máximo de carregamento: **5 MB** (ficheiros maiores são rejeitados com `400`). As imagens são comprimidas automaticamente para ~0.5 MB antes do processamento, pelo que resoluções muito altas não melhoram a precisão. A imagem deve conter um único sujeito — quando vários rostos estão presentes, o maior é avaliado e um aviso `MULTIPLE_FACES_DETECTED` é adicionado." }, "face_liveness_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "Limiar da pontuação de prova de vida (0–100). Uma pontuação calculada **igual ou inferior** a este valor emite um aviso `LOW_LIVENESS_SCORE` e define o `status` como `Declined`. Predefinição `30`; aumente-o para uma postura antispoofing mais rigorosa. Valores fora de 0–100 devolvem `400`.", "example": 30 }, "rotate_image": { "type": "boolean", "default": false, "description": "Quando `true`, o serviço tenta rotações de 90 graus da entrada e utiliza a orientação que produzir a melhor deteção facial. Útil quando a orientação EXIF está ausente. Adiciona latência.", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando `true` (padrão), persiste a chamada como uma sessão do tipo API, armazena as imagens do rosto, emite um webhook `status.updated` e regista o rosto detetado no seu índice de Pesquisa facial. Quando `false`, a chamada é de execução única — nada é armazenado e o rosto não é registado. A triagem de lista de bloqueio e de duplicados é executada em ambos os casos.", "example": true }, "vendor_data": { "type": "string", "description": "Identificador opaco opcional (o seu ID de utilizador, e-mail, UUID...) guardado na sessão persistida e devolvido. Também é utilizado para excluir sessões anteriores com o mesmo `vendor_data` da verificação de rostos duplicados, para que a reverificação do mesmo utilizador não acione `DUPLICATED_FACE`.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido. Em pedidos multipart, envie-o como um campo de texto codificado em JSON — é convertido num objeto.", "example": { "flow": "withdrawal" } } } }, "example": { "user_image": "(binary JPEG/PNG selfie)", "face_liveness_score_decline_threshold": 30, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "withdrawal" } } } } }, "responses": { "200": { "description": "Prova de vida passiva concluída. `liveness.score` é a confiança de 0 a 100 do modelo de que a imagem mostra uma pessoa viva; `status` é `Approved`, a menos que tenha sido acionado um aviso com gravidade `error`. Um rosto falsificado ou na lista de bloqueio continua a devolver `200` — inspecione `liveness.status` e `liveness.warnings`, e não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o ID da sessão persistida.", "content": { "application/json": { "examples": { "Approved": { "summary": "Rosto com prova de vida — sem avisos", "value": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "liveness": { "status": "Approved", "method": "PASSIVE", "score": 95.0, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [], "face_quality": 84.21, "face_luminance": 50.33 }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - presentation attack": { "summary": "O modelo sinalizou um ataque de spoofing (impressão, reprodução, máscara…)", "value": { "request_id": "f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c", "liveness": { "status": "Declined", "method": "PASSIVE", "score": 12.5, "user_image": { "entities": [ { "bbox": [ 100, 120, 420, 540 ], "confidence": 0.81, "age": 30.1, "gender": "female", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "LOW_LIVENESS_SCORE", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data." }, { "risk": "LIVENESS_FACE_ATTACK", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Liveness Face Attack", "long_description": "The system detected a potential attempt to bypass the liveness check." } ], "face_quality": 72.4, "face_luminance": 48.2 }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - face on blocklist": { "summary": "Rosto com prova de vida, mas corresponde a uma entrada da lista de bloqueio", "value": { "request_id": "0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e", "liveness": { "status": "Declined", "method": "PASSIVE", "score": 93.75, "user_image": { "entities": [ { "bbox": [ 40, 40, 100, 100 ], "confidence": 0.722082, "age": 27.0, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "FACE_IN_BLOCKLIST", "feature": "LIVENESS", "additional_data": { "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "blocklisted_session_number": 3242, "api_service": null }, "log_type": "error", "short_description": "Face in blocklist", "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified." } ], "face_quality": null, "face_luminance": null }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "liveness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Declined` quando for acionado pelo menos um aviso de gravidade `error` (nenhum rosto, pontuação baixa, ataque de apresentação ou correspondência numa lista de bloqueio); caso contrário, `Approved`. Entradas de `warning`/`information` (múltiplos rostos, duplicados) nunca recusam por si só." }, "method": { "type": "string", "enum": [ "PASSIVE" ], "description": "Sempre `PASSIVE` para este endpoint." }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Confiança da prova de vida (0–100, duas casas decimais) de que a imagem retrata uma pessoa viva e não resulta de spoofing. `null` quando o modelo não devolveu nenhuma confiança.", "example": 95.0 }, "user_image": { "type": "object", "description": "Resultados da deteção facial para a imagem submetida.", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Caixa delimitadora do rosto detetado como coordenadas de píxeis `[x_min, y_min, x_max, y_max]` na imagem processada.", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Confiança da deteção facial (0–1).", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "Idade estimada pelo modelo para o rosto detetado, em anos. Apenas informativa — não afeta a decisão de prova de vida.", "example": 26.91 }, "gender": { "type": "string", "description": "Género previsto pelo modelo para o rosto detetado (`male` ou `female`). Apenas informativo.", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "Campo reservado — sempre `null` nas respostas deste endpoint.", "example": null } } }, "description": "Uma entrada por rosto detetado. O maior rosto é o avaliado." }, "best_angle": { "type": "integer", "nullable": true, "description": "Rotação (graus) que produziu a melhor deteção facial; diferente de zero apenas quando `rotate_image=true` corrigiu a orientação.", "example": 0 } } }, "warnings": { "type": "array", "description": "Sinais de risco. Gravidade `error` (recusa): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (pontuação igual ou inferior ao limiar), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Gravidade `warning` (revisão, sem recusa): `MULTIPLE_FACES_DETECTED`. Gravidade `information` (sem recusa): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` — o mesmo rosto já apareceu noutra sessão aprovada.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_FACE_DETECTED", "LOW_LIVENESS_SCORE", "LIVENESS_FACE_ATTACK", "MULTIPLE_FACES_DETECTED", "FACE_IN_BLOCKLIST", "POSSIBLE_FACE_IN_BLOCKLIST", "DUPLICATED_FACE", "POSSIBLE_DUPLICATED_FACE" ], "description": "Código de risco legível por máquina." }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "Funcionalidade que gerou o aviso. Sempre `LIVENESS` neste endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`null` para a maioria dos avisos. Correspondências na lista de bloqueio contêm `{blocklisted_session_id, blocklisted_session_number, api_service}`; correspondências duplicadas contêm `{duplicated_session_id, duplicated_session_number, api_service}` apontando para a sessão correspondente." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravidade. Os avisos `error` alteram o `status` para `Declined`; as entradas `warning` e `information` são informativas e nunca recusam por si sós." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos sobre o risco." }, "long_description": { "type": "string", "description": "Explicação legível do risco." } } } }, "face_quality": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Pontuação de qualidade de captura do rosto detetado, normalizada para 0–100. `null` quando o modelo não conseguiu produzir um valor fiável.", "example": 84.21 }, "face_luminance": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Luminosidade do rosto detetado, normalizada para 0–100. `null` quando não disponível.", "example": 50.33 } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, ou `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, ou `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada, por exemplo `2026-06-12T01:04:42.763237+00:00`." } } } } } }, "400": { "description": "Erro de validação. Devolvido quando `user_image` está em falta, excede 5 MB, tem uma extensão não suportada, falha na descodificação da imagem no lado do servidor ou quando uma opção está fora do intervalo. Os erros de campo utilizam o envelope `{field: [messages]}` do DRF; as falhas de descodificação de imagem utilizam `{\"error\": ...}`.", "content": { "application/json": { "examples": { "Missing image": { "summary": "`user_image` não incluído nos dados do formulário", "value": { "user_image": [ "No file was submitted." ] } }, "Invalid image format": { "summary": "Extensão permitida, mas conteúdo de imagem que não foi possível descodificar", "value": { "error": "Invalid user image format.", "code": "invalid_image" } }, "Unsupported file extension": { "summary": "Extensão de ficheiro fora de tiff/jpg/jpeg/png/webp", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "O carregamento excede o limite de 5 MB", "value": { "user_image": [ "File size should not exceed 5 MB" ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer processamento de imagens ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'face_liveness_score_decline_threshold=30' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.passive_liveness.check(\n user_image=open(\"user_image.jpg\", \"rb\"),\n face_liveness_score_decline_threshold=30.0,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"withdrawal\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.passiveLiveness.check({\n user_image: await fileFromPath(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"withdrawal\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"withdrawal\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.PassiveLivenessCheckParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .faceLivenessScoreDeclineThreshold(30.0)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"withdrawal\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "passiveLiveness->check([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'face_liveness_score_decline_threshold' => 30.0,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'withdrawal'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.passive_liveness.check(\n user_image: Pathname(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"withdrawal\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n FaceLivenessScoreDeclineThreshold = 30.0,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"withdrawal\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/database-validation/": { "post": { "summary": "Validação de base de dados (independente)", "operationId": "post_v3database-validation", "x-didit-sdk": { "resource": "database_validation", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Valide os dados de identidade de uma pessoa em relação a fontes oficiais governamentais e de registo — CPF no Brasil, RENAPER na Argentina, registos de DNI em Espanha e no Peru, INE no México e 100+ outros serviços em 60+ países.\n\n**Seleção de serviços.** Cada país disponibiliza um ou mais serviços de catálogo identificados por um `service_id` (por exemplo, `bra_cpf`, `arg_renaper`, `pan_cedula_sib`). Fixe os serviços pretendidos com o array `services` — se o omitir, é executado exatamente **um** serviço predefinido (o serviço em produção há mais tempo estabelecido para o país). Enviar `services` também altera a resposta para o formato alargado com `services_used` e `match_score`. Descubra serviços, os seus campos obrigatórios e preços através de `GET /v1/organization/database-validation-countries/` (um endpoint de catálogo não documentado nesta especificação) ou no editor de fluxos da Business Console. Alguns serviços estão marcados com `requires_consent=true` no catálogo e exigem `consent=true`; outros requerem onboarding para a sua organização antes de poderem ser chamados.\n\n**Campos de entrada.** `identification_number` é um campo universal que mapeia automaticamente para o campo específico do país correto (consulte a sua descrição). As regras de formato do país são aplicadas antes de qualquer fornecedor ser chamado (por exemplo, o CPF do BRA tem de ter exatamente 11 dígitos) e falhas de formato nunca são faturadas. Os serviços biométricos necessitam do carregamento de uma `selfie` (apenas multipart); o RENAPER da Argentina requer adicionalmente `gender`.\n\n**Resultados.** Cada serviço devolve um mapa `validation` campo a campo mais um `outcome_code` neutro em relação ao fornecedor (`MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT`, `MINOR_BLOCKED`, `DECEASED`, `BIOMETRIC_NO_MATCH`, `BIOMETRIC_IMAGE_UNUSABLE`, `INCONCLUSIVE`, `DOCUMENT_SUPERSEDED`, `REGISTRY_UNAVAILABLE`, `REGISTRY_ERROR`). Tenha em conta as distinções: `NO_MATCH` é uma não correspondência definitiva, `INCONCLUSIVE` significa que o registo não conseguiu confirmar em qualquer sentido (revisão, não recusa) e `BIOMETRIC_IMAGE_UNUSABLE` é um problema técnico com a selfie (repetir a captura), ao contrário do definitivo `BIOMETRIC_NO_MATCH`. O `match_type` global agrega entre serviços (qualquer total → `full_match`, caso contrário qualquer parcial → `partial_match`, caso contrário `no_match`) e `no_match_action`/`partial_match_action` traduzem-no no `status` final. `validation_type` é derivado: `two_by_two` quando dois ou mais serviços distintos produziram uma correspondência total (no número de identificação, no nome completo + data de nascimento em conjunto, ou na morada sem contradições), caso contrário `one_by_one`.\n\n**Persistência.** `save_api_request` tem como predefinição **true**: o resultado é armazenado como uma sessão (`request_id` funciona com `GET /v3/session/{sessionId}/decision/`), aparece na consola e dispara um webhook `status.updated`. Também controla o formato de `validations` — objetos por serviço quando guardado, um mapa fundido `{field: match}` quando não guardado.\n\n**Faturação.** Por serviço: a cada serviço que devolva um resultado faturável é cobrado o seu próprio preço de catálogo. Serviços com falha ou ignorados não são faturados, e pedidos rejeitados com `400` não têm custos. A verificação prévia de saldo cobre a soma dos preços dos serviços selecionados (`403` quando insuficiente).\n\n**Falhas.** Quando nenhum serviço selecionado devolve um resultado utilizável, a API devolve `400` com `validation_errors` se todas as tentativas não respondidas recusaram explicitamente os dados de entrada (`provider_rejected_input`, `retryable: false`). Corrija os dados de entrada antes de tentar novamente. Caso contrário, devolve `502` com `validation_errors` (`empty_provider_response`, `retryable: true`), incluindo rejeições de entrada mistas e tentativas de contingência indisponíveis; nada é faturado (uma sessão continua a ser registada com o estado `Not Finished` quando `save_api_request=true`). Quando apenas alguns serviços falham, a resposta `200` inclui as respetivas falhas em `database_validation.errors`.\n\n**Sandbox.** Chaves de aplicações de sandbox ignoram as chamadas aos registos e a faturação e devolvem uma resposta estática `full_match` — o payload da sandbox inclui sempre `services_used` e `match_score: 100`, independentemente de como `services` foi enviado, pelo que não deve validar a restrição do formato alargado em produção ou a fração 0.0–1.0 de `match_score` face a respostas da sandbox.\n\nEnvie o pedido como `application/json`, ou como `multipart/form-data` ao carregar uma `selfie`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "issuing_state" ], "properties": { "issuing_state": { "type": "string", "description": "Código de país ISO 3166-1 **alpha-3** do registo a validar (ex.: `BRA`, `ESP`, `COL`). Determina quais os serviços disponíveis. Códigos não suportados retornam `400` com a lista completa de opções válidas.", "example": "BRA" }, "services": { "type": "array", "items": { "type": "string" }, "description": "`service_id`s do catálogo a executar para este país (por ex., `[\"bra_cpf\"]`). Também aceita uma única cadeia de caracteres ou uma cadeia separada por vírgulas/codificada em JSON. **Se for omitido ou estiver vazio, é executado exatamente um serviço predefinido** — o serviço em produção há mais tempo estabelecido para o país; serviços mais recentes, biométricos e de pagamento conforme a utilização têm de ser indicados explicitamente. Enviar `services` altera a resposta para o formato alargado (adiciona `services_used` e `match_score`). Cada ID tem de existir e estar em produção para o `issuing_state`; serviços que requerem onboarding devolvem `400` até serem ativados para a sua organização. Descubra os serviços disponíveis por país através de `GET /v1/organization/database-validation-countries/` (um endpoint de catálogo não documentado nesta especificação) ou no editor de fluxos da Business Console.", "example": [ "bra_cpf" ] }, "validation_type": { "type": "string", "deprecated": true, "description": "OBSOLETO. Aceite para retrocompatibilidade, mas ignorado — o `validation_type` da resposta é agora derivado do número de serviços com correspondência total. Utilize `services` para fixar serviços específicos." }, "consent": { "type": "boolean", "default": false, "description": "Defina como `true` quando o utilizador final tiver dado consentimento explícito aos serviços de validação selecionados. Obrigatório para serviços assinalados com `requires_consent=true` no catálogo — sem isso, esses serviços devolvem `400` com `services_requiring_consent`." }, "identification_number": { "type": "string", "description": "Número de identificação universal — mapeado automaticamente para o campo específico do país correto, pelo que pode utilizá-lo em vez de `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 dígitos), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 dígitos), ECU→personal_number (Cédula, 10 dígitos), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 carateres), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 dígitos), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Nunca sobrepõe um campo específico do país fornecido explicitamente." }, "first_name": { "type": "string", "description": "O primeiro nome do indivíduo. Obrigatório para alguns serviços/países.", "example": "John" }, "last_name": { "type": "string", "description": "O apelido do indivíduo. Obrigatório para alguns serviços/países.", "example": "Doe" }, "middle_name": { "type": "string", "description": "Segundo nome, utilizado por serviços de alguns países (AUS, NZL, …)." }, "full_name": { "type": "string", "description": "Nome completo — alguns serviços aceitam isto em vez de nome próprio/apelido (por exemplo, serviços CHN, que correspondem ao nome no sistema de escrita nativo)." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data de nascimento, `YYYY-MM-DD`. Obrigatória para muitos serviços.", "example": "1980-01-01" }, "personal_number": { "type": "string", "description": "Identificador pessoal único emitido pelo governo. Utilizado por: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Considere utilizar `identification_number` em alternativa." }, "tax_number": { "type": "string", "description": "Número de identificação fiscal. Utilizado por: BRA (CPF, 11 dígitos). Considere utilizar `identification_number` em alternativa." }, "document_number": { "type": "string", "description": "Número do documento. Utilizado por: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considere utilizar `identification_number`." }, "document_type": { "type": "string", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "description": "Tipo de documento a validar: `P` passaporte, `DL` carta de condução, `ID` documento de identificação nacional, `RP` autorização de residência (mais `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Obrigatório em alguns serviços (por exemplo, ESP)." }, "expiration_date": { "type": "string", "format": "date", "description": "Data de validade do documento, `YYYY-MM-DD`. Obrigatório para validação ESP (Espanha).", "example": "2030-01-15" }, "date_of_issue": { "type": "string", "format": "date", "description": "Data de emissão do documento, `YYYY-MM-DD` (fecha de expedición). Obrigatório para validação de cédula COL (Colômbia).", "example": "2015-06-20" }, "nationality": { "type": "string", "description": "Nacionalidade em formato ISO 3166-1 alpha-3. Obrigatória para alguns serviços." }, "gender": { "type": "string", "enum": [ "M", "F", "X" ], "description": "Género: `M`, `F` ou `X` (outro/desconhecido). Obrigatório para a validação RENAPER da Argentina (`arg_renaper`)." }, "address": { "description": "Morada de residência. Dê preferência ao objeto estruturado `{\"street_1\":\"123 Main St\",\"street_2\":\"Apt 4B\",\"city\":\"Springfield\",\"region\":\"IL\",\"postal_code\":\"62701\",\"country\":\"US\"}`; uma string completa numa única linha continua a ser aceite. Obrigatório para serviços de verificação de morada; quando um serviço define requisitos de morada, partes em falta devolvem `400` com `address_fields_required_by`.", "oneOf": [ { "type": "object", "properties": { "street_1": { "type": "string" }, "street_2": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, { "type": "string", "description": "Morada completa numa única linha (legado)." } ] }, "address_element_1": { "type": "string", "description": "Morada de rua, incluindo o número e o tipo de rua. Se omitida, é obtida a partir de `address`." }, "address_element_2": { "type": "string", "description": "Apartamento, fração, edifício, piso ou linha de morada adicional. Envie-a apenas quando a tiver explicitamente." }, "address_element_3": { "type": "string", "description": "Cidade, subúrbio, distrito, localidade ou bairro. Se omitido, é derivado de `address`." }, "address_element_4": { "type": "string", "description": "Estado, província, região ou localidade. Se omitido, é derivado de `address`." }, "address_element_5": { "type": "string", "description": "Código postal. `postal_code` é aceite como alias." }, "postal_code": { "type": "string", "description": "Código postal para serviços baseados na morada (alias de `address_element_5`)." }, "driver_license_number": { "type": "string", "description": "Número da carta de condução para serviços de verificação de documentos governamentais (AUS, NZL, IND)." }, "driver_license_card_number": { "type": "string", "description": "Número do cartão físico da carta de condução, quando exigido separadamente do número da carta de condução (AUS)." }, "driver_license_state": { "type": "string", "description": "Estado ou território de emissão da carta de condução (AUS)." }, "driver_license_version": { "type": "string", "description": "Código da versão da carta de condução (NZL)." }, "passport_number": { "type": "string", "description": "Número do passaporte para serviços governamentais de verificação de passaportes (AUS, NZL, IND, CHN)." }, "passport_expiration_date": { "type": "string", "format": "date", "description": "Data de validade do passaporte, `YYYY-MM-DD`, para serviços de verificação de passaportes." }, "passport_file_number": { "type": "string", "description": "Número de ficheiro do passaporte (IND)." }, "passport_issue_country": { "type": "string", "description": "País emissor do passaporte (ISO 3166-1 alfa-3) para serviços de verificação de passaporte." }, "medicare_card_number": { "type": "string", "description": "Número do cartão Medicare (AUS)." }, "immi_card_number": { "type": "string", "description": "Número do ImmiCard australiano." }, "immi_card_expiry_date": { "type": "string", "format": "date", "description": "Data de validade do ImmiCard australiano." }, "citizenship_certificate_number": { "type": "string", "description": "Número do certificado de cidadania (AUS)." }, "birth_registration_number": { "type": "string", "description": "Número de registo da certidão de nascimento (AUS)." }, "birth_registration_date": { "type": "string", "format": "date", "description": "Data de registo da certidão de nascimento (AUS)." }, "birth_registration_state": { "type": "string", "description": "Estado de registo da certidão de nascimento (AUS)." }, "marriage_certificate_number": { "type": "string", "description": "Número da certidão de casamento (AUS)." }, "change_of_name_certificate_number": { "type": "string", "description": "Número da certidão de alteração de nome (AUS)." }, "first_partner_name": { "type": "string", "description": "Primeiro nome do parceiro numa certidão de casamento (AUS)." }, "last_partner_name": { "type": "string", "description": "Apelido do cônjuge numa certidão de casamento (AUS)." }, "voter_id": { "type": "string", "description": "Número de recenseamento eleitoral (IND EPIC, IRL)." }, "epic_card": { "type": "string", "description": "Número do cartão de eleitor EPIC da Índia." }, "pan": { "type": "string", "description": "PAN (Permanent Account Number) da Índia." }, "national_id": { "type": "string", "description": "Número de identificação nacional (CHN, MYS, KEN, KHM, NGA, ZAF, …)." }, "cic": { "type": "string", "description": "Código de Identificación de Credencial (CIC) do INE/IFE mexicano, 9 dígitos. Utilizado pelo serviço de validade de credenciais do INE do México (`mex_ine_vigencia`)." }, "identificador_ciudadano": { "type": "string", "description": "Identificador del Ciudadano do INE mexicano (9 dígitos). Utilizado com `cic` para modelos INE modernos (E/F/G/H) em `mex_ine_vigencia`." }, "ocr": { "type": "string", "description": "Número OCR do INE mexicano (13 dígitos, verso do cartão). Utilizado com `cic` para o Modelo D em `mex_ine_vigencia`." }, "voter_number": { "type": "string", "description": "Clave de Elector do INE mexicano (18 carateres). Utilizado com `emission_number` para modelos IFE legados (A/B/C) em `mex_ine_vigencia`." }, "emission_number": { "type": "string", "description": "Número de Emisión do INE mexicano. Utilizado com `voter_number` para modelos IFE legados (A/B/C) em `mex_ine_vigencia`." }, "bvn": { "type": "string", "description": "Número de Verificação Bancária da Nigéria." }, "bank_card_number": { "type": "string", "description": "Número do cartão bancário (verificação de cartões bancários CHN)." }, "company_registration_number": { "type": "string", "description": "Número de registo da empresa conforme emitido pelo registo de empresas: o CNPJ no Brasil (ex.: `11222333000181`), o número de registo na África do Sul (ex.: `1936/007721/06`). Obrigatório para os serviços de registo de empresas e de administradores da empresa (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`)." }, "company_name": { "type": "string", "description": "Nome registado da empresa, comparado com a entrada no registo. Opcional para `zaf_company_registry`." }, "initials": { "type": "string", "description": "As iniciais da pessoa conforme impressas no documento. Obrigatórias para `zaf_drivers_license`; aceites por `zaf_bank_account_holder`." }, "licence_number": { "type": "string", "description": "Número da carta de condução tal como impresso no cartão, para `zaf_drivers_license`. Quando omitido, é utilizado `document_number`." }, "refugee_file_number": { "type": "string", "description": "Número de processo de refugiado emitido pelo Department of Home Affairs da África do Sul. Obrigatório para `zaf_refugee`." }, "bank_name": { "type": "string", "description": "Nome do banco detentor da conta. Obrigatório para `zaf_bank_account_holder`." }, "bank_account_number": { "type": "string", "description": "Número de conta bancária. Obrigatório por `zaf_bank_account_holder`; aceite por `zaf_fraud_prevention`." }, "account_type": { "type": "string", "description": "Tipo de conta bancária para `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` ou `notKnown`, não sensível a maiúsculas/minúsculas. Qualquer outro valor devolve `400`. Omita-o quando não souber o tipo: a verificação cruzada do tipo de conta é então reportada como não confirmada." }, "phone_number": { "type": "string", "description": "Número de telemóvel de contacto, para os serviços que cruzam a contactabilidade (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`)." }, "right_thumb": { "type": "string", "description": "Impressão digital do polegar direito codificada em base64 para `zaf_dha_fingerprint_match`, com `left_thumb` ou isoladamente." }, "left_thumb": { "type": "string", "description": "Impressão digital do polegar esquerdo codificada em base64 para `zaf_dha_fingerprint_match`, com `right_thumb` ou isoladamente." }, "score_level": { "type": "integer", "description": "Nível mínimo de pontuação biométrica para `zaf_criminal_face_screening`. O valor predefinido é `3`." }, "max_matches": { "type": "integer", "description": "Número máximo de correspondências candidatas devolvidas por `zaf_criminal_face_screening`. Assume por predefinição `1`." }, "vehicle_register_number": { "type": "string", "description": "Número de registo do veículo. Obrigatório, juntamente com `vehicle_licence_plate` e `vin`, para `zaf_vehicle_ownership`." }, "vehicle_licence_plate": { "type": "string", "description": "Matrícula do veículo. Obrigatório, juntamente com `vehicle_register_number` e `vin`, para `zaf_vehicle_ownership`." }, "vin": { "type": "string", "description": "Número de Identificação do Veículo (VIN ou número de chassis). Obrigatório, juntamente com `vehicle_register_number` e `vehicle_licence_plate`, para `zaf_vehicle_ownership`." }, "ssn": { "type": "string", "description": "Número de Segurança Social (EUA)." }, "phone": { "type": "string", "description": "Número de telefone para serviços de verificação de telefone." }, "landline": { "type": "string", "description": "Número de telefone fixo para serviços de verificação de telefone." }, "email": { "type": "string", "format": "email", "description": "Endereço de e-mail para serviços de verificação de identidade." }, "country_of_residence": { "type": "string", "description": "País de residência ISO 3166-1 alfa-2. Utilizado por serviços globais de enriquecimento de identidade (por exemplo, `glb_identity_enrichment`) para direcionar a consulta.", "example": "US" }, "partial_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "NO_ACTION", "description": "O impacto que um `partial_match` tem em `database_validation.status`. A predefinição é `NO_ACTION` (o estado permanece `Approved`, com um aviso)." }, "no_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "O impacto que um `no_match` tem em `database_validation.status`. A predefinição é `DECLINE`." }, "save_api_request": { "type": "boolean", "default": true, "description": "Persistir a validação como uma sessão (visibilidade na consola, endpoint de decisão, webhook `status.updated`). Também altera a estrutura da resposta de `validations`: objetos por serviço quando `true` (predefinição), um mapa de campos unificado quando `false`." }, "vendor_data": { "type": "string", "description": "O seu identificador para o utilizador validado; devolvido e armazenado com a sessão." }, "metadata": { "type": "object", "nullable": true, "description": "JSON de formato livre armazenado com o pedido e devolvido na resposta." } } }, "example": { "issuing_state": "BRA", "services": [ "bra_cpf" ], "identification_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01", "vendor_data": "user-1234" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "issuing_state" ], "properties": { "issuing_state": { "type": "string", "description": "Código de país ISO 3166-1 **alpha-3** do registo a validar (ex.: `BRA`, `ESP`, `COL`). Determina quais os serviços disponíveis. Códigos não suportados retornam `400` com a lista completa de opções válidas.", "example": "BRA" }, "services": { "type": "array", "items": { "type": "string" }, "description": "`service_id`s do catálogo a executar para este país (por ex., `[\"bra_cpf\"]`). Também aceita uma única cadeia de caracteres ou uma cadeia separada por vírgulas/codificada em JSON. **Se for omitido ou estiver vazio, é executado exatamente um serviço predefinido** — o serviço em produção há mais tempo estabelecido para o país; serviços mais recentes, biométricos e de pagamento conforme a utilização têm de ser indicados explicitamente. Enviar `services` altera a resposta para o formato alargado (adiciona `services_used` e `match_score`). Cada ID tem de existir e estar em produção para o `issuing_state`; serviços que requerem onboarding devolvem `400` até serem ativados para a sua organização. Descubra os serviços disponíveis por país através de `GET /v1/organization/database-validation-countries/` (um endpoint de catálogo não documentado nesta especificação) ou no editor de fluxos da Business Console.", "example": [ "bra_cpf" ] }, "validation_type": { "type": "string", "deprecated": true, "description": "OBSOLETO. Aceite para retrocompatibilidade, mas ignorado — o `validation_type` da resposta é agora derivado do número de serviços com correspondência total. Utilize `services` para fixar serviços específicos." }, "consent": { "type": "boolean", "default": false, "description": "Defina como `true` quando o utilizador final tiver dado consentimento explícito aos serviços de validação selecionados. Obrigatório para serviços assinalados com `requires_consent=true` no catálogo — sem isso, esses serviços devolvem `400` com `services_requiring_consent`." }, "identification_number": { "type": "string", "description": "Número de identificação universal — mapeado automaticamente para o campo específico do país correto, pelo que pode utilizá-lo em vez de `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 dígitos), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 dígitos), ECU→personal_number (Cédula, 10 dígitos), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 carateres), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 dígitos), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Nunca sobrepõe um campo específico do país fornecido explicitamente." }, "first_name": { "type": "string", "description": "O primeiro nome do indivíduo. Obrigatório para alguns serviços/países.", "example": "John" }, "last_name": { "type": "string", "description": "O apelido do indivíduo. Obrigatório para alguns serviços/países.", "example": "Doe" }, "middle_name": { "type": "string", "description": "Segundo nome, utilizado por serviços de alguns países (AUS, NZL, …)." }, "full_name": { "type": "string", "description": "Nome completo — alguns serviços aceitam isto em vez de nome próprio/apelido (por exemplo, serviços CHN, que correspondem ao nome no sistema de escrita nativo)." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data de nascimento, `YYYY-MM-DD`. Obrigatória para muitos serviços.", "example": "1980-01-01" }, "personal_number": { "type": "string", "description": "Identificador pessoal único emitido pelo governo. Utilizado por: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Considere utilizar `identification_number` em alternativa." }, "tax_number": { "type": "string", "description": "Número de identificação fiscal. Utilizado por: BRA (CPF, 11 dígitos). Considere utilizar `identification_number` em alternativa." }, "document_number": { "type": "string", "description": "Número do documento. Utilizado por: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considere utilizar `identification_number`." }, "document_type": { "type": "string", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "description": "Tipo de documento a validar: `P` passaporte, `DL` carta de condução, `ID` documento de identificação nacional, `RP` autorização de residência (mais `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Obrigatório em alguns serviços (por exemplo, ESP)." }, "expiration_date": { "type": "string", "format": "date", "description": "Data de validade do documento, `YYYY-MM-DD`. Obrigatório para validação ESP (Espanha).", "example": "2030-01-15" }, "date_of_issue": { "type": "string", "format": "date", "description": "Data de emissão do documento, `YYYY-MM-DD` (fecha de expedición). Obrigatório para validação de cédula COL (Colômbia).", "example": "2015-06-20" }, "nationality": { "type": "string", "description": "Nacionalidade em formato ISO 3166-1 alpha-3. Obrigatória para alguns serviços." }, "gender": { "type": "string", "enum": [ "M", "F", "X" ], "description": "Género: `M`, `F` ou `X` (outro/desconhecido). Obrigatório para a validação RENAPER da Argentina (`arg_renaper`)." }, "address": { "description": "Morada de residência. Dê preferência ao objeto estruturado `{\"street_1\":\"123 Main St\",\"street_2\":\"Apt 4B\",\"city\":\"Springfield\",\"region\":\"IL\",\"postal_code\":\"62701\",\"country\":\"US\"}`; uma string completa numa única linha continua a ser aceite. Obrigatório para serviços de verificação de morada; quando um serviço define requisitos de morada, partes em falta devolvem `400` com `address_fields_required_by`.", "oneOf": [ { "type": "object", "properties": { "street_1": { "type": "string" }, "street_2": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, { "type": "string", "description": "Morada completa numa única linha (legado)." } ] }, "address_element_1": { "type": "string", "description": "Morada de rua, incluindo o número e o tipo de rua. Se omitida, é obtida a partir de `address`." }, "address_element_2": { "type": "string", "description": "Apartamento, fração, edifício, piso ou linha de morada adicional. Envie-a apenas quando a tiver explicitamente." }, "address_element_3": { "type": "string", "description": "Cidade, subúrbio, distrito, localidade ou bairro. Se omitido, é derivado de `address`." }, "address_element_4": { "type": "string", "description": "Estado, província, região ou localidade. Se omitido, é derivado de `address`." }, "address_element_5": { "type": "string", "description": "Código postal. `postal_code` é aceite como alias." }, "postal_code": { "type": "string", "description": "Código postal para serviços baseados na morada (alias de `address_element_5`)." }, "driver_license_number": { "type": "string", "description": "Número da carta de condução para serviços de verificação de documentos governamentais (AUS, NZL, IND)." }, "driver_license_card_number": { "type": "string", "description": "Número do cartão físico da carta de condução, quando exigido separadamente do número da carta de condução (AUS)." }, "driver_license_state": { "type": "string", "description": "Estado ou território de emissão da carta de condução (AUS)." }, "driver_license_version": { "type": "string", "description": "Código da versão da carta de condução (NZL)." }, "passport_number": { "type": "string", "description": "Número do passaporte para serviços governamentais de verificação de passaportes (AUS, NZL, IND, CHN)." }, "passport_expiration_date": { "type": "string", "format": "date", "description": "Data de validade do passaporte, `YYYY-MM-DD`, para serviços de verificação de passaportes." }, "passport_file_number": { "type": "string", "description": "Número de ficheiro do passaporte (IND)." }, "passport_issue_country": { "type": "string", "description": "País emissor do passaporte (ISO 3166-1 alfa-3) para serviços de verificação de passaporte." }, "medicare_card_number": { "type": "string", "description": "Número do cartão Medicare (AUS)." }, "immi_card_number": { "type": "string", "description": "Número do ImmiCard australiano." }, "immi_card_expiry_date": { "type": "string", "format": "date", "description": "Data de validade do ImmiCard australiano." }, "citizenship_certificate_number": { "type": "string", "description": "Número do certificado de cidadania (AUS)." }, "birth_registration_number": { "type": "string", "description": "Número de registo da certidão de nascimento (AUS)." }, "birth_registration_date": { "type": "string", "format": "date", "description": "Data de registo da certidão de nascimento (AUS)." }, "birth_registration_state": { "type": "string", "description": "Estado de registo da certidão de nascimento (AUS)." }, "marriage_certificate_number": { "type": "string", "description": "Número da certidão de casamento (AUS)." }, "change_of_name_certificate_number": { "type": "string", "description": "Número da certidão de alteração de nome (AUS)." }, "first_partner_name": { "type": "string", "description": "Primeiro nome do parceiro numa certidão de casamento (AUS)." }, "last_partner_name": { "type": "string", "description": "Apelido do cônjuge numa certidão de casamento (AUS)." }, "voter_id": { "type": "string", "description": "Número de recenseamento eleitoral (IND EPIC, IRL)." }, "epic_card": { "type": "string", "description": "Número do cartão de eleitor EPIC da Índia." }, "pan": { "type": "string", "description": "PAN (Permanent Account Number) da Índia." }, "national_id": { "type": "string", "description": "Número de identificação nacional (CHN, MYS, KEN, KHM, NGA, ZAF, …)." }, "cic": { "type": "string", "description": "Código de Identificación de Credencial (CIC) do INE/IFE mexicano, 9 dígitos. Utilizado pelo serviço de validade de credenciais do INE do México (`mex_ine_vigencia`)." }, "identificador_ciudadano": { "type": "string", "description": "Identificador del Ciudadano do INE mexicano (9 dígitos). Utilizado com `cic` para modelos INE modernos (E/F/G/H) em `mex_ine_vigencia`." }, "ocr": { "type": "string", "description": "Número OCR do INE mexicano (13 dígitos, verso do cartão). Utilizado com `cic` para o Modelo D em `mex_ine_vigencia`." }, "voter_number": { "type": "string", "description": "Clave de Elector do INE mexicano (18 carateres). Utilizado com `emission_number` para modelos IFE legados (A/B/C) em `mex_ine_vigencia`." }, "emission_number": { "type": "string", "description": "Número de Emisión do INE mexicano. Utilizado com `voter_number` para modelos IFE legados (A/B/C) em `mex_ine_vigencia`." }, "bvn": { "type": "string", "description": "Número de Verificação Bancária da Nigéria." }, "bank_card_number": { "type": "string", "description": "Número do cartão bancário (verificação de cartões bancários CHN)." }, "company_registration_number": { "type": "string", "description": "Número de registo da empresa conforme emitido pelo registo de empresas: o CNPJ no Brasil (ex.: `11222333000181`), o número de registo na África do Sul (ex.: `1936/007721/06`). Obrigatório para os serviços de registo de empresas e de administradores da empresa (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`)." }, "company_name": { "type": "string", "description": "Nome registado da empresa, comparado com a entrada no registo. Opcional para `zaf_company_registry`." }, "initials": { "type": "string", "description": "As iniciais da pessoa conforme impressas no documento. Obrigatórias para `zaf_drivers_license`; aceites por `zaf_bank_account_holder`." }, "licence_number": { "type": "string", "description": "Número da carta de condução tal como impresso no cartão, para `zaf_drivers_license`. Quando omitido, é utilizado `document_number`." }, "refugee_file_number": { "type": "string", "description": "Número de processo de refugiado emitido pelo Department of Home Affairs da África do Sul. Obrigatório para `zaf_refugee`." }, "bank_name": { "type": "string", "description": "Nome do banco detentor da conta. Obrigatório para `zaf_bank_account_holder`." }, "bank_account_number": { "type": "string", "description": "Número de conta bancária. Obrigatório por `zaf_bank_account_holder`; aceite por `zaf_fraud_prevention`." }, "account_type": { "type": "string", "description": "Tipo de conta bancária para `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` ou `notKnown`, não sensível a maiúsculas/minúsculas. Qualquer outro valor devolve `400`. Omita-o quando não souber o tipo: a verificação cruzada do tipo de conta é então reportada como não confirmada." }, "phone_number": { "type": "string", "description": "Número de telemóvel de contacto, para os serviços que cruzam a contactabilidade (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`)." }, "right_thumb": { "type": "string", "description": "Impressão digital do polegar direito codificada em base64 para `zaf_dha_fingerprint_match`, com `left_thumb` ou isoladamente." }, "left_thumb": { "type": "string", "description": "Impressão digital do polegar esquerdo codificada em base64 para `zaf_dha_fingerprint_match`, com `right_thumb` ou isoladamente." }, "score_level": { "type": "integer", "description": "Nível mínimo de pontuação biométrica para `zaf_criminal_face_screening`. O valor predefinido é `3`." }, "max_matches": { "type": "integer", "description": "Número máximo de correspondências candidatas devolvidas por `zaf_criminal_face_screening`. Assume por predefinição `1`." }, "vehicle_register_number": { "type": "string", "description": "Número de registo do veículo. Obrigatório, juntamente com `vehicle_licence_plate` e `vin`, para `zaf_vehicle_ownership`." }, "vehicle_licence_plate": { "type": "string", "description": "Matrícula do veículo. Obrigatório, juntamente com `vehicle_register_number` e `vin`, para `zaf_vehicle_ownership`." }, "vin": { "type": "string", "description": "Número de Identificação do Veículo (VIN ou número de chassis). Obrigatório, juntamente com `vehicle_register_number` e `vehicle_licence_plate`, para `zaf_vehicle_ownership`." }, "ssn": { "type": "string", "description": "Número de Segurança Social (EUA)." }, "phone": { "type": "string", "description": "Número de telefone para serviços de verificação de telefone." }, "landline": { "type": "string", "description": "Número de telefone fixo para serviços de verificação de telefone." }, "email": { "type": "string", "format": "email", "description": "Endereço de e-mail para serviços de verificação de identidade." }, "country_of_residence": { "type": "string", "description": "País de residência ISO 3166-1 alfa-2. Utilizado por serviços globais de enriquecimento de identidade (por exemplo, `glb_identity_enrichment`) para direcionar a consulta.", "example": "US" }, "partial_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "NO_ACTION", "description": "O impacto que um `partial_match` tem em `database_validation.status`. A predefinição é `NO_ACTION` (o estado permanece `Approved`, com um aviso)." }, "no_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "O impacto que um `no_match` tem em `database_validation.status`. A predefinição é `DECLINE`." }, "save_api_request": { "type": "boolean", "default": true, "description": "Persistir a validação como uma sessão (visibilidade na consola, endpoint de decisão, webhook `status.updated`). Também altera a estrutura da resposta de `validations`: objetos por serviço quando `true` (predefinição), um mapa de campos unificado quando `false`." }, "vendor_data": { "type": "string", "description": "O seu identificador para o utilizador validado; devolvido e armazenado com a sessão." }, "metadata": { "type": "object", "nullable": true, "description": "JSON de formato livre armazenado com o pedido e devolvido na resposta." }, "selfie": { "type": "string", "format": "binary", "description": "Imagem de selfie (`jpg`, `jpeg`, `png`, `webp`; máx. 2 MB — as imagens são comprimidas para ~1,5 MB antes do carregamento para o registo) para serviços de validação biométrica, por ex. Argentina RENAPER (`arg_renaper`) e Panamá SIB (`pan_cedula_sib`, `pan_cedula_sib_plus`). Obrigatória sempre que um serviço selecionado a indique como campo obrigatório. Apenas disponível via `multipart/form-data`." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/database-validation/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"issuing_state\": \"BRA\",\n \"services\": [\"bra_cpf\"],\n \"identification_number\": \"12345678900\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1980-01-01\",\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.database_validation.validate(\n issuing_state=\"BRA\",\n services=[\"bra_cpf\"],\n identification_number=\"12345678900\",\n first_name=\"John\",\n last_name=\"Doe\",\n date_of_birth=\"1980-01-01\",\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.databaseValidation.validate({\n issuing_state: \"BRA\",\n services: [\"bra_cpf\"],\n identification_number: \"12345678900\",\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1980-01-01\",\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{\n\tIssuingState: \"BRA\",\n\tServices: didit.Some([]string{\"bra_cpf\"}),\n\tIdentificationNumber: didit.String(\"12345678900\"),\n\tFirstName: didit.String(\"John\"),\n\tLastName: didit.String(\"Doe\"),\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.DatabaseValidationValidateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder()\n .issuingState(\"BRA\")\n .services(List.of(\"bra_cpf\"))\n .identificationNumber(\"12345678900\")\n .firstName(\"John\")\n .lastName(\"Doe\")\n .dateOfBirth(LocalDate.parse(\"1980-01-01\"))\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "databaseValidation->validate([\n 'issuing_state' => 'BRA',\n 'services' => ['bra_cpf'],\n 'identification_number' => '12345678900',\n 'first_name' => 'John',\n 'last_name' => 'Doe',\n 'date_of_birth' => '1980-01-01',\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.database_validation.validate(\n issuing_state: \"BRA\",\n services: [\"bra_cpf\"],\n identification_number: \"12345678900\",\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1980-01-01\",\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams\n{\n IssuingState = \"BRA\",\n Services = new string[] { \"bra_cpf\" },\n IdentificationNumber = \"12345678900\",\n FirstName = \"John\",\n LastName = \"Doe\",\n DateOfBirth = \"1980-01-01\",\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Validação concluída — pelo menos um serviço selecionado devolveu um resultado utilizável. Inspecione `database_validation.match_type` para o resultado agregado, `validations` para as comparações de campos por serviço e `outcome_code`s, e `errors` (quando presentes) para serviços que falharam.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório." }, "database_validation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "`Declined` quando o `match_type` global aciona uma ação `DECLINE` (`no_match_action` tem como predefinição `DECLINE`, `partial_match_action` tem `NO_ACTION`); `In Review` quando nenhum serviço produziu uma comparação utilizável, por exemplo, quando o único serviço selecionado devolveu `REGISTRY_UNAVAILABLE` ou `INCONCLUSIVE`; caso contrário, `Approved`. Um pedido que selecionou vários serviços pode ser `Approved` com base na correspondência de um serviço enquanto outro esteve indisponível, por isso verifique também `errors` e os respetivos `outcome_code`s de cada serviço." }, "issuing_state": { "type": "string", "description": "Eco do país ISO 3166-1 alfa-3 relativamente ao qual foi validado.", "example": "BRA" }, "validation_type": { "type": "string", "enum": [ "one_by_one", "two_by_two" ], "description": "Derivado dos resultados: `two_by_two` quando ≥2 serviços distintos produziram uma correspondência completa (no número de identificação, no nome completo + data de nascimento em conjunto, ou na morada sem contradições); `one_by_one` caso contrário. (O campo do pedido com o mesmo nome foi descontinuado e é ignorado.)" }, "screened_data": { "type": "object", "description": "Eco dos campos de entrada que foram enviados para os serviços selecionados (datas normalizadas para `YYYY-MM-DD`; uma `selfie`, quando enviada, é devolvida como um URL pré-assinado; `consent_obtained: true` é adicionado quando o consentimento foi dado)." }, "match_type": { "type": "string", "nullable": true, "enum": [ "full_match", "partial_match", "no_match" ], "description": "Resultado global agregado entre serviços com comparações ao nível dos campos: qualquer `full_match` → `full_match`; caso contrário, qualquer `partial_match` → `partial_match`; caso contrário, `no_match`. Serviços apenas de resultado, como a triagem criminal biométrica, podem devolver `null`; inspecione cada item em `validations` para obter o seu `outcome_code`." }, "validations": { "description": "O formato depende de `save_api_request`. **`true` (predefinição):** um array de objetos por serviço (`service_id`, `service_name`, `validation`, `outcome_code`, `outcome_detail`, `source_data`). **`false`:** um único objeto simples que funde os resultados ao nível do campo de todos os serviços (`{\"full_name\": \"full_match\", ...}`).", "oneOf": [ { "type": "array", "items": { "type": "object", "description": "Resultado de validação por serviço (devolvido quando `save_api_request=true`, o valor predefinido).", "properties": { "service_id": { "type": "string", "description": "ID de catálogo do serviço que produziu este resultado (por ex., `bra_cpf`).", "example": "bra_cpf" }, "service_name": { "type": "string", "description": "Nome de catálogo legível do serviço.", "example": "Brazil - CPF status check" }, "validation": { "type": "object", "description": "Comparação campo a campo entre os seus dados de entrada e o registo oficial. As chaves são nomes canónicos de campos (`full_name`, `date_of_birth`, `identification_number`, `address`, …); os valores são `full_match`, `partial_match` ou `no_match`.", "additionalProperties": { "type": "string", "enum": [ "full_match", "partial_match", "no_match" ] } }, "outcome_code": { "type": "string", "enum": [ "MATCH", "PARTIAL_MATCH", "NO_MATCH", "DOCUMENT_NOT_FOUND", "INVALID_DOCUMENT_FORMAT", "INVALID_INPUT", "MINOR_BLOCKED", "DECEASED", "BIOMETRIC_NO_MATCH", "BIOMETRIC_IMAGE_UNUSABLE", "INCONCLUSIVE", "DOCUMENT_SUPERSEDED", "REGISTRY_UNAVAILABLE", "REGISTRY_ERROR" ], "description": "Resultado neutro em relação ao fornecedor da consulta ao registo. `MATCH`/`PARTIAL_MATCH`/`NO_MATCH` descrevem a comparação; `DOCUMENT_NOT_FOUND` significa que o identificador não está no registo; `INCONCLUSIVE` significa que o registo não conseguiu confirmar em nenhum sentido (encaminhado para revisão — NÃO é uma não correspondência); `BIOMETRIC_NO_MATCH` é uma não correspondência facial definitiva, enquanto `BIOMETRIC_IMAGE_UNUSABLE` é um problema técnico de imagem (repita a selfie); `DECEASED`/`MINOR_BLOCKED` são resultados definidos pela política do registo; `DOCUMENT_SUPERSEDED` significa que a identidade coincidiu mas a edição do documento apresentado não é a que consta no ficheiro (foi emitida uma edição mais recente); `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` significam que o próprio registo rejeitou os dados enviados; `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` indicam falhas a montante." }, "outcome_detail": { "type": "string", "nullable": true, "description": "Detalhe do estado a montante em bruto que suporta o código de resultado (por ex., um código de estado HTTP ou de registo)." }, "source_data": { "type": "object", "nullable": true, "description": "Visualização limpa e normalizada do registo oficial com recurso a nomes de campos canónicos (`identification_number`, `first_name`, `last_name`, `date_of_birth`, além de sinalizadores específicos do registo). Os campos de imagem, quando presentes, são devolvidos como URLs pré-assinados." } } } }, { "type": "object", "additionalProperties": { "type": "string", "enum": [ "full_match", "partial_match", "no_match" ] }, "description": "Resultados fundidos ao nível do campo (formato sem estado `save_api_request=false`)." } ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Funcionalidade que gerou o aviso." }, "risk": { "type": "string", "description": "Identificador de risco legível por máquina." }, "additional_data": { "type": "object", "nullable": true, "description": "Contexto adicional para o aviso, quando disponível." }, "log_type": { "type": "string", "description": "`warning`, `information` ou `error` — como o risco afetou o resultado." }, "short_description": { "type": "string", "description": "Resumo legível por humanos numa única linha." }, "long_description": { "type": "string", "description": "Explicação completa e legível por humanos." } } }, "description": "`DATABASE_VALIDATION_NO_MATCH` ou `DATABASE_VALIDATION_PARTIAL_MATCH` quando aplicável; vazio em caso de correspondência total." }, "errors": { "type": "array", "description": "Presente apenas quando alguns (mas não todos) os serviços selecionados falharam. Cada entrada contém `service_id`, `code`, `message` e `retryable`. Um serviço aqui reportado está ausente de `validations` e `services_used`, e não é faturado. Este array é o único local onde aparece, pelo que deve inspecioná-lo mesmo quando `status` for `Approved`.", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string", "example": "empty_provider_response" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "`true` quando o serviço não produziu resposta e tentar novamente mais tarde pode ser bem-sucedido; `false` quando a fonte recusou os dados enviados e os dados de entrada têm de ser corrigidos primeiro.", "example": true } } } }, "services_used": { "type": "array", "items": { "type": "string" }, "description": "IDs de catálogo dos serviços que devolveram um resultado faturável. **Apenas presente quando o pedido enviou explicitamente `services`.**" }, "match_score": { "type": "number", "description": "Fração (0.0–1.0) dos serviços tentados que produziram uma correspondência total (no número de identificação, no nome completo + data de nascimento em conjunto, ou na morada sem contradições). **Apenas presente quando o pedido incluiu explicitamente `services`.**" } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou." }, "metadata": { "type": "object", "nullable": true, "description": "Eco do objeto `metadata` que enviou." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Full match (Approved)": { "summary": "Predefinição save_api_request=true — objetos `validations` por serviço", "value": { "request_id": "7f9a1c0e-1f2b-4f6e-9d3a-2b1c0e7f9a1c", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": [ { "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "outcome_code": "MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "12345678900", "first_name": "JOHN", "last_name": "DOE", "date_of_birth": "1980-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-11T10:30:00.000000+00:00" } }, "Explicit services (extended shape)": { "summary": "Pedido enviado com `services` — a resposta adiciona `services_used` e `match_score`", "value": { "request_id": "b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": [ { "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "outcome_code": "MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "12345678900", "first_name": "JOHN", "last_name": "DOE", "date_of_birth": "1980-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [], "services_used": [ "bra_cpf" ], "match_score": 1.0 }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-11T10:30:00.000000+00:00" } }, "No match (Declined)": { "summary": "Não há correspondência no registo de empresas — predefinição `no_match_action=DECLINE`", "value": { "request_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789", "database_validation": { "status": "Declined", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "no_match", "validations": [ { "validation": { "full_name": "no_match", "date_of_birth": "no_match", "identification_number": "no_match" }, "outcome_code": "NO_MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "00987654321", "first_name": "TOTALLY", "last_name": "DIFFERENT NAME", "date_of_birth": "1999-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [ { "feature": "DATABASE_VALIDATION", "risk": "DATABASE_VALIDATION_NO_MATCH", "additional_data": null, "log_type": "error", "short_description": "Database validation no match", "long_description": "The system identified a no match in the database validation, requiring further investigation." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:31:00.000000+00:00" } }, "Stateless (save_api_request=false)": { "summary": "`validations` condensa-se num mapa de campos consolidado; nada é guardado", "value": { "request_id": "c4d5e6f7-8901-2345-6789-abcdef012345", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:32:00.000000+00:00" } } } } } }, "400": { "description": "Erro de validação - nada é faturado. Os erros de campo de pré-verificação ocorrem antes de qualquer chamada externa. Se todas as tentativas sem resposta recusarem explicitamente a entrada, a resposta inclui, em alternativa, `validation_errors` com `code: provider_rejected_input` e `retryable: false`; corrija a entrada antes de tentar novamente. Os problemas ao nível do campo utilizam o envelope padrão do DRF; os problemas de catálogo devolvem um array `services` (mais `requires_onboarding` ou `services_requiring_consent` quando relevante); os erros de campos em falta incluem `fields_required_by`, mapeando cada campo em falta para os serviços que o exigem; os serviços que necessitam de pelo menos um identificador adicional (por exemplo, `usa_states_credit_bureau`, que não consegue verificar apenas um nome) devolvem `any_field_required_by`, mapeando cada serviço para os campos dos quais pelo menos um deve estar presente; os problemas de formato verificados por serviço devolvem `invalid_fields_by_service`.", "content": { "application/json": { "examples": { "Invalid issuing_state": { "summary": "País não suportado — a mensagem lista todos os códigos alpha-3 válidos", "value": { "error": [ "Invalid issuing state. Valid options are: ARE, ARG, AUS, AUT, BEL, BGD, BOL, BRA, CAN, CHE, CHL, CHN, CIV, COL, CRI, CZE, DEU, DNK, DOM, ECU, ESP, FIN, FRA, GBR, GHA, GLB, GRC, GTM, HKG, HND, IDN, IND, IRL, ITA, KEN, KHM, MAR, MEX, MYS, NGA, NLD, NOR, NZL, OMN, PAN, PER, PHL, POL, PRT, PRY, QAT, SGP, SLV, SVK, SWE, THA, UGA, URY, USA, VEN, ZAF, ZMB, ZWE" ] } }, "Missing required fields": { "summary": "União de campos obrigatórios entre os serviços selecionados, com a sugestão de campo universal", "value": { "error": [ "Missing required fields: tax_number (or use 'identification_number' which maps to 'tax_number' for BRA)" ], "fields_required_by": { "tax_number": [ "bra_cpf" ] } } }, "Unknown service id": { "summary": "`services` contém um ID que não consta do catálogo", "value": { "services": [ "Unknown service_id(s): ['bogus_service']" ] } }, "Service not live for country": { "summary": "`services` indica um serviço de outro país (ou uma entrada fictícia)", "value": { "services": [ "Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration']" ] } }, "Service requires onboarding": { "summary": "O serviço existe, mas ainda não está ativado para a sua organização", "value": { "services": [ "Services require onboarding before they can be enabled for AUS: ['aus_australia_driver_licence']. Contact Didit support to activate them." ], "requires_onboarding": [ "aus_australia_driver_licence" ] } }, "Consent missing": { "summary": "Um serviço selecionado está marcado com requires_consent=true e `consent` não era `true`", "value": { "consent": [ "Explicit end-user consent is required for these database validation services: ['chn_national_id']. Send `consent=true`." ], "services_requiring_consent": [ "chn_national_id" ] } }, "Country format rule violation": { "summary": "O identificador falha a regra de formato do país (comprimento/dígitos/regex)", "value": { "tax_number": [ "Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10)." ] } }, "Service-specific format violation": { "summary": "Um campo não cumpre os requisitos de formato próprios do serviço selecionado", "value": { "error": [ "One or more fields do not match the format required by the selected service." ], "invalid_fields_by_service": { "chn_national_id": [ "national_id_format" ] } } }, "Input refused by every attempt": { "summary": "Corrija os dados de entrada antes de tentar novamente", "value": { "error": "The source refused to run this query with the supplied input.", "validation_errors": [ { "service_id": "bra_cpf", "code": "provider_rejected_input", "message": "The source refused to run this query with the supplied input.", "retryable": false } ] } } }, "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "description": "Explicação ao nível do pedido ou erros de campos na pré-validação.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "validation_errors": { "type": "array", "description": "Presente quando todas as tentativas não respondidas recusaram a entrada após a pré-verificação.", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "Se tentar novamente mais tarde pode resolver esta falha de serviço. False significa que deve primeiro corrigir os dados fornecidos." } } } } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer triagem ou chamada ao fornecedor ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "Nenhum serviço selecionado devolveu um resultado utilizável. Inspecione cada entrada de validation_errors antes de tentar novamente; o HTTP 502 por si só não determina uma falha transitória. Um empty_provider_response com retryable: true indica resultados indisponíveis ou não explicados, incluindo um serviço primário recusado seguido de um fallback indisponível. Em contrapartida, as entradas legadas provider_invalid_input e provider_validation_error exigem dados de entrada corrigidos e podem omitir retryable. Nada é faturado. Quando save_api_request=true, a tentativa falhada é registada como uma sessão com o estado Not Finished. Falhas parciais devolvem 200 com database_validation.errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "Se tentar novamente mais tarde pode resolver esta falha de serviço. False significa que deve primeiro corrigir os dados fornecidos." } } } } } }, "examples": { "Provider returned no result": { "summary": "Todos os serviços selecionados falharam", "value": { "error": "Database validation could not be performed. The external validation service did not return a result. Please try again later.", "validation_errors": [ { "service_id": "bra_cpf", "code": "empty_provider_response", "message": "The provider did not return a database validation result.", "retryable": true } ] } } } } } } } } }, "/v3/phone/send/": { "post": { "summary": "Enviar código por telefone", "description": "Envie um código de utilização única (OTP) para um número de telefone através do WhatsApp, SMS ou outro canal suportado e, em seguida, verifique-o com [`POST /v3/phone/check/`](/pt/standalone-apis/phone-check).\n\n**Como o envio e a verificação se articulam.** O estado da verificação tem como chave a sua aplicação e o `phone_number` em formato E.164 — a chamada de verificação não recebe `request_id`. Cada novo envio cria uma verificação pendente que dura **5 minutos**: chame a verificação com o mesmo número e o código que o utilizador recebeu antes do fecho da janela. Chamar o envio novamente para o mesmo número enquanto uma verificação estiver pendente volta a enviar um código para essa mesma verificação (`status: \"Retry\"`, o mesmo `request_id`). No máximo, uma nova tentativa é associada desta forma (dois envios no total); um envio adicional inicia uma nova verificação com um novo `request_id`. A janela de 5 minutos é contada a partir do primeiro envio e não é prolongada por novas tentativas.\n\n**Canais de entrega.** `options.preferred_channel` seleciona o canal (`whatsapp` por predefinição; `sms`, `telegram`, `voice`, `rcs`, `viber` e `zalo` também são suportados). Quando o canal preferencial não estiver disponível para o país ou número de destino, a entrega recorre automaticamente ao SMS como alternativa — o envio continua a indicar `Success` e o canal efetivamente utilizado é indicado pela resposta de verificação (`phone.verification_method` e os eventos de `lifecycle`).\n\n**Marca.** Os códigos por SMS incluem o nome de remetente de SMS da sua aplicação, configurado na Business Console, sem custos adicionais. Passe `options.sms_sender_name` para enviar um código com outro nome, ou `options.use_white_label_customization: true` para recorrer ao seu nome público de marca branca quando nenhum nome de remetente estiver definido. Os códigos do WhatsApp utilizam uma mensagem fixa; associe o seu próprio número de WhatsApp Business na Business Console para os enviar a partir do nome e número da sua empresa, sendo faturado apenas pela tarifa da Didit.\n\n**Estados de envio.** `Success` — OTP enviado para uma nova verificação; `Retry` — OTP reenviado para a verificação pendente; `Blocked` — a camada antifraude recusou o envio (consulte `reason`, por exemplo `repeated_attempts`, `suspicious`, `spam`). Um envio `Blocked` finaliza imediatamente a verificação como `Declined` com um aviso de risco elevado, pelo que uma verificação posterior devolve `Expired or Not Found`.\n\n**Faturação.** O preço depende do país de destino e do canal que efetivamente entrega a mensagem — consulte [Preços da Verificação de telefone](/pt/getting-started/phone-verification-pricing). Apenas os envios `Blocked` têm garantia de gratuitidade: qualquer outra tentativa de envio não faturada é cobrada na finalização ou expiração da verificação, mesmo que a entrega nunca tenha sido confirmada ou o fornecedor de entrega tenha reportado a mensagem como impossível de entregar. As verificações são sempre gratuitas. Como medida antiabuso, a verificação de telefone fica desativada até ao primeiro carregamento de saldo da sua organização (`403`).\n\n**Persistência da sessão.** Cada nova verificação é persistida como uma sessão do tipo API: `request_id` é um ID de sessão real que pode passar para `GET /v3/session/{sessionId}/decision/`, a verificação é apresentada na Business Console e os webhooks `status.updated` são disparados à medida que progride.\n\n**Sandbox.** As chaves de API da sandbox ignoram a entrega e a faturação: após a validação do pedido (dados de entrada com formato incorreto continuam a devolver `400`), o endpoint devolve um payload estático de `Success` com um `request_id` aleatório; nenhuma mensagem é enviada e nada é persistido. Utilize o código `123456` na verificação em sandbox.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limites de pedidos.** Orçamento de escrita partilhado de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE, além de um limite antiabuso de 4 tentativas de envio por número de telefone por hora; exceder qualquer um deles devolve `429`.", "operationId": "post_v3phone_send", "x-didit-sdk": { "resource": "phone", "method": "send_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/send/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"options\": {\n \"code_size\": 6,\n \"preferred_channel\": \"whatsapp\",\n \"locale\": \"en-US\"\n },\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.send_code(\n phone_number=\"+14155552671\",\n options={\n \"locale\": \"en-US\",\n \"preferred_channel\": \"whatsapp\",\n },\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.sendCode({\n phone_number: \"+14155552671\",\n options: {\n locale: \"en-US\",\n preferred_channel: \"whatsapp\",\n },\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.SendCode(ctx, didit.PhoneSendCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tOptions: didit.Some(didit.PhoneSendCodeParamsOptions{\n\t\tLocale: didit.String(\"en-US\"),\n\t\tPreferredChannel: didit.Some(didit.PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneSendCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().sendCode(PhoneSendCodeParams.builder()\n .phoneNumber(\"+14155552671\")\n .options(PhoneSendCodeParams.Options.builder()\n .locale(\"en-US\")\n .preferredChannel(PhoneSendCodeParams.Options.PreferredChannel.of(\"whatsapp\"))\n .build())\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->sendCode([\n 'phone_number' => '+14155552671',\n 'options' => [\n 'locale' => 'en-US',\n 'preferred_channel' => 'whatsapp',\n ],\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.send_code(\n phone_number: \"+14155552671\",\n options: {\n locale: \"en-US\",\n preferred_channel: \"whatsapp\",\n },\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.SendCodeAsync(new PhoneSendCodeParams\n{\n PhoneNumber = \"+14155552671\",\n Options = new PhoneSendCodeParamsOptions\n {\n Locale = \"en-US\",\n PreferredChannel = new PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\"),\n },\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "Número de telefone do destinatário no formato E.164 — `+` inicial e código do país (por exemplo, `+14155552671`). Os números são validados e normalizados para o formato E.164; números inválidos ou que não possam ser analisados devolvem `400` com um erro no campo `phone_number`.", "example": "+14155552671" }, "options": { "type": "object", "description": "Opções de entrega do OTP. Todos os campos são opcionais.", "properties": { "code_size": { "type": "integer", "minimum": 4, "maximum": 8, "default": 6, "description": "Número de dígitos no OTP." }, "locale": { "type": "string", "maxLength": 5, "pattern": "^[a-z]{2,3}(-[A-Z]{2,3})?$", "description": "Localidade BCP-47 utilizada para localizar a mensagem de verificação (por exemplo, `en-US`, `fr`, `es`). Formatos inválidos devolvem `400`.", "example": "en-US" }, "preferred_channel": { "type": "string", "enum": [ "whatsapp", "sms", "telegram", "voice", "rcs", "viber", "zalo" ], "default": "whatsapp", "description": "Canal de entrega preferencial. Se o canal não estiver disponível para o país de destino ou número, a mensagem reverte automaticamente para SMS — o envio continua a reportar `Success`." }, "use_white_label_customization": { "type": "boolean", "default": false, "description": "Quando `true`, o envio é efetuado em marca branca: se a sua aplicação não tiver um nome de remetente de SMS, o SMS menciona o seu nome público de marca branca (\"123456 é o seu código de verificação para o Acme Bank\"). O seu nome de remetente de SMS, quando configurado, é utilizado com ou sem este indicador. Aplica-se a mensagens SMS, incluindo uma alternativa por SMS a partir de outro canal; os códigos por WhatsApp são enviados com uma mensagem fixa e não têm marca. Por predefinição, é `false`." }, "sms_sender_name": { "type": "string", "nullable": true, "maxLength": 30, "example": "Acme Bank", "description": "O nome que o SMS deste código apresenta (\"123456 é o seu código de verificação para o Acme Bank\"), em vez do nome de remetente de SMS da sua aplicação. Gratuito. 1 a 30 carateres: apenas letras, dígitos, espaços e ' & - !, não apenas dígitos, com espaços simples entre palavras; qualquer outro valor devolve `400` e nenhum código é enviado. Omitido, `null` ou em branco, é utilizado o nome de remetente de SMS da sua aplicação. Cada aplicação pode começar a utilizar até dois novos nomes por dia (UTC); a partir daí, o código é enviado com o nome da sua aplicação. Aplica-se a mensagens SMS, incluindo um fallback para SMS a partir de outro canal; os códigos do WhatsApp não têm marca personalizada.", "pattern": "^$|^(?![\\d ]+$)[\\p{L}\\p{N}'&!-]+( [\\p{L}\\p{N}'&!-]+)*$" } } }, "signals": { "type": "object", "description": "Sinais opcionais de dispositivo e rede sobre o utilizador final, encaminhados para a camada antifraude para melhorar a deteção de tráfego abusivo ou automatizado. Todos os campos são opcionais.", "properties": { "ip": { "type": "string", "description": "Endereço IP do dispositivo do utilizador final. IPv4 ou IPv6.", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "Identificador único do dispositivo do utilizador final. Android: `ANDROID_ID`; iOS: `identifierForVendor`.", "example": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2" }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "Plataforma do dispositivo do utilizador final." }, "device_model": { "type": "string", "maxLength": 255, "description": "Modelo do dispositivo do utilizador final.", "example": "iPhone17,2" }, "os_version": { "type": "string", "maxLength": 64, "description": "Versão do sistema operativo do dispositivo do utilizador final.", "example": "18.0.1" }, "app_version": { "type": "string", "maxLength": 64, "description": "Versão da sua aplicação.", "example": "1.2.34" }, "user_agent": { "type": "string", "maxLength": 512, "description": "Agente do utilizador do navegador ou da aplicação do utilizador final.", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1" } } }, "vendor_data": { "type": "string", "description": "Identificador opcional controlado pelo chamador (o seu ID de utilizador interno, um e-mail, um UUID, etc.) guardado na sessão e devolvido na resposta de envio, na resposta de verificação de correspondência, nos webhooks e na Business Console. Utilize-o para correlacionar o `request_id` da Didit com o registo do seu utilizador." }, "metadata": { "type": "object", "nullable": true, "description": "Objeto JSON de formato livre opcional persistido na sessão e devolvido na resposta de envio, na resposta de verificação de correspondência, nos webhooks e na Business Console." } }, "required": [ "phone_number" ] }, "examples": { "WhatsApp (default)": { "summary": "OTP de 6 dígitos via WhatsApp, recorrendo a SMS automaticamente", "value": { "phone_number": "+14155552671", "options": { "preferred_channel": "whatsapp", "locale": "en-US" }, "vendor_data": "user-1234" } }, "SMS with custom code length": { "summary": "Forçar entrega por SMS com um código de 4 dígitos", "value": { "phone_number": "+34699999999", "options": { "preferred_channel": "sms", "code_size": 4, "locale": "es" } } }, "With fraud signals": { "summary": "Reencaminhar sinais do dispositivo para reforçar a triagem antifraude", "value": { "phone_number": "+14155552671", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "ios", "device_model": "iPhone17,2", "os_version": "18.0.1", "app_version": "1.2.34" }, "vendor_data": "user-1234" } } } } } }, "responses": { "200": { "description": "Envio confirmado. Inspecione `status`: `Success` e `Retry` significam que um código está a caminho; `Blocked` significa que a camada antifraude recusou e a verificação já foi finalizada como `Declined`. `request_id` é o ID persistido da sessão (o mesmo ID num `Retry`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerificationSendResponse" }, "examples": { "Success": { "summary": "OTP enviado para uma nova verificação", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Success", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Retry": { "summary": "Segundo envio para o mesmo número dentro da janela de 5 minutos — mesmo request_id", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Retry", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Blocked": { "summary": "Recusa antifraude — verificação finalizada como Recusada, nada faturado", "value": { "request_id": "0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3", "status": "Blocked", "reason": "repeated_attempts", "vendor_data": "user-1234", "metadata": null } } } } } }, "400": { "description": "Erro de validação. Dados de entrada malformados devolvem o envelope de erro de campo do DRF (um array de mensagens por campo afetado, aninhado sob `options` para erros de opções). Um número que é analisado com sucesso, mas rejeitado no momento do envio (inacessível ou um tipo de linha não elegível, como um short code) devolve um envelope `{\"detail\": ...}`.", "content": { "application/json": { "examples": { "Invalid phone number (field error)": { "summary": "O número não é válido segundo a norma E.164", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Missing phone number": { "summary": "`phone_number` não incluído no corpo", "value": { "phone_number": [ "This field is required." ] } }, "Invalid options": { "summary": "`code_size` fora dos limites, `locale` mal formatado, `preferred_channel` desconhecido", "value": { "options": { "code_size": [ "Ensure this value is less than or equal to 8." ], "locale": [ "Ensure this field has no more than 5 characters." ], "preferred_channel": [ "\"carrier_pigeon\" is not a valid choice." ] } } }, "Number rejected at send time": { "summary": "Formato E.164 válido, mas o número não consegue receber um OTP", "value": { "detail": "Invalid phone number provided." } }, "Ineligible line type": { "summary": "O tipo de linha não pode receber um OTP (por exemplo, código curto)", "value": { "detail": "Invalid phone line type provided." } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta (`{\"detail\": ...}`); uma chave incorreta, revogada ou expirada devolve `401`. Também é devolvido antes de qualquer envio quando a organização nunca carregou saldo (controlo antiabuso) ou quando o seu saldo não consegue cobrir o preço de envio do destino (`{\"error\": ...}`).", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Top-up required": { "summary": "A verificação de telefone permanece desativada até ao primeiro carregamento de saldo da organização", "value": { "detail": "To protect against abuse, phone verification is disabled until your first top-up." } }, "Not enough credits": { "summary": "O saldo da organização não cobre o preço de envio", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). Adicionalmente, aplica-se a montante um limite antiabuso de 4 tentativas de verificação por número de telefone por hora. A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. Nota: os cabeçalhos `X-RateLimit-*`/`Retry-After` acompanham apenas o 429 do limite de escrita de 300/min; o 429 do limite por número não inclui cabeçalhos de limite de pedidos.", "content": { "application/json": { "examples": { "Per-number cap": { "summary": "Mais de 4 tentativas de verificação para o mesmo número na última hora", "value": { "detail": "Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number." } }, "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "O fornecedor de verificação de telefone está temporariamente indisponível - uma resposta 5xx, timeout ou falha de ligação que persistiu após as tentativas automáticas integradas. É seguro tentar novamente; nada é faturado e nenhuma tentativa é consumida.", "content": { "application/json": { "examples": { "Provider outage": { "summary": "O fornecedor não respondeu ao pedido de envio", "value": { "detail": "Phone verification is temporarily unavailable. Please try again shortly.", "code": "phone_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Falha inesperada ao criar a verificação que não é uma interrupção conhecida do fornecedor. Pode tentar novamente em segurança.", "content": { "application/json": { "examples": { "Provider error": { "summary": "Não foi possível iniciar a entrega do OTP", "value": { "detail": "Error creating phone verification" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/phone/check/": { "post": { "summary": "Verificar código de telefone", "description": "Verifique o OTP entregue por [`POST /v3/phone/send/`](/pt/standalone-apis/phone-send) e obtenha o resultado final da verificação, além de informações sobre o telefone: nome da operadora e tipo de linha, flags de número virtual (VoIP) e descartável, e utilização duplicada do número nas suas sessões.\n\n**Como a verificação localiza o registo.** A correspondência é feita pela sua aplicação juntamente com o `phone_number` em formato E.164 (o `request_id` não é um parâmetro de entrada). É verificada a verificação pendente mais recente criada há menos de **5 minutos**. Se não existir nenhuma (nunca enviada, já finalizada ou com mais de 5 minutos), o endpoint devolve `200` com `status: \"Expired or Not Found\"`.\n\n**Limite de tentativas.** Cada verificação permite **3 tentativas de código**. As duas primeiras tentativas incorretas devolvem `status: \"Failed\"` com as tentativas restantes e `phone: null`; a terceira tentativa incorreta finaliza a verificação como `Declined` com um aviso `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` e devolve o relatório telefónico completo.\n\n**Resultados.** `Approved` — código correto e sem riscos de recusa. `Declined` — terminal: o código estava correto, mas foi detetado um risco de recusa (uma ação `DECLINE` abaixo, um número na lista de bloqueio ou de alto risco), ou o limite de tentativas foi esgotado. `Failed` — código incorreto, com tentativas restantes. `Expired or Not Found` — nada a verificar. Em `Approved`/`Declined`, o `request_id` é igual ao `request_id` do envio (o id da sessão) e `phone` inclui o relatório completo (`carrier`, `is_virtual`, `is_disposable`, `warnings`, `lifecycle`, `matches`); em `Failed` e `Expired or Not Found`, o `request_id` é um UUID aleatório e único.\n\n**Ações de risco.** `duplicated_phone_number_action`, `disposable_number_action` e `voip_number_action` decidem o que acontece quando o risco correspondente é detetado num código correto: `DECLINE` altera o estado final para `Declined`; `NO_ACTION` (predefinição) regista o risco em `phone.warnings` sem afetar o estado.\n\n**Faturação.** As verificações são gratuitas — a entrega é faturada no lado do envio (consulte [Preços da verificação de telefone](/pt/getting-started/phone-verification-pricing)).\n\n**Persistência da sessão.** Uma verificação finalizada atualiza a sessão criada pelo envio (visível na Business Console, consultável através de `GET /v3/session/{sessionId}/decision/`) e aciona um webhook `status.updated`.\n\n**Sandbox.** As chaves de API de sandbox ignoram todo o processamento: qualquer código bem formatado (4–8 dígitos, incluindo `123456`) devolve um payload estático `Approved` com um objeto simples `phone` (`status`, `phone_number`, `country_code`, `carrier_name`, `line_type`, `flags`); entradas mal formatadas continuam a devolver `400`. Nada é persistido.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limites de pedidos.** Limite partilhado de escrita de 300 pedidos/min por chave de API, mais o limite antiabuso upstream de 4 tentativas por número por hora; ultrapassar qualquer um deles devolve `429`.\n\n**Pegada social.** Defina `enable_social` como `true` para adicionar um bloco `phone_social`: as plataformas online onde este número está registado, com contagens por categoria e quaisquer detalhes de perfil disponíveis. `profiles_registered: 0` significa que as plataformas foram verificadas e o número não foi encontrado em nenhuma delas — uma resposta válida e faturável. O bloco está ausente quando o add-on não foi solicitado ou a verificação não pôde ser concluída, e não é faturado nesse caso. A faturação adiciona uma unidade de `phone_social` por pedido além do preço próprio deste endpoint.", "operationId": "post_v3phone_check", "x-didit-sdk": { "resource": "phone", "method": "check_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"code\": \"123456\",\n \"voip_number_action\": \"DECLINE\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.check_code(\n phone_number=\"+14155552671\",\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.checkCode({\n phone_number: \"+14155552671\",\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneCheckCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().checkCode(PhoneCheckCodeParams.builder()\n .phoneNumber(\"+14155552671\")\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->checkCode([\n 'phone_number' => '+14155552671',\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.check_code(\n phone_number: \"+14155552671\",\n code: \"123456\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.CheckCodeAsync(new PhoneCheckCodeParams\n{\n PhoneNumber = \"+14155552671\",\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "O mesmo número de telefone utilizado na chamada [`POST /v3/phone/send/`](/pt/standalone-apis/phone-send) correspondente, no formato E.164. É isto que associa a verificação ao envio.", "example": "+14155552671" }, "code": { "type": "string", "minLength": 4, "maxLength": 8, "pattern": "^[0-9]{4,8}$", "description": "O OTP que o utilizador final recebeu. Deve ter entre 4 e 8 dígitos numéricos — qualquer outro valor devolve `400` sem consumir uma tentativa. Um código bem formatado mas incorreto devolve `200` com `status: \"Failed\"` e consome uma das 3 tentativas.", "example": "123456" }, "duplicated_phone_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "O que fazer quando o mesmo número já foi utilizado por um utilizador diferente (com um `vendor_data` diferente) da sua aplicação. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `phone.warnings` e preenche `phone.matches`." }, "disposable_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "O que fazer quando a consulta de operadora sinalizar o número como uma linha temporária/descartável (`phone.is_disposable`). `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `phone.warnings`." }, "voip_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "O que fazer quando a consulta de operadora indicar um tipo de linha virtual — `voip`, `isp` ou `vpn` (`phone.is_virtual`). `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `phone.warnings`." }, "enable_enrichment": { "type": "boolean", "default": false, "description": "Quando `true`, executa também inteligência telefónica sobre o número: uma pontuação de risco, o tipo de linha, se foi recentemente portado e um índice de confiança. Faturado como uma unidade `phone_intelligence_api` por pedido ($0.05 ao preço de tabela), além do próprio preço deste endpoint. O pedido devolve `403` quando o seu saldo não for suficiente para cobri-lo.", "example": false }, "phone_intelligence_score_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando a pontuação de risco da inteligência de telefone está acima do limiar. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`." }, "phone_type_risk_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando o número é de um tipo de linha de alto risco. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`." }, "recent_port_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando o número foi recentemente portado para outra operadora. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`." }, "low_phone_trust_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando o índice de confiança da inteligência de telefone está no limiar ou abaixo dele. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`." }, "enable_social": { "type": "boolean", "default": false, "description": "Quando for true, consulta também a pegada social do número: as plataformas de mensagens, redes sociais, de comércio eletrónico e profissionais nas quais está registado. Faturado como uma unidade `phone_social` por pedido, além do preço do próprio endpoint.", "example": true }, "phone_no_social_presence_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando a verificação da pegada social deteta que o número não está registado em nenhuma das plataformas abrangidas. Apenas NO_ACTION e DECLINE são aceites neste endpoint; REVIEW está disponível na chave de configuração do fluxo com o mesmo nome." } }, "required": [ "phone_number", "code" ] }, "examples": { "Default": { "summary": "Registar quaisquer riscos, mas nunca recusar automaticamente", "value": { "phone_number": "+14155552671", "code": "123456" } }, "Strict risk policy": { "summary": "Recusar automaticamente linhas VoIP e descartáveis", "value": { "phone_number": "+14155552671", "code": "123456", "voip_number_action": "DECLINE", "disposable_number_action": "DECLINE" } } } } } }, "responses": { "200": { "description": "Verificação concluída — códigos errados e verificações em falta também devolvem `200`; inspecione `status`, não o código HTTP. `phone` é preenchido apenas em resultados finalizados (`Approved`/`Declined`), `null` em `Failed` e ausente em `Expired or Not Found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerificationCheckResponse" }, "examples": { "Approved": { "summary": "Código correto — relatório telefónico completo com operadora, ciclo de vida e correspondências", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Approved", "message": "The verification code is correct.", "phone": { "status": "Approved", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "AT&T", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.0509 }, { "type": "PHONE_DELIVERY_DELIVERED", "timestamp": "2026-06-12T01:23:43.118220+00:00", "details": { "channel": "whatsapp", "status": "delivered" }, "fee": 0 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Failed (attempts remaining)": { "summary": "Código incorreto — o utilizador pode tentar novamente; o request_id aqui é um UUID de utilização única", "value": { "request_id": "11111111-2222-3333-4444-555555555555", "status": "Failed", "message": "The verification code is incorrect. Attempts remaining: 2", "phone": null, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:21.512340+00:00" } }, "Declined (max attempts)": { "summary": "Terceiro código errado — verificação finalizada como Recusada", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Declined", "message": "The verification code is incorrect. Maximum attempts reached.", "phone": { "status": "Declined", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "AT&T", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": null, "warnings": [ { "feature": "PHONE", "risk": "VERIFICATION_CODE_ATTEMPTS_EXCEEDED", "additional_data": null, "log_type": "error", "short_description": "Verification code attempts exceeded", "long_description": "The system detected that the phone number has exceeded the maximum number of verification code attempts." } ], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.0509 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:01.118220+00:00", "details": { "code_tried": "111111", "status": "Failed" }, "fee": 0 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:21.512340+00:00", "details": { "code_tried": "222222", "status": "Failed" }, "fee": 0 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "333333", "status": "Failed" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "VERIFICATION_CODE_ATTEMPTS_EXCEEDED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Declined (risk policy)": { "summary": "Código correto, mas a linha é VoIP e voip_number_action=DECLINE", "value": { "request_id": "7f1c9d2e-44a1-4b6e-9a3e-5b8e6f1c2d3a", "status": "Declined", "message": "The verification code is correct.", "phone": { "status": "Declined", "phone_number_prefix": "+1", "phone_number": "5005550006", "full_number": "+15005550006", "country_code": "US", "country_name": "United States", "carrier": { "name": "CLEC LLC", "type": "voip" }, "is_disposable": false, "is_virtual": true, "verification_method": "sms", "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "PHONE", "risk": "VOIP_NUMBER_DETECTED", "additional_data": null, "log_type": "error", "short_description": "VoIP number detected", "long_description": "The system detected that the phone number is a VoIP number, which is not allowed." } ], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "sms" }, "fee": 0.0509 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "VOIP_NUMBER_DETECTED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Expired or Not Found": { "summary": "Nenhuma verificação pendente para este número nos últimos 5 minutos", "value": { "request_id": "69cc35c6-280a-47a6-ab8c-4f32abc02ed0", "status": "Expired or Not Found", "message": "No pending phone verification found in the last 5 minutes.", "vendor_data": null, "metadata": null, "created_at": "2026-06-12T01:24:47.311323+00:00" } } } } } }, "400": { "description": "Erro de validação — envelope de erro de campo do DRF: um array de mensagens por campo com problemas.", "content": { "application/json": { "examples": { "Invalid code format": { "summary": "`code` não tem entre 4 e 8 dígitos numéricos", "value": { "code": [ "Invalid code format. Enter 4 to 8 numeric digits." ] } }, "Invalid phone number": { "summary": "`phone_number` não é um número E.164 válido", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Invalid action": { "summary": "As ações de risco aceitam apenas NO_ACTION ou DECLINE", "value": { "voip_number_action": [ "\"REVIEW\" is not a valid choice." ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta; uma chave incorreta, revogada ou expirada devolve `401`. As verificações são gratuitas, pelo que não existe qualquer verificação de crédito aqui.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). Adicionalmente, aplica-se a montante um limite antiabuso de 4 tentativas de verificação por número de telefone por hora. A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. Nota: os cabeçalhos `X-RateLimit-*`/`Retry-After` acompanham apenas o 429 do limite de escrita de 300/min; o 429 do limite por número não inclui cabeçalhos de limite de pedidos.", "content": { "application/json": { "examples": { "Per-number cap": { "summary": "Mais de 4 tentativas de verificação para o mesmo número na última hora", "value": { "detail": "Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number." } }, "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "O fornecedor de verificação de telefone está temporariamente indisponível - uma resposta 5xx, timeout ou falha de ligação que persistiu após as tentativas automáticas integradas. É seguro tentar novamente; o orçamento de tentativas não é consumido.", "content": { "application/json": { "examples": { "Provider outage": { "summary": "O fornecedor não respondeu ao pedido de verificação", "value": { "detail": "Phone verification is temporarily unavailable. Please try again shortly.", "code": "phone_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Falha inesperada ao verificar o código a montante que não é uma interrupção conhecida do fornecedor. Pode tentar novamente em segurança; o limite de tentativas só é consumido por verificações concluídas.", "content": { "application/json": { "examples": { "Provider error": { "summary": "Não foi possível concluir a verificação do código", "value": { "detail": "Error checking phone verification" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/bank/account-check/": { "post": { "summary": "Verificar uma conta bancária", "description": "Verifique se uma conta bancária pertence à pessoa ou empresa indicada, antes de lhe enviar fundos. Sem sessão e sem início de sessão: envie o nome e a conta, leia o resultado. Trata-se da [verificação de conta](/pt/core-technology/bank-verification/account-check) do passo Verificação bancária, executada a partir do seu back-end.\n\n**O que envia.** O `country` da conta (ISO 3166-1 alfa-3), o `account` no formato em que esse país o escreve e o nome do `holder`: `full_name` para uma pessoa ou `business_name` para uma empresa. O nome de uma empresa verifica uma conta empresarial.\n\n**O que recebe em resposta.** O `result` é `match`, `close_match`, `no_match` ou `cannot_verify`. Num `close_match`, `holder_name` é o nome sob o qual o banco detém a conta, quando devolvido pelo banco. O `account` é devolvido mascarado para os seus últimos 4 carateres.\n\n**Faturação.** Cada verificação respondida pelo banco é faturada uma vez ao preço de verificação de conta do país da conta, independentemente do resultado: um `no_match`, uma conta que não existe e um `cannot_verify` também são faturados. Um pedido respondido com erro nunca é faturado.\n\n**Cada pedido é uma nova verificação.** Não existe chave de idempotência nem endpoint para consultar uma verificação anterior, pelo que um pedido repetido é executado e faturado novamente. Guarde a resposta.\n\n**Sandbox.** Use uma chave de API de sandbox com os dados de conta de exemplo. Uma chave de sandbox não contacta nenhum banco e não tem quaisquer custos. Os últimos 4 carateres do IBAN, ou então do número de conta, definem a resposta: `0001` um `close_match` com `holder_name`, `0002` um `close_match` sem este, `0003` e `0006` um `no_match`, `0004` `cannot_verify`, `0005` um `503` e `0009` um `400`. Qualquer outra terminação resulta num `match`.\n\n**Chaves de API.** Uma chave de API com âmbitos requer permissões de escrita para sessões.", "operationId": "post_v3_bank_account_check", "tags": [ "Standalone APIs" ], "x-didit-sdk": { "resource": "bank", "method": "account_check", "auth": "api_key", "server": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckRequest" }, "examples": { "Person, Nigeria": { "summary": "Um código bancário e número de conta, verificados face ao nome de uma pessoa", "value": { "country": "NGA", "account": { "bank_code": "000014", "account_number": "0123450001" }, "holder": { "full_name": "Maria Oliveira" }, "vendor_data": "payout_20481" } }, "Company, Nigeria": { "summary": "Um código bancário e número de conta, verificados face ao nome de uma empresa", "value": { "country": "NGA", "account": { "bank_code": "000014", "account_number": "0123456789" }, "holder": { "business_name": "Northwind Trading Ltd" } } } } } } }, "responses": { "200": { "description": "O banco respondeu. A verificação é faturada, independentemente do resultado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckResponse" }, "examples": { "Close match": { "summary": "O banco detém a conta sob um nome aproximado", "value": { "request_id": "c2f4a9e0-7b1d-4c3a-9e55-1d0a6b8f2a47", "result": "close_match", "holder_name": "MARIA R OLIVEIRA", "account": "****0001", "vendor_data": "payout_20481", "created_at": "2026-10-21T14:32:08Z" } }, "Match": { "summary": "O banco detém a conta sob o nome enviado", "value": { "request_id": "5b0e2d7c-41a8-4f6e-9c3b-8e7d1a2f6c90", "result": "match", "holder_name": null, "account": "****6789", "vendor_data": null, "created_at": "2026-10-21T14:35:41Z" } } } } } }, "400": { "description": "Recusado como enviado e não faturado. `field` indica o campo do corpo a corrigir e `reason` explica o motivo, com as mesmas razões apresentadas no formulário de conta alojado. Apenas o primeiro campo recusado é comunicado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Missing field": { "summary": "A verificação do país requer um código bancário", "value": { "detail": "The bank code is not valid (required).", "code": "invalid_account_input", "field": "account.bank_code", "reason": "required" } }, "Invalid IBAN": { "summary": "O IBAN tem o comprimento incorreto para o respetivo país", "value": { "detail": "The iban is not valid (length).", "code": "invalid_account_input", "field": "account.iban", "reason": "length" } }, "Refused by the bank": { "summary": "O banco recusou a conta conforme enviada", "value": { "detail": "The account was refused as typed (rejected).", "code": "invalid_account_input", "field": "account.account_number", "reason": "rejected" } }, "No name": { "summary": "`holder` não tem `full_name` nem `business_name`", "value": { "detail": "Send full_name for a person or business_name for a company.", "code": "invalid_account_input", "field": "holder", "reason": "required" } }, "Consent required": { "summary": "A verificação de conta do país requer o consentimento do titular da conta", "value": { "detail": "Account checks in this country need the account holder's explicit consent. Ask for it, then send `consent=true`.", "code": "invalid_account_input", "field": "consent", "reason": "required" } } } } } }, "401": { "description": "A chave de API com âmbito expirou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "402": { "description": "A verificação não pode ser paga e, por isso, não foi executada. Carregue o seu saldo e envie novamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Out of credit": { "summary": "O seu saldo não cobre uma verificação", "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } }, "Not in your contract": { "summary": "O seu contrato não tem preço para a API de verificação de conta", "value": { "detail": "Your contract does not price the Account check API. Contact your account manager.", "code": "contract_rate_missing" } } } } } }, "403": { "description": "O cabeçalho `x-api-key` ou o token bearer está em falta ou é inválido, o pedido veio de um endereço fora da lista de IPs da chave, ou uma chave com âmbito não tem acesso de escrita a sessões.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Missing or invalid credentials": { "summary": "Nenhuma chave de API válida ou token válido", "value": { "detail": "You do not have permission to perform this action." } }, "No sessions write": { "summary": "Uma chave com âmbito sem acesso de escrita a sessões", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "404": { "description": "Nenhuma verificação de conta serve esta conta de momento, pelo que nada foi verificado nem faturado. `country_not_covered`: nenhuma serve o respetivo país ou o respetivo tipo de conta (pessoa singular ou empresa) nesse país. `bank_not_covered`: nenhuma serve o respetivo banco.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Country not covered": { "summary": "Nenhuma verificação de conta serve o país", "value": { "detail": "No account check serves this country yet.", "code": "country_not_covered" } }, "Bank not covered": { "summary": "Nenhuma verificação de conta serve o banco da conta", "value": { "detail": "No account check serves this account's bank yet.", "code": "bank_not_covered" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "O banco não conseguiu responder. Nada foi verificado ou faturado; envie a verificação novamente mais tarde.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Unavailable": { "summary": "O banco não respondeu", "value": { "detail": "The account check is temporarily unavailable and this request was not charged. Please try again.", "code": "account_check_unavailable" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/bank/account-check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"country\": \"NGA\",\n \"account\": {\"bank_code\": \"000014\", \"account_number\": \"0123450001\"},\n \"holder\": {\"full_name\": \"Maria Oliveira\"},\n \"vendor_data\": \"payout_20481\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.bank.account_check(\n country=\"NGA\",\n account={\n \"account_number\": \"0123450001\",\n \"bank_code\": \"000014\",\n },\n holder={\n \"full_name\": \"Maria Oliveira\",\n },\n vendor_data=\"payout_20481\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.bank.accountCheck({\n country: \"NGA\",\n account: {\n account_number: \"0123450001\",\n bank_code: \"000014\",\n },\n holder: {\n full_name: \"Maria Oliveira\",\n },\n vendor_data: \"payout_20481\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.AccountCheck(ctx, didit.BankAccountCheckRequest{\n\tCountry: \"NGA\",\n\tAccount: didit.BankAccountCheckRequestAccount{\n\t\tAccountNumber: didit.String(\"0123450001\"),\n\t\tBankCode: didit.String(\"000014\"),\n\t},\n\tHolder: didit.BankAccountCheckHolder{\n\t\tFullName: didit.String(\"Maria Oliveira\"),\n\t},\n\tVendorData: didit.String(\"payout_20481\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BankAccountCheckHolder;\nimport me.didit.types.BankAccountCheckPersonHolder;\nimport me.didit.types.BankAccountCheckRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.bank().accountCheck(BankAccountCheckRequest.builder()\n .country(\"NGA\")\n .account(BankAccountCheckRequest.Account.builder()\n .accountNumber(\"0123450001\")\n .bankCode(\"000014\")\n .build())\n .holder(BankAccountCheckHolder.ofBankAccountCheckPersonHolder(BankAccountCheckPersonHolder.builder()\n .fullName(\"Maria Oliveira\")\n .build()))\n .vendorData(\"payout_20481\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "bank->accountCheck([\n 'country' => 'NGA',\n 'account' => [\n 'account_number' => '0123450001',\n 'bank_code' => '000014',\n ],\n 'holder' => [\n 'full_name' => 'Maria Oliveira',\n ],\n 'vendor_data' => 'payout_20481',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.bank.account_check(\n country: \"NGA\",\n account: {\n account_number: \"0123450001\",\n bank_code: \"000014\",\n },\n holder: {\n full_name: \"Maria Oliveira\",\n },\n vendor_data: \"payout_20481\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Bank.AccountCheckAsync(new BankAccountCheckRequest\n{\n Country = \"NGA\",\n Account = new()\n {\n AccountNumber = \"0123450001\",\n BankCode = \"000014\",\n },\n Holder = new()\n {\n FullName = \"Maria Oliveira\",\n },\n VendorData = \"payout_20481\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/email/send/": { "post": { "summary": "Enviar código por e-mail", "description": "Envie um código de utilização única (OTP) para um endereço de e-mail e, em seguida, verifique-o com [`POST /v3/email/check/`](/pt/standalone-apis/email-check).\n\n**Como funcionam o envio e a verificação em conjunto.** O estado da verificação é indexado pela sua aplicação mais o endereço `email` — a chamada de verificação não recebe `request_id`. Cada novo envio cria uma verificação pendente que dura **5 minutos**: chame a verificação com o mesmo endereço e o código que o utilizador recebeu antes do fecho da janela temporal. Chamar o envio novamente para o mesmo endereço enquanto uma verificação está pendente gera um novo código para essa mesma verificação (`status: \"Retry\"`, mesmo `request_id`); o código anterior deixa de funcionar. É associada no máximo uma nova tentativa desta forma (dois envios no total); um envio adicional inicia uma nova verificação com um novo `request_id`. A janela de 5 minutos é contabilizada a partir do primeiro envio e não é prolongada por novas tentativas.\n\n**Pré-verificação de capacidade de entrega.** Antes de qualquer envio, o endereço passa por validação de sintaxe e de DNS/MX. Os endereços que não conseguem receber mensagens devolvem `200` com `status: \"Undeliverable\"` e `reason: \"email_can_not_be_delivered\"` — nenhum e-mail é enviado, nada é faturado e a verificação é imediatamente finalizada como `Declined` (uma verificação posterior devolve `Expired or Not Found`). Um envio que falhe por um motivo que não seja o endereço (o e-mail não pôde ser entregue para envio) devolve `503`: nenhum código é enviado, nada é faturado, a verificação permanece aberta e o mesmo pedido pode ser repetido.\n\n**Formato do código e personalização.** Os códigos têm entre 4 e 8 carateres (`options.code_size`, por omissão 6), numéricos por predefinição; defina `options.alphanumeric_code: true` para letras maiúsculas e dígitos (a comparação na verificação não diferencia maiúsculas de minúsculas). O modelo de e-mail é localizado através de `options.locale` (54 idiomas suportados) e pode utilizar a personalização de marca branca da sua aplicação através de `options.use_white_label_customization`.\n\n**Faturação.** Um crédito da API de Verificação de e-mail por envio bem-sucedido (`status: \"Success\"`), cobrado no momento do envio. Os envios `Retry` e `Undeliverable` são gratuitos, e as verificações são gratuitas.\n\n**Persistência da sessão.** Cada nova verificação é persistida como uma sessão do tipo API: `request_id` é um ID de sessão real que pode passar a `GET /v3/session/{sessionId}/decision/`, a verificação aparece na Business Console e os webhooks `status.updated` são acionados à medida que progride.\n\n**Sandbox.** As chaves de API de sandbox ignoram a entrega e a faturação: após a validação do pedido (dados malformados continuam a devolver `400`), o endpoint devolve um payload estático `Success` com um `request_id` aleatório; nenhum e-mail é enviado e nada é persistido. Utilize o código `123456` na verificação em sandbox.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limite de pedidos.** Limite partilhado de escrita de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-lo devolve `429`.", "operationId": "post_v3email_send", "x-didit-sdk": { "resource": "email", "method": "send_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/send/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"options\": { \"code_size\": 6, \"locale\": \"en\" },\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.send_code(\n email=\"alice@example.com\",\n options={\n \"locale\": \"en\",\n },\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.sendCode({\n email: \"alice@example.com\",\n options: {\n locale: \"en\",\n },\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.SendCode(ctx, didit.EmailSendCodeParams{\n\tEmail: \"alice@example.com\",\n\tOptions: didit.Some(didit.EmailSendCodeParamsOptions{\n\t\tLocale: didit.Some(didit.EmailSendCodeParamsOptionsLocale(\"en\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailSendCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().sendCode(EmailSendCodeParams.builder()\n .email(\"alice@example.com\")\n .options(EmailSendCodeParams.Options.builder()\n .locale(EmailSendCodeParams.Options.Locale.of(\"en\"))\n .build())\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->sendCode([\n 'email' => 'alice@example.com',\n 'options' => [\n 'locale' => 'en',\n ],\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.send_code(\n email: \"alice@example.com\",\n options: {\n locale: \"en\",\n },\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.SendCodeAsync(new EmailSendCodeParams\n{\n Email = \"alice@example.com\",\n Options = new EmailSendCodeParamsOptions\n {\n Locale = new EmailSendCodeParamsOptionsLocale(\"en\"),\n },\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Endereço de e-mail do destinatário. Endereços malformados devolvem `400`; endereços sintaticamente válidos que não conseguem receber correio (falha na validação de DNS/MX) devolvem `200` com `status: \"Undeliverable\"`.", "example": "alice@example.com" }, "options": { "type": "object", "description": "Opções de formato, localização e personalização de marca do OTP. Todos os campos são opcionais.", "properties": { "code_size": { "type": "integer", "minimum": 4, "maximum": 8, "default": 6, "description": "Número de carateres no OTP (dígitos por predefinição; letras maiúsculas e dígitos quando `alphanumeric_code` for `true`)." }, "alphanumeric_code": { "type": "boolean", "default": false, "description": "Quando `true`, o OTP é composto por letras maiúsculas `A–Z` e dígitos `0–9`, em vez de apenas dígitos. A comparação de `/v3/email/check/` não faz distinção entre maiúsculas e minúsculas." }, "locale": { "type": "string", "maxLength": 5, "enum": [ "en", "ar", "bn", "bg", "bs", "ca", "cs", "da", "de", "el", "es", "et", "fa", "fi", "fr", "he", "hi", "hr", "hu", "hy", "id", "it", "ja", "ka", "kk", "ko", "ky", "lt", "lv", "cnr", "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" ], "description": "Idioma do modelo de e-mail de OTP. A predefinição é `en`. Valores não suportados devolvem `400`, que lista todas as configurações regionais suportadas.", "example": "en" }, "use_white_label_customization": { "type": "boolean", "default": false, "description": "Quando `true`, o e-mail com OTP utiliza a personalização de marca branca da sua aplicação (logótipo, cores, marca do remetente) em vez do modelo predefinido da Didit." } } }, "signals": { "type": "object", "description": "Sinais opcionais de dispositivo e rede sobre o utilizador final, encaminhados para a camada antifraude para melhorar a deteção de tráfego abusivo ou automatizado. Todos os campos são opcionais.", "properties": { "ip": { "type": "string", "description": "Endereço IP do dispositivo do utilizador final. IPv4 ou IPv6.", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "Identificador único do dispositivo do utilizador final. Android: `ANDROID_ID`; iOS: `identifierForVendor`.", "example": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2" }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "Plataforma do dispositivo do utilizador final." }, "device_model": { "type": "string", "maxLength": 255, "description": "Modelo do dispositivo do utilizador final.", "example": "iPhone17,2" }, "os_version": { "type": "string", "maxLength": 64, "description": "Versão do sistema operativo do dispositivo do utilizador final.", "example": "18.0.1" }, "app_version": { "type": "string", "maxLength": 64, "description": "Versão da sua aplicação.", "example": "1.2.34" }, "user_agent": { "type": "string", "maxLength": 512, "description": "Agente do utilizador do navegador ou da aplicação do utilizador final.", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1" } } }, "vendor_data": { "type": "string", "description": "Identificador opcional controlado pelo chamador (o seu ID de utilizador interno, um e-mail, um UUID, etc.) guardado na sessão e devolvido na resposta de envio, na resposta de verificação de correspondência, nos webhooks e na Business Console. Utilize-o para correlacionar o `request_id` da Didit com o registo do seu utilizador." }, "metadata": { "type": "object", "nullable": true, "description": "Objeto JSON de formato livre opcional persistido na sessão e devolvido na resposta de envio, na resposta de verificação de correspondência, nos webhooks e na Business Console." } }, "required": [ "email" ] }, "examples": { "Numeric 6-digit code": { "summary": "Predefinição — código numérico de 6 dígitos em inglês", "value": { "email": "alice@example.com", "options": { "locale": "en" }, "vendor_data": "user-1234" } }, "Alphanumeric 8-character code": { "summary": "Letras maiúsculas + dígitos, modelo espanhol", "value": { "email": "bob@example.com", "options": { "code_size": 8, "alphanumeric_code": true, "locale": "es" } } }, "White-label branding": { "summary": "Envie o e-mail com OTP com a personalização de marca branca da sua aplicação", "value": { "email": "carol@example.com", "options": { "locale": "en", "use_white_label_customization": true }, "vendor_data": "user-5678" } } } } } }, "responses": { "200": { "description": "Envio confirmado. Inspecione `status`: `Success` e `Retry` significam que um código está a caminho; `Undeliverable` significa que a morada não pode receber correio e a verificação já foi finalizada como `Declined`. `request_id` é o ID persistido da sessão (o mesmo ID num `Retry`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationSendResponse" }, "examples": { "Success": { "summary": "OTP enviado por e-mail para uma nova verificação (faturado)", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Success", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Retry": { "summary": "Segundo envio dentro da janela de 5 minutos — código novo, mesmo request_id, gratuito", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Retry", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Undeliverable": { "summary": "O endereço falhou a validação de DNS/MX — verificação finalizada como Recusada, sem qualquer faturação", "value": { "request_id": "cb1a5011-344d-444d-bdce-218904745d7f", "status": "Undeliverable", "reason": "email_can_not_be_delivered", "vendor_data": "user-1234", "metadata": null } } } } } }, "400": { "description": "Erro de validação — envelope de erro de campo do DRF: um array de mensagens por campo com problemas, aninhado sob `options` para erros de opções.", "content": { "application/json": { "examples": { "Invalid email": { "summary": "Endereço de e-mail mal formatado", "value": { "email": [ "Enter a valid email address." ] } }, "Unsupported locale": { "summary": "`options.locale` fora do conjunto suportado", "value": { "options": { "locale": [ "Invalid locale. Supported locales are en, ar, bn, bg, bs, ca, cs, da, de, el, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, kk, ko, ky, lt, lv, cnr, 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." ] } } }, "Code size out of range": { "summary": "`options.code_size` fora do intervalo 4–8", "value": { "options": { "code_size": [ "Ensure this value is less than or equal to 8." ] } } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta (`{\"detail\": ...}`); uma chave incorreta, revogada ou expirada devolve `401`. Também é devolvido antes de qualquer envio quando o saldo da organização não consegue cobrir um crédito da API de Verificação de e-mail (`{\"error\": ...}`).", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre o preço de envio", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "description": "Não foi possível enviar o e-mail por um motivo não relacionado com o endereço (não foi possível contactar o fornecedor de e-mail, o tempo limite expirou ou este recusou o próprio envio), pelo que nenhum código foi enviado e nada foi faturado ou contabilizado como tentativa de envio. Repita o mesmo pedido.", "content": { "application/json": { "examples": { "Email delivery unavailable": { "summary": "O fornecedor de e-mail falhou após uma nova tentativa automática", "value": { "detail": "Email delivery is temporarily unavailable. Please try again." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/email/check/": { "post": { "summary": "Verificar código de e-mail", "description": "Verifique o OTP entregue por [`POST /v3/email/send/`](/pt/standalone-apis/email-send) e obtenha o resultado final da verificação juntamente com informações de inteligência sobre o e-mail: capacidade de entrega, exposição a violações de dados (`is_breached` e a lista `breaches` de uma base de dados de inteligência sobre violações de dados), deteção de fornecedores de e-mail descartáveis e utilização duplicada do endereço entre as suas sessões.\n\n**Como é encontrada a verificação.** A correspondência é feita pela sua aplicação juntamente com o endereço de `email` — `request_id` não é um parâmetro de entrada. A verificação pendente mais recente criada nos últimos **5 minutos** é verificada. Se não existir nenhuma (nunca enviada, já finalizada, não entregável no momento do envio ou com mais de 5 minutos), o endpoint devolve `200` com `status: \"Expired or Not Found\"`.\n\n**Limite de tentativas.** Cada verificação permite **3 tentativas de código**. Os primeiros dois códigos incorretos devolvem `status: \"Failed\"` com as tentativas restantes e `email: null`; o terceiro código incorreto finaliza a verificação como `Declined` com um aviso `EMAIL_CODE_ATTEMPTS_EXCEEDED` e devolve o relatório de e-mail completo. Os códigos são comparados sem distinção entre maiúsculas e minúsculas (relevante para envios de `alphanumeric_code`); apenas o código enviado mais recentemente é válido.\n\n**Resultados.** `Approved` — código correto e nenhum risco de recusa. `Declined` — terminal: o código estava correto, mas foi detetado um risco de recusa (uma ação `DECLINE` abaixo, um endereço incluído na lista de bloqueio ou o endereço foi considerado não entregável na finalização), ou o limite de tentativas esgotou-se. `Failed` — código incorreto, com tentativas restantes. `Expired or Not Found` — nada a verificar. Em `Approved`/`Declined`, o `request_id` é igual ao `request_id` do envio (o ID da sessão) e `email` inclui o relatório completo (`is_breached`, `breaches`, `is_disposable`, `is_undeliverable`, `warnings`, `lifecycle`, `matches`); em `Failed` e `Expired or Not Found`, o `request_id` é um UUID aleatório de uso único.\n\n**Ações de risco.** `duplicated_email_action`, `breached_email_action` e `disposable_email_action` decidem o que acontece quando o risco correspondente é detetado com um código correto: `DECLINE` altera o estado final para `Declined`; `NO_ACTION` (predefinição) regista o risco em `email.warnings` sem afetar o estado.\n\n**Faturação.** As verificações são gratuitas — o crédito é consumido pelo envio bem-sucedido.\n\n**Persistência da sessão.** Uma verificação finalizada atualiza a sessão criada pelo envio (visível na Business Console, consultável via `GET /v3/session/{sessionId}/decision/`) e aciona um webhook `status.updated`.\n\n**Sandbox.** As chaves de API de sandbox ignoram todo o processamento: qualquer código bem formatado (`123456` incluído) devolve um payload estático de `Approved` com um objeto `email` simplificado (`status`, `email`, `is_breached`, `is_disposable`, `is_undeliverable`); dados de entrada malformados continuam a devolver `400`. Nada é persistido.\n\n**Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais ausentes ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — esta API nunca devolve `401`.\n\n**Limite de pedidos.** Limite partilhado de escrita de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; exceder este limite devolve `429`.\n\n**Pegada social.** Defina `enable_social` como `true` para adicionar um bloco `email_social`: as plataformas online onde este endereço está registado, com contagens por categoria e todos os detalhes de perfil disponíveis. `profiles_registered: 0` significa que as plataformas foram verificadas e o endereço não foi encontrado em nenhuma delas - uma resposta válida e faturável. O bloco está ausente quando o suplemento não foi solicitado ou a verificação não pôde ser concluída, não sendo faturado nesse caso. A faturação adiciona uma unidade de `email_social` por pedido ao preço próprio deste endpoint.", "operationId": "post_v3email_check", "x-didit-sdk": { "resource": "email", "method": "check_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"code\": \"123456\",\n \"disposable_email_action\": \"DECLINE\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.check_code(\n email=\"alice@example.com\",\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.checkCode({\n email: \"alice@example.com\",\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.CheckCode(ctx, didit.EmailCheckCodeParams{\n\tEmail: \"alice@example.com\",\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailCheckCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().checkCode(EmailCheckCodeParams.builder()\n .email(\"alice@example.com\")\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->checkCode([\n 'email' => 'alice@example.com',\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.check_code(\n email: \"alice@example.com\",\n code: \"123456\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.CheckCodeAsync(new EmailCheckCodeParams\n{\n Email = \"alice@example.com\",\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "O mesmo endereço de e-mail utilizado na chamada [`POST /v3/email/send/`](/pt/standalone-apis/email-send) correspondente. É isto que associa a verificação ao envio.", "example": "alice@example.com" }, "code": { "type": "string", "maxLength": 10, "description": "O OTP que o utilizador final recebeu: 4–8 dígitos, ou 4–8 letras/dígitos quando `alphanumeric_code: true` foi utilizado no momento do envio. A comparação não diferencia maiúsculas de minúsculas.", "example": "123456" }, "duplicated_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "O que fazer quando o mesmo endereço já foi utilizado e aprovado por um utilizador diferente (apenas contam verificações aprovadas anteriormente) (com um `vendor_data` diferente) da sua aplicação. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `email.warnings` e preenche `email.matches`." }, "breached_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "O que fazer quando o endereço constar de fugas de dados conhecidas (`email.is_breached`). `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `email.warnings`." }, "disposable_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "O que fazer quando o domínio pertence a um fornecedor de e-mail temporário/descartável (`email.is_disposable`). `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `email.warnings`." }, "enable_enrichment": { "type": "boolean", "default": false, "description": "Quando `true`, executa também inteligência de e-mail sobre o endereço: uma pontuação de risco e o respetivo histórico de violações de dados. Faturado como uma unidade `email_intelligence_api` por pedido ($0.05 ao preço de tabela), além do próprio preço deste endpoint. O pedido devolve `403` quando o seu saldo não for suficiente para cobri-lo.", "example": false }, "email_intelligence_score_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando a pontuação de risco da inteligência de e-mail está acima do limiar. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`." }, "recent_email_breach_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando o endereço surge numa violação de dados conhecida recente. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Só produz efeitos quando `enable_enrichment` for `true`." }, "frequent_email_breach_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando o endereço surge em muitas violações de dados conhecidas. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Só produz efeitos quando `enable_enrichment` for `true`." }, "enable_social": { "type": "boolean", "default": false, "description": "Quando for true, consulta também a pegada social do endereço: as plataformas de e-mail, redes sociais, profissionais, de comércio eletrónico e de entretenimento nas quais está registado. Faturado como uma unidade `email_social` por pedido, além do preço do próprio endpoint.", "example": true }, "email_no_social_presence_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Ação quando a verificação da pegada social deteta que o endereço não está registado em nenhuma das plataformas abrangidas. Apenas NO_ACTION e DECLINE são aceites neste endpoint; REVIEW está disponível na chave de configuração do fluxo com o mesmo nome." } }, "required": [ "email", "code" ] }, "examples": { "Default": { "summary": "Registar quaisquer riscos, mas nunca recusar automaticamente", "value": { "email": "alice@example.com", "code": "123456" } }, "Strict risk policy": { "summary": "Recusar automaticamente caixas de correio descartáveis e comprometidas", "value": { "email": "alice@example.com", "code": "123456", "disposable_email_action": "DECLINE", "breached_email_action": "DECLINE" } } } } } }, "responses": { "200": { "description": "Verificação concluída — códigos errados e verificações em falta também devolvem `200`; inspecione `status`, não o código HTTP. `email` é preenchido apenas em resultados finalizados (`Approved`/`Declined`), `null` em `Failed` e ausente em `Expired or Not Found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationCheckResponse" }, "examples": { "Approved": { "summary": "Código correto — endereço limpo, relatório completo de e-mail", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Approved", "message": "The verification code is correct.", "email": { "status": "Approved", "email": "alice@example.com", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Approved with breach exposure": { "summary": "Código correto; exposição a uma violação de dados registada como aviso (breached_email_action=NO_ACTION)", "value": { "request_id": "3a1f2b6c-9d4e-4f7a-8b2c-1e5d6f7a8b9c", "status": "Approved", "message": "The verification code is correct.", "email": { "status": "Approved", "email": "bob@example.com", "is_breached": true, "breaches": [ { "name": "ExampleApp", "domain": "exampleapp.com", "breach_date": "2019-03-21", "breach_emails_count": 763117, "description": "In March 2019, the social platform ExampleApp suffered a data breach that exposed email addresses and passwords.", "logo_path": "https:///logos/ExampleApp.png", "data_classes": [ "email_addresses", "passwords" ], "is_verified": true } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "EMAIL", "risk": "BREACHED_EMAIL_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Breached email detected", "long_description": "This email address was found in one or more known data breaches." } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "835126", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-5678", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Failed (attempts remaining)": { "summary": "Código incorreto — o utilizador pode tentar novamente; o request_id aqui é um UUID de utilização única", "value": { "request_id": "11111111-2222-3333-4444-555555555555", "status": "Failed", "message": "The verification code is incorrect. Attempts remaining: 2", "email": null, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:21.512340+00:00" } }, "Declined (risk policy)": { "summary": "Código correto, mas o endereço é descartável e disposable_email_action=DECLINE", "value": { "request_id": "8c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "status": "Declined", "message": "The verification code is correct.", "email": { "status": "Declined", "email": "tempuser42@mailinator.com", "is_breached": false, "breaches": [], "is_disposable": true, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "EMAIL", "risk": "DISPOSABLE_EMAIL_DETECTED", "additional_data": null, "log_type": "error", "short_description": "Disposable email detected", "long_description": "The system detected that the email is disposable, which is not allowed." } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "DISPOSABLE_EMAIL_DETECTED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Expired or Not Found": { "summary": "Nenhuma verificação pendente para este endereço nos últimos 5 minutos", "value": { "request_id": "88808a77-06e9-4cb0-85f5-9c052ddfd987", "status": "Expired or Not Found", "message": "No pending email verification found in the last 5 minutes.", "vendor_data": null, "metadata": null, "created_at": "2026-06-12T01:24:59.887904+00:00" } } } } } }, "400": { "description": "Erro de validação — envelope de erro de campo do DRF: um array de mensagens por campo com problemas.", "content": { "application/json": { "examples": { "Invalid email": { "summary": "Endereço de e-mail mal formatado", "value": { "email": [ "Enter a valid email address." ] } }, "Missing code": { "summary": "`code` não incluído no corpo", "value": { "code": [ "This field is required." ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta; uma chave incorreta, revogada ou expirada devolve `401`. As verificações são gratuitas, pelo que não existe qualquer verificação de crédito aqui.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/workflows/": { "get": { "summary": "Listar fluxos", "description": "Liste os seus fluxos, os mais recentes primeiro, num envelope de paginação limit/offset (`{count, next, previous, results}`, tamanho de página predefinido de 50). Cada linha é uma versão; `workflow_id` é o ID de grupo estável e as novas sessões utilizam a versão `published` mais recente.", "operationId": "list_workflows", "x-didit-sdk": { "resource": "workflows", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Tamanho da página (número de fluxos por página)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Número de linhas a ignorar antes do primeiro fluxo devolvido." } ], "responses": { "200": { "description": "Uma página de fluxos ordenada por `created_at` descendente, envolvida no envelope de paginação. Cada item em `results` é um `WorkflowListItem`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número total de versões de fluxos para a aplicação." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowListItem" } } } }, "examples": { "Two workflows": { "summary": "Um fluxo de KYC predefinido e um rascunho de fluxo de KYC + AML", "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_id": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_label": "Standard KYC", "workflow_type": "kyc", "is_default": true, "is_archived": false, "is_white_label_enabled": false, "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "is_simple_workflow": true, "is_editable": false, "workflow_url": "https://verify.didit.me/u/_yljPOx8RWG3UAz5ZRQGVQ", "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 2, "status": "published", "has_draft": false, "created_by": { "name": "Alex Mateo", "email": "alex@example.com", "type": "user" }, "updated_at": "2026-04-12T10:30:00Z" }, { "uuid": "b2c3d4e5-6789-01bc-defa-222222222222", "workflow_id": "b2c3d4e5-6789-01bc-defa-222222222222", "workflow_label": "Full Verification + AML", "workflow_type": "kyc", "is_default": false, "is_archived": false, "is_white_label_enabled": false, "total_price": 0.25, "min_price": 0.25, "max_price": 0.25, "features": "OCR + LIVENESS + FACE_MATCH + AML", "is_simple_workflow": true, "is_editable": true, "workflow_url": "https://verify.didit.me/u/Aq3kPOx8RWG3UAz5ZRQGVQ", "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 1, "status": "draft", "has_draft": true, "created_by": null, "updated_at": "2026-04-15T18:05:21Z" } ] } } } } } }, "403": { "description": "A chave de API está em falta, mal formatada, expirada ou pertence a uma aplicação diferente. Corpo: `{\"detail\": \"You do not have permission to perform this action.\"}`. Atualize o token através da [Auth API](/pt/auth-api/get-credentials) e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial e respeite qualquer cabeçalho `Retry-After`." }, "500": { "description": "Erro de servidor inesperado ao compilar a lista. O pedido pode ser repetido em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/workflows/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Accept: application/json'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.workflows.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.workflows.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Workflows.ListAutoPaging(ctx, didit.WorkflowsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.workflows().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "workflows->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.workflows.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Workflows.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Criar fluxo", "description": "Crie um fluxo simples. Envie `features` por ordem de execução (aplicam-se regras de ordenação); o valor predefinido é `published` v1. O corpo aceita APENAS os campos listados em `SimpleWorkflowRequest` — qualquer outra chave (incluindo `workflow_type`) é rejeitada com o código 400. Não idempotente — cada chamada cria um novo fluxo. Máximo de 50 fluxos por aplicação.", "operationId": "create_workflow", "x-didit-sdk": { "resource": "workflows", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleWorkflowRequest" }, "examples": { "Simple KYC": { "summary": "Fluxo linear de ID, prova de vida e correspondência facial", "value": { "workflow_label": "Standard KYC", "features": [ { "feature": "OCR", "config": { "duplicated_user_action": "review" } }, { "feature": "LIVENESS", "config": { "face_liveness_method": "passive" } }, { "feature": "FACE_MATCH", "config": { "face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60 } } ] } }, "KYC + AML": { "summary": "Executar AML após a verificação de identidade", "value": { "workflow_label": "KYC with AML", "features": [ { "feature": "OCR" }, { "feature": "AML", "config": { "aml_score_review_threshold": 70, "aml_score_approve_threshold": 30 } } ] } }, "Questionnaire workflow": { "summary": "Executar um questionário criado com POST /v3/questionnaires/", "value": { "workflow_label": "Source of Funds", "features": [ { "feature": "QUESTIONNAIRE", "config": { "questionnaire_uuid": "11111111-2222-3333-4444-555555555555", "review_questionnaire_manually": true } } ] } } } } } }, "responses": { "201": { "description": "Fluxo criado. O corpo da resposta é a configuração COMPLETA do fluxo — a mesma serialização bruta de `VerificationSettings` devolvida por `GET /v3/workflows/{settings_uuid}/` (~190 campos: todas as opções de funcionalidades, limiares, ações e o `workflow_graph` gerado), e não o elemento compacto da lista. Guarde o `uuid` (também exposto como `workflow_id`) para poder referenciá-lo em chamadas posteriores de criação de sessões. Nota: `features` é uma cadeia unida por `\" + \"` e os preços são números JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" }, "examples": { "Created (abbreviated)": { "summary": "Campos principais do objeto de configuração completo", "value": { "uuid": "c3d4e5f6-7890-12cd-ef34-333333333333", "workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333", "workflow_label": "Standard KYC", "workflow_type": null, "is_default": false, "is_archived": false, "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "is_simple_workflow": false, "is_editable": false, "workflow_url": "https://verify.didit.me/u/w9TkPOx8RWG3UAz5ZRQGVQ", "workflow_graph": { "start_node": "ocr", "nodes": "... one node per feature plus a final status node ..." }, "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 1, "status": "published", "published_at": "2026-05-17T10:30:00Z", "created_at": "2026-05-17T10:30:00Z", "updated_at": "2026-05-17T10:30:00Z" } } } } } }, "400": { "description": "Erro de validação. Causas comuns: uma chave de nível superior fora da lista de permissões aceite (por ex., `workflow_type`), um valor de `feature` desconhecido, uma funcionalidade colocada antes da sua dependência (por ex., `FACE_MATCH` antes de `OCR`), uma funcionalidade passiva (`AML`, `IP_ANALYSIS`, `DATABASE_VALIDATION`, `KYB_KEY_PEOPLE`) utilizada como primeiro passo, uma funcionalidade `QUESTIONNAIRE` cujo `config.questionnaire_uuid` não existe para esta aplicação, uma funcionalidade `SIGNATURE` que entraria em produção sem nenhum documento para assinar, uma funcionalidade `SIGNATURE` com `signature_level: \"aes\"` quando o nível Avançado (AES) não está disponível (`aes_not_available`, consulte `signature_availability` no fluxo) ou um limiar fora do intervalo. O corpo é um objeto de erro de validação do DRF — as chaves são nomes de campos e os valores são arrays de mensagens legíveis por humanos.", "content": { "application/json": { "examples": { "Advanced (AES) not available": { "value": { "features": { "signature_level": [ "Node 'signature': Advanced (AES) is not available yet (aes_not_available)." ] } } }, "Signature step with no document": { "value": { "features": { "non_field_errors": [ "Node 'signature': Add a document to sign, or let each session bring its own." ] } } }, "Missing feature": { "value": { "features": [ "At least one feature is required." ] } }, "Unknown top-level field": { "value": { "workflow_type": [ "The v3 workflow API only accepts `workflow_label`, `is_default`, `status`, `features`, `is_white_label_enabled`, `is_desktop_allowed`, `max_retry_attempts`, `retry_window_days`, `session_expiration_time`, `face_liveness_max_attempts`, `face_match_max_attempts`." ] } }, "Unknown feature": { "value": { "features": [ "Invalid feature 'FOO'. Allowed values: AGE_ESTIMATION, AML, DATABASE_VALIDATION, EMAIL_VERIFICATION, FACE_MATCH, IP_ANALYSIS, KYB_DOCUMENTS, KYB_KEY_PEOPLE, KYB_REGISTRY, LIVENESS, NFC, OCR, PHONE_VERIFICATION, PROOF_OF_ADDRESS, QUESTIONNAIRE." ] } }, "Ordering": { "value": { "features": [ "Feature 'FACE_MATCH' must appear after one of: OCR." ] } }, "Questionnaire not found": { "value": { "features": "Questionnaire '11111111-2222-3333-4444-555555555555' was not found for this application. Create the questionnaire first, then use its questionnaire_id." } } } } } }, "403": { "description": "A chave de API está em falta, mal formatada, expirada ou tem como âmbito uma aplicação diferente. Atualize através da [Auth API](/pt/auth-api/get-credentials) e tente novamente.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "415": { "description": "Tipo de conteúdo não suportado. Defina `Content-Type: application/json` e envie um corpo JSON." }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado ao criar o fluxo. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/workflows/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"workflow_label\": \"Standard KYC\",\n \"features\": [\n {\"feature\": \"OCR\"},\n {\"feature\": \"LIVENESS\", \"config\": {\"face_liveness_method\": \"passive\"}},\n {\"feature\": \"FACE_MATCH\", \"config\": {\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60}}\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.create(\n workflow_label=\"Standard KYC\",\n features=[{\n \"feature\": \"OCR\",\n \"config\": {\"duplicated_user_action\": \"review\"},\n }, {\n \"feature\": \"LIVENESS\",\n \"config\": {\"face_liveness_method\": \"passive\"},\n }, {\n \"feature\": \"FACE_MATCH\",\n \"config\": {\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60},\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.create({\n workflow_label: \"Standard KYC\",\n features: [{\n feature: \"OCR\",\n config: { duplicated_user_action: \"review\" },\n }, {\n feature: \"LIVENESS\",\n config: { face_liveness_method: \"passive\" },\n }, {\n feature: \"FACE_MATCH\",\n config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Create(ctx, didit.SimpleWorkflowRequest{\n\tWorkflowLabel: didit.String(\"Standard KYC\"),\n\tFeatures: []didit.SimpleWorkflowFeature{{\n\t\tFeature: \"OCR\",\n\t\tConfig: didit.Some(map[string]any{\"duplicated_user_action\": \"review\"}),\n\t}, {\n\t\tFeature: \"LIVENESS\",\n\t\tConfig: didit.Some(map[string]any{\"face_liveness_method\": \"passive\"}),\n\t}, {\n\t\tFeature: \"FACE_MATCH\",\n\t\tConfig: didit.Some(map[string]any{\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SimpleWorkflowFeature;\nimport me.didit.types.SimpleWorkflowRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().create(SimpleWorkflowRequest.builder()\n .workflowLabel(\"Standard KYC\")\n .features(List.of(\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"OCR\"))\n .config(Map.of(\"duplicated_user_action\", \"review\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"LIVENESS\"))\n .config(Map.of(\"face_liveness_method\", \"passive\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"FACE_MATCH\"))\n .config(Map.of(\"face_match_score_decline_threshold\", 40, \"face_match_score_review_threshold\", 60))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->create([\n 'workflow_label' => 'Standard KYC',\n 'features' => [[\n 'feature' => 'OCR',\n 'config' => ['duplicated_user_action' => 'review'],\n ], [\n 'feature' => 'LIVENESS',\n 'config' => ['face_liveness_method' => 'passive'],\n ], [\n 'feature' => 'FACE_MATCH',\n 'config' => ['face_match_score_decline_threshold' => 40, 'face_match_score_review_threshold' => 60],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.create(\n workflow_label: \"Standard KYC\",\n features: [{\n feature: \"OCR\",\n config: { duplicated_user_action: \"review\" },\n }, {\n feature: \"LIVENESS\",\n config: { face_liveness_method: \"passive\" },\n }, {\n feature: \"FACE_MATCH\",\n config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.CreateAsync(new SimpleWorkflowRequest\n{\n WorkflowLabel = \"Standard KYC\",\n Features = new SimpleWorkflowFeature[]\n {\n new()\n {\n Feature = \"OCR\",\n Config = new Dictionary { [\"duplicated_user_action\"] = \"review\" },\n },\n new()\n {\n Feature = \"LIVENESS\",\n Config = new Dictionary { [\"face_liveness_method\"] = \"passive\" },\n },\n new()\n {\n Feature = \"FACE_MATCH\",\n Config = new Dictionary { [\"face_match_score_decline_threshold\"] = 40, [\"face_match_score_review_threshold\"] = 60 },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/workflows/{settings_uuid}/": { "get": { "summary": "Obter fluxo", "description": "Obter a configuração completa de uma versão de fluxo através de `settings_uuid`: alternadores de funcionalidades, limiares, documentos permitidos, grafo, política de tentativas, callbacks e preços.", "operationId": "get_workflow", "x-didit-sdk": { "resource": "workflows", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID por versão do fluxo (o valor `uuid` devolvido pelo endpoint de listagem). Cada versão de um fluxo tem o seu próprio `settings_uuid`." } ], "responses": { "200": { "description": "Configuração completa do fluxo. O formato é a serialização bruta de `VerificationSettings` (~190 campos: cada alternador de funcionalidade, limiar, ação de aviso, configuração de documentos permitidos, o `workflow_graph`, política de nova tentativa, callbacks e preços). O exemplo abaixo está abreviado. Notas: `features` é uma cadeia de carateres unida por `\" + \"` (por exemplo, `\"OCR + LIVENESS\"`), os preços são números JSON e `is_editable` é `true` apenas para versões `draft`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" }, "examples": { "KYC workflow with face match (abbreviated)": { "value": { "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_id": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_label": "Standard KYC", "workflow_type": "kyc", "is_default": true, "is_archived": false, "is_liveness_enabled": true, "face_liveness_method": "passive", "face_liveness_score_decline_threshold": 50, "face_liveness_score_review_threshold": 70, "is_face_match_enabled": true, "face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60, "is_aml_enabled": false, "is_phone_verification_enabled": false, "is_email_verification_enabled": false, "is_database_validation_enabled": false, "is_ip_analysis_enabled": false, "is_nfc_enabled": false, "duplicated_user_action": "no_action", "documents_allowed": { "ESP": { "P": { "sides": 1, "enabled": 1, "subtypes": [ "EPASSPORT", "PASSPORT_GENERIC" ], "preferred_characters": "latin", "expiration_check_mode": "strict" } } }, "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 2, "status": "published", "published_at": "2026-04-12T10:30:00Z", "is_simple_workflow": false, "is_editable": false, "workflow_url": "https://verify.didit.me/u/_yljPOx8RWG3UAz5ZRQGVQ", "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2026-04-12T10:30:00Z" } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum fluxo com este `settings_uuid` para a aplicação autenticada. Ou o UUID está incorreto ou pertence a outra aplicação — a Didit não distingue deliberadamente os dois casos para evitar revelar a existência de registos de outras aplicações.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Atualizar fluxo", "description": "Atualizar um fluxo. O controlo de versões depende do campo `status` que enviar e do estado atual da versão: (1) sem `status` numa versão **publicada** → a versão publicada é atualizada diretamente (mesmo `uuid`, mesma `version`); (2) sem `status` num **rascunho** → o rascunho é atualizado e publicado imediatamente; (3) `status: \"published\"` numa versão **publicada** → uma NOVA versão publicada é criada sob o mesmo `workflow_id` (novo `uuid`, `version` + 1) e devolvida, e qualquer rascunho existente no grupo é eliminado; (4) `status: \"draft\"` mantém um rascunho como rascunho (gravação automática), mas é rejeitado com 400 numa versão publicada (`\"Cannot revert a published version to draft.\"`). O corpo aceita a mesma lista estrita de campos permitidos que a criação — chaves desconhecidas são rejeitadas com 400.", "operationId": "update_workflow", "x-didit-sdk": { "resource": "workflows", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID por versão do fluxo a atualizar." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleWorkflowUpdateRequest" }, "examples": { "Replace features": { "summary": "Envie a ordem completa pretendida das funcionalidades", "value": { "features": [ { "feature": "OCR" }, { "feature": "AML" } ] } }, "Rename": { "summary": "Renomear um fluxo", "value": { "workflow_label": "Premium KYC" } }, "Set as default": { "summary": "Definir este fluxo como o predefinido da aplicação", "value": { "is_default": true } }, "Update config": { "summary": "Alterar configuração da funcionalidade", "value": { "features": [ { "feature": "OCR" }, { "feature": "LIVENESS", "config": { "face_liveness_method": "passive" } } ] } }, "Publish a draft": { "summary": "Promover um rascunho para publicado", "value": { "status": "published" } } } } } }, "responses": { "200": { "description": "Fluxo atualizado. O corpo é a configuração COMPLETA da versão resultante (mesmo formato bruto `VerificationSettings` que `GET /v3/workflows/{settings_uuid}/`). Quando a atualização cria uma nova versão (`status: \"published\"` enviado numa linha publicada), o `uuid` e a `version` devolvidos diferem dos que alterou — utilize o `uuid` devolvido para chamadas subsequentes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" } } } }, "400": { "description": "Erro de validação — uma chave de nível superior fora da lista de permissões aceite, uma funcionalidade desconhecida, ordenação inválida, limiar fora do intervalo, referência a um questionário inexistente, uma funcionalidade `SIGNATURE` que entraria em produção sem documento para assinar, uma nova funcionalidade `SIGNATURE` com `signature_level: \"aes\"` quando Advanced (AES) não está disponível (`aes_not_available`, consulte `signature_availability` no fluxo; um passo que já armazene `aes` mantém-no), ou `status: \"draft\"` enviado para uma versão publicada (`\"Cannot revert a published version to draft.\"`). O corpo da resposta é um erro de validação do DRF indexado pelo nome do campo." }, "403": { "description": "Chave de API em falta ou inválida.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum fluxo com este `settings_uuid` para a aplicação autenticada." }, "415": { "description": "Tipo de conteúdo não suportado. Defina `Content-Type: application/json`." }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"workflow_label\": \"Premium KYC\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.update(\n \"11111111-2222-3333-4444-555555555555\",\n features=[{\n \"feature\": \"OCR\",\n }, {\n \"feature\": \"AML\",\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.update(\"11111111-2222-3333-4444-555555555555\", {\n features: [{\n feature: \"OCR\",\n }, {\n feature: \"AML\",\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SimpleWorkflowUpdateRequest{\n\tFeatures: didit.Some([]didit.SimpleWorkflowFeature{{\n\t\tFeature: \"OCR\",\n\t}, {\n\t\tFeature: \"AML\",\n\t}}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SimpleWorkflowFeature;\nimport me.didit.types.SimpleWorkflowUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().update(\"11111111-2222-3333-4444-555555555555\", SimpleWorkflowUpdateRequest.builder()\n .features(List.of(\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"OCR\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"AML\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->update('11111111-2222-3333-4444-555555555555', [\n 'features' => [[\n 'feature' => 'OCR',\n ], [\n 'feature' => 'AML',\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.update(\n \"11111111-2222-3333-4444-555555555555\",\n features: [{\n feature: \"OCR\",\n }, {\n feature: \"AML\",\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new SimpleWorkflowUpdateRequest\n{\n Features = new SimpleWorkflowFeature[]\n {\n new()\n {\n Feature = \"OCR\",\n },\n new()\n {\n Feature = \"AML\",\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Eliminar fluxo", "description": "Elimina permanentemente uma versão de fluxo (sem anulação). As sessões existentes mantêm os seus resultados de verificação, mas a respetiva referência de fluxo é removida; outras versões no mesmo grupo de `workflow_id` não são eliminadas.", "operationId": "delete_workflow", "x-didit-sdk": { "resource": "workflows", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID por versão do fluxo a eliminar." } ], "responses": { "204": { "description": "Fluxo eliminado. O corpo da resposta está vazio." }, "403": { "description": "Chave de API em falta ou inválida.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum fluxo com este `settings_uuid` para a aplicação autenticada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.workflows.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.workflows.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Workflows.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.workflows().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "workflows->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.workflows.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Workflows.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/questionnaires/": { "get": { "summary": "Listar questionários", "description": "Liste os seus questionários, os mais recentes primeiro, num envelope de paginação limit/offset (`{count, next, previous, results}`, tamanho de página predefinido de 50). Cada linha é uma versão; `questionnaire_group_id` é o ID de grupo estável resolvido para a versão `published` mais recente.", "operationId": "list_questionnaires", "x-didit-sdk": { "resource": "questionnaires", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Tamanho da página (número de questionários por página)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Número de linhas a ignorar antes do primeiro questionário devolvido." } ], "responses": { "200": { "description": "Uma página de questionários ordenada por `created_at` descendente, envolvida no envelope de paginação. Cada item em `results` é um `QuestionnaireListItem`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número total de versões de questionários para a aplicação." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionnaireListItem" } } } }, "examples": { "One questionnaire": { "summary": "Um questionário bilingue simples", "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "11111111-2222-3333-4444-555555555555", "title": "KYC Questionnaire", "description": "Additional verification questions", "languages": [ "en", "es" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "created_at": "2026-04-23T09:55:00Z", "updated_at": "2026-04-23T10:00:00Z", "question_types": [ "SHORT_TEXT", "MULTIPLE_CHOICE", "FILE_UPLOAD" ], "workflow_names": [], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } ] } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado ao compilar a lista. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/questionnaires/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.questionnaires.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.questionnaires.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Questionnaires.ListAutoPaging(ctx, didit.QuestionnairesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.questionnaires().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "questionnaires->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.questionnaires.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Questionnaires.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Criar questionário", "description": "Crie um questionário linear simples. Envie `form_elements` na ordem de apresentação; ramificações e grupos repetíveis requerem a Console. O valor predefinido é `published` v1.", "operationId": "create_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleQuestionnaireRequest" }, "examples": { "Simple": { "summary": "Questionário básico", "value": { "title": "Customer Onboarding", "description": "Additional information needed for verification", "default_language": "en", "languages": [ "en" ], "is_active": true, "form_elements": [ { "id": "occupation", "element_type": "short_text", "label": { "en": "What is your occupation?" }, "is_required": true, "placeholder": { "en": "Software engineer" } }, { "id": "source_of_funds", "element_type": "multiple_choice", "label": { "en": "Source of funds" }, "is_required": true, "options": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } }, { "value": "investments", "label": { "en": "Investments" } }, { "value": "other", "label": { "en": "Other" } } ] } ] } } } } } }, "responses": { "201": { "description": "Questionário criado. A resposta inclui o `questionnaire_id` — guarde-o para referenciar este questionário em fluxos ou em futuras chamadas de atualização/eliminação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" }, "examples": { "Created": { "value": { "questionnaire_id": "11111111-2222-3333-4444-555555555555", "title": "Customer Onboarding", "description": "Additional information needed for verification", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "graph": { "start_node": "occupation", "nodes": { "occupation": { "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" }, "next": "source_of_funds" }, "source_of_funds": { "element_type": "MULTIPLE_CHOICE", "is_required": true, "title": { "en": "Source of funds" }, "choices": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ], "next": null } } }, "sections": [], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } } } } } }, "400": { "description": "Erro de validação. Causas comuns: um `element_type` desconhecido, um campo traduzível sem tradução para um dos `languages`, `languages` sem `en`, `default_language` não presente em `languages`, uma opção sem `label`, uma pergunta que contenha `branches`/`required_if`/`repeatable_config` (não suportados por este endpoint) ou o envio de um `graph` em bruto em vez de `form_elements`. O corpo é um erro de validação do DRF indexado pelo nome do campo.", "content": { "application/json": { "examples": { "Graph not accepted": { "value": { "graph": "The v3 questionnaire API only accepts simple `form_elements`, not `graph`." } }, "Missing label": { "value": { "form_elements": [ { "label": [ "This field is required." ] } ] } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "415": { "description": "Tipo de conteúdo não suportado. Defina `Content-Type: application/json` e envie um corpo JSON." }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado ao criar o questionário. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/questionnaires/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"title\": \"Customer Onboarding\",\n \"default_language\": \"en\",\n \"languages\": [\"en\"],\n \"form_elements\": [\n {\n \"id\": \"occupation\",\n \"element_type\": \"short_text\",\n \"label\": {\"en\": \"What is your occupation?\"},\n \"is_required\": true\n }\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.create(\n title=\"Customer Onboarding\",\n description=\"Additional information needed for verification\",\n languages=[\"en\"],\n default_language=\"en\",\n is_active=True,\n form_elements=[{\n \"id\": \"occupation\",\n \"element_type\": \"short_text\",\n \"label\": {\"en\": \"What is your occupation?\"},\n \"placeholder\": {\"en\": \"Software engineer\"},\n \"is_required\": True,\n }, {\n \"id\": \"source_of_funds\",\n \"element_type\": \"multiple_choice\",\n \"label\": {\"en\": \"Source of funds\"},\n \"is_required\": True,\n \"options\": [{\n \"value\": \"employment\",\n \"label\": {\"en\": \"Employment\"},\n }, {\n \"value\": \"business\",\n \"label\": {\"en\": \"Business\"},\n }, {\n \"value\": \"investments\",\n \"label\": {\"en\": \"Investments\"},\n }, {\n \"value\": \"other\",\n \"label\": {\"en\": \"Other\"},\n }],\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.create({\n title: \"Customer Onboarding\",\n description: \"Additional information needed for verification\",\n languages: [\"en\"],\n default_language: \"en\",\n is_active: true,\n form_elements: [{\n id: \"occupation\",\n element_type: \"short_text\",\n label: { en: \"What is your occupation?\" },\n placeholder: { en: \"Software engineer\" },\n is_required: true,\n }, {\n id: \"source_of_funds\",\n element_type: \"multiple_choice\",\n label: { en: \"Source of funds\" },\n is_required: true,\n options: [{\n value: \"employment\",\n label: { en: \"Employment\" },\n }, {\n value: \"business\",\n label: { en: \"Business\" },\n }, {\n value: \"investments\",\n label: { en: \"Investments\" },\n }, {\n value: \"other\",\n label: { en: \"Other\" },\n }],\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Create(ctx, didit.SimpleQuestionnaireRequest{\n\tTitle: \"Customer Onboarding\",\n\tDescription: didit.String(\"Additional information needed for verification\"),\n\tLanguages: []string{\"en\"},\n\tDefaultLanguage: didit.String(\"en\"),\n\tIsActive: didit.Bool(true),\n\tFormElements: []didit.SimpleQuestionnaireElement{{\n\t\tID: didit.String(\"occupation\"),\n\t\tElementType: \"short_text\",\n\t\tLabel: map[string]string{\"en\": \"What is your occupation?\"},\n\t\tPlaceholder: didit.Some(map[string]string{\"en\": \"Software engineer\"}),\n\t\tIsRequired: didit.Bool(true),\n\t}, {\n\t\tID: didit.String(\"source_of_funds\"),\n\t\tElementType: \"multiple_choice\",\n\t\tLabel: map[string]string{\"en\": \"Source of funds\"},\n\t\tIsRequired: didit.Bool(true),\n\t\tOptions: didit.Some([]didit.SimpleQuestionnaireElementOptions{{\n\t\t\tValue: didit.String(\"employment\"),\n\t\t\tLabel: map[string]string{\"en\": \"Employment\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"business\"),\n\t\t\tLabel: map[string]string{\"en\": \"Business\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"investments\"),\n\t\t\tLabel: map[string]string{\"en\": \"Investments\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"other\"),\n\t\t\tLabel: map[string]string{\"en\": \"Other\"},\n\t\t}}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SimpleQuestionnaireElement;\nimport me.didit.types.SimpleQuestionnaireRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().create(SimpleQuestionnaireRequest.builder()\n .title(\"Customer Onboarding\")\n .description(\"Additional information needed for verification\")\n .languages(List.of(\"en\"))\n .defaultLanguage(\"en\")\n .isActive(true)\n .formElements(List.of(\n SimpleQuestionnaireElement.builder()\n .id(\"occupation\")\n .elementType(SimpleQuestionnaireElement.ElementType.of(\"short_text\"))\n .label(Map.of(\"en\", \"What is your occupation?\"))\n .placeholder(Map.of(\"en\", \"Software engineer\"))\n .isRequired(true)\n .build(),\n SimpleQuestionnaireElement.builder()\n .id(\"source_of_funds\")\n .elementType(SimpleQuestionnaireElement.ElementType.of(\"multiple_choice\"))\n .label(Map.of(\"en\", \"Source of funds\"))\n .isRequired(true)\n .options(List.of(\n SimpleQuestionnaireElement.Options.builder()\n .value(\"employment\")\n .label(Map.of(\"en\", \"Employment\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"business\")\n .label(Map.of(\"en\", \"Business\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"investments\")\n .label(Map.of(\"en\", \"Investments\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"other\")\n .label(Map.of(\"en\", \"Other\"))\n .build()))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->create([\n 'title' => 'Customer Onboarding',\n 'description' => 'Additional information needed for verification',\n 'languages' => ['en'],\n 'default_language' => 'en',\n 'is_active' => true,\n 'form_elements' => [[\n 'id' => 'occupation',\n 'element_type' => 'short_text',\n 'label' => ['en' => 'What is your occupation?'],\n 'placeholder' => ['en' => 'Software engineer'],\n 'is_required' => true,\n ], [\n 'id' => 'source_of_funds',\n 'element_type' => 'multiple_choice',\n 'label' => ['en' => 'Source of funds'],\n 'is_required' => true,\n 'options' => [[\n 'value' => 'employment',\n 'label' => ['en' => 'Employment'],\n ], [\n 'value' => 'business',\n 'label' => ['en' => 'Business'],\n ], [\n 'value' => 'investments',\n 'label' => ['en' => 'Investments'],\n ], [\n 'value' => 'other',\n 'label' => ['en' => 'Other'],\n ]],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.create(\n title: \"Customer Onboarding\",\n description: \"Additional information needed for verification\",\n languages: [\"en\"],\n default_language: \"en\",\n is_active: true,\n form_elements: [{\n id: \"occupation\",\n element_type: \"short_text\",\n label: { en: \"What is your occupation?\" },\n placeholder: { en: \"Software engineer\" },\n is_required: true,\n }, {\n id: \"source_of_funds\",\n element_type: \"multiple_choice\",\n label: { en: \"Source of funds\" },\n is_required: true,\n options: [{\n value: \"employment\",\n label: { en: \"Employment\" },\n }, {\n value: \"business\",\n label: { en: \"Business\" },\n }, {\n value: \"investments\",\n label: { en: \"Investments\" },\n }, {\n value: \"other\",\n label: { en: \"Other\" },\n }],\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.CreateAsync(new SimpleQuestionnaireRequest\n{\n Title = \"Customer Onboarding\",\n Description = \"Additional information needed for verification\",\n Languages = new string[] { \"en\" },\n DefaultLanguage = \"en\",\n IsActive = true,\n FormElements = new SimpleQuestionnaireElement[]\n {\n new()\n {\n Id = \"occupation\",\n ElementType = \"short_text\",\n Label = new Dictionary { [\"en\"] = \"What is your occupation?\" },\n Placeholder = new Dictionary { [\"en\"] = \"Software engineer\" },\n IsRequired = true,\n },\n new()\n {\n Id = \"source_of_funds\",\n ElementType = \"multiple_choice\",\n Label = new Dictionary { [\"en\"] = \"Source of funds\" },\n IsRequired = true,\n Options = new SimpleQuestionnaireElementOptions[]\n {\n new()\n {\n Value = \"employment\",\n Label = new Dictionary { [\"en\"] = \"Employment\" },\n },\n new()\n {\n Value = \"business\",\n Label = new Dictionary { [\"en\"] = \"Business\" },\n },\n new()\n {\n Value = \"investments\",\n Label = new Dictionary { [\"en\"] = \"Investments\" },\n },\n new()\n {\n Value = \"other\",\n Label = new Dictionary { [\"en\"] = \"Other\" },\n },\n },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/questionnaires/{questionnaire_uuid}/": { "get": { "summary": "Obter questionário", "description": "Obter os detalhes completos do questionário para uma versão através de `questionnaire_uuid`: título, `languages`, `graph` canónico, `sections` derivadas e metadados da versão.", "operationId": "get_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID por versão do questionário (o valor `uuid` devolvido pelo endpoint de listagem, também devolvido como `questionnaire_id` nos endpoints de detalhe)." } ], "responses": { "200": { "description": "Detalhe completo do questionário incluindo o `graph` canónico, a visualização derivada `sections`, metadados de versão e `is_editable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" }, "examples": { "Published questionnaire": { "value": { "questionnaire_id": "11111111-2222-3333-4444-555555555555", "title": "Customer Onboarding", "description": "Additional information needed for verification", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "graph": { "start_node": "occupation", "nodes": { "occupation": { "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" }, "next": "source_of_funds" }, "source_of_funds": { "element_type": "MULTIPLE_CHOICE", "is_required": true, "title": { "en": "Source of funds" }, "choices": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ], "next": null } } }, "sections": [ { "title": {}, "description": {}, "items": [ { "uuid": "11111111-2222-3333-4444-666666666666", "value": "occupation", "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" } } ] } ], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum questionário com este `questionnaire_uuid` para a aplicação autenticada. Ou o UUID está incorreto ou pertence a outra aplicação — a API não distingue deliberadamente os dois casos.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Atualizar questionário", "description": "Atualizar um questionário. O controlo de versões depende do campo `status` que enviar e do estado atual da versão: (1) sem `status` numa versão **publicada** → a versão publicada é atualizada diretamente (mesmo `questionnaire_id`, mesma `version`); (2) sem `status` num **rascunho** → o rascunho é atualizado e publicado imediatamente; (3) `status: \"published\"` numa versão **publicada** → uma NOVA versão publicada é criada sob o mesmo `questionnaire_group_id` (novo `questionnaire_id`, `version` + 1) e devolvida, e qualquer rascunho existente no grupo é eliminado; (4) `status: \"draft\"` mantém um rascunho como rascunho (gravação automática), mas é rejeitado com 400 numa versão publicada (`\"Cannot revert a published version to draft.\"`).", "operationId": "update_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID por versão do questionário a atualizar." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleQuestionnaireUpdateRequest" }, "examples": { "Rename": { "summary": "Renomear um questionário", "value": { "title": "Updated Customer Onboarding" } }, "Replace questions": { "summary": "Substituir a lista linear completa de perguntas", "value": { "form_elements": [ { "id": "occupation", "element_type": "short_text", "label": { "en": "What is your occupation?" }, "is_required": true }, { "id": "source_of_funds", "element_type": "multiple_choice", "label": { "en": "Source of funds" }, "options": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ] } ] } } } } } }, "responses": { "200": { "description": "Questionário atualizado. O corpo é o estado mais recente da versão resultante — a versão atualizada diretamente, ou a versão publicada recém-criada quando enviou `status: \"published\"` num registo publicado (nesse caso `questionnaire_id` e `version` diferem daqueles que modificou). O `questionnaire_id` na resposta é o UUID por versão; utilize `questionnaire_group_id` se precisar do identificador estável do grupo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" } } } }, "400": { "description": "Erro de validação — `element_type` desconhecido, tradução em falta, campos condicionais/de ramificação não suportados, `languages` sem `en`, `default_language` não presente em `languages`, opção sem etiqueta, envio de um `graph` em bruto ou `status: \"draft\"` numa versão publicada (`\"Cannot revert a published version to draft.\"`). O corpo da resposta é um erro de validação do DRF indexado pelo nome do campo." }, "403": { "description": "Chave de API em falta ou inválida.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum questionário com este `questionnaire_uuid` para a aplicação autenticada." }, "415": { "description": "Tipo de conteúdo não suportado. Defina `Content-Type: application/json`." }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Updated Customer Onboarding\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.update(\n \"11111111-2222-3333-4444-555555555555\",\n title=\"Updated Customer Onboarding\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.update(\"11111111-2222-3333-4444-555555555555\", {\n title: \"Updated Customer Onboarding\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SimpleQuestionnaireUpdateRequest{\n\tTitle: didit.String(\"Updated Customer Onboarding\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SimpleQuestionnaireUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().update(\"11111111-2222-3333-4444-555555555555\", SimpleQuestionnaireUpdateRequest.builder()\n .title(\"Updated Customer Onboarding\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->update('11111111-2222-3333-4444-555555555555', [\n 'title' => 'Updated Customer Onboarding',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.update(\n \"11111111-2222-3333-4444-555555555555\",\n title: \"Updated Customer Onboarding\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new SimpleQuestionnaireUpdateRequest\n{\n Title = \"Updated Customer Onboarding\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Eliminar questionário", "description": "Elimina permanentemente uma versão de questionário (sem possibilidade de anulação). As respostas a questionários armazenadas e associadas a esta versão são eliminadas juntamente com ela, e as sessões que a referenciam perdem a ligação; outras versões no mesmo grupo não são eliminadas. Os fluxos que a referenciavam continuam a ser executados, mas o passo do questionário já não a consegue carregar.", "operationId": "delete_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID por versão do questionário a eliminar." } ], "responses": { "204": { "description": "Questionário eliminado. O corpo da resposta está vazio." }, "403": { "description": "Chave de API em falta ou inválida.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum questionário com este `questionnaire_uuid` para a aplicação autenticada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." }, "500": { "description": "Erro de servidor inesperado. Pode tentar novamente em segurança." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.questionnaires.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.questionnaires.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Questionnaires.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.questionnaires().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "questionnaires->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.questionnaires.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Questionnaires.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/users/": { "get": { "summary": "Listar utilizadores", "description": "Listar [utilizadores](/entities/users) que a Didit reúne a partir de sessões de KYC que partilham o mesmo `vendor_data` (cadeia de carateres livre, NÃO um UUID), mais utilizadores criados através da API. Paginado, ordenado por `last_session_at` desc. Este endpoint não suporta parâmetros de filtro ou pesquisa — obtenha as páginas e filtre do lado do cliente.", "operationId": "list_users", "x-didit-sdk": { "resource": "users", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Tamanho da página. A predefinição é 50 quando omitido. Não existe um limite máximo imposto, mas mantenha as páginas pequenas para reduzir a latência." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Offset de base zero do primeiro registo a devolver. Prefira seguir o URL `next` da página anterior em vez de calcular este valor manualmente." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/users/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.users.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.users.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Users.ListAutoPaging(ctx, didit.UsersListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.users().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "users->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.users.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Users.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Lista paginada de utilizadores com estado de verificação, contagem de sessões e detalhe de funcionalidades.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número de linhas correspondentes — exato até 100, limitado a 100 acima disso por motivos de desempenho. Não o utilize para detetar a última página; em vez disso, confie no facto de `next` ser `null`." }, "next": { "type": "string", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/UserListItem" } } } }, "examples": { "Example": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "ACTIVE", "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2025-06-01T08:00:00Z" }, { "didit_internal_id": "6ed99d53-e8f5-4cf8-9ac1-4a506cb40f6b", "vendor_data": null, "display_name": "Jane S.", "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22", "effective_name": "Jane S.", "status": "FLAGGED", "portrait_image_url": null, "session_count": 1, "approved_count": 0, "declined_count": 0, "in_review_count": 1, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": { "ID_VERIFICATION": "In Review" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "In Review" } ], "last_session_at": "2025-06-20T14:00:00Z", "last_activity_at": "2025-06-20T14:05:00Z", "first_session_at": "2025-06-20T14:00:00Z", "tags": [], "created_at": "2025-06-20T14:00:00Z" } ] } } } } } }, "401": { "description": "Nenhuma credencial fornecida. Os pedidos para caminhos `/v3/users/*` sem um cabeçalho `x-api-key` (ou token `Authorization: Bearer`) são rejeitados pelo middleware de autenticação antes de chegarem à API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "A chave não pode listar utilizadores para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/{vendor_data}/": { "get": { "summary": "Obter utilizador", "description": "Obter um [utilizador](/entities/users) por `vendor_data` (correspondência exata). Adiciona `metadata`, `comments` e `updated_at` à visualização em lista, e altera `tags` para o formato detalhado de associação de etiquetas.", "operationId": "get_user", "x-didit-sdk": { "resource": "users", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O seu identificador exclusivo para o utilizador — uma string de formato livre (NÃO um UUID). Este é o mesmo valor que indicou como `vendor_data` ao criar a sessão que introduziu este utilizador pela primeira vez, correspondido exatamente como enviado.", "example": "user-abc-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/users/user-abc-123/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.retrieve(\n \"user-abc-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.retrieve(\"user-abc-123\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Retrieve(ctx, \"user-abc-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().retrieve(\"user-abc-123\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->retrieve('user-abc-123');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.retrieve(\"user-abc-123\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.RetrieveAsync(\"user-abc-123\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhes completos do utilizador incluindo metadados, registo de comentários/atividade e dados agregados da sessão.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Active user": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "ACTIVE", "metadata": { "tier": "premium", "source": "website" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "comment_type": "STATUS_CHANGED", "comment": null, "actor_email": "analyst@acme.com", "actor_name": "Jane Analyst", "previous_status": "FLAGGED", "new_status": "ACTIVE", "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "mentioned_emails": [], "created_at": "2025-06-01T10:30:00Z" } ], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "401": { "description": "Nenhuma credencial fornecida. Os pedidos para caminhos `/v3/users/*` sem um cabeçalho `x-api-key` (ou token `Authorization: Bearer`) são rejeitados pelo middleware de autenticação antes de chegarem à API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "Chave de API inválida ou revogada, ou a chave não pode ler os utilizadores desta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum utilizador com o `vendor_data` fornecido para esta aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar utilizador", "description": "Atualização parcial de um utilizador: `display_name`, `full_name`, `date_of_birth`, `status`, `metadata`, `approved_emails`/`approved_phones`/`issuing_states`. `metadata` substitui completamente. Alterar o `status` aqui funciona como [Update User Status](#patch-/v3/users/-vendor_data-/update-status/): regista uma atividade `STATUS_CHANGED` com o `reason` opcional, e `BLOCKED` adiciona os `vendor_data` à lista de bloqueio do sistema (alterar para outro valor diferente de `BLOCKED` remove essa entrada). Alterações a `display_name`, `full_name`, `date_of_birth` ou `metadata` são registadas como uma atividade `PROFILE_UPDATED`.", "operationId": "update_user", "x-didit-sdk": { "resource": "users", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O seu identificador exclusivo para o utilizador (string de formato livre, NÃO um UUID).", "example": "user-abc-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"display_name\": \"Jane S.\", \"status\": \"FLAGGED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.update(\n \"user-abc-123\",\n display_name=\"Jane S.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.update(\"user-abc-123\", {\n display_name: \"Jane S.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Update(ctx, \"user-abc-123\", didit.UsersUpdateParams{\n\tDisplayName: didit.String(\"Jane S.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().update(\"user-abc-123\", UsersUpdateParams.builder()\n .displayName(\"Jane S.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->update('user-abc-123', [\n 'display_name' => 'Jane S.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.update(\n \"user-abc-123\",\n display_name: \"Jane S.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UpdateAsync(\"user-abc-123\", new UsersUpdateParams\n{\n DisplayName = \"Jane S.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Utilizador atualizado. É devolvido o registo completo e atualizado do utilizador (mesma estrutura que Obter utilizador).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Updated": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": "Jane S.", "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22", "effective_name": "Jane S.", "status": "FLAGGED", "metadata": { "tier": "premium" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "400": { "description": "Corpo inválido — normalmente um `status` desconhecido ou uma `date_of_birth` que não está em `YYYY-MM-DD`.", "content": { "application/json": { "examples": { "Bad status": { "value": { "status": [ "\"INVALID\" is not a valid choice." ] } }, "Bad date_of_birth": { "value": { "date_of_birth": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "401": { "description": "Nenhuma credencial fornecida. Os pedidos para caminhos `/v3/users/*` sem um cabeçalho `x-api-key` (ou token `Authorization: Bearer`) são rejeitados pelo middleware de autenticação antes de chegarem à API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "A chave não pode atualizar utilizadores para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum utilizador com o `vendor_data` fornecido para esta aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "Nome completo do utilizador" }, "display_name": { "type": "string", "nullable": true, "description": "Nome de apresentação personalizado para este utilizador" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento no formato YYYY-MM-DD" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Estado do ciclo de vida do utilizador. Uma alteração é registada como uma atividade `STATUS_CHANGED`, e `BLOCKED` adiciona o `vendor_data` à lista de bloqueio do sistema (mudar para um estado diferente de `BLOCKED` remove essa entrada)." }, "metadata": { "type": "object", "nullable": true, "description": "Objeto JSON arbitrário que associa ao utilizador. **Substitui totalmente** os metadados existentes na atualização — faça a junção no lado do cliente se pretender apenas adicionar chaves." }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "Endereços de e-mail verificados para este utilizador, por exemplo, `[\"john@example.com\"]`. Substitui totalmente a lista armazenada." }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "Números de telefone verificados para este utilizador. Substitui totalmente a lista armazenada." }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "Países emissores (ISO 3166-1 alfa-3), por ex. `[\"USA\"]`. Substitui totalmente a lista guardada." }, "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "O motivo da alteração de estado. Registado na entrada de alteração de estado da atividade do utilizador (`comments[].comment` e **Activity** na Business Console), apenas quando o estado realmente muda. Os webhooks não o transmitem." } } }, "examples": { "Rename": { "summary": "Definir nome de apresentação", "value": { "display_name": "Jane S." } }, "Override status": { "summary": "Sinalizar o utilizador para revisão", "value": { "status": "FLAGGED" } }, "Add metadata": { "summary": "Substituir JSON de metadados", "value": { "metadata": { "tier": "premium", "risk_level": "low" } } }, "Fix extracted DOB": { "summary": "Campos de perfil extraídos corretos", "value": { "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22" } }, "Flag with reason": { "summary": "Sinalizar o utilizador e registar o motivo", "value": { "status": "FLAGGED", "reason": "Address does not match the billing country" } } } } } } } }, "/v3/users/{vendor_data}/generate-pdf/": { "get": { "summary": "Descarregar o relatório PDF completo do histórico do utilizador", "description": "Renderize e descarregue um PDF pronto para efeitos de conformidade contendo o histórico completo de verificação do utilizador identificado por `vendor_data`. É o mesmo documento que a Console produz a partir de **User detail → Actions → Download PDF**, pelo que as exportações periódicas de conformidade já não necessitam da intervenção de uma pessoa na Console.\n\n**O que o relatório contém.** Uma página de rosto com o resumo do perfil (nome, data de nascimento, estados emissores, e-mails e telefones aprovados), o estado mais recente de cada funcionalidade, os contadores de sessões e um índice das sessões incluídas — seguido do relatório padrão de cada sessão incluída, por ordem cronológica (a mais antiga primeiro). O relatório de cada sessão é o mesmo documento retornado por `GET /v3/session/{sessionId}/generate-pdf/` para essa sessão.\n\n**Sessões elegíveis.** Apenas são incluídas sessões de Verificação de utilizadores (KYC) em `Approved`, `Declined`, `In Review` ou `Kyc Expired`; as sessões em qualquer outro estado são ignoradas. Se o utilizador não tiver nenhuma sessão num desses estados, o endpoint devolve `403` — veja abaixo.\n\n**Limite máximo.** O relatório está limitado às **20 sessões mais recentes** passíveis de relatório. Quando um utilizador tem mais, são incluídas as 20 mais recentes e a página de rosto indica quantas sessões mais antigas foram omitidas. Utilize `GET /v3/sessions/?vendor_data=…` para obter a lista completa em formato JSON.\n\n**Personalização de marca.** Se a sua aplicação tiver personalização de marca branca, a página de rosto e o relatório de cada sessão são renderizados com o seu logótipo e o URL da política de privacidade; caso contrário, apresentam a marca da Didit. Os relatórios são renderizados em inglês — não existe um parâmetro de idioma.\n\n**Sem colocação em cache.** Cada chamada volta a renderizar o PDF a partir dos dados atuais, pelo que um relatório gerado após uma revisão manual reflete a decisão do revisor. Duas chamadas para o mesmo utilizador podem produzir ficheiros diferentes ao nível dos bytes — arquive o ficheiro descarregado se precisar de uma cópia imutável.\n\n**Latência.** A renderização é síncrona e descarrega todas as imagens armazenadas de cada sessão incluída, pelo que um utilizador com muitas sessões ricas em conteúdos multimédia pode demorar dezenas de segundos. Utilize um tempo limite de leitura no cliente generoso (recomendam-se 120 s) e transmita o corpo diretamente para o disco. A geração é interrompida num limite de tempo do lado do servidor em vez de continuar até que o seu cliente desista: se esse limite for atingido, a resposta continua a ser um PDF válido contendo as sessões mais recentes, e a página de rosto indica quantas foram omitidas.\n\n**Âmbito.** O utilizador é resolvido no âmbito da aplicação à qual pertence a chave de API. Uma chave nunca pode exportar um utilizador de outra aplicação — esse utilizador não existe para ela e o endpoint devolve `404`.\n\n**Barra final.** O caminho canónico termina com uma barra final (`…/generate-pdf/`). Um pedido sem ela é processado diretamente com a mesma resposta — não há redirecionamento `301`, pelo que nenhum cliente tem de seguir redirecionamentos e o `curl` não necessita de `-L`. Utilize o URL com a barra final como nos exemplos.", "operationId": "get_user_generate_pdf", "x-didit-sdk": { "resource": "users", "method": "generate_pdf", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O seu identificador exclusivo para o utilizador — uma string de formato livre (NÃO um UUID). Este é o mesmo valor que indicou como `vendor_data` ao criar as sessões do utilizador, correspondido exatamente como enviado. Codifique-o para URL; um valor que contenha `/` não pode ser endereçado por esta rota.", "example": "user-abc-123" } ], "responses": { "200": { "description": "O documento PDF renderizado, devolvido diretamente como binário `application/pdf` — não há invólucro JSON nem redirecionamento por URL de descarregamento. O corpo começa com os bytes mágicos `%PDF`. Guarde-o num ficheiro `.pdf` ou transmita-o diretamente para o chamador.", "headers": { "Content-Disposition": { "description": "`attachment; filename=user_{didit_internal_id}.pdf` — o ficheiro tem o nome do identificador estável Didit do utilizador (`didit_internal_id` em `GET /v3/users/{vendor_data}/`), e não de `vendor_data`.", "schema": { "type": "string", "example": "attachment; filename=user_f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418.pdf" } }, "Content-Length": { "description": "Tamanho total do PDF em bytes; o corpo não é fragmentado.", "schema": { "type": "integer", "example": 148213 } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Nenhuma credencial fornecida. Os pedidos para caminhos `/v3/users/*` sem um cabeçalho `x-api-key` (ou token `Authorization: Bearer`) são rejeitados pelo middleware de autenticação antes de chegarem à API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "Falha de autorização ou elegibilidade. Distinga as duas pela string `detail`:\n\n- `\"You do not have permission to perform this action.\"` — a chave de API é inválida ou foi revogada, ou o pedido inclui um token de utilizador da consola em vez de uma chave de API da aplicação.\n- `\"This user has no sessions in review, declined, approved or kyc expired to report.\"` — o utilizador existe na sua aplicação mas nenhuma das suas sessões está ainda num estado passível de relatório (por exemplo, todas as sessões continuam em `In Progress`, ou o utilizador foi criado através de `POST /v3/users/create/` e nunca realizou verificação). Aguarde por um webhook `status.updated` antes de solicitar o relatório.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "This user has no sessions in review, declined, approved or kyc expired to report." } } }, "examples": { "Invalid credentials": { "summary": "Chave de API revogada ou inválida, ou token de utilizador da Consola", "value": { "detail": "You do not have permission to perform this action." } }, "No reportable sessions": { "summary": "O utilizador existe mas não tem sessão Aprovada / Recusada / Em análise / KYC expirado", "value": { "detail": "This user has no sessions in review, declined, approved or kyc expired to report." } } } } } }, "404": { "description": "Não existe nenhum utilizador com o `vendor_data` fornecido na aplicação associada à chave de API. Os utilizadores de outras aplicações são invisíveis para esta chave e devolvem o mesmo `404`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "User not found." } } }, "examples": { "Unknown user": { "summary": "vendor_data não corresponde a nenhum utilizador desta aplicação", "value": { "detail": "User not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. A geração de PDF tem um limite dedicado de **50 pedidos por minuto por credencial** (chave de API, Bearer token ou IP de origem quando não autenticado), partilhado entre este endpoint e `GET /v3/session/{sessionId}/generate-pdf/`, além do limite global de pedidos GET de 600/min. Aguarde `Retry-After` segundos (também refletido nos cabeçalhos `X-RateLimit-*`) e tente novamente. Os relatórios não são guardados em cache no servidor, portanto transfira cada relatório uma vez e armazene o ficheiro em vez de o voltar a obter.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente o pedido.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Número máximo de gerações de PDF permitidas na janela atual (50).", "schema": { "type": "integer", "example": 50 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Carimbo de data/hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Explicação legível da violação do limite de pedidos.", "example": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } }, "examples": { "Throttled": { "summary": "Mais de 50 gerações de PDF num minuto a partir da mesma credencial", "value": { "detail": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --fail \\\n 'https://verification.didit.me/v3/users/user-abc-123/generate-pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output user-history.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.users.generate_pdf(\n \"user-abc-123\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.users.generatePdf(\"user-abc-123\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Users.GeneratePDF(ctx, \"user-abc-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.users().generatePdf(\"user-abc-123\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "users->generatePdf('user-abc-123');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.users.generate_pdf(\"user-abc-123\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Users.GeneratePdfAsync(\"user-abc-123\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/users/delete/": { "post": { "summary": "Eliminar utilizadores em lote", "description": "**Elimine permanentemente** utilizadores: os registos de utilizador são removidos permanentemente. Para o bloqueio do dia a dia, prefira [Update User Status](#patch-/v3/users/-vendor_data-/update-status/) com `BLOCKED`. Selecione utilizadores com `vendor_data_list`, com `didit_internal_id_list` ou com ambos em simultâneo; ou passe `delete_all: true`. Este endpoint nunca restringe `delete_all` com filtros. Os filtros de Pessoas da Console são recusados com um `400` (consulte a resposta `400`), para que uma intenção restrita não se transforme numa eliminação total. Duas exceções: `filter_has_approved_sessions` e `filter_has_declined_sessions` não são recusados nem aplicados, pelo que com `delete_all: true` continuam a eliminar todos os utilizadores; não os envie.\n\n**Templates biométricos:** a menos que defina `retain_face_embeddings` como `true`, todos os templates biométricos sem imagem retidos para estes utilizadores após a eliminação da sessão (consulte `/v3/biometric-templates/`) são purgados antes de o utilizador ser eliminado, pelo que a pessoa deixa de gerar correspondências na deteção de duplicados e na Pesquisa facial. Com `retain_face_embeddings: true` e `face_retention_days`, opta por manter um template biométrico sem imagem por pessoa durante esse número de dias, não sendo mantido mais nada sobre a pessoa. Se um template não puder ser purgado devido à indisponibilidade de um armazenamento biométrico, a chamada devolve `503`, nenhum utilizador no pedido é eliminado e a repetição do pedido conclui a operação.\n\n**Relatórios regulamentares submetidos:** se os dados selecionados estiverem num relatório regulamentar finalizado, todo o pedido é recusado com `409` e nada é eliminado. O corpo utiliza `code: in_filed_report` e identifica cada relatório com `uuid`, `report_number`, `report_type` e `case_uuid`. Elimine os relatórios e repita o pedido.", "operationId": "batch_delete_users", "x-didit-sdk": { "resource": "users", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Forneça `vendor_data_list`, `didit_internal_id_list` ou `delete_all: true`. As duas listas podem ser combinadas com um operador OR. Quando `delete_all` é `true`, tem precedência e ambas as listas são ignoradas.", "properties": { "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "Os seus próprios identificadores a eliminar, correspondidos exatamente como foram enviados." }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs internos de utilizador da Didit a eliminar - o `didit_internal_id` devolvido pelos endpoints de criação e obtenção." }, "delete_all": { "type": "boolean", "default": false, "description": "Se `true`, elimina todos os utilizadores na aplicação." }, "retain_face_embeddings": { "type": "boolean", "default": false, "description": "A sua escolha explícita de manter um modelo biométrico sem imagem de cada pessoa eliminada para deteção de duplicados, durante `face_retention_days`. Tudo o resto sobre a pessoa é eliminado. Omita este campo, ou envie `false`, para eliminar os modelos juntamente com os utilizadores. Quando for `true`, `face_retention_days` é obrigatório." }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Número de dias durante os quais o template biométrico sem imagem é conservado quando `retain_face_embeddings` for `true`. Obrigatório com este parâmetro e rejeitado sem ele com um `400` em `face_retention_days`.", "example": 365 } } }, "examples": { "Specific users": { "summary": "Eliminar utilizadores por vendor_data", "value": { "vendor_data_list": [ "user-123", "user-456" ] } }, "By Didit internal ID": { "summary": "Eliminar utilizadores por didit_internal_id", "value": { "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } }, "All users": { "summary": "Apagar todos os utilizadores nesta aplicação", "value": { "delete_all": true } }, "Keep face templates": { "summary": "Eliminar utilizadores e manter modelos faciais anónimos durante 365 dias", "value": { "vendor_data_list": [ "user-123" ], "retain_face_embeddings": true, "face_retention_days": 365 } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data_list\": [\"user-123\", \"user-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.batch_delete(\n vendor_data_list=[\"user-123\", \"user-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.batchDelete({\n vendor_data_list: [\"user-123\", \"user-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.BatchDelete(ctx, didit.UsersBatchDeleteParams{\n\tVendorDataList: didit.Some([]string{\"user-123\", \"user-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.UsersBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().batchDelete(UsersBatchDeleteParams.builder()\n .vendorDataList(List.of(\"user-123\", \"user-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->batchDelete([\n 'vendor_data_list' => ['user-123', 'user-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.batch_delete(vendor_data_list: [\"user-123\", \"user-456\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.BatchDeleteAsync(new UsersBatchDeleteParams\n{\n VendorDataList = new string[] { \"user-123\", \"user-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Utilizadores eliminados. Devolve o número de utilizadores efetivamente eliminados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "Número de utilizadores eliminados (exclui valores de vendor_data que não corresponderam a nada)." } } }, "examples": { "Deleted some": { "value": { "deleted": 2 } }, "Nothing matched": { "value": { "deleted": 0 } } } } } }, "400": { "description": "Erro de validação; nada é eliminado. Os erros são indexados pelo nome do campo. Sem nenhum seletor (nenhuma lista e `delete_all` não sendo `true`), o corpo é `{\"vendor_data_list\": [\"This field is required unless delete_all is true.\"]}`; uma lista vazia é recusada sob a sua própria chave com `\"This list may not be empty.\"`. Um filtro exclusivo da Console (`filter_search`, `filter_status`, `filter_country`, `filter_date_from`, `filter_date_to`, `filter_tag`, `filter_latest_verification_status`, `filter_risk`, `filter_has_sessions`, `filter_has_open_alerts`, `filter_aml_monitoring`, `filter_can_sign_in`, `filter_auth_status`, `filter_auth_method` ou `filter_auth_mfa_enabled`) é recusado sempre que tiver um valor, mesmo `false`, com um objeto indexado por cada um desses campos. Qualquer outra chave `filter_*` desconhecida é recusada com `\"Unknown filter.\"`.", "content": { "application/json": { "examples": { "Missing selector": { "summary": "Nem list nem delete_all fornecidos", "value": { "vendor_data_list": [ "This field is required unless delete_all is true." ] } }, "Console-only filter": { "value": { "filter_has_sessions": "This filter is Console-only and is not supported by this endpoint." } } } } } }, "401": { "description": "Nenhuma credencial fornecida. Os pedidos para caminhos `/v3/users/*` sem um cabeçalho `x-api-key` (ou token `Authorization: Bearer`) são rejeitados pelo middleware de autenticação antes de chegarem à API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "Chave de API inválida ou revogada, ou a chave não pode eliminar utilizadores para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } }, "503": { "description": "Um armazenamento biométrico estava indisponível durante a retenção ou eliminação de um template biométrico. Nada é eliminado; repita o mesmo pedido. As novas tentativas são idempotentes e convergem para um único modelo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } }, "409": { "description": "Nada é eliminado. O `code` indica o motivo: `in_filed_report` quando a seleção inclui uma pessoa num relatório regulamentar finalizado, `subject_deletion_in_progress` quando outro pedido ainda está a eliminar uma das pessoas selecionadas. Repita o pedido assim que essa eliminação estiver concluída.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InFiledReportError" }, { "$ref": "#/components/schemas/SubjectDeletionInProgressError" } ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/sessions/delete/": { "post": { "summary": "Eliminar sessões de KYC em massa por session_number", "description": "Elimine em massa sessões de Verificação de utilizadores (KYC) pelo seu `session_number` numérico, ou todas as sessões de KYC na sua aplicação com `delete_all: true`.\n\nO `session_number` é o contador incremental legível por humanos apresentado na lista de sessões da Consola e devolvido como `session_number` pelos endpoints de criação de sessão e de decisão; **não** é o UUID `session_id`. Para eliminar uma sessão por UUID, ou para eliminar uma sessão de Verificação de empresas (KYB), que este endpoint nunca afeta, utilize `DELETE /v3/session/{sessionId}/delete/`.\n\n**São eliminadas até 20 sessões no pedido; mais de 20 são processadas como uma tarefa.** O número de sessões correspondentes decide o comportamento, quer sejam selecionadas por `session_numbers` quer com `delete_all`:\n- Até 20 sessões correspondentes: são eliminadas antes da resposta, que é `200` com uma entrada por sessão em `results[]`.\n- Mais de 20: a resposta é `202` com uma tarefa de eliminação, e as sessões são eliminadas em segundo plano. Consulte periodicamente `GET /v3/sessions/delete/{job_id}/` até que o `status` seja `COMPLETED` ou `FAILED`. Uma tarefa comunica contagens por resultado, nunca que sessões eliminou. Uma tarefa com `delete_all` elimina apenas as sessões criadas antes do pedido; as sessões iniciadas enquanto está em execução não são eliminadas.\n\nCada sessão eliminada recebe exatamente o mesmo tratamento que no endpoint de eliminação de sessão individual: a sessão, todas as tentativas de verificação que contenha, a sua decisão e dados extraídos, os seus registos de funcionalidades relacionados (verificação de identidade, rosto, prova de vida, correspondência facial, entre outros) e todos os seus ficheiros armazenados são eliminados, desaparece de todos os endpoints de leitura e os URLs de multimédia emitidos anteriormente deixam de resolver. As entregas de webhooks que ainda estejam em fila para uma sessão eliminada, bem como as respetivas novas tentativas, são descartadas; os webhooks já entregues não são afetados. As entradas na lista de bloqueio **não** são removidas, os créditos já consumidos **não** são reembolsados e as entidades de utilizador principais **não** são eliminadas (utilize `POST /v3/users/delete/` para essas); nenhum webhook é emitido para a eliminação. A eliminação é permanente e irreversível.\n\n**Semântica de seleção:**\n- Com `delete_all: true`, pode restringir a seleção com os filtros de `GET /v3/sessions/`, cada um com o prefixo `filter_` (por exemplo, `filter_status`, `filter_workflow_id`, `filter_date_from`). Os filtros que aceitam vários valores em List Sessions (`status`, `workflow_id`, `country`, `region`, `document_type`, `document_name`, `session_type`, `warning`, `organization_name`) aceitam uma cadeia de carateres separada por vírgulas ou um array; os outros aceitam um único valor. Um valor vazio é ignorado. Os filtros aplicam-se apenas juntamente com `delete_all`, e uma tarefa de eliminação aplica os mesmos filtros.\n- Uma chave `filter_*` desconhecida, ou um valor de filtro que não possa ser lido, rejeita todo o pedido com `400` antes de qualquer elemento ser eliminado, para que um filtro incorretamente introduzido nunca alargue a eliminação a todas as sessões.\n- As entradas em `session_numbers` que não correspondam a uma sessão de KYC existente na sua aplicação (números desconhecidos, sessões já eliminadas ou sessões pertencentes a outra aplicação) são **ignoradas silenciosamente**: não aparecem em `results` e não são contabilizadas no `total` de uma tarefa.\n- Falhas de validação (uma entrada não numérica, uma lista vazia, a ausência de `session_numbers` ou `delete_all`, ou uma conservação de modelos que a aplicação não consiga cumprir) rejeitam o **pedido inteiro** com `400` e não eliminam nada.\n- As sessões são eliminadas em grupos. Se um grupo não puder ser eliminado (por exemplo, devido à indisponibilidade de um serviço de armazenamento), todas as sessões desse grupo são reportadas como `face_retention_outcome: failed_retryable` e mantêm-se inalteradas; os restantes grupos não são afetados. Repita o pedido para essas sessões. Uma tarefa tenta novamente esse grupo de forma automática.\n- Não existe um limite máximo documentado para o comprimento da lista; o limite partilhado de pedidos de escrita (abaixo) constitui o limite prático.\n\n**Dados biométricos faciais:** os campos opcionais `retain_face_embeddings`, `face_retention_days`, `face_retention_deadline`, `deletion_instruction` e `instruction_id` têm o mesmo significado que em `DELETE /v3/session/{sessionId}/delete/` e aplicam-se a todas as sessões correspondentes. Cada resultado comunica o seu próprio `face_retention_outcome`.\n\n**Resposta:** `200 OK` com `results[]` para até 20 sessões correspondentes, ou `202 Accepted` com uma tarefa de eliminação para quantidades superiores. Todos os resultados confirmam a eliminação, exceto `face_retention_outcome: failed_retryable`, que comunica uma sessão que NÃO foi eliminada e deve ser tentada novamente. Versões anteriores deste endpoint devolviam `204 No Content`; atualize os clientes que validam `204`.\n\n**Idempotência:** repetir o mesmo pedido não elimina mais nada: os números que já não correspondam a uma sessão são ignorados.\n\n**`delete_all: true` (destrutivo):** elimina **todas** as sessões de KYC restantes na aplicação; `session_numbers` é ignorado quando este estiver definido. Não existe qualquer passo de confirmação nem possibilidade de anular.\n\n**Autenticação:** chave de API no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`); esta API nunca devolve `401`.\n\n**Limite de pedidos:** orçamento de escrita partilhado de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; exceder este limite devolve `429`.\n\nEste endpoint aceita apenas chaves de API. Os tokens Bearer de utilizadores da Business Console são rejeitados com `403` (ao contrário da eliminação de sessão individual, que aceita ambos).\n\n**Relatórios regulamentares submetidos:** se os dados selecionados estiverem num relatório regulamentar finalizado, todo o pedido é recusado com `409` e nada é eliminado. O corpo utiliza `code: in_filed_report` e identifica cada relatório com `uuid`, `report_number`, `report_type` e `case_uuid`. Elimine os relatórios e, em seguida, repita o pedido.", "operationId": "batch_delete_sessions", "x-didit-sdk": { "resource": "sessions", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_numbers": { "type": "array", "description": "Valores numéricos de `session_number` das sessões de KYC a eliminar, como strings compostas apenas por dígitos (números JSON também são aceites e convertidos). Obrigatório, salvo se `delete_all` for `true`; uma lista vazia devolve `400`. Qualquer entrada com carateres não numéricos rejeita todo o pedido com `400` (exceto se `delete_all` for `true`, caso em que a validação é ignorada e as entradas não são consideradas). Números que não correspondam a uma sessão ativa na sua aplicação são ignorados silenciosamente.", "items": { "type": "string", "pattern": "^[0-9]+$", "example": "1001" }, "minItems": 1, "example": [ "1001", "1002", "1003" ] }, "delete_all": { "type": "boolean", "description": "Quando `true`, todas as sessões de KYC restantes na aplicação que efetua a chamada são eliminadas e `session_numbers` é ignorado, a menos que restrinja a seleção com chaves `filter_*`. Mais de 20 sessões correspondentes são processadas como uma tarefa de eliminação (`202`) que abrange apenas as sessões criadas antes do pedido. O valor predefinido é `false`. Irreversível; não existe um passo de confirmação.", "default": false, "example": false }, "retain_face_embeddings": { "type": "boolean", "nullable": true, "description": "Substitui a `face_retention_policy` da aplicação para esta eliminação. `true` mantém um template biométrico facial sem imagem associado ao utilizador da sessão após a sessão ser eliminada; `false` elimina o embedding facial com a sessão; omita ou use `null` para seguir a política da aplicação. Ignorado para sessões KYB e para sessões sem embedding facial.", "example": true }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Duração finita de conservação, em dias, para um modelo conservado. Obrigatória quando um modelo é conservado, a menos que a aplicação já defina `face_retention_days`. O `expires_at` do modelo é determinado pelo limite mais cedo entre esta duração, a janela geral de conservação de dados da aplicação e `face_retention_deadline`.", "example": 365 }, "face_retention_deadline": { "type": "string", "format": "date-time", "description": "Data de expiração definitiva opcional para um modelo retido. Tem de ser no futuro.", "example": "2027-08-28T00:00:00Z" }, "deletion_instruction": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ], "default": "operational_session_delete", "description": "A classe de instrução que está a fornecer. `operational_session_delete` elimina a sessão e retém um modelo apenas quando a política ou `retain_face_embeddings` o determinar. `privacy_erasure` elimina permanentemente todos os templates biométricos retidos associados ao utilizador da sessão antes de eliminar a sessão, não pode ser substituído pela política da aplicação e não pode ser combinado com `retain_face_embeddings: true` (`400`).", "example": "operational_session_delete" }, "instruction_id": { "type": "string", "maxLength": 255, "description": "A sua referência duradoura para esta instrução de eliminação (por exemplo, o id de um pedido de eliminação). Registada no registo de auditoria e em qualquer modelo retido. Gerada pela Didit quando omitida.", "example": "dsar-2026-0142" }, "filter_status": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `status` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma string separada por vírgulas ou um array. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_vendor_data": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `vendor_data` de [List Sessions](/pt/sessions-api/list-sessions), com o mesmo valor. Um único valor, não uma lista: um array é unido num único texto separado por vírgulas, pelo que múltiplos valores não são correspondidos como alternativas. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "string" }, "filter_search": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `search` de [List Sessions](/pt/sessions-api/list-sessions), com o mesmo valor. Um único valor, não uma lista: um array é unido num único texto separado por vírgulas, pelo que múltiplos valores não são correspondidos como alternativas. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "string" }, "filter_workflow_id": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `workflow_id` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma string separada por vírgulas ou um array. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_date_from": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `date_from` de [List Sessions](/pt/sessions-api/list-sessions), com o mesmo valor. Um valor, não uma lista: um array é unido num único valor separado por vírgulas, pelo que vários valores são recusados com `400`. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "string", "format": "date" }, "filter_date_to": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `date_to` de [List Sessions](/pt/sessions-api/list-sessions), com o mesmo valor. Um valor, não uma lista: um array é unido num único valor separado por vírgulas, pelo que vários valores são recusados com `400`. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "string", "format": "date" }, "filter_country": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `country` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma cadeia de carateres separada por vírgulas ou um array. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_document_type": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `document_type` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma cadeia de carateres separada por vírgulas ou um array. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_document_name": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `document_name` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma cadeia de carateres separada por vírgulas ou um array. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_region": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `region` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma string separada por vírgulas ou um array. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_didit_internal_id": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `didit_internal_id` de [List Sessions](/pt/sessions-api/list-sessions), com o mesmo valor. Um valor, não uma lista: um array é unido num único valor separado por vírgulas, pelo que vários valores são recusados com `400`. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "string", "format": "uuid" }, "filter_session_type": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `session_type` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma string separada por vírgulas ou um array. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_api_service": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `api_service` de [List Sessions](/pt/sessions-api/list-sessions), com o mesmo valor. Um valor, não uma lista: um array é unido num único valor separado por vírgulas, pelo que vários valores são recusados com `400`. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "string" }, "filter_screened_full_name": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `screened_full_name` de [List Sessions](/pt/sessions-api/list-sessions), com o mesmo valor. Um único valor, não uma lista: um array é unido num único texto separado por vírgulas, pelo que múltiplos valores não são correspondidos como alternativas. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "string" }, "filter_warning": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `warning` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma string separada por vírgulas ou um array. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_status_initialized_as_in_review": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `status_initialized_as_in_review` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "boolean" }, "filter_is_kyc_to_be_reviewed": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `is_kyc_to_be_reviewed` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "boolean" }, "filter_euuid": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `euuid` de [List Sessions](/pt/sessions-api/list-sessions), com o mesmo valor. Um valor, não uma lista: um array é unido num único valor separado por vírgulas, pelo que vários valores são recusados com `400`. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "type": "string", "format": "uuid" }, "filter_organization_name": { "description": "Restringe um `delete_all` às sessões que correspondam ao filtro `organization_name` de [List Sessions](/pt/sessions-api/list-sessions), com os mesmos valores. Uma string separada por vírgulas ou um array. Com uma chave de API, só pode corresponder ao nome da sua própria organização, pelo que seleciona todas as suas sessões ou nenhuma. Ignorado sem `delete_all`. Um valor vazio é ignorado e não restringe a seleção.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "examples": { "Specific sessions": { "summary": "Eliminar sessões específicas por número", "value": { "session_numbers": [ "1001", "1002", "1003" ] } }, "All sessions": { "summary": "Eliminar todas as sessões de KYC na aplicação", "value": { "delete_all": true } }, "Delete and retain templates": { "summary": "Eliminar sessões, mas manter templates biométricos sem imagem durante 365 dias", "value": { "session_numbers": [ "1001", "1002" ], "retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "post-approval-cleanup-2026-08" } }, "Privacy erasure": { "summary": "Eliminar sessões e purgar todos os modelos retidos para os respetivos Utilizadores", "value": { "session_numbers": [ "1001" ], "deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142" } }, "Filtered delete_all": { "summary": "Eliminar todas as sessões Recusadas de um fluxo criadas em setembro de 2026", "value": { "delete_all": true, "filter_status": [ "Declined" ], "filter_workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "filter_date_from": "2026-09-01", "filter_date_to": "2026-09-30" } } } } } }, "responses": { "200": { "description": "Até 20 sessões corresponderam e foram processadas no pedido. Um resultado por sessão correspondente; números que não corresponderam a nada (desconhecidos ou já eliminados) são ignorados e não aparecem. Um resultado confirma a eliminação, exceto quando `face_retention_outcome` for `failed_retryable`: essa sessão NÃO foi eliminada e deve ser tentada novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "A sessão eliminada." }, "session_number": { "type": "integer", "nullable": true, "description": "O número da sessão eliminada." }, "face_retention_outcome": { "type": "string", "enum": [ "retained_with_user", "deleted", "none", "ineligible_no_vendor_user", "failed_retryable" ], "description": "O que aconteceu aos dados biométricos faciais da sessão. `deleted`: o embedding facial foi eliminado com a sessão (predefinição). `retained_with_user`: a sessão é eliminada e um template biométrico sem imagem permanece associado ao Utilizador; consulte `biometric_template_uuid`. `none`: a sessão não tinha nenhum embedding facial (por exemplo, uma sessão de KYC apenas de documentos sem selfie de prova de vida; as sessões de KYB nunca são selecionadas por este endpoint). `ineligible_no_vendor_user`: a conservação foi solicitada, mas a sessão não tem nenhum Utilizador associado, pelo que o embedding foi eliminado com a sessão. `failed_retryable` (apenas no endpoint de lote): não foi possível eliminar o grupo com o qual esta sessão foi eliminada (um serviço de armazenamento, um armazenamento biométrico ou um fornecedor de monitorização estavam indisponíveis); esta sessão permanece, repita o pedido para a mesma." }, "biometric_template_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "ID do template biométrico retido quando `face_retention_outcome` é `retained_with_user`; `null` caso contrário. Faça a sua gestão através de `/v3/biometric-templates/{template_uuid}/`." }, "biometric_template_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o template biométrico retido é eliminado, quando `face_retention_outcome` é `retained_with_user`; `null` quando nenhum template é retido." }, "deleted_child_verifications": { "type": "integer", "description": "Sempre `0` neste endpoint, que elimina apenas sessões de KYC. Eliminar uma sessão de Verificação de empresas (KYB) com `DELETE /v3/session/{sessionId}/delete/` comunica as verificações que criou e que foram eliminadas com a mesma." } } } } } }, "examples": { "Mixed outcomes": { "value": { "results": [ { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1001, "face_retention_outcome": "deleted", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 }, { "session_id": "b8e1d2c3-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "session_number": 1002, "face_retention_outcome": "retained_with_user", "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "biometric_template_expires_at": "2027-10-09T10:15:00Z", "deleted_child_verifications": 0 }, { "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c", "session_number": 1003, "face_retention_outcome": "ineligible_no_vendor_user", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 }, { "session_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "session_number": 1004, "face_retention_outcome": "failed_retryable", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } ] } } } } } }, "202": { "description": "Mais de 20 sessões corresponderam. São eliminadas em segundo plano; consulte `GET /v3/sessions/delete/{job_id}/` até que o `status` seja `COMPLETED` ou `FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDeletionJob" }, "examples": { "Job accepted": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "PENDING", "total": 250, "processed": 0, "outcomes": { "deleted": 0, "none": 0, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": null } } } } } }, "400": { "description": "Erro de validação — nada foi eliminado. Os valores de erro são arrays de strings de mensagem indexados pelo nome do campo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_numbers": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": { "description": "Outras chaves: uma chave `filter_*` que não seja um filtro de Listar Sessões (`\"Unknown filter.\"`), ou uma chave `filter_*` cujo valor não possa ser lido (com a chave `filter_*` correspondente e uma matriz de mensagens)." } }, "examples": { "Missing selector": { "summary": "Nem session_numbers nem delete_all fornecidos", "value": { "session_numbers": [ "This field is required unless delete_all is true." ] } }, "Empty list": { "summary": "session_numbers é um array vazio", "value": { "session_numbers": [ "This list may not be empty." ] } }, "Non-numeric entry": { "summary": "session_numbers contém uma cadeia que não é composta por dígitos", "value": { "session_numbers": [ "All session_numbers must be numeric." ] } }, "Privacy erasure cannot retain": { "summary": "deletion_instruction privacy_erasure combinado com retain_face_embeddings true", "value": { "retain_face_embeddings": [ "Privacy erasure cannot retain biometric templates." ] } }, "No finite retention duration": { "summary": "Conservação solicitada sem face_retention_days no pedido ou na aplicação", "value": { "detail": "A finite biometric-template retention duration is required." } }, "Unknown filter": { "summary": "Uma chave filter_* que List Sessions não possui", "value": { "filter_reviewer": "Unknown filter." } }, "Unreadable filter value": { "summary": "Um valor de filtro que não pode ser lido", "value": { "filter_date_from": [ "Enter a valid date." ] } } } } } }, "403": { "description": "Chave de API em falta. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho x-api-key ou a chave é inválida", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos de escrita partilhado excedido (300 pedidos POST/PATCH/DELETE por minuto por chave de API). Inspecione o cabeçalho `Retry-After` e os cabeçalhos de resposta `X-RateLimit-*` antes de tentar novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Orçamento de escrita esgotado", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } }, "409": { "description": "Uma sessão selecionada faz parte de um relatório regulamentar finalizado. Nada foi eliminado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/sessions/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_numbers\": [\"1001\", \"1002\", \"1003\"]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.batch_delete(\n session_numbers=[\"1001\", \"1002\", \"1003\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.batchDelete({\n session_numbers: [\"1001\", \"1002\", \"1003\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.BatchDelete(ctx, didit.SessionsBatchDeleteParams{\n\tSessionNumbers: didit.Some([]string{\"1001\", \"1002\", \"1003\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().batchDelete(SessionsBatchDeleteParams.builder()\n .sessionNumbers(List.of(\"1001\", \"1002\", \"1003\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->batchDelete([\n 'session_numbers' => ['1001', '1002', '1003'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.batch_delete(session_numbers: [\"1001\", \"1002\", \"1003\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.BatchDeleteAsync(new SessionsBatchDeleteParams\n{\n SessionNumbers = new string[] { \"1001\", \"1002\", \"1003\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/sessions/delete/{job_id}/": { "get": { "summary": "Obter tarefa de eliminação de sessões em massa", "description": "Progresso de uma eliminação em massa de sessões à qual `POST /v3/sessions/delete/` respondeu com `202` (mais de 20 sessões correspondentes, selecionadas por `session_numbers` ou com `delete_all`). Efetue sondagens a cada poucos segundos enquanto `status` for `PENDING` ou `PROCESSING`; pare quando for `COMPLETED` ou `FAILED`.\n\nA tarefa comunica quantas sessões terminaram em cada resultado e quantas processou, nunca quais as sessões que eliminou. Uma tarefa em estado `FAILED` apresenta o motivo em `error`; as sessões a que ainda não tinha chegado permanecem intactas, pelo que deve repetir o pedido de eliminação para as eliminar.\n\n**Autenticação:** Chave de API no cabeçalho `x-api-key`. Uma tarefa só é visível para a aplicação que a criou; qualquer outro `job_id` devolve `404`. Credenciais em falta ou inválidas devolvem `403`; esta API nunca devolve `401`.", "operationId": "get_session_deletion_job", "x-didit-sdk": { "resource": "sessions", "method": "retrieve_deletion_job", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O `job_id` devolvido com o `202` de `POST /v3/sessions/delete/`." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/sessions/delete/JOB_ID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.retrieve_deletion_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.retrieveDeletionJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RetrieveDeletionJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().retrieveDeletionJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->retrieveDeletionJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.retrieve_deletion_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RetrieveDeletionJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A tarefa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDeletionJob" }, "examples": { "Processing": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "PROCESSING", "total": 250, "processed": 100, "outcomes": { "deleted": 82, "none": 18, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": null } }, "Completed": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "COMPLETED", "total": 250, "processed": 250, "outcomes": { "deleted": 204, "none": 44, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 2 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": "2026-10-09T10:16:40Z" } }, "Failed": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "FAILED", "total": 250, "processed": 100, "outcomes": { "deleted": 82, "none": 18, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": "The deletion stopped before it finished. The sessions it had not reached are still in place; repeat the request to delete them.", "created_at": "2026-10-09T10:15:00Z", "completed_at": "2026-10-09T10:15:52Z" } } } } } }, "403": { "description": "Chave de API em falta. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho x-api-key ou a chave é inválida", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhuma tarefa de eliminação com este `job_id` para a aplicação que faz o pedido. As tarefas só são visíveis para a aplicação que as criou." } } } }, "/v3/sessions/{session_id}/reviews/": { "get": { "summary": "Listar revisões da sessão e registo de atividade", "description": "Retorna o registo de auditoria / feed de atividade de uma sessão de Verificação de utilizadores (KYC), da mais recente para a mais antiga, num invólucro paginado (`count` / `next` / `previous` / `results`, 50 entradas por página por predefinição).\n\nAs entradas do feed são registadas por todos os intervenientes que interagem com a sessão: decisões manuais tomadas através de `PATCH /v3/session/{session_id}/update-status/` (que regista `previous_status` → `new_status`), atividade do revisor na Console (comentários com menções `@email`, edições de dados de KYC/POA, carregamentos/remoções de ficheiros, alterações de etiquetas, visualizações da página de detalhes), correspondências de monitorização contínua de AML e notas adicionadas via `POST` neste mesmo caminho. A leitura deste feed é o equivalente do lado da API ao painel **Activity** na vista de sessão da Didit Console.\n\nApenas sessões de Verificação de utilizadores (KYC) podem ser consultadas aqui; os IDs de sessão de Verificação de empresas (KYB) retornam `404`.", "operationId": "list_session_reviews", "x-didit-sdk": { "resource": "sessions.reviews", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "UUID da sessão de Verificação de utilizadores (KYC). Tem de pertencer à mesma aplicação da chave de API — UUIDs entre aplicações, sessões eliminadas e IDs de sessões de Verificação de empresas (KYB) devolvem todos `404`.", "schema": { "type": "string", "format": "uuid", "example": "8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d" } }, { "name": "limit", "in": "query", "required": false, "description": "Tamanho da página. A predefinição é `50`.", "schema": { "type": "integer", "default": 50, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Número de entradas a ignorar desde o início do feed (ordenado). O valor predefinido é `0`. Os URLs `next` / `previous` na resposta contêm os valores corretos para percorrer o feed.", "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "Ordem de ordenação. O feed tem como predefinição os mais recentes primeiro (`-created_at`); passe `created_at` para o ler do mais antigo para o mais recente. Os valores desconhecidos são ignorados silenciosamente (a ordem predefinida é utilizada); outros nomes de campos do serializador também são aceites.", "schema": { "type": "string", "default": "-created_at", "example": "created_at" } } ], "responses": { "200": { "description": "Fluxo de atividade paginado, o mais recente primeiro por predefinição. `count` é o número total de entradas; `next` / `previous` são URLs de página prontos a usar (`null` nas extremidades). Um `count` de `0` com `results` vazio significa que ainda não foi registada qualquer atividade.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número total de entradas de feed para esta sessão (em todas as páginas).", "example": 3 }, "next": { "type": "string", "nullable": true, "description": "URL da página seguinte, ou `null` na última página.", "example": null }, "previous": { "type": "string", "nullable": true, "description": "URL da página anterior, ou `null` na primeira página.", "example": null }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewItem" }, "description": "Entradas de feed para esta página." } } }, "examples": { "DecisionTrail": { "summary": "Aprovação manual e notas adicionadas pela API", "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "de0561bc-5583-4409-9171-1a31a4c8a5f4", "activity_type": "STATUS_UPDATED", "actor_display": "API Client", "actor_email": null, "actor_type": "API_KEY", "new_status": "Approved", "previous_status": "In Review", "comment": "Document re-checked manually; address matches.", "mentioned_emails": [], "previous_value": { "status": "In Review" }, "new_value": { "status": "Approved" }, "changed_fields": [ "status" ], "metadata": null, "created_at": "2026-06-12T00:19:31.918735Z" }, { "uuid": "35370f58-5098-44ee-8a06-8c9af80b2455", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": null, "previous_status": null, "comment": "Note without status.", "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.504157Z" }, { "uuid": "00338f82-f1c5-4f57-8614-c49bb258af1a", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": "In Review", "previous_status": null, "comment": "Flagging for manual document re-check.", "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.466537Z" } ] } }, "PaginatedFirstPage": { "summary": "Primeira página com limit=2 — a seguinte contém o URL de seguimento", "value": { "count": 4, "next": "https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/?limit=2&offset=2", "previous": null, "results": [ { "uuid": "de0561bc-5583-4409-9171-1a31a4c8a5f4", "activity_type": "STATUS_UPDATED", "actor_display": "API Client", "actor_email": null, "actor_type": "API_KEY", "new_status": "Approved", "previous_status": "In Review", "comment": "Document re-checked manually; address matches.", "mentioned_emails": [], "previous_value": { "status": "In Review" }, "new_value": { "status": "Approved" }, "changed_fields": [ "status" ], "metadata": null, "created_at": "2026-06-12T00:19:31.918735Z" }, { "uuid": "bd4e6227-bdd2-42b2-a726-1d12f785a457", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": null, "previous_status": null, "comment": null, "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.540238Z" } ] } }, "Empty": { "summary": "Sessão ainda sem atividade registada", "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "403": { "description": "`x-api-key` em falta, malformado, expirado ou revogado. A autenticação é verificada antes da pesquisa da sessão, pelo que uma chave em falta devolve `403` mesmo quando o UUID da sessão não existe.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." } } }, "examples": { "InvalidKey": { "summary": "Cabeçalho x-api-key em falta ou inválido", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nenhuma sessão de Verificação de utilizadores (KYC) com este UUID está visível para a sua aplicação: o UUID não existe, a sessão foi eliminada ou pertence a uma aplicação diferente. Os IDs de sessão de Verificação de empresas (KYB) também devolvem `404` aqui — o feed de revisões só pode ser acedido para sessões de KYC.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Session not found." } } }, "examples": { "NotFound": { "summary": "UUID de sessão desconhecido, eliminado ou de outra aplicação", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. Inspecione os cabeçalhos de resposta `Retry-After` e `X-RateLimit-*`. Consulte [Limite de pedidos](/pt/integration/rate-limiting)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s 'https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.reviews.list(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.reviews.list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.Reviews.ListAutoPaging(ctx, \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", didit.SessionsReviewsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().reviews().list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->reviews->list('8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.reviews.list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.Reviews.ListAsync(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Adicionar uma nota de revisão ao registo de auditoria de uma sessão", "description": "Anexe uma nota ao feed de atividade / revisão de uma sessão de Verificação de utilizadores (KYC). **Este endpoint apenas regista uma entrada — nunca altera a sessão.** O `status` da sessão não é modificado, nenhuma validação de transição de estado é executada e nenhum webhook é disparado. Para aprovar, recusar ou reabrir efetivamente uma sessão (o que também escreve uma entrada `STATUS_UPDATED` com atribuição completa neste feed), use antes `PATCH /v3/session/{session_id}/update-status/`.\n\nAmbos os campos do corpo são opcionais e é aceite um objeto JSON vazio. O `new_status` é armazenado puramente como uma etiqueta na entrada e aceita qualquer um dos dez valores de estado da sessão (sensível a maiúsculas e minúsculas). As menções `@email` dentro de `comment` são guardadas apenas como texto simples — não acionam quaisquer notificações neste endpoint, e o campo `mentioned_emails` da entrada permanece vazio.\n\nNota sobre a atribuição: as entradas aqui criadas não contêm informação sobre o interveniente. No feed exibem `actor_display: \"Unknown\"`, `actor_type: \"CONSOLE_USER\"` e `activity_type: \"STATUS_UPDATED\"` (valores predefinidos de armazenamento), e o campo `user` no corpo da resposta `201` é `\"Unknown\"`.", "operationId": "create_session_review", "x-didit-sdk": { "resource": "sessions.reviews", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": false, "description": "Defina como `application/json` ao enviar um corpo JSON.", "schema": { "type": "string", "example": "application/json" } }, { "name": "session_id", "in": "path", "required": true, "description": "UUID da sessão de Verificação de utilizadores (KYC). Tem de pertencer à mesma aplicação da chave de API — UUIDs entre aplicações, sessões eliminadas e IDs de sessões de Verificação de empresas (KYB) devolvem todos `404`.", "schema": { "type": "string", "format": "uuid", "example": "8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Etiqueta de estado opcional a registar na entrada. Aceita qualquer valor de estado da sessão, sensível a maiúsculas e minúsculas (`\"approved\"` é rejeitado com `400`). Registar um estado aqui **não** altera o estado real da sessão — utilize o endpoint de atualização de estado para esse efeito.", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "Nota de texto livre opcional (sem limite de comprimento imposto). Armazenada literalmente; as menções `@email` não são processadas neste endpoint.", "example": "Flagging for manual document re-check." } } }, "examples": { "NoteWithStatusLabel": { "summary": "Nota com uma etiqueta de estado (estado da sessão inalterado)", "value": { "new_status": "In Review", "comment": "Flagging for manual document re-check." } }, "CommentOnly": { "summary": "Nota simples sem etiqueta de estado", "value": { "comment": "Customer emailed an updated utility bill; awaiting upload." } } } } } }, "responses": { "201": { "description": "Entrada registada no registo de auditoria da sessão. A sessão em si não é alterada — o respetivo `status` mantém o valor anterior e nenhum webhook é enviado. A nova entrada também aparece no topo de `GET …/reviews/` (com `actor_display: \"Unknown\"`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "Nome de apresentação do autor da entrada. Sempre `\"Unknown\"` para entradas criadas através deste endpoint, porque não regista a atribuição do interveniente.", "example": "Unknown" }, "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "A etiqueta de estado registada na entrada, ou `null` se nenhuma tiver sido enviada. O estado real da sessão não é afetado.", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "A nota registada na entrada, ou `null` se nenhuma tiver sido enviada.", "example": "Flagging for manual document re-check." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a entrada foi gravada, ISO 8601 UTC.", "example": "2026-06-12T00:18:44.466537Z" } } }, "examples": { "NoteWithStatusLabel": { "summary": "Nota com uma etiqueta de estado", "value": { "user": "Unknown", "new_status": "In Review", "comment": "Flagging for manual document re-check.", "created_at": "2026-06-12T00:18:44.466537Z" } }, "CommentOnly": { "summary": "Nota simples", "value": { "user": "Unknown", "new_status": null, "comment": "Note without status.", "created_at": "2026-06-12T00:18:44.504157Z" } } } } } }, "400": { "description": "Erro de validação, devolvido como um mapa de mensagens por campo. A causa habitual é um valor de `new_status` que não seja um dos dez estados permitidos — a verificação diferencia maiúsculas de minúsculas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "new_status": { "type": "array", "items": { "type": "string" }, "example": [ "\"approved\" is not a valid choice." ] } } }, "examples": { "InvalidStatusChoice": { "summary": "Valor de estado em minúsculas / desconhecido", "value": { "new_status": [ "\"approved\" is not a valid choice." ] } } } } } }, "403": { "description": "`x-api-key` em falta, malformado, expirado ou revogado. A autenticação é verificada antes da pesquisa da sessão, pelo que uma chave em falta devolve `403` mesmo quando o UUID da sessão não existe.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." } } }, "examples": { "InvalidKey": { "summary": "Cabeçalho x-api-key em falta ou inválido", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nenhuma sessão de Verificação de utilizadores (KYC) com este UUID está visível para a sua aplicação: o UUID não existe, a sessão foi eliminada ou pertence a uma aplicação diferente. Os IDs de sessão de Verificação de empresas (KYB) também devolvem `404` aqui — o feed de revisões só pode ser acedido para sessões de KYC.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Session not found." } } }, "examples": { "NotFound": { "summary": "UUID de sessão desconhecido, eliminado ou de outra aplicação", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite de pedidos excedido. Inspecione os cabeçalhos de resposta `Retry-After` e `X-RateLimit-*`. Consulte [Limite de pedidos](/pt/integration/rate-limiting)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "# Records an audit-trail note only -- the session's status does NOT change.\ncurl -s -X POST https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"In Review\",\n \"comment\": \"Flagging for manual document re-check.\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.reviews.create(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n new_status=\"In Review\",\n comment=\"Flagging for manual document re-check.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.reviews.create(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", {\n new_status: \"In Review\",\n comment: \"Flagging for manual document re-check.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Reviews.Create(ctx, \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", didit.SessionsReviewsCreateParams{\n\tNewStatus: didit.Some(didit.SessionsReviewsCreateParamsNewStatus(\"In Review\")),\n\tComment: didit.String(\"Flagging for manual document re-check.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsReviewsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().reviews().create(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", SessionsReviewsCreateParams.builder()\n .newStatus(SessionsReviewsCreateParams.NewStatus.of(\"In Review\"))\n .comment(\"Flagging for manual document re-check.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->reviews->create('8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d', [\n 'new_status' => 'In Review',\n 'comment' => 'Flagging for manual document re-check.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.reviews.create(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n new_status: \"In Review\",\n comment: \"Flagging for manual document re-check.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Reviews.CreateAsync(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", new SessionsReviewsCreateParams\n{\n NewStatus = new SessionsReviewsCreateParamsNewStatus(\"In Review\"),\n Comment = \"Flagging for manual document re-check.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/billing/balance/": { "get": { "summary": "Obter saldo de créditos", "description": "Obter o saldo atual de créditos pré-pagos em USD (para toda a organização) e a configuração de recarga automática. Os montantes são strings decimais — processe com uma biblioteca decimal.", "operationId": "get_billing_balance", "x-didit-sdk": { "resource": "billing", "method": "retrieve_balance", "auth": "api_key", "server": true }, "tags": [ "Billing" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/billing/balance/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.billing.retrieve_balance()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.billing.retrieveBalance();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.RetrieveBalance(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.billing().retrieveBalance();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "billing->retrieveBalance();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.billing.retrieve_balance\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Billing.RetrieveBalanceAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Saldo de créditos atual mais a configuração de carregamento automático da organização.", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance", "auto_refill_enabled" ], "properties": { "balance": { "type": "string", "description": "Saldo atual de créditos pré-pagos em USD, como uma cadeia de caracteres decimal de ponto fixo. Diminui à medida que as verificações são faturadas e aumenta quando um carregamento de saldo é liquidado." }, "auto_refill_enabled": { "type": "boolean", "description": "Quando `true`, a Didit cobrará automaticamente o método de pagamento guardado para adicionar créditos assim que o saldo ultrapassar `auto_refill_threshold`. Configurado a partir da Console → Faturação." }, "auto_refill_amount": { "type": "string", "nullable": true, "description": "Montante em USD que será cobrado e adicionado ao saldo em cada recarga automática, pelo valor nominal. Configurável de \\$50 a \\$20,000 em Consola → Faturação. `null` quando a recarga automática está desativada ou não definida." }, "auto_refill_threshold": { "type": "string", "nullable": true, "description": "Limiar de acionamento em USD. O carregamento automático dispara quando o `balance` desce abaixo deste valor. `null` quando o carregamento automático está desativado ou não configurado." } } }, "examples": { "Healthy balance with auto-refill": { "value": { "balance": "1234.5600", "auto_refill_enabled": true, "auto_refill_amount": "500.00", "auto_refill_threshold": "100.00" } }, "Low balance, manual top-up only": { "value": { "balance": "12.0000", "auto_refill_enabled": false, "auto_refill_amount": null, "auto_refill_threshold": null } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode ler dados de faturação para esta organização. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/billing/top-up/": { "post": { "summary": "Carregar saldo de créditos", "description": "Adicione créditos através de uma sessão Stripe Checkout alojada (**\\$50 a \\$20,000** por carregamento de saldo). Os carregamentos de saldo estão disponíveis nos planos Free, Growth e Scale, são adicionados pelo valor nominal sem desconto ou bónus, e duram 12 meses; os contratos anuais Enterprise não podem carregar saldo. Redirecione o cliente para o `checkout_session_url` devolvido.", "operationId": "billing_top_up", "x-didit-sdk": { "resource": "billing", "method": "top_up", "auth": "api_key", "server": true }, "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_in_dollars" ], "properties": { "amount_in_dollars": { "type": "number", "minimum": 50, "maximum": 20000, "description": "Montante a cobrar, em USD. **Deve ser entre 50 e 20 000.** O saldo recebe o mesmo montante, sem desconto nem bónus. O imposto é adicionado automaticamente no processo de pagamento com base na morada de faturação do cliente." }, "success_url": { "type": "string", "format": "uri", "description": "URL para onde o checkout alojado redireciona o cliente após um pagamento bem-sucedido. Atualmente o valor predefinido é `https://console.didit.me`. Indique explicitamente um URL funcional; o anfitrião predefinido não está disponível. Anexe o marcador de posição literal `{CHECKOUT_SESSION_ID}` se pretender que o checkout alojado substitua o ID da sessão." }, "cancel_url": { "type": "string", "format": "uri", "description": "URL para onde o checkout alojado redireciona o cliente quando este cancela ou fecha a janela do Checkout. Atualmente o valor predefinido é `https://console.didit.me`. Indique explicitamente um URL funcional; o anfitrião predefinido não está disponível." } } }, "examples": { "Minimum top-up": { "value": { "amount_in_dollars": 50 } }, "Custom amount with redirects": { "value": { "amount_in_dollars": 500, "success_url": "https://yourapp.com/billing/top-up/success", "cancel_url": "https://yourapp.com/billing/top-up/cancel" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/billing/top-up/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"amount_in_dollars\": 500,\n \"success_url\": \"https://yourapp.com/billing/success\",\n \"cancel_url\": \"https://yourapp.com/billing/cancel\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.billing.top_up(\n amount_in_dollars=50.0,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.billing.topUp({\n amount_in_dollars: 50.0,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.TopUp(ctx, didit.BillingTopUpParams{\n\tAmountInDollars: 50.0,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BillingTopUpParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.billing().topUp(BillingTopUpParams.builder()\n .amountInDollars(50.0)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "billing->topUp([\n 'amount_in_dollars' => 50.0,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.billing.top_up(amount_in_dollars: 50.0)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Billing.TopUpAsync(new BillingTopUpParams\n{\n AmountInDollars = 50.0,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Sessão de checkout alojada criada. Redirecione o utilizador para `checkout_session_url` para concluir o pagamento.", "content": { "application/json": { "schema": { "type": "object", "required": [ "checkout_session_id", "checkout_session_url" ], "properties": { "checkout_session_id": { "type": "string", "description": "Identificador da sessão de checkout alojada (ex.: `cs_test_a1B2c3...`). Útil para reconciliação do lado do servidor." }, "checkout_session_url": { "type": "string", "format": "uri", "description": "URL de página de pagamento alojada de utilização única. Redirecione o cliente para esta página para concluir o pagamento." } } }, "examples": { "Created": { "value": { "checkout_session_id": "cs_test_a1B2c3D4e5F6g7H8i9J0", "checkout_session_url": "https://checkout.example.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0" } } } } } }, "400": { "description": "Payload inválido: o montante está em falta, não é um número, está abaixo do mínimo de \\$50 ou acima do máximo de \\$20,000, ou a organização tem um contrato anual Enterprise. O corpo do erro é uma matriz JSON.", "content": { "application/json": { "examples": { "Missing amount": { "value": [ "amount_in_dollars is required." ] }, "Not a number": { "value": [ "amount_in_dollars must be a number." ] }, "Below minimum": { "value": [ "Amount must be at least $50." ] }, "Above maximum": { "value": [ "Amount must be at most $20,000." ] }, "Annual plan": { "value": [ "You have an annual plan. Contact your account manager to top up." ] } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode criar sessões de carregamento de saldo para esta organização. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/": { "get": { "summary": "Listar destinos de webhooks", "description": "Listar todos os destinos de webhook (array não paginado, do mais antigo para o mais recente). Cada item contém a configuração do destino, as suas métricas de entrega nos últimos 30 dias (`metrics_window_days`) com uma entrada `daily_points` por dia, e o seu estado (`health_status`, `failing_streak`, `failing_since`, `last_success_at`). A lista não tem o objeto `summary` e nunca inclui o segredo de assinatura: cada item mostra apenas `secret_last4`. Obtenha um destino individual (`GET /v3/webhook/destinations/{destination_uuid}/`) para consultar `secret_shared_key`.", "operationId": "list_webhook_destinations", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.list()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.list();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.List(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().list();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->list();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.list.each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.ListAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Lista de destinos do webhook (sem paginação, do mais antigo para o mais recente).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador estável de destino; utilize como `{destination_uuid}` para atualizar/eliminar." }, "label": { "type": "string", "description": "Nome legível apresentado na Console." }, "url": { "type": "string", "format": "uri", "description": "URL de destino que recebe pedidos `POST` com o payload do webhook." }, "enabled": { "type": "boolean", "description": "Quando for `false`, a Didit ignora silenciosamente a entrega para este destino." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versão do esquema do payload enviada para este destino. `v3` é o formato atual/recomendado." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "subscribed_events_count": { "type": "integer", "description": "Comprimento em cache de `subscribed_events`, útil para renderização na IU." }, "deliveries_count": { "type": "integer", "description": "Tentativas de entrega (incluindo novas tentativas) efetuadas para este destino nos últimos 30 dias." }, "failed_deliveries_count": { "type": "integer", "description": "Tentativas de entrega nos últimos 30 dias às quais o destino respondeu com HTTP 400 ou superior, ou não respondeu (tempo limite excedido, ligação recusada ou endereço bloqueado)." }, "average_response_time_ms": { "type": "integer", "nullable": true, "description": "Tempo médio de resposta em milissegundos nos últimos 30 dias, arredondado a um número inteiro. `null` quando não existiram entregas nessa janela." }, "error_rate_percentage": { "type": "integer", "description": "`round(failed_deliveries_count / deliveries_count * 100)` nos últimos 30 dias; `0` quando não existem entregas." }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da tentativa de entrega mais recente (sucesso ou falha). `null` se nunca foi entregue." }, "metrics_window_days": { "type": "integer", "description": "Duração em dias do intervalo abrangido por `deliveries_count`, `failed_deliveries_count`, `average_response_time_ms`, `error_rate_percentage` e `daily_points`. Sempre `30`." }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "Estado da entrega. `failing`: 3 ou mais eventos consecutivos falharam a primeira tentativa de entrega desde que o destino respondeu com sucesso pela última vez (consulte `failing_streak`). `degraded`: não está a falhar, mas uma tentativa de entrega falhou nas últimas 24 horas e nenhuma tentativa posterior entregou esse evento; uma nova tentativa ou reenvio bem-sucedido limpa este estado. `healthy`: nenhum dos anteriores. Independente de `enabled`. Uma tentativa falhada é aquela respondida com HTTP 400 ou superior, ou que não obteve qualquer resposta." }, "failing_streak": { "type": "integer", "description": "Quantos eventos consecutivos falharam a primeira tentativa de entrega desde a última resposta bem-sucedida do destino, nos últimos 30 dias. As novas tentativas não são contabilizadas, e qualquer tentativa bem-sucedida, incluindo uma nova tentativa ou um reenvio, termina a sequência. `0` quando nenhum evento falhou desde o último sucesso." }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando foi feita a primeira tentativa falhada da atual `failing_streak`. `null` quando `failing_streak` é `0`." }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o destino respondeu pela última vez a uma entrega com um estado HTTP inferior a 400, nos últimos 30 dias. `null` se não o tiver feito nesse período." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente da aplicação a que pertence o destino." }, "daily_points": { "type": "array", "description": "Uma entrada por dia UTC dos últimos 30 dias, da mais antiga para a mais recente, incluindo dias sem entregas. Conta todas as tentativas, incluindo novas tentativas.", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "O dia UTC." }, "total_deliveries": { "type": "integer", "description": "Tentativas de entrega efetuadas nesse dia." }, "failed_deliveries": { "type": "integer", "description": "Tentativas efetuadas nesse dia que receberam como resposta HTTP 400 ou superior, ou não obtiveram resposta." } } } }, "secret_last4": { "type": "string", "description": "Últimos quatro carateres do segredo de assinatura atual do destino, para que possa distinguir os segredos. Não são suficientes para verificar uma assinatura." }, "created_by_email": { "type": "string", "nullable": true, "description": "E-mail do membro da Business Console que criou o destino. `null` para um destino criado com uma chave de API." }, "created_by_name": { "type": "string", "nullable": true, "description": "Nome do membro da Business Console que criou o destino. `null` para um destino criado com uma chave de API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "examples": { "Two destinations": { "value": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "subscribed_events": [ "status.updated", "data.updated" ], "subscribed_events_count": 2, "deliveries_count": 12453, "failed_deliveries_count": 14, "average_response_time_ms": 187, "error_rate_percentage": 0, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30, "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "daily_points": [ { "date": "2026-04-18", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-19", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-20", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-21", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-22", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-23", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-24", "total_deliveries": 415, "failed_deliveries": 9 }, { "date": "2026-04-25", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-26", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-27", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-28", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-29", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-30", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-01", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-02", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-03", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-04", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-05", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-06", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-07", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-08", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-09", "total_deliveries": 415, "failed_deliveries": 5 }, { "date": "2026-05-10", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-11", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-12", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-13", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-14", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-15", "total_deliveries": 416, "failed_deliveries": 0 }, { "date": "2026-05-16", "total_deliveries": 416, "failed_deliveries": 0 }, { "date": "2026-05-17", "total_deliveries": 416, "failed_deliveries": 0 } ], "secret_last4": "0xnQ", "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-04-22T14:09:11Z" }, { "uuid": "22222222-3333-4444-5555-666666666666", "label": "Staging mirror", "url": "https://staging.yourapp.com/webhooks/didit", "enabled": false, "webhook_version": "v3", "subscribed_events": [ "status.updated" ], "subscribed_events_count": 1, "deliveries_count": 0, "failed_deliveries_count": 0, "average_response_time_ms": null, "error_rate_percentage": 0, "last_delivery_at": null, "metrics_window_days": 30, "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": null, "environment": "live", "daily_points": [ { "date": "2026-04-18", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-19", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-20", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-21", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-22", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-23", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-24", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-25", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-26", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-27", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-28", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-29", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-30", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-01", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-02", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-03", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-04", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-05", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-06", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-07", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-08", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-09", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-10", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-11", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-12", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-13", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-14", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-15", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-16", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-17", "total_deliveries": 0, "failed_deliveries": 0 } ], "secret_last4": "k9Qe", "created_by_email": "reviewer@example.com", "created_by_name": "Example Reviewer", "created_at": "2026-03-12T10:15:02Z", "updated_at": "2026-03-12T10:15:02Z" } ] } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar destino do webhook", "description": "Crie um destino de webhook. A resposta inclui o segredo de assinatura HMAC `secret_shared_key` gerado automaticamente (também consultável posteriormente através de `GET /v3/webhook/destinations/{destination_uuid}/`). Envie sempre `subscribed_events` com pelo menos um evento (sem carateres universais): uma lista vazia explícita é rejeitada com 400, e omitir o campo cria um destino sem subscrições, que nunca recebe um webhook. O par `(application, url)` deve ser único entre os destinos da aplicação.", "operationId": "create_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"label\": \"Production session webhooks\",\n \"url\": \"https://yourapp.com/webhooks/didit\",\n \"webhook_version\": \"v3\",\n \"subscribed_events\": [\"status.updated\", \"data.updated\"]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.create(\n label=\"Production session webhooks\",\n url=\"https://yourapp.com/webhooks/didit\",\n webhook_version=\"v3\",\n subscribed_events=[\"status.updated\", \"data.updated\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.create({\n label: \"Production session webhooks\",\n url: \"https://yourapp.com/webhooks/didit\",\n webhook_version: \"v3\",\n subscribed_events: [\"status.updated\", \"data.updated\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.WebhookEvent;\nimport me.didit.types.WebhooksDestinationsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder()\n .label(\"Production session webhooks\")\n .url(\"https://yourapp.com/webhooks/didit\")\n .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of(\"v3\"))\n .subscribedEvents(List.of(WebhookEvent.of(\"status.updated\"), WebhookEvent.of(\"data.updated\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->create([\n 'label' => 'Production session webhooks',\n 'url' => 'https://yourapp.com/webhooks/didit',\n 'webhook_version' => 'v3',\n 'subscribed_events' => ['status.updated', 'data.updated'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.create(\n label: \"Production session webhooks\",\n url: \"https://yourapp.com/webhooks/didit\",\n webhook_version: \"v3\",\n subscribed_events: [\"status.updated\", \"data.updated\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams\n{\n Label = \"Production session webhooks\",\n Url = \"https://yourapp.com/webhooks/didit\",\n WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion(\"v3\"),\n SubscribedEvents = new WebhookEvent[] { \"status.updated\", \"data.updated\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "url" ], "properties": { "label": { "type": "string", "maxLength": 255, "description": "Nome legível apresentado em Console → Webhooks. Ajuda a distinguir destinos quando tem vários (por exemplo, \"Prod\", \"Staging mirror\")." }, "url": { "type": "string", "format": "uri", "description": "URL HTTPS que receberá pedidos `POST`. Deve ser único entre os destinos da aplicação. Utilize um endpoint estável e protegido: a Didit tenta novamente entregas que falharam num esquema de espera progressiva.", "maxLength": 2000 }, "enabled": { "type": "boolean", "default": true, "description": "Quando for `false`, o destino é guardado, mas a Didit não enviará quaisquer webhooks para o mesmo. Útil para configurações de teste que queira manter em pausa." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versão do esquema do payload que a Didit irá enviar. `v3` é o formato atual/recomendado; as versões mais antigas são mantidas para retrocompatibilidade com integrações legadas." }, "subscribed_events": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscribedEvents" } ], "description": "Eventos a entregar. Efetivamente obrigatório: um `[]` explícito é rejeitado com 400, e omitir o campo cria um destino sem subscrições que não recebe nada." } } }, "examples": { "session_updates": { "summary": "Atualizações de dados e do estado da sessão", "value": { "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": [ "status.updated", "data.updated" ] } }, "transaction_updates": { "summary": "Atualizações de monitorização de transações", "value": { "label": "Transaction monitoring webhooks", "url": "https://yourapp.com/webhooks/didit-transactions", "webhook_version": "v3", "subscribed_events": [ "transaction.created", "transaction.status.updated" ] } }, "entity_updates": { "summary": "Atualizações de entidades de Utilizador e Empresa", "value": { "label": "Entity lifecycle webhooks", "url": "https://yourapp.com/webhooks/didit-entities", "webhook_version": "v3", "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } } } } } }, "responses": { "201": { "description": "Destino criado. `secret_shared_key` é o segredo de assinatura HMAC — guarde-o agora.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador estável de destino. Utilize como `{destination_uuid}` em chamadas subsequentes." }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string", "description": "Segredo de assinatura HMAC gerado automaticamente e associado a este destino (token de 43 carateres seguro para URL). Utilize-o para verificar os cabeçalhos de assinatura nos webhooks recebidos. Devolvido sempre na totalidade a quem efetua chamadas com chave de API; os utilizadores da consola precisam da permissão `read:webhooks`, caso contrário verão uma string vazia." }, "secret_last4": { "type": "string", "description": "Últimos quatro carateres do segredo de assinatura atual do destino, para que possa distinguir os segredos. Não são suficientes para verificar uma assinatura." }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Definido durante 24 horas após o segredo de assinatura do destino ser alterado na Business Console. Até esse momento, cada entrega para o destino também inclui `X-Signature-Previous`, `X-Signature-V2-Previous` e `X-Signature-Simple-Previous`, gerados com o segredo substituído (consulte [Verificação da assinatura](/pt/integration/webhooks#verificação-da-assinatura)). `null` quando não ocorreu qualquer rotação nas últimas 24 horas." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "E-mail do membro da Business Console que criou o destino. `null` para um destino criado com uma chave de API." }, "created_by_name": { "type": "string", "nullable": true, "description": "Nome do membro da Business Console que criou o destino. `null` para um destino criado com uma chave de API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "Estado da entrega. `failing`: 3 ou mais eventos consecutivos falharam a primeira tentativa de entrega desde que o destino respondeu com sucesso pela última vez (consulte `failing_streak`). `degraded`: não está a falhar, mas uma tentativa de entrega falhou nas últimas 24 horas e nenhuma tentativa posterior entregou esse evento; uma nova tentativa ou reenvio bem-sucedido limpa este estado. `healthy`: nenhum dos anteriores. Independente de `enabled`. Uma tentativa falhada é aquela respondida com HTTP 400 ou superior, ou que não obteve qualquer resposta." }, "failing_streak": { "type": "integer", "description": "Quantos eventos consecutivos falharam a primeira tentativa de entrega desde a última resposta bem-sucedida do destino, nos últimos 30 dias. As novas tentativas não são contabilizadas, e qualquer tentativa bem-sucedida, incluindo uma nova tentativa ou um reenvio, termina a sequência. `0` quando nenhum evento falhou desde o último sucesso." }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando foi feita a primeira tentativa falhada da atual `failing_streak`. `null` quando `failing_streak` é `0`." }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o destino respondeu pela última vez a uma entrega com um estado HTTP inferior a 400, nos últimos 30 dias. `null` se não o tiver feito nesse período." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente da aplicação a que pertence o destino." }, "summary": { "type": "object", "description": "Métricas de entrega para os últimos `metrics_window_days` (30) dias. `last_delivery_at` é a tentativa mais recente, independentemente de quando foi efetuada.", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "Duração em dias do intervalo abrangido pelas outras métricas de resumo. Sempre `30`." } } } } }, "examples": { "Created": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-05-17T10:00:00Z", "updated_at": "2026-05-17T10:00:00Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": null, "environment": "live", "summary": { "total_deliveries": 0, "failed_deliveries": 0, "error_rate_percentage": 0, "min_response_time_ms": null, "avg_response_time_ms": null, "max_response_time_ms": null, "last_delivery_at": null, "metrics_window_days": 30 } } } } } } }, "400": { "description": "A validação falhou — geralmente um URL duplicado, `subscribed_events` em falta/inválido ou nome de evento desconhecido.", "content": { "application/json": { "examples": { "Duplicate URL": { "value": { "url": [ "This webhook destination already exists for the application." ] } }, "Empty events list": { "value": { "subscribed_events": [ "At least one subscribed event is required." ] } }, "Unknown event": { "value": { "subscribed_events": [ "Unsupported webhook events: foo.bar" ] } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/": { "get": { "summary": "Obter destino do webhook", "description": "Obtenha um destino do webhook com o seu segredo de assinatura `secret_shared_key`, o seu estado (`health_status`, `failing_streak`, `failing_since`, `last_success_at`) e um resumo (`summary`) de entregas dos últimos 30 dias. Quem chama via chave de API recebe sempre o segredo na íntegra; os utilizadores da Consola sem `read:webhooks` veem uma cadeia de carateres vazia.", "operationId": "get_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID do destino (o `uuid` retornado por criar / listar).", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhes do destino do webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string", "description": "Segredo de assinatura HMAC (token seguro para URL de 43 carateres). Devolvido sempre na totalidade para chamadas com chave de API; os utilizadores da Consola necessitam de `read:webhooks`, caso contrário recebem uma string vazia." }, "secret_last4": { "type": "string", "description": "Últimos quatro carateres do segredo de assinatura atual do destino, para que possa distinguir os segredos. Não são suficientes para verificar uma assinatura." }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Definido durante 24 horas após o segredo de assinatura do destino ser alterado na Business Console. Até esse momento, cada entrega para o destino também inclui `X-Signature-Previous`, `X-Signature-V2-Previous` e `X-Signature-Simple-Previous`, gerados com o segredo substituído (consulte [Verificação da assinatura](/pt/integration/webhooks#verificação-da-assinatura)). `null` quando não ocorreu qualquer rotação nas últimas 24 horas." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "E-mail do membro da Business Console que criou o destino. `null` para um destino criado com uma chave de API." }, "created_by_name": { "type": "string", "nullable": true, "description": "Nome do membro da Business Console que criou o destino. `null` para um destino criado com uma chave de API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "Estado da entrega. `failing`: 3 ou mais eventos consecutivos falharam a primeira tentativa de entrega desde que o destino respondeu com sucesso pela última vez (consulte `failing_streak`). `degraded`: não está a falhar, mas uma tentativa de entrega falhou nas últimas 24 horas e nenhuma tentativa posterior entregou esse evento; uma nova tentativa ou reenvio bem-sucedido limpa este estado. `healthy`: nenhum dos anteriores. Independente de `enabled`. Uma tentativa falhada é aquela respondida com HTTP 400 ou superior, ou que não obteve qualquer resposta." }, "failing_streak": { "type": "integer", "description": "Quantos eventos consecutivos falharam a primeira tentativa de entrega desde a última resposta bem-sucedida do destino, nos últimos 30 dias. As novas tentativas não são contabilizadas, e qualquer tentativa bem-sucedida, incluindo uma nova tentativa ou um reenvio, termina a sequência. `0` quando nenhum evento falhou desde o último sucesso." }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando foi feita a primeira tentativa falhada da atual `failing_streak`. `null` quando `failing_streak` é `0`." }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o destino respondeu pela última vez a uma entrega com um estado HTTP inferior a 400, nos últimos 30 dias. `null` se não o tiver feito nesse período." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente da aplicação a que pertence o destino." }, "summary": { "type": "object", "description": "Métricas de entrega para os últimos `metrics_window_days` (30) dias. `last_delivery_at` é a tentativa mais recente, independentemente de quando foi efetuada.", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "Duração em dias do intervalo abrangido pelas outras métricas de resumo. Sempre `30`." } } } } }, "examples": { "Healthy destination": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-04-22T14:09:11Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "summary": { "total_deliveries": 12453, "failed_deliveries": 14, "error_rate_percentage": 0, "min_response_time_ms": 41, "avg_response_time_ms": 187, "max_response_time_ms": 2103, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30 } } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum destino com este UUID, pertence a uma aplicação diferente ou foi eliminado.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar destino do webhook", "description": "Atualizar um destino do webhook. **`subscribed_events` é SUBSTITUÍDO na totalidade, não intercalado**: obtenha primeiro, adicione, reenvie. O segredo não é renovado. Um `uuid` no corpo é ignorado: o caminho identifica o destino.", "operationId": "update_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID do destino a atualizar.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Novo nome legível por humanos." }, "url": { "type": "string", "format": "uri", "description": "Novo URL de destino. Deve ser único dentro da aplicação." }, "enabled": { "type": "boolean", "description": "Defina como `false` para pausar as entregas para este destino sem o eliminar." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Nova versão do esquema de payload para entregas futuras." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" } } }, "examples": { "Pause destination": { "value": { "enabled": false } }, "Add transaction events": { "value": { "subscribed_events": [ "status.updated", "data.updated", "transaction.created", "transaction.status.updated" ] } }, "Move target URL": { "value": { "label": "Production session webhooks v2", "url": "https://api.yourapp.com/webhooks/didit/v2" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"subscribed_events\": [\n \"status.updated\",\n \"data.updated\",\n \"transaction.created\"\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.update(\n \"11111111-2222-3333-4444-555555555555\",\n enabled=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.update(\"11111111-2222-3333-4444-555555555555\", {\n enabled: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsUpdateParams{\n\tEnabled: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WebhooksDestinationsUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().update(\"11111111-2222-3333-4444-555555555555\", WebhooksDestinationsUpdateParams.builder()\n .enabled(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->update('11111111-2222-3333-4444-555555555555', [\n 'enabled' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.update(\n \"11111111-2222-3333-4444-555555555555\",\n enabled: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new WebhooksDestinationsUpdateParams\n{\n Enabled = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Destino do webhook atualizado. O corpo tem a mesma estrutura de `GET /v3/webhook/destinations/{destination_uuid}/`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string" }, "secret_last4": { "type": "string", "description": "Últimos quatro carateres do segredo de assinatura atual do destino, para que possa distinguir os segredos. Não são suficientes para verificar uma assinatura." }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Definido durante 24 horas após o segredo de assinatura do destino ser alterado na Business Console. Até esse momento, cada entrega para o destino também inclui `X-Signature-Previous`, `X-Signature-V2-Previous` e `X-Signature-Simple-Previous`, gerados com o segredo substituído (consulte [Verificação da assinatura](/pt/integration/webhooks#verificação-da-assinatura)). `null` quando não ocorreu qualquer rotação nas últimas 24 horas." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "E-mail do membro da Business Console que criou o destino. `null` para um destino criado com uma chave de API." }, "created_by_name": { "type": "string", "nullable": true, "description": "Nome do membro da Business Console que criou o destino. `null` para um destino criado com uma chave de API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "Estado da entrega. `failing`: 3 ou mais eventos consecutivos falharam a primeira tentativa de entrega desde que o destino respondeu com sucesso pela última vez (consulte `failing_streak`). `degraded`: não está a falhar, mas uma tentativa de entrega falhou nas últimas 24 horas e nenhuma tentativa posterior entregou esse evento; uma nova tentativa ou reenvio bem-sucedido limpa este estado. `healthy`: nenhum dos anteriores. Independente de `enabled`. Uma tentativa falhada é aquela respondida com HTTP 400 ou superior, ou que não obteve qualquer resposta." }, "failing_streak": { "type": "integer", "description": "Quantos eventos consecutivos falharam a primeira tentativa de entrega desde a última resposta bem-sucedida do destino, nos últimos 30 dias. As novas tentativas não são contabilizadas, e qualquer tentativa bem-sucedida, incluindo uma nova tentativa ou um reenvio, termina a sequência. `0` quando nenhum evento falhou desde o último sucesso." }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando foi feita a primeira tentativa falhada da atual `failing_streak`. `null` quando `failing_streak` é `0`." }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o destino respondeu pela última vez a uma entrega com um estado HTTP inferior a 400, nos últimos 30 dias. `null` se não o tiver feito nesse período." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente da aplicação a que pertence o destino." }, "summary": { "type": "object", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "Duração em dias do intervalo abrangido pelas outras métricas de resumo. Sempre `30`." } }, "description": "Métricas de entrega para os últimos `metrics_window_days` (30) dias. `last_delivery_at` é a tentativa mais recente, independentemente de quando foi efetuada." } } }, "examples": { "Paused": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": false, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-05-17T11:02:55Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "summary": { "total_deliveries": 12453, "failed_deliveries": 14, "error_rate_percentage": 0, "min_response_time_ms": 41, "avg_response_time_ms": 187, "max_response_time_ms": 2103, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30 } } } } } } }, "400": { "description": "Falha na validação (URL duplicado, lista de eventos vazia/com eventos desconhecidos, corpo malformado).", "content": { "application/json": { "examples": { "Duplicate URL": { "value": { "url": [ "This webhook destination already exists for the application." ] } }, "Empty events": { "value": { "subscribed_events": [ "At least one subscribed event is required." ] } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "O destino com este UUID não existe (ou foi eliminado, ou pertence a outra aplicação).", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Eliminar destino do webhook", "description": "Elimine permanentemente um destino de webhook, o seu segredo de assinatura e todo o seu registo de entregas. Esta ação não pode ser anulada. Nenhum novo webhook é enviado para o URL do destino; outros destinos subscritos aos mesmos eventos continuam a recebê-los. Posteriormente, o destino deixa de aparecer em `GET /v3/webhook/destinations/`, e todas as rotas sob `/v3/webhook/destinations/{destination_uuid}/`, incluindo as suas entregas, o detalhe de uma entrega e o seu reenvio, respondem 404. O `webhook_url` legado da aplicação é definido para o URL do destino ativado mais antigo que reste, ou limpo caso não reste nenhum destino ativado. Chamar DELETE novamente devolve 404.", "operationId": "delete_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID do destino a eliminar.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.webhooks.destinations.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.webhooks.destinations.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Webhooks.Destinations.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.webhooks().destinations().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Webhooks.Destinations.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "Destino, segredo de assinatura e registo de entregas eliminados permanentemente. Sem corpo de resposta." }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum destino com este UUID para a aplicação (já eliminado ou nunca existiu).", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/wallet-screening/": { "post": { "summary": "Fazer a triagem de um endereço", "description": "Executar uma triagem AML a pedido para uma única carteira/endereço cripto sem criar uma transação. Resolve o fornecedor de análise de blockchain configurado para a sua aplicação, efetua a triagem do endereço de forma síncrona e devolve o resultado de risco normalizado. O LIGHTNING está disponível apenas com uma ligação BYOK da Elliptic ou da Chainalysis adicionada através do Marketplace. Nada é escrito na tabela de transações. É faturada uma utilização de monitorização AML por cada triagem bem-sucedida (as aplicações em sandbox não são faturadas).", "operationId": "screenWallet", "x-didit-sdk": { "resource": "wallet_screening", "method": "screen", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet_address" ], "properties": { "wallet_address": { "type": "string", "description": "O endereço de criptoativos ou identificador de rede a analisar. Deve corresponder à rede selecionada (por exemplo, um endereço de 40 carateres hexadecimais com prefixo `0x` para redes EVM). Pseudónimo: `address`.", "example": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a" }, "blockchain": { "type": "string", "description": "Identificador de rede opcional. Quando omitido, a rede é lida a partir do formato do endereço: endereços `bc1`, `1` e `3` são Bitcoin (BTC), endereços `T` são Tron (TRX) e chaves públicas base58 são Solana (SOL). Um endereço `0x` é válido em todas as redes EVM, pelo que omitir `blockchain` para o mesmo devolve 422 com as redes candidatas em `candidate_chains`. A triagem gerida suporta BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE (Base), OP (Optimism), ARB (Arbitrum One), AVAX (Avalanche C-Chain), ADA (Cardano), XLM (Stellar) e HBAR (Hedera). USDT e USDC são aliases legados de Ethereum, não pesquisas em várias redes. A cobertura de fornecedores associados varia. O LIGHTNING requer um fornecedor associado suportado. CELO (Celo), MODE (Mode) e PLUME (Plume) são analisados através de uma conta TRM Labs associada; a triagem gerida devolve 400 para estes. Alias: `currency`.", "enum": [ "BTC", "LIGHTNING", "ETH", "LTC", "XRP", "BCH", "DOGE", "TRX", "SOL", "MATIC", "BNB", "USDT", "USDC", "BASE", "OP", "ARB", "AVAX", "ADA", "XLM", "HBAR", "CELO", "MODE", "PLUME" ], "example": "ETH" }, "direction": { "type": "string", "description": "Opcional. Se o endereço está a ser submetido a triagem como contraparte de entrada (depósito) ou de saída (levantamento). Aceita `inbound`, `outbound`, `deposit` ou `withdrawal`. O valor predefinido é uma triagem neutra pré-transferência quando omitido. Isto é transmitido ao fornecedor apenas como contexto; não altera o `risk_score`, `severity` ou os detalhes de `source_of_funds`/`destination_of_funds` devolvidos, que são sempre ambos devolvidos independentemente da `direction`. Alterar ou omitir `direction`, portanto, não requer uma nova triagem do endereço.", "enum": [ "inbound", "outbound", "deposit", "withdrawal" ] } } }, "example": { "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "blockchain": "ETH" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/wallet-screening/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"wallet_address\": \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n \"blockchain\": \"ETH\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.wallet_screening.screen(\n wallet_address=\"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain=\"ETH\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.walletScreening.screen({\n wallet_address: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain: \"ETH\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.WalletScreening.Screen(ctx, didit.WalletScreeningScreenParams{\n\tWalletAddress: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n\tBlockchain: didit.Some(didit.WalletScreeningScreenParamsBlockchain(\"ETH\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletScreeningScreenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.walletScreening().screen(WalletScreeningScreenParams.builder()\n .walletAddress(\"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\")\n .blockchain(WalletScreeningScreenParams.Blockchain.of(\"ETH\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "walletScreening->screen([\n 'wallet_address' => '0x94f1b9b64e2932f6a2db338f616844400cd58e8a',\n 'blockchain' => 'ETH',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.wallet_screening.screen(\n wallet_address: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain: \"ETH\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.WalletScreening.ScreenAsync(new WalletScreeningScreenParams\n{\n WalletAddress = \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n Blockchain = new WalletScreeningScreenParamsBlockchain(\"ETH\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O resultado normalizado da triagem de carteiras.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletScreeningResult" }, "example": { "provider": "merklescience", "screening_type": "WALLET_SCREENING", "risk_score": 95, "severity": "CRITICAL", "status": "SCREENED", "summary": "Merkle Science risk: Critical (5/5). SANCTIONS HIT. Dominant risk: sanctioned. Driven by: the address is attributed to Sanctions / OFAC (Example Sanctions)", "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "transaction_hash": null, "blockchain": "ETH", "block_timestamp": null, "total_value_usd": null, "fee_usd": null, "sender_rows": [], "receiver_rows": [], "transaction_flows": [], "transaction_flows_status": null, "transaction_flows_error": null, "source_of_funds": [ { "category": "sanctioned", "percentage": 100.0, "amount_usd": 9813695.0, "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "hops": null, "description": "Sanctions / OFAC", "is_direct": true, "exposure_direction": "incoming", "exposure_type": "direct", "provider_entity_id": "118885", "provider_entity_type_id": "30", "provider_entity_subtype_id": "125", "country": "", "raw_amount": null, "raw_currency": null } ], "destination_of_funds": [ { "category": "defi", "percentage": 84.824453, "amount_usd": 7783414.38, "entity_name": "Example DeFi 7", "entity_type": "DeFi", "entity_subtype": "Bridges", "hops": null, "description": "DeFi / Bridges", "is_direct": false, "exposure_direction": "outgoing", "exposure_type": "indirect", "provider_entity_id": "118459", "provider_entity_type_id": "33", "provider_entity_subtype_id": "143", "country": "", "raw_amount": null, "raw_currency": null }, { "category": "defi", "percentage": 15.175547, "amount_usd": 1392494.37, "entity_name": "Example DeFi 2", "entity_type": "DeFi", "entity_subtype": "Yield Aggregator", "hops": null, "description": "DeFi / Yield Aggregator", "is_direct": false, "exposure_direction": "outgoing", "exposure_type": "indirect", "provider_entity_id": "90192", "provider_entity_type_id": "33", "provider_entity_subtype_id": "142", "country": "", "raw_amount": null, "raw_currency": null } ], "counterparty_connections": [ { "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "risk_level": "critical", "categories": [ "sanctioned" ], "received_usd": null, "sent_usd": null, "received_hops": null, "sent_hops": null, "percentage": 0.0, "is_direct": true, "country": null, "provider_entity_id": null }, { "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "risk_level": "critical", "categories": [ "sanctioned" ], "received_usd": null, "sent_usd": null, "received_hops": null, "sent_hops": null, "percentage": 0.0, "is_direct": true, "country": null, "provider_entity_id": null } ], "network_nodes": [], "network_edges": [], "sanctions_hit": true, "pep_counterparty": null, "dominant_risk_category": "sanctioned", "risk_factors": [ { "source": "attribution", "category": "sanctioned", "label": "Sanctions / OFAC", "entity_name": "Example Sanctions", "direction": "attribution", "exposure_type": "attribution", "amount_usd": null, "percentage": 0.0, "is_high_risk": true, "description": "the address is attributed to Sanctions / OFAC (Example Sanctions)" }, { "source": "exposure", "category": "sanctioned", "label": "Sanctions / OFAC", "entity_name": "Example Sanctions", "direction": "incoming", "exposure_type": "direct", "amount_usd": 9813695.0, "percentage": 51.679304, "is_high_risk": true, "description": "51.6793% direct incoming exposure to Sanctions / OFAC (Example Sanctions)" }, { "source": "exposure", "category": "defi", "label": "DeFi / Bridges", "entity_name": "Example DeFi 7", "direction": "outgoing", "exposure_type": "indirect", "amount_usd": 7783414.38, "percentage": 40.987766, "is_high_risk": false, "description": "40.9878% indirect outgoing exposure to DeFi / Bridges (Example DeFi 7)" }, { "source": "exposure", "category": "defi", "label": "DeFi / Yield Aggregator", "entity_name": "Example DeFi 2", "direction": "outgoing", "exposure_type": "indirect", "amount_usd": 1392494.37, "percentage": 7.33293, "is_high_risk": false, "description": "7.33293% indirect outgoing exposure to DeFi / Yield Aggregator (Example DeFi 2)" } ], "raw_response": { "...": "provider-specific details" }, "report_signature": "" } } } }, "400": { "description": "Erro de validação — endereço malformado, `wallet_address` em falta, `blockchain` não suportada, `blockchain` omitida para um endereço cujo formato não indica nenhuma rede, ou LIGHTNING sem uma ligação de Marketplace BYOK da Elliptic ou Chainalysis." }, "401": { "description": "`x-api-key` em falta ou inválido." }, "409": { "description": "Nenhum fornecedor de AML está configurado para a aplicação, ou o fornecedor configurado ainda não suporta a triagem de carteiras. Configure a monitorização de transações primeiro." }, "422": { "description": "`blockchain` omitido para um endereço `0x`, cujo formato é partilhado por todas as redes EVM. Nada é analisado nem faturado; reenvie com `blockchain` definido para uma das `candidate_chains`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchain": { "type": "array", "items": { "type": "string" }, "example": [ "A 0x address is valid on every EVM chain. Send blockchain as one of: ETH, BNB, MATIC, BASE, ARB, OP, CELO, MODE, PLUME." ] }, "candidate_chains": { "type": "array", "items": { "type": "string" }, "example": [ "ETH", "BNB", "MATIC", "BASE", "ARB", "OP", "CELO", "MODE", "PLUME" ] } } } } } }, "502": { "description": "O fornecedor de AML não conseguiu concluir a triagem. Tente novamente mais tarde." } } } }, "/v3/wallet-screening/pdf/": { "post": { "summary": "Renderizar o resultado de uma triagem de carteiras em PDF", "description": "Complemento sem estado para `POST /v3/wallet-screening/`: envie novamente o corpo JSON exato devolvido por esse endpoint — incluindo a `report_signature` adicionada — e receba um PDF com a marca Didit do mesmo resultado. Nenhum fornecedor é chamado e nada é faturado ou persistido; isto apenas volta a compor um resultado que a Didit já produziu. A assinatura vincula o PDF a um resultado não modificado: editar `risk_score`, `severity`, `sanctions_hit` ou qualquer outro campo assinado antes do reenvio falha com `400`.", "operationId": "screenWalletPdf", "x-didit-sdk": { "resource": "wallet_screening", "method": "screen_pdf", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "description": "O objeto JSON não modificado devolvido por `POST /v3/wallet-screening/`, incluindo `report_signature`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WalletScreeningResult" } ], "required": [ "report_signature" ], "description": "O mesmo formato que a resposta de `POST /v3/wallet-screening/` — transmita esse corpo de resposta textualmente, incluindo `report_signature`." } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "# $RESULT is the saved JSON body from POST /v3/wallet-screening/\ncurl -X POST 'https://verification.didit.me/v3/wallet-screening/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d \"$RESULT\" \\\n -o wallet_screening_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.wallet_screening.screen_pdf(\n provider=\"your-provider\",\n screening_type=\"WALLET_SCREENING\",\n risk_score=1,\n severity=\"UNKNOWN\",\n status=\"SCREENED\",\n summary=\"your-summary\",\n wallet_address=\"your-wallet-address\",\n blockchain=\"your-blockchain\",\n source_of_funds=[{}],\n destination_of_funds=[{}],\n counterparty_connections=[{}],\n sanctions_hit=True,\n dominant_risk_category=\"your-dominant-risk-category\",\n report_signature=\"your-report-signature\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.walletScreening.screenPdf({\n provider: \"your-provider\",\n screening_type: \"WALLET_SCREENING\",\n risk_score: 1,\n severity: \"UNKNOWN\",\n status: \"SCREENED\",\n summary: \"your-summary\",\n wallet_address: \"your-wallet-address\",\n blockchain: \"your-blockchain\",\n source_of_funds: [{}],\n destination_of_funds: [{}],\n counterparty_connections: [{}],\n sanctions_hit: true,\n dominant_risk_category: \"your-dominant-risk-category\",\n report_signature: \"your-report-signature\",\n});\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.WalletScreening.ScreenPDF(ctx, didit.WalletScreeningResultParam{\n\tProvider: \"your-provider\",\n\tScreeningType: \"WALLET_SCREENING\",\n\tRiskScore: 1,\n\tSeverity: \"UNKNOWN\",\n\tStatus: \"SCREENED\",\n\tSummary: \"your-summary\",\n\tWalletAddress: \"your-wallet-address\",\n\tBlockchain: \"your-blockchain\",\n\tSourceOfFunds: []didit.WalletScreeningResultParamSourceOfFunds{{}},\n\tDestinationOfFunds: []didit.WalletScreeningResultParamDestinationOfFunds{{}},\n\tCounterpartyConnections: []didit.WalletScreeningResultParamCounterpartyConnections{{}},\n\tSanctionsHit: true,\n\tDominantRiskCategory: didit.String(\"your-dominant-risk-category\"),\n\tReportSignature: \"your-report-signature\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.WalletScreeningResult;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.walletScreening().screenPdf(WalletScreeningResult.builder()\n .provider(\"your-provider\")\n .screeningType(WalletScreeningResult.ScreeningType.of(\"WALLET_SCREENING\"))\n .riskScore(1L)\n .severity(WalletScreeningResult.Severity.of(\"UNKNOWN\"))\n .status(WalletScreeningResult.Status.of(\"SCREENED\"))\n .summary(\"your-summary\")\n .walletAddress(\"your-wallet-address\")\n .blockchain(\"your-blockchain\")\n .sourceOfFunds(List.of(WalletScreeningResult.SourceOfFunds.builder()\n .build()))\n .destinationOfFunds(List.of(WalletScreeningResult.DestinationOfFunds.builder()\n .build()))\n .counterpartyConnections(List.of(WalletScreeningResult.CounterpartyConnections.builder()\n .build()))\n .sanctionsHit(true)\n .dominantRiskCategory(\"your-dominant-risk-category\")\n .reportSignature(\"your-report-signature\")\n .build())\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "walletScreening->screenPdf([\n 'provider' => 'your-provider',\n 'screening_type' => 'WALLET_SCREENING',\n 'risk_score' => 1,\n 'severity' => 'UNKNOWN',\n 'status' => 'SCREENED',\n 'summary' => 'your-summary',\n 'wallet_address' => 'your-wallet-address',\n 'blockchain' => 'your-blockchain',\n 'source_of_funds' => [[]],\n 'destination_of_funds' => [[]],\n 'counterparty_connections' => [[]],\n 'sanctions_hit' => true,\n 'dominant_risk_category' => 'your-dominant-risk-category',\n 'report_signature' => 'your-report-signature',\n]);\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.wallet_screening.screen_pdf(\n provider: \"your-provider\",\n screening_type: \"WALLET_SCREENING\",\n risk_score: 1,\n severity: \"UNKNOWN\",\n status: \"SCREENED\",\n summary: \"your-summary\",\n wallet_address: \"your-wallet-address\",\n blockchain: \"your-blockchain\",\n source_of_funds: [{}],\n destination_of_funds: [{}],\n counterparty_connections: [{}],\n sanctions_hit: true,\n dominant_risk_category: \"your-dominant-risk-category\",\n report_signature: \"your-report-signature\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.WalletScreening.ScreenPdfAsync(new WalletScreeningResult\n{\n Provider = \"your-provider\",\n ScreeningType = \"WALLET_SCREENING\",\n RiskScore = 1,\n Severity = \"UNKNOWN\",\n Status = \"SCREENED\",\n Summary = \"your-summary\",\n WalletAddress = \"your-wallet-address\",\n Blockchain = \"your-blockchain\",\n SourceOfFunds = new WalletScreeningResultSourceOfFunds[] { new() },\n DestinationOfFunds = new WalletScreeningResultDestinationOfFunds[] { new() },\n CounterpartyConnections = new WalletScreeningResultCounterpartyConnections[] { new() },\n SanctionsHit = true,\n DominantRiskCategory = \"your-dominant-risk-category\",\n ReportSignature = \"your-report-signature\",\n});\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "O documento PDF renderizado, devolvido diretamente como binário `application/pdf` — não há invólucro JSON.", "headers": { "Content-Disposition": { "description": "`attachment; filename=wallet_screening_{address}.pdf`, derivado de `wallet_address` (ou `transaction_hash`) no resultado republicado.", "schema": { "type": "string", "example": "attachment; filename=wallet_screening_0x28c6c06298d514db0899.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "O corpo não é um objeto JSON correspondente à estrutura de resultados de triagem de carteiras, ou `report_signature` está em falta ou não corresponde aos campos reenviados (editados ou truncados antes do reenvio).", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Not an object": { "value": { "non_field_errors": [ "Expected a JSON object matching a wallet-screening result." ] } }, "Missing or invalid signature": { "value": { "report_signature": [ "This wallet-screening result is missing or fails its report signature - repost the exact JSON returned by the wallet-screening endpoint, unmodified." ] } } } } } }, "401": { "description": "`x-api-key` em falta ou inválido." } } } }, "/v3/transactions/": { "get": { "summary": "Listar transações", "description": "Lista paginada de transações monitorizadas, as mais recentes primeiro (`txn_date` desc). `count` está limitado a 100; utilize `total_transactions` para obter o número real de linhas. Este endpoint não suporta parâmetros de filtragem ou de pesquisa.", "operationId": "listTransactions", "x-didit-sdk": { "resource": "transactions", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Tamanho da página. A predefinição é 50 quando omitido. Não existe um limite máximo imposto, mas mantenha as páginas pequenas para reduzir a latência." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Offset de base zero do primeiro registo a devolver. Prefira seguir o URL `next` da página anterior." }, { "name": "travel_rule_status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Devolve apenas as transações cuja transferência da Travel Rule esteja neste estado exato (por exemplo, `ON_HOLD` ou `AWAITING_COUNTERPARTY`). O `count` segue este filtro; o `total_transactions` continua a contabilizar todas as transações na aplicação." }, { "name": "assignee", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Separados por vírgulas; uma transação corresponde quando cumpre qualquer valor. `unassigned` é o que ninguém atribuiu ainda, `rules` é o que as regras decidiram por si próprias sem um revisor, e um e-mail de membro corresponde ao revisor atribuído a ela. `me` é o revisor com sessão iniciada na Consola, pelo que uma chave de API que envie `me` recebe `400`." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.ListAutoPaging(ctx, didit.TransactionsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Lista paginada de resumos de transações, os mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Contagem limitada de transações correspondentes (exata até 100, limitada a partir daí). Utilize `total_transactions` para obter a contagem real ao paginar." }, "next": { "type": "string", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "total_transactions": { "type": "integer", "description": "Contagem total exata de transações (não eliminadas) para a aplicação. Presente em respostas paginadas." }, "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador Didit estável da transação. Utilize como `{transaction_id}` em chamadas de detalhes/notas/relacionadas." }, "transaction_number": { "type": "integer", "description": "Número sequencial da transação no âmbito da aplicação apresentado na Consola (ex.: `4123`)." }, "txn_id": { "type": "string", "description": "Identificador fornecido pelo cliente a partir da chamada de criação (máx. 128 carateres). Único por aplicação." }, "transaction_type": { "type": "string", "description": "Categoria de nível superior tal como armazenada: `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`, `gamblingLimitChange`, `gamblingBonusChange`, `auditTrailEvent`. Tenha em atenção que os valores com várias palavras são devolvidos em camelCase, mesmo quando enviados em snake_case." }, "action_type": { "type": "string", "description": "Subtipo dentro da categoria (p. ex. `deposit`, `withdrawal`, `transfer`)." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Veredito atual de monitorização." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direção em relação ao sujeito. Armazenada em maiúsculas independentemente da capitalização submetida." }, "amount": { "type": "string", "description": "Montante da transação como uma string decimal sem zeros à direita (por exemplo, `\"1500\"`, `\"0.5\"`, `\"0.123456789012345678\"`). Até 18 casas decimais." }, "currency": { "type": "string", "description": "Código de moeda de `amount`. Qualquer código alfabético ISO 4217 é aceite (por exemplo, `EUR`, `USD`, `NGN`), bem como um símbolo de ativo criptográfico (por exemplo, `BTC`). Dê preferência a um código atualmente em circulação. Nem todos os códigos aceites têm uma taxa de câmbio: quando nenhuma estiver disponível para o código (por exemplo, a unidade contabilística ISO `XSU`, ou um símbolo criptográfico que a Didit não precifique), a conversão automática falha e `preferred_currency_amount` é devolvido a null, a menos que o pedido tenha fornecido um `amount_in_default_currency` pré-convertido." }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` convertido para a moeda preferida da aplicação, quando disponível." }, "preferred_currency_code": { "type": "string", "nullable": true, "description": "Código de moeda preferencial utilizado para `preferred_currency_amount` - a moeda base da aplicação, qualquer código ISO 4217 atualmente em circulação. Um código sem taxa de câmbio disponível deixa `preferred_currency_amount` como null, a menos que o pedido tenha fornecido um `amount_in_default_currency` pré-convertido." }, "payment_details": { "type": "string", "nullable": true, "description": "Referência ou memorando de pagamento em texto livre proveniente do envio." }, "score": { "type": "integer", "description": "Pontuação de risco (normalmente 0–100). Mais alta = maior risco." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Gravidade de risco categórica definida por regras/fornecedores (`UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`). `null` até que algo a defina." }, "subject_name": { "type": "string", "nullable": true, "description": "Nome completo da parte `APPLICANT`." }, "subject_vendor_data": { "type": "string", "nullable": true, "description": "O seu identificador interno de utilizador/empresa para o requerente." }, "subject_country": { "type": "string", "nullable": true, "description": "Código do país do requerente, a partir do `address.country` submetido (normalmente ISO 3166-1 alpha-3)." }, "counterparty_name": { "type": "string", "nullable": true, "description": "Nome completo da parte `COUNTERPARTY`, se existir." }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "O seu identificador interno para a contraparte." }, "counterparty_country": { "type": "string", "nullable": true, "description": "Código do país da contraparte, a partir do `address.country` submetido." }, "tags": { "type": "array", "description": "Etiquetas associadas à transação (manualmente ou por regras).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "Se a etiqueta é uma predefinição da Didit ou uma etiqueta personalizada." } } } }, "txn_date": { "type": "string", "format": "date-time", "description": "Quando a transação ocorreu (a partir de `transaction_at` no momento da criação)." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a Didit registou a submissão." }, "decision_reason_code": { "type": "string", "nullable": true, "description": "Motivo legível por máquina para o `status` atual (por exemplo, `WALLET_HIGH_RISK`)." }, "decision_reason_label": { "type": "string", "nullable": true, "description": "Rótulo legível para `decision_reason_code`." }, "assigned_to_name": { "type": "string", "nullable": true, "description": "Nome de apresentação do revisor da Console atribuído a esta transação." }, "travel_rule_status": { "type": "string", "nullable": true, "description": "Estado da transferência da Travel Rule da transação (por exemplo, `COMPLETED`), ou `null` caso não tenha nenhuma." }, "travel_rule": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionTravelRule" } ], "description": "A transferência de Travel Rule da transação, o mesmo bloco que `travel_rule` em `GET /v3/transactions/{transaction_id}/`, ou `null` quando a transação não tem nenhuma." } } } } } }, "examples": { "Single transaction": { "value": { "count": 1, "next": null, "previous": null, "total_transactions": 1, "results": [ { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "transaction_type": "finance", "action_type": "withdrawal", "status": "IN_REVIEW", "direction": "OUTBOUND", "amount": "1500", "currency": "EUR", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "txn_date": "2026-05-17T08:42:00Z", "created_at": "2026-05-17T08:42:11Z", "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Manual review", "color": "#F59E0B", "description": null, "source": "custom" } ], "subject_name": "Maria Garcia", "subject_vendor_data": "user-12345", "counterparty_name": null, "counterparty_vendor_data": null, "counterparty_country": null, "subject_country": null, "assigned_to_name": "Alex Reviewer", "travel_rule_status": null, "travel_rule": null } ] } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode listar transações para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar transação", "description": "Submeta uma transação para monitorização síncrona de AML/risco. A transação é criada como `APPROVED`, executando-se de seguida as suas regras (e a triagem de criptoativos, quando aplicável) em linha, podendo alterar o `status` devolvido para `IN_REVIEW` ou `DECLINED`. **`transaction_id` é a sua chave de idempotência** (máx. 128 carateres, único por aplicação); reutilizá-lo devolve 400. Um webhook `transaction.created` é enviado em caso de sucesso para aplicações em produção. As aplicações em sandbox não são faturadas e não emitem webhooks `transaction.created` nem `transaction.status.updated`. As trocas Travel Rule em sandbox emitem webhooks `travel_rule.status.updated` com `environment: sandbox`. Uma transferência Travel Rule é armazenada e devolvida antes de qualquer contraparte ser contactada: `travel_rule.status` é devolvido como `AWAITING_COUNTERPARTY` (ou `NOT_APPLICABLE` abaixo do seu limiar, `UNCONFIRMED_OWNERSHIP` para uma carteira autocustodiada declarada, `COMPLETED` quando a outra carteira é a sua própria carteira verificada) e `travel_rule.protocol` é null. A Didit escolhe então a via e envia a troca, e cada alteração posterior de estado da transferência, incluindo `COUNTERPARTY_VASP_NOT_FOUND` quando nenhuma via alcança a contraparte, chega como um webhook `travel_rule.status.updated`. As suas regras são executadas novamente quando a via ou o estado se alteram.", "operationId": "createTransaction", "tags": [ "Transactions" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"transaction_id\": \"your-txn-2026-05-17-001\",\n \"transaction_category\": \"finance\",\n \"transaction_details\": {\n \"direction\": \"outbound\",\n \"amount\": 1500,\n \"currency\": \"EUR\",\n \"action_type\": \"withdrawal\"\n },\n \"subject\": {\n \"entity_type\": \"individual\",\n \"vendor_data\": \"user-12345\",\n \"full_name\": \"Maria Garcia\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.create(\n transaction_id=\"your-txn-2026-05-17-001\",\n transaction_category=\"finance\",\n transaction_details={\n \"direction\": \"outbound\",\n \"amount\": 1500.0,\n \"currency\": \"EUR\",\n \"action_type\": \"withdrawal\",\n },\n subject={\n \"entity_type\": \"individual\",\n \"vendor_data\": \"user-12345\",\n \"full_name\": \"Maria Garcia\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.create({\n transaction_id: \"your-txn-2026-05-17-001\",\n transaction_category: \"finance\",\n transaction_details: {\n direction: \"outbound\",\n amount: 1500.0,\n currency: \"EUR\",\n action_type: \"withdrawal\",\n },\n subject: {\n entity_type: \"individual\",\n vendor_data: \"user-12345\",\n full_name: \"Maria Garcia\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Create(ctx, didit.TransactionsCreateParams{\n\tTransactionID: \"your-txn-2026-05-17-001\",\n\tTransactionCategory: \"finance\",\n\tTransactionDetails: didit.TransactionsCreateParamsTransactionDetails{\n\t\tDirection: \"outbound\",\n\t\tAmount: 1500.0,\n\t\tCurrency: \"EUR\",\n\t\tActionType: didit.String(\"withdrawal\"),\n\t},\n\tSubject: didit.TransactionsCreateParamsSubject{\n\t\tEntityType: didit.String(\"individual\"),\n\t\tVendorData: \"user-12345\",\n\t\tFullName: \"Maria Garcia\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().create(TransactionsCreateParams.builder()\n .transactionId(\"your-txn-2026-05-17-001\")\n .transactionCategory(TransactionsCreateParams.TransactionCategory.of(\"finance\"))\n .transactionDetails(TransactionsCreateParams.TransactionDetails.builder()\n .direction(TransactionsCreateParams.TransactionDetails.Direction.of(\"outbound\"))\n .amount(1500.0)\n .currency(\"EUR\")\n .actionType(\"withdrawal\")\n .build())\n .subject(TransactionsCreateParams.Subject.builder()\n .entityType(\"individual\")\n .vendorData(\"user-12345\")\n .fullName(\"Maria Garcia\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->create([\n 'transaction_id' => 'your-txn-2026-05-17-001',\n 'transaction_category' => 'finance',\n 'transaction_details' => [\n 'direction' => 'outbound',\n 'amount' => 1500.0,\n 'currency' => 'EUR',\n 'action_type' => 'withdrawal',\n ],\n 'subject' => [\n 'entity_type' => 'individual',\n 'vendor_data' => 'user-12345',\n 'full_name' => 'Maria Garcia',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.create(\n transaction_id: \"your-txn-2026-05-17-001\",\n transaction_category: \"finance\",\n transaction_details: {\n direction: \"outbound\",\n amount: 1500.0,\n currency: \"EUR\",\n action_type: \"withdrawal\",\n },\n subject: {\n entity_type: \"individual\",\n vendor_data: \"user-12345\",\n full_name: \"Maria Garcia\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.CreateAsync(new TransactionsCreateParams\n{\n TransactionId = \"your-txn-2026-05-17-001\",\n TransactionCategory = \"finance\",\n TransactionDetails = new()\n {\n Direction = \"outbound\",\n Amount = 1500.0,\n Currency = \"EUR\",\n ActionType = \"withdrawal\",\n },\n Subject = new()\n {\n EntityType = \"individual\",\n VendorData = \"user-12345\",\n FullName = \"Maria Garcia\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "O seu identificador exclusivo para esta transação (máx. 128 carateres).", "example": "your-txn-2026-05-17-001" }, "transaction_at": { "type": "string", "format": "date-time", "description": "Quando a transação ocorreu. O padrão é o momento atual se omitido." }, "time_zone": { "type": "string", "description": "Identificador de fuso horário IANA, ex.: `Europe/Madrid`." }, "transaction_category": { "type": "string", "description": "Categoria da transação. Aliases em CamelCase (`travelRule`, `userPlatformEvent`, `gamblingBet`, …) também são aceites; o valor armazenado/devolvido é camelCase para categorias compostas por várias palavras.", "example": "finance", "enum": [ "finance", "kyc", "travel_rule", "user_event", "audit_trail_event", "gambling_bet", "gambling_limit_change", "gambling_bonus_change", "travelRule" ] }, "transaction_details": { "type": "object", "description": "Detalhes financeiros principais da transação.", "required": [ "direction", "amount", "currency" ], "properties": { "direction": { "type": "string", "description": "Direção da transação em relação ao sujeito. Insensível a maiúsculas/minúsculas; `in`/`out` são aceites como pseudónimos. Devolvida em maiúsculas (`INBOUND`/`OUTBOUND`).", "example": "outbound", "enum": [ "inbound", "outbound", "in", "out" ] }, "amount": { "type": "number", "description": "Montante da transação (até 18 casas decimais). Envie-o como uma string decimal (por exemplo, `\"0.123456789012345678\"`) quando a precisão exata for importante: um número JSON é analisado primeiro como um float binário, pelo que os dígitos além de cerca de 15 dígitos significativos são arredondados antes de o montante ser armazenado. Deve ser igual ou superior a zero: a direção indica o sinal e um montante negativo devolve `400`.", "example": 1500 }, "currency": { "type": "string", "description": "Código de moeda. Qualquer código alfabético ISO 4217 é aceite (por exemplo, `EUR`, `USD`, `NGN`), bem como um símbolo de criptoativo (por exemplo, `BTC`). Dê preferência a um código atualmente em circulação. Nem todos os códigos aceites têm uma taxa de câmbio: quando nenhuma estiver disponível para o código (por exemplo, a unidade contabilística ISO `XSU`, ou um símbolo criptográfico que a Didit não precifique), a conversão automática falha e `preferred_currency_amount` é devolvido como null, a menos que o pedido tenha fornecido um `amount_in_default_currency` pré-convertido.", "example": "EUR" }, "currency_kind": { "type": "string", "description": "Indica se a moeda é `fiat` ou `crypto`." }, "amount_in_default_currency": { "type": "number", "nullable": true, "description": "Montante pré-convertido na moeda padrão. Se omitido, é tentada a conversão cambial automática. Deve ser zero ou superior." }, "default_currency": { "type": "string", "description": "O código de moeda predefinido para o montante convertido. Qualquer código ISO 4217 atualmente em circulação." }, "payment_details": { "type": "string", "nullable": true, "description": "Referência ou memorando de pagamento em texto livre." }, "payment_reference_id": { "type": "string", "nullable": true, "description": "Referência externa do sistema de pagamento. Para triagem de hash de transação cripto no âmbito de AML, envie o hash da transação na blockchain e forneça também `subject.payment_method.account_id` com o endereço relacionado." }, "action_type": { "type": "string", "nullable": true, "description": "Subtipo da transação, p. ex. `deposit`, `withdrawal`, `transfer`." }, "crypto_params": { "type": "object", "description": "Seleção da rede de criptomoeda, separada da moeda (o símbolo do ativo). Registar um símbolo de token personalizado não garante a cobertura de hashes de transação para o respetivo contrato.", "properties": { "crypto_chain": { "type": "string", "description": "Rede real utilizada para a triagem. A triagem gerida suporta BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE (Base), OP (Optimism), ARB (Arbitrum One), AVAX (Avalanche C-Chain), ADA (Cardano), XLM (Stellar) e HBAR (Hedera). Nomes comuns de redes também são aceites, por exemplo POLYGON ou POL para MATIC, BSC para BNB e TRON para TRX. Especifique sempre isto para tokens multirrede. Quando estiver em falta para USDT, USDC ou ETH enviados com um hash de transação 0x, o Didit pesquisa o hash em Ethereum, BNB Chain, Polygon, Base, Arbitrum e Optimism e faz a triagem na rede onde for encontrado; se nenhuma rede o tiver, a transação não é submetida a triagem e custom_values.aml_screening_status fica FAILED com o motivo em custom_values.aml_screening_error. Quando estiver em falta para USDT ou USDC submetidos a triagem por carteira (sem hash de transação), um endereço Tron é submetido a triagem na Tron, um endereço Solana na Solana e um endereço 0x na primeira dessas seis redes onde tenha enviado uma transação ou detenha o token, ou na Ethereum quando não estiver ativo em nenhuma delas. A cobertura de fornecedores associados varia; LIGHTNING requer um fornecedor associado suportado.", "example": "BASE" } } } } }, "subject": { "type": "object", "description": "O sujeito (requerente) da transação.", "required": [ "vendor_data", "full_name" ], "properties": { "entity_type": { "type": "string", "description": "Tipo de entidade: `individual` ou `company`." }, "vendor_data": { "type": "string", "description": "O seu identificador interno de utilizador/empresa.", "example": "user-12345" }, "full_name": { "type": "string", "description": "Nome completo do sujeito.", "example": "Maria Garcia" }, "first_name": { "type": "string", "description": "Primeiro nome do sujeito." }, "last_name": { "type": "string", "description": "Apelido do sujeito." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data de nascimento (YYYY-MM-DD)." }, "address": { "type": "object", "description": "Objeto de morada.", "properties": { "country": { "type": "string", "description": "Código do país (recomenda-se ISO 3166-1 alpha-3). Copiado para o `country_code` da parte." }, "town": { "type": "string" }, "state": { "type": "string" }, "street": { "type": "string" }, "post_code": { "type": "string" } } }, "institution_details": { "type": "object", "description": "Detalhes da instituição (para sujeitos institucionais).", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "address": { "type": "object" } } }, "device_context": { "type": "object", "description": "Contexto do dispositivo capturado no momento da transação. browser_family e platform têm de ser enviados como chaves explícitas de nível superior — não são derivados de user_agent. O alias em camelCase device também é aceite no pedido.", "properties": { "fingerprint": { "type": "string", "description": "Impressão digital única do dispositivo." }, "persistent_device_id": { "type": "string", "description": "Identificador estável de dispositivo entre sessões (esquema de fingerprint v2)." }, "user_agent": { "type": "string", "description": "Cadeia de caracteres do agente do utilizador do navegador ou da aplicação. Alias em CamelCase: userAgent." }, "browser_family": { "type": "string", "description": "Família do navegador (por exemplo, Chrome, Firefox, Safari). Deve ser enviada explicitamente — não é derivada de user_agent. Alias em CamelCase: browserFamily." }, "browser_version": { "type": "string", "description": "Cadeia de caracteres da versão do navegador. Deve ser enviada explicitamente. Alias em CamelCase: browserVersion." }, "platform": { "type": "string", "description": "Identificador da plataforma (web, ios, android, macos, windows, linux). Tem de ser enviado explicitamente — não é derivado de user_agent." }, "os_family": { "type": "string", "description": "Família do sistema operativo (por exemplo, iOS, Android, Windows). Alias CamelCase: osFamily." }, "os_version": { "type": "string", "description": "String da versão do sistema operativo. Alias CamelCase: osVersion." }, "accept_language": { "type": "string", "description": "Valor do cabeçalho Accept-Language. Alias em CamelCase: acceptLang." }, "session_id": { "type": "string", "description": "Identificador de sessão da sessão atual do utilizador. Guardado nos metadados. Alias CamelCase: sessionId." }, "session_age_ms": { "type": "number", "description": "Idade da sessão do utilizador em milissegundos no momento da transação. Alias em CamelCase: sessionAgeMs." }, "network_context": { "type": "object", "description": "Contexto de rede com endereço IP e geolocalização. Um bloco ipInfo de nível superior também é integrado neste objeto.", "properties": { "ip_address": { "type": "string", "description": "Endereço IP do cliente. Alias CamelCase: ip." }, "ip_country_code": { "type": "string", "description": "País determinado por geolocalização do IP (ISO 3166-1 alfa-3). Alias CamelCase: countryCode3." }, "latitude": { "type": "number", "description": "Latitude geográfica do IP. Alias em CamelCase: lat." }, "longitude": { "type": "number", "description": "Longitude geográfica do IP. Alias em CamelCase: lon." } } } } }, "payment_method": { "type": "object", "description": "Método de pagamento utilizado pelo sujeito.", "properties": { "method_type": { "type": "string", "description": "Tipo de método de pagamento: `bank_card`, `bank_account`, `crypto_wallet`, `ewallet`, `unhosted_wallet`, `other`." }, "account_id": { "type": "string", "description": "Identificador de conta (por exemplo, IBAN, endereço de carteira). Para triagem de criptomoedas, deve conter o endereço de carteira para este participante. A triagem de hash de transações de entrada requer o endereço de depósito do serviço/cliente associado ao sujeito. A triagem de saída utiliza a carteira de destino na contraparte. Numa transferência de criptomoedas em bitcoin ou Lightning, pode ser um pedido de pagamento Lightning (fatura BOLT11, oferta BOLT12, LNURL) ou um Lightning Address: a Didit armazena o beneficiário indicado como a conta (\"\" quando não indica nenhum) e o conteúdo do pedido em `chain_details.lightning` da transferência Travel Rule. No máximo 255 carateres após armazenamento. Numa transferência de criptomoedas em bitcoin ou Lightning, pode ser um pedido de pagamento Lightning (fatura BOLT11, oferta BOLT12, LNURL) ou um Lightning Address: a Didit armazena o beneficiário indicado como a conta (\"\" quando não indica nenhum) e o conteúdo do pedido em `chain_details.lightning` da transferência Travel Rule. No máximo 255 carateres após armazenamento." }, "memo": { "type": "string", "maxLength": 256, "description": "A tag ou memo de destino que faz parte da carteira numa rede baseada em memo (XRP, XLM, EOS, ATOM, HBAR). Num único endereço de exchange partilhado, cada memo constitui o seu próprio método de pagamento. XRP: uma tag de destino, um número inteiro de 0 a 4294967295 (é aceite um número em formato JSON). XLM: um memo de texto com até 28 bytes, um id de 64 bits ou um hash de 32 bytes em hexadecimal. EOS: até 256 bytes. ATOM: até 256 carateres. HBAR: até 100 bytes. As carteiras de Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning não aceitam memo: caso seja fornecido um, é devolvido um erro `400`. Alias: `destinationTag` ou `destination_tag`." }, "issuing_country": { "type": "string", "description": "Código de país ISO 3166-1 alfa-3 do emissor." } } } } }, "counterparty": { "type": "object", "description": "A contraparte da transação (opcional).", "properties": { "entity_type": { "type": "string", "description": "Tipo de entidade: `individual` ou `company`." }, "vendor_data": { "type": "string", "description": "O seu identificador interno para a contraparte." }, "full_name": { "type": "string", "description": "Nome completo da contraparte." }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "address": { "type": "object", "description": "Objeto de morada com `country` (ISO 3166-1 alfa-3)." }, "institution_details": { "type": "object" }, "device_context": { "type": "object", "description": "Contexto do dispositivo para a contraparte. browser_family e platform têm de ser enviados como chaves explícitas de nível superior — não são derivados de user_agent.", "properties": { "fingerprint": { "type": "string", "description": "Impressão digital única do dispositivo." }, "persistent_device_id": { "type": "string", "description": "Identificador estável de dispositivo entre sessões (esquema de fingerprint v2)." }, "user_agent": { "type": "string", "description": "Cadeia de caracteres do agente do utilizador do navegador ou da aplicação. Alias em CamelCase: userAgent." }, "browser_family": { "type": "string", "description": "Família do navegador (por exemplo, Chrome, Firefox, Safari). Deve ser enviada explicitamente — não é derivada de user_agent. Alias em CamelCase: browserFamily." }, "browser_version": { "type": "string", "description": "Cadeia de caracteres da versão do navegador. Deve ser enviada explicitamente. Alias em CamelCase: browserVersion." }, "platform": { "type": "string", "description": "Identificador da plataforma (web, ios, android, macos, windows, linux). Tem de ser enviado explicitamente — não é derivado de user_agent." }, "os_family": { "type": "string", "description": "Família do sistema operativo (por exemplo, iOS, Android, Windows). Alias CamelCase: osFamily." }, "os_version": { "type": "string", "description": "String da versão do sistema operativo. Alias CamelCase: osVersion." }, "accept_language": { "type": "string", "description": "Valor do cabeçalho Accept-Language. Alias em CamelCase: acceptLang." }, "session_id": { "type": "string", "description": "Identificador de sessão para a sessão da contraparte. Guardado nos metadados. Alias CamelCase: sessionId." }, "session_age_ms": { "type": "number", "description": "Idade da sessão do utilizador em milissegundos no momento da transação. Alias em CamelCase: sessionAgeMs." }, "network_context": { "type": "object", "description": "Contexto de rede com endereço IP e geolocalização. Um bloco ipInfo de nível superior também é integrado neste objeto.", "properties": { "ip_address": { "type": "string", "description": "Endereço IP do cliente. Alias CamelCase: ip." }, "ip_country_code": { "type": "string", "description": "País determinado por geolocalização do IP (ISO 3166-1 alfa-3). Alias CamelCase: countryCode3." }, "latitude": { "type": "number", "description": "Latitude geográfica do IP. Alias em CamelCase: lat." }, "longitude": { "type": "number", "description": "Longitude geográfica do IP. Alias em CamelCase: lon." } } } } }, "payment_method": { "type": "object", "description": "Método de pagamento utilizado pela contraparte. Em transações de travelRule, `method_type: \"unhosted_wallet\"` declara a carteira da contraparte como autocustodiada: a transferência ignora o encaminhamento VASP da contraparte, é criada diretamente em `UNCONFIRMED_OWNERSHIP` e (quando `auto_wallet_verification` está ativado) uma sessão de widget de propriedade da carteira é gerada automaticamente e devolvida no bloco `action_required` da transação.", "properties": { "method_type": { "type": "string", "description": "Tipo de método de pagamento: `bank_card`, `bank_account`, `crypto_wallet`, `ewallet`, `unhosted_wallet`, `other`. Utilize `unhosted_wallet` para declarar uma carteira autocustodiada para a Travel Rule." }, "account_id": { "type": "string", "description": "Identificador de conta (por exemplo, IBAN ou endereço de carteira). Numa transferência de cripto em bitcoin ou Lightning, pode ser um pedido de pagamento Lightning (fatura BOLT11, oferta BOLT12, LNURL) ou um Lightning Address: a Didit armazena o beneficiário indicado como a conta (\"\" quando não indica nenhum) e o conteúdo do pedido em `chain_details.lightning` da transferência Travel Rule. No máximo 255 carateres após armazenamento. Numa transferência de cripto em bitcoin ou Lightning, pode ser um pedido de pagamento Lightning (fatura BOLT11, oferta BOLT12, LNURL) ou um Lightning Address: a Didit armazena o beneficiário indicado como a conta (\"\" quando não indica nenhum) e o conteúdo do pedido em `chain_details.lightning` da transferência Travel Rule. No máximo 255 carateres após armazenamento." }, "memo": { "type": "string", "maxLength": 256, "description": "A tag ou memo de destino que faz parte da carteira numa rede baseada em memo (XRP, XLM, EOS, ATOM, HBAR). Num único endereço de exchange partilhado, cada memo constitui o seu próprio método de pagamento. XRP: uma tag de destino, um número inteiro de 0 a 4294967295 (é aceite um número em formato JSON). XLM: um memo de texto com até 28 bytes, um id de 64 bits ou um hash de 32 bytes em hexadecimal. EOS: até 256 bytes. ATOM: até 256 carateres. HBAR: até 100 bytes. As carteiras de Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning não aceitam memo: caso seja fornecido um, é devolvido um erro `400`. Alias: `destinationTag` ou `destination_tag`." }, "issuing_country": { "type": "string" } } } } }, "custom_properties": { "type": "object", "description": "Pares chave-valor arbitrários associados à transação. Cada chave pode ser referenciada nas condições das regras através do caminho de campo `custom_values.`.", "additionalProperties": true, "example": { "merchant_id": "test", "bank_name": "test_2" } }, "travel_rule_details": { "type": "object", "description": "Dados da Travel Rule. Quando a Travel Rule está ativada e transaction_category é travel_rule, a Didit executa a troca por si própria: ignora status, protocol, required e obligations_count, e utiliza originator_data, beneficiary_data e metadata. Caso contrário, a Didit armazena estes valores como um registo passivo da Travel Rule. Enquanto a Travel Rule estiver ativada, uma transferência de saída igual ou superior ao seu limiar deve incluir o que o respetivo regime exige (EU TFR ou Recomendação 16 do GAFI), verificado nas partes que enviar: um campo em falta responde com 400 sob `travel_rule_details.originator_data` ou `travel_rule_details.beneficiary_data`, por exemplo \"O EU TFR exige o nome do ordenante.\"", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Obrigatório sempre que enviar travel_rule_details. Um dos estados de transferência da Travel Rule (por exemplo, AWAITING_COUNTERPARTY, COMPLETED, NOT_APPLICABLE); grafias em minúsculas e camelCase e os valores legados UNKNOWN, COMPLIANT, PENDING_ACTION, PENDING_COUNTERPARTY, FAILED e EXEMPT também são aceites e mapeados. Qualquer outro valor devolve 400." }, "protocol": { "type": "string" }, "required": { "type": "boolean" }, "obligations_count": { "type": "integer" }, "originator_data": { "type": "object", "description": "Parte ordenante, como campos simples ou uma pessoa IVMS 101. Para o seu utilizador com uma verificação de KYC aprovada, a Didit substitui os campos que a verificação contém pelos valores verificados (consulte `metadata.originator_provenance`). Deve ser um objeto: qualquer outra coisa resulta num `400`. Numa rede com memo, uma chave `memo` indica o memo ou tag da carteira do ordenante." }, "beneficiary_data": { "type": "object", "description": "Parte beneficiária, como campos simples ou uma pessoa IVMS 101. Deve ser um objeto: qualquer outra coisa resulta num `400`. Para encaminhar a transferência, a Didit lê `wallet_address` (um campo vazio é preenchido a partir de `counterparty.payment_method.account_id`), `chain` (preenchido a partir de `transaction_details.crypto_params.crypto_chain` ou da `currency` quando esta indica uma rede suportada), `name` (recorrendo a `counterparty.full_name`), `travel_address`, `counterparty_vasp_name`, `counterparty_vasp_lei` e `counterparty_vasp_email`. Numa rede com memo, `memo` indica o memo ou tag da carteira do beneficiário; `wallet_address` e `memo` sobrepõem-se ao método de pagamento da contraparte." }, "metadata": { "type": "object" }, "utxo": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleUtxo" } ], "description": "Opcional, apenas para cadeias UTXO (BTC, LTC, BCH, DOGE). As entradas e saídas da transação, a partir das quais a Didit deduz a carteira do ordenante e a saída do beneficiário quando não as declarar." }, "originator": { "type": "object", "description": "Um bloco de ordenante IVMS 101: `originatorPersons` (uma `naturalPerson` ou `legalPerson`; uma pessoa coletiva torna a parte uma empresa) e `accountNumber` (endereços de carteira). Utilizado para `originator_data` quando esse objeto está vazio. Um bloco malformado responde com 400 identificado pelo seu caminho, por exemplo `originator.originatorPersons`." }, "beneficiary": { "type": "object", "description": "Um bloco de beneficiário IVMS 101: `beneficiaryPersons` (uma `naturalPerson` ou `legalPerson`; uma pessoa coletiva torna a parte uma empresa) e `accountNumber` (endereços de carteira). Utilizado para `beneficiary_data` quando esse objeto está vazio. Um bloco malformado responde com 400 identificado pelo seu caminho, por exemplo `beneficiary.beneficiaryPersons`." }, "ivms101": { "type": "object", "description": "Os blocos `originator` e `beneficiary` encapsulados num único objeto IVMS 101 (`IVMS101` também é aceite). Os blocos de nível superior prevalecem sobre os do encapsulamento." } } }, "network_snapshot": { "type": "object", "description": "Instantâneo pré-computado do grafo de rede.", "properties": { "nodes": { "type": "array", "items": { "type": "object" } }, "edges": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "object" } } }, "include_crypto_screening": { "type": "boolean", "nullable": true, "description": "Substituição por transação para a triagem de análise de blockchain de criptoativos. Quando `true`, a triagem de criptoativos é realizada independentemente do valor predefinido da aplicação. Quando `false`, a triagem de criptoativos é ignorada mesmo que esteja ativada nas definições da aplicação. Quando omitido ou `null`, é utilizado o valor predefinido ao nível da aplicação configurado na Console. A triagem de criptoativos requer `transaction_details.direction`, `currency_kind: \"crypto\"`, uma blockchain/moeda e o endereço de carteira selecionado pela direção: a triagem pré-transferência de entrada utiliza `counterparty.payment_method.account_id`, a triagem de hash de transação de entrada utiliza `subject.payment_method.account_id` e a triagem de saída utiliza `counterparty.payment_method.account_id`. Quando `transaction_details.payment_reference_id` contém um hash de transação de blockchain, a Didit realiza a triagem de transação e devolve o enriquecimento do resumo da transação quando disponível." } }, "required": [ "transaction_id", "transaction_category", "transaction_details", "subject" ] }, "examples": { "Minimal fiat withdrawal": { "summary": "Menor payload aceitável para uma transferência de saída fiduciária", "value": { "transaction_id": "your-txn-2026-05-17-001", "transaction_category": "finance", "transaction_details": { "direction": "outbound", "amount": 1500, "currency": "EUR", "action_type": "withdrawal" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia" } } }, "Crypto outbound with screening": { "summary": "Levantamento de criptoativos de saída para uma carteira autocustodiada, triagem opcional", "value": { "transaction_id": "your-txn-2026-05-17-002", "transaction_category": "finance", "include_crypto_screening": true, "transaction_details": { "direction": "outbound", "amount": 0.5, "currency": "BTC", "currency_kind": "crypto", "amount_in_default_currency": 32500, "default_currency": "USD", "action_type": "withdrawal" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "payment_method": { "method_type": "crypto_wallet", "account_id": "bc1qexampleexchangewalletaddressxyz", "issuing_country": "ESP" } }, "counterparty": { "entity_type": "individual", "payment_method": { "method_type": "unhosted_wallet", "account_id": "bc1qexampleexternalwalletaddressabc" } } } }, "Travel Rule transfer": { "summary": "Transferência de criptoativos de saída com dados do ordenante/beneficiário da Travel Rule", "value": { "transaction_id": "your-txn-2026-05-17-003", "transaction_category": "travel_rule", "transaction_details": { "direction": "outbound", "amount": 25000, "currency": "USDT", "currency_kind": "crypto", "action_type": "transfer" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "date_of_birth": "1992-03-14", "address": { "country": "ESP", "town": "Madrid", "street": "Calle Mayor 1", "post_code": "28013" } }, "counterparty": { "entity_type": "individual", "full_name": "John Beneficiary", "institution_details": { "name": "Beneficiary VASP, Inc.", "code": "BVASP-US" } }, "travel_rule_details": { "status": "AWAITING_COUNTERPARTY", "protocol": "IVMS101", "required": true, "originator_data": { "name": "Maria Garcia" }, "beneficiary_data": { "name": "John Beneficiary" } } } } } } } }, "responses": { "201": { "description": "Transação submetida e monitorizada. O corpo contém os detalhes completos da transação (mesma estrutura de `GET /v3/transactions/{transaction_id}/`), refletindo quaisquer resultados de regras já aplicados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "Approved with no rule hits": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "environment": "live", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "APPROVED", "source": "LIVE", "amount": "1500", "currency": "EUR", "currency_type": "fiat", "amount_in_default_currency": "1620.45", "default_currency_code": "USD", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 0, "severity": null, "decision_reason_code": null, "decision_reason_label": null, "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": {}, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [ { "uuid": "d4e5f6a7-8901-4bcd-9ef0-123456789abc", "activity_type": "TRANSACTION_CREATED", "source": "TRANSACTION", "status": "APPROVED", "title": "withdrawal", "description": "Transaction recorded.", "metadata": {}, "occurred_at": "2026-05-17T08:42:11Z" } ], "alerts": [], "rule_runs": [], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } }, "Flagged for review": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567891", "environment": "live", "transaction_number": 4124, "txn_id": "your-txn-2026-05-17-002", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "IN_REVIEW", "source": "LIVE", "amount": "0.5", "currency": "BTC", "currency_type": "crypto", "amount_in_default_currency": "32500", "default_currency_code": "USD", "preferred_currency_amount": "32500", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": { "order_id": "ord-9988" }, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [], "alerts": [ { "uuid": "a7b8c9d0-1234-4abc-9def-567890abcdef", "title": "Destination wallet flagged as high risk", "description": "Provider risk score exceeded the configured threshold.", "severity": "HIGH", "status": "OPEN", "source": "RULE", "metadata": {}, "created_at": "2026-05-17T08:42:12Z", "due_at": null } ], "rule_runs": [ { "uuid": "e5f6a7b8-9012-4cde-af01-23456789abcd", "rule": "f6a7b8c9-0123-4def-b012-3456789abcde", "rule_title": "High-risk wallet screening", "rule_description": null, "rule_category": "crypto", "matched": true, "is_test": false, "mode": "ACTIVE", "severity": "HIGH", "score_delta": 78, "status_target": "IN_REVIEW", "action_summary": "score +78; change_status:IN_REVIEW", "metadata": {}, "created_at": "2026-05-17T08:42:12Z" } ], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } } } } } }, "400": { "description": "A validação falhou (campos obrigatórios em falta, `transaction_id` duplicado, valor de enumeração desconhecido, moeda inválida, etc.).", "content": { "application/json": { "examples": { "Missing required field": { "value": { "transaction_details": { "amount": [ "This field is required." ] } } }, "Duplicate transaction_id": { "value": { "transaction_id": [ "A transaction with this transaction_id already exists." ] } }, "Invalid category": { "value": { "non_field_errors": [ "Unsupported transaction category." ] } }, "Missing subject identity": { "value": { "subject": [ "subject.vendor_data and subject.full_name are required." ] } }, "Blocklisted participant": { "value": { "vendor_data": [ "The individual 'user-12345' is in the blocklist and cannot participate in transactions." ] } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode submeter transações para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "409": { "description": "Outro pedido com o mesmo `transaction_id` criou a transação enquanto este estava a ser processado, pelo que apenas uma de duas submissões simultâneas tem êxito. Consulte a transação existente em vez de submeter novamente.", "content": { "application/json": { "examples": { "Concurrent duplicate": { "value": { "detail": "A transaction with this transaction_id already exists." } } } } } }, "429": { "description": "Limite de pedidos excedido: a criação de transações e a ingestão de eventos (`POST /v3/transactions/`, `POST /v3/events/`, `POST /v3/events/batch/`) partilham um orçamento de 600 pedidos por minuto por chave de API, separado dos 300 partilhados por todos os outros pedidos de escrita. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente, arredondados para cima para que a nova tentativa ocorra na janela seguinte.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "transactions", "method": "create", "auth": "api_key", "server": true } } }, "/v3/transactions/{transaction_id}/": { "get": { "summary": "Obter transação", "description": "Obter o registo de monitorização completo para uma transação: partes, pontuação/gravidade, execuções de regras, alertas, resultado da Travel Rule, sessão de remediação.", "operationId": "getTransaction", "x-didit-sdk": { "resource": "transactions", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID de transação estável da Didit (o `uuid` devolvido na criação/listagem, **não** o seu `txn_id`).", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.retrieve(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Retrieve(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->retrieve('abcdef12-3456-7890-abcd-ef1234567890');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.RetrieveAsync(\"abcdef12-3456-7890-abcd-ef1234567890\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhe completo da transação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "In review with an alert": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "environment": "live", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "IN_REVIEW", "source": "LIVE", "amount": "1500", "currency": "EUR", "currency_type": "fiat", "amount_in_default_currency": "1620.45", "default_currency_code": "USD", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": { "order_id": "ord-9988" }, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [], "alerts": [ { "uuid": "a7b8c9d0-1234-4abc-9def-567890abcdef", "title": "Destination wallet flagged as high risk", "description": "Provider risk score exceeded the configured threshold.", "severity": "HIGH", "status": "OPEN", "source": "RULE", "metadata": {}, "created_at": "2026-05-17T08:42:12Z", "due_at": null } ], "rule_runs": [], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode ler as transações desta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhuma transação com este UUID para a aplicação (eliminada, nunca criada, pertence a outra aplicação ou o segmento de caminho não é um UUID válido).", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/sdk-token/": { "post": { "summary": "Emitir um token de transação do SDK", "description": "Emita um token com âmbito de curta duração que a sua aplicação passa aos SDKs da Didit para que possam submeter transações diretamente a partir do dispositivo do utilizador final através de `POST /v1/transactions/`. O token está vinculado a um `vendor_data` (o seu ID de utilizador): cada transação submetida com ele tem a identidade do sujeito aplicada do lado do servidor a partir dessa vinculação, pelo que um cliente adulterado não pode submeter em nome de outro utilizador. Emita tokens a partir do seu backend - nunca inclua a própria chave de API numa aplicação. Os aliases em camelCase (`vendorData`, `ttlSeconds`, `maxUses`) também são aceites.", "operationId": "createTransactionSdkToken", "x-didit-sdk": { "resource": "transactions", "method": "create_sdk_token", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor_data": { "type": "string", "description": "O seu identificador interno para o utilizador final a que este token está circunscrito. Aplicado como a identidade do sujeito de cada transação submetida com o token.", "example": "user-042" }, "ttl_seconds": { "type": "integer", "default": 900, "maximum": 86400, "description": "Tempo de vida útil do token em segundos. O valor predefinido é 900 (15 minutos); o máximo é 86400 (24 horas)." }, "max_uses": { "type": "integer", "nullable": true, "description": "Número máximo de envios bem-sucedidos permitidos com este token. Omita ou defina como null para utilizações ilimitadas dentro do TTL." } }, "required": [ "vendor_data" ] }, "example": { "vendor_data": "user-042", "ttl_seconds": 900, "max_uses": 3 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/sdk-token/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"user-042\", \"ttl_seconds\": 900, \"max_uses\": 3}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.create_sdk_token(\n vendor_data=\"user-042\",\n ttl_seconds=900,\n max_uses=3,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.createSdkToken({\n vendor_data: \"user-042\",\n ttl_seconds: 900,\n max_uses: 3,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.CreateSDKToken(ctx, didit.TransactionsCreateSDKTokenParams{\n\tVendorData: \"user-042\",\n\tTTLSeconds: didit.Int(900),\n\tMaxUses: didit.Int(3),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionsCreateSdkTokenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().createSdkToken(TransactionsCreateSdkTokenParams.builder()\n .vendorData(\"user-042\")\n .ttlSeconds(900L)\n .maxUses(3L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->createSdkToken([\n 'vendor_data' => 'user-042',\n 'ttl_seconds' => 900,\n 'max_uses' => 3,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.create_sdk_token(\n vendor_data: \"user-042\",\n ttl_seconds: 900,\n max_uses: 3\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.CreateSdkTokenAsync(new TransactionsCreateSdkTokenParams\n{\n VendorData = \"user-042\",\n TtlSeconds = 900,\n MaxUses = 3,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "O token gerado. Passe o `sdk_token` à sua aplicação; este autentica os endpoints `/v1/transactions/` direcionados ao dispositivo através do cabeçalho `X-Transaction-Token` até `expires_at`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sdk_token": { "type": "string", "description": "O token de transação com âmbito a transmitir ao SDK." }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando o token deixa de ser aceite." } } }, "example": { "sdk_token": "q7Zt...urlsafe", "expires_at": "2026-07-07T12:15:00Z" } } } }, "400": { "description": "A validação falhou: `vendor_data` em falta ou `ttl_seconds` fora do intervalo permitido.", "content": { "application/json": { "examples": { "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada.", "content": { "application/json": { "examples": { "Invalid API Key": { "value": { "detail": "Invalid API Key." } } } } } } } } }, "/v1/transactions/": { "post": { "summary": "Submeter uma transação a partir de um SDK", "description": "Endpoint virado para o dispositivo que os SDKs da Didit chamam para submeter uma transação diretamente a partir do dispositivo do utilizador final. A autenticação é um token com âmbito de `POST /v3/transactions/sdk-token/` enviado no cabeçalho `X-Transaction-Token` em vez de uma chave de API, e o endpoint tem CORS ativado para que os navegadores possam chamá-lo entre origens. O payload utiliza os aliases de transmissão camelCase mostrados abaixo (os métodos `submitTransaction` do SDK constroem-no por si). Três garantias do lado do servidor: a aplicação é sempre obtida a partir do token; a identidade do sujeito (`externalUserId`) é sempre aplicada a partir de `vendor_data` do token, pelo que valores de payload falsificados são ignorados; e a inteligência de dispositivos (a impressão digital do dispositivo do SDK mais o IP e o agente do utilizador derivados pelo servidor) é associada ao sujeito automaticamente.", "operationId": "submitTransactionFromSdk", "x-didit-sdk": { "resource": "transactions", "method": "submit_from_device", "auth": "device_token", "server": false }, "tags": [ "Transactions" ], "security": [ { "TransactionTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "txnId": { "type": "string", "description": "O seu identificador exclusivo para esta transação (mapeia para `transaction_id`, máx. 128 carateres).", "example": "wd-2026-07-07-0042" }, "txnDate": { "type": "string", "format": "date-time", "description": "Quando a transação ocorreu (mapeia para `transaction_at`). O padrão é o momento atual se omitido." }, "zoneId": { "type": "string", "description": "Identificador de fuso horário IANA (mapeia para `time_zone`), ex.: `Europe/Madrid`." }, "type": { "type": "string", "description": "Categoria da transação (mapeia para `transaction_category`), por exemplo, `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`.", "example": "travelRule" }, "info": { "type": "object", "description": "Detalhes financeiros principais da transação (mapeia para `transaction_details`).", "required": [ "direction", "amount", "currency" ], "properties": { "direction": { "type": "string", "description": "Direção em relação ao sujeito. Insensível a maiúsculas/minúsculas; `in`/`out` são aceites como pseudónimos. Devolvida em maiúsculas (`INBOUND`/`OUTBOUND`).", "example": "out" }, "amount": { "type": "number", "description": "Montante da transação (até 18 casas decimais). Também é aceite uma string decimal e é a única forma de preservar mais de cerca de 15 dígitos significativos: um número JSON é analisado primeiro como um float binário, pelo que `0.123456789012345678` é armazenado como `0.12345678901234568`.", "example": 0.25 }, "currency": { "type": "string", "description": "Código de moeda. Qualquer código alfabético ISO 4217 é aceite (por exemplo, `EUR`, `USD`, `NGN`), bem como um símbolo de ativo criptográfico (por exemplo, `BTC`). Dê preferência a um código atualmente em circulação. Nem todos os códigos aceites têm uma taxa de câmbio: quando nenhuma estiver disponível para o código (por exemplo, a unidade contabilística ISO `XSU`, ou um símbolo criptográfico que a Didit não precifique), a conversão automática falha e `preferred_currency_amount` é devolvido a null, a menos que o pedido tenha fornecido um `amountInDefaultCurrency` pré-convertido.", "example": "ETH" }, "currencyType": { "type": "string", "description": "Indica se a moeda é `fiat` ou `crypto` (associa-se a `currency_kind`)." }, "amountInDefaultCurrency": { "type": "number", "nullable": true, "description": "Montante pré-convertido na moeda padrão (mapeia para `amount_in_default_currency`). Se omitido, é tentada a conversão cambial automática." }, "defaultCurrencyCode": { "type": "string", "description": "O código de moeda predefinido para o montante convertido (mapeia para `default_currency`). Qualquer código ISO 4217 atualmente em circulação." }, "paymentDetails": { "type": "string", "nullable": true, "description": "Referência ou memorando de pagamento em texto livre (associa-se a `payment_details`)." }, "paymentTxnId": { "type": "string", "nullable": true, "description": "Referência de pagamento externa (mapeia para `payment_reference_id`); o hash da transação on-chain para transações de criptomoeda." }, "type": { "type": "string", "nullable": true, "description": "Subtipo da transação (mapeia para `action_type`), p. ex. `deposit`, `withdrawal`, `transfer`." }, "cryptoParams": { "type": "object", "description": "Parâmetros específicos de criptomoeda, por exemplo, `{\"crypto_chain\": \"ETH\"}`." } } }, "subject": { "type": "object", "description": "O sujeito (requerente) da transação. `externalUserId` é ignorado aqui: a identidade do sujeito é sempre imposta a partir de `vendor_data` do token.", "required": [ "fullName" ], "properties": { "type": { "type": "string", "description": "Tipo de entidade (mapeia para `entity_type`): `individual` (por predefinição) ou `company`." }, "externalUserId": { "type": "string", "description": "Ignorado no sujeito - aplicado no lado do servidor a partir do `vendor_data` do token." }, "fullName": { "type": "string", "example": "Jane Doe" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dob": { "type": "string", "format": "date", "description": "Data de nascimento (YYYY-MM-DD; mapeia para `date_of_birth`)." }, "address": { "type": "object", "description": "Objeto de morada com `country` (ISO 3166-1 alfa-3), `town`, `state`, `street`, `post_code`." }, "institutionInfo": { "type": "object", "description": "Detalhes da instituição para participantes institucionais (mapeia para `institution_details`)." }, "device": { "type": "object", "description": "Contexto de dispositivo explícito opcional. Combinado com as informações de dispositivo recolhidas automaticamente; os campos derivados do servidor prevalecem em caso de conflito." }, "paymentMethod": { "type": "object", "description": "Método de pagamento utilizado pelo sujeito (mapeia para `payment_method`).", "properties": { "type": { "type": "string", "description": "Tipo de método de pagamento (mapeia para `method_type`), por exemplo, `bank_card`, `bank_account`, `crypto_wallet`, `ewallet`, `unhosted_wallet`, `other`." }, "accountId": { "type": "string", "description": "Identificador de conta (mapeia para `account_id`): IBAN, impressão digital do cartão ou endereço de carteira." }, "issuingCountry": { "type": "string", "description": "Código de país ISO 3166-1 alfa-3 do emissor (mapeia para `issuing_country`)." } } } } }, "counterparty": { "type": "object", "description": "A contraparte da transação (opcional). Mesma estrutura que `subject`; `externalUserId` tem relevância aqui.", "properties": { "type": { "type": "string", "description": "Tipo de entidade (mapeia para `entity_type`): `individual` ou `company`." }, "externalUserId": { "type": "string", "description": "O seu identificador interno para a contraparte (mapeia para `vendor_data`)." }, "fullName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dob": { "type": "string", "format": "date" }, "address": { "type": "object" }, "institutionInfo": { "type": "object" }, "device": { "type": "object" }, "paymentMethod": { "type": "object", "description": "Método de pagamento utilizado pela contraparte (mapeia para `payment_method`). Em transações de travelRule, `type: \"unhosted_wallet\"` declara a carteira da contraparte como autocustodiada: a transferência ignora o encaminhamento VASP da contraparte, é criada diretamente em `UNCONFIRMED_OWNERSHIP` e (quando `auto_wallet_verification` está ativado) uma sessão de widget de propriedade da carteira é criada automaticamente e devolvida em `action_required` para que o SDK a possa iniciar.", "properties": { "type": { "type": "string", "description": "Tipo de método de pagamento (mapeia para `method_type`), por exemplo, `bank_card`, `bank_account`, `crypto_wallet`, `ewallet`, `unhosted_wallet`, `other`. Utilize `unhosted_wallet` para declarar uma carteira autocustodiada para a Travel Rule." }, "accountId": { "type": "string", "description": "Identificador de conta (mapeia para `account_id`): IBAN, impressão digital do cartão ou endereço de carteira." }, "issuingCountry": { "type": "string" } } } } }, "props": { "type": "object", "additionalProperties": true, "description": "Pares chave-valor personalizados (mapeia para `custom_properties`). Cada chave pode ser referenciada em condições de regras como `custom_values.`." }, "travelRule": { "type": "object", "description": "Detalhes da Travel Rule (mapeia para `travel_rule_details`). Quando a Travel Rule está ativada para a aplicação, a Didit ignora qualquer `status` que envie e gere a troca por si própria.", "required": [ "status" ], "properties": { "status": { "type": "string" }, "protocol": { "type": "string" }, "required": { "type": "boolean" }, "obligationsCount": { "type": "integer" }, "originatorData": { "type": "object" }, "beneficiaryData": { "type": "object" }, "metadata": { "type": "object" } } }, "includeCryptoScreening": { "type": "boolean", "nullable": true, "description": "Substituição por transação para a triagem de análise de blockchain de criptoativos (mapeia para `include_crypto_screening`)." }, "fingerprint_v2": { "type": "object", "description": "O payload de impressão digital do dispositivo `didit-fp-v2`. Injetado automaticamente pelos SDKs; apenas relevante ao chamar diretamente a wire API." } }, "required": [ "txnId", "type", "info", "subject" ] }, "example": { "txnId": "wd-2026-07-07-0042", "type": "travelRule", "info": { "direction": "out", "amount": "0.25", "currency": "ETH", "currencyType": "crypto", "cryptoParams": { "crypto_chain": "ETH" } }, "subject": { "fullName": "Jane Doe" }, "counterparty": { "fullName": "Ana Diaz", "paymentMethod": { "type": "unhosted_wallet", "accountId": "0xBeneficiaryWallet01" } }, "travelRule": { "status": "AWAITING_COUNTERPARTY", "beneficiaryData": { "wallet_address": "0xBeneficiaryWallet01", "name": "Ana Diaz" } }, "includeCryptoScreening": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v1/transactions/ \\\n -H 'X-Transaction-Token: SDK_TOKEN' -H 'Content-Type: application/json' \\\n -d '{\"txnId\": \"wd-2026-07-07-0042\", \"type\": \"travelRule\", \"info\": {\"direction\": \"out\", \"amount\": \"0.25\", \"currency\": \"ETH\", \"currencyType\": \"crypto\"}, \"subject\": {\"fullName\": \"Jane Doe\"}, \"counterparty\": {\"fullName\": \"Ana Diaz\", \"paymentMethod\": {\"type\": \"unhosted_wallet\", \"accountId\": \"0xBeneficiaryWallet01\"}}, \"travelRule\": {\"status\": \"AWAITING_COUNTERPARTY\", \"beneficiaryData\": {\"wallet_address\": \"0xBeneficiaryWallet01\", \"name\": \"Ana Diaz\"}}, \"includeCryptoScreening\": true}'" }, { "lang": "javascript", "label": "Web SDK", "source": "import { DiditSdk } from '@didit-protocol/sdk-web';\n\nconst result = await DiditSdk.shared.submitTransaction({\n transactionToken: sdkToken,\n transaction: {\n txnId: 'wd-2026-07-07-0042',\n category: 'travelRule',\n details: { direction: 'out', amount: '0.25', currency: 'ETH', currencyType: 'crypto' },\n subject: { fullName: 'Jane Doe' },\n counterparty: { fullName: 'Ana Diaz', paymentMethod: { type: 'unhosted_wallet', accountId: '0xBeneficiaryWallet01' } },\n travelRule: { status: 'AWAITING_COUNTERPARTY', beneficiaryData: { wallet_address: '0xBeneficiaryWallet01', name: 'Ana Diaz' } },\n includeCryptoScreening: true\n },\n onActionCompleted: (refreshed) => console.log(refreshed.status)\n});" } ], "responses": { "201": { "description": "Transação submetida e monitorizada. Mesma estrutura de detalhes de `GET /v3/transactions/{transaction_id}/`, incluindo o bloco `action_required` quando o utilizador final tem de concluir uma ação de seguimento (os SDKs iniciam-na automaticamente por predefinição).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "Wallet ownership required": { "value": { "uuid": "22222222-3333-4444-5555-666666666666", "txn_id": "wd-2026-07-07-0042", "transaction_type": "travelRule", "direction": "OUTBOUND", "status": "APPROVED", "amount": "0.25", "currency": "ETH", "travel_rule": { "uuid": "33333333-4444-5555-6666-777777777777", "status": "UNCONFIRMED_OWNERSHIP", "required": true }, "action_required": { "type": "wallet_ownership", "url": "https://verify.didit.me/wallet-ownership/3s9x...urlsafe", "widget_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "expires_at": "2026-07-07T13:00:00Z" } } } } } } }, "400": { "description": "A validação falhou (campos obrigatórios em falta, `txnId` duplicado, categoria desconhecida).", "content": { "application/json": { "examples": { "Missing fields": { "value": { "transaction_details": { "currency": [ "This field is required." ] } } }, "Duplicate txnId": { "value": { "transaction_id": [ "A transaction with this transaction_id already exists." ] } } } } } }, "401": { "description": "O token de transação foi rejeitado: em falta, desconhecido, revogado, excedeu o respetivo `max_uses` ou expirou. As respostas de token expirado contêm sempre a palavra `expired` nos detalhes, sendo assim que os SDKs distinguem os erros `expired_token` de `invalid_token`.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "Invalid transaction token." } }, "Expired token": { "value": { "detail": "Transaction token expired." } } } } } }, "409": { "description": "Outro pedido com o mesmo `txnId` criou a transação enquanto este estava a ser processado, pelo que apenas uma de duas submissões simultâneas tem êxito. Consulte a transação existente em vez de submeter novamente.", "content": { "application/json": { "examples": { "Concurrent duplicate": { "value": { "detail": "A transaction with this transaction_id already exists." } } } } } } } } }, "/v1/transactions/{transaction_id}/": { "get": { "summary": "Obter transação a partir de um SDK", "description": "Endpoint de leitura virado para o dispositivo, autenticado com o mesmo `X-Transaction-Token` utilizado para submeter. Os SDKs consultam-no periodicamente após um fluxo de ação iniciado automaticamente terminar ou a sua janela fechar, para que o estado final nunca dependa de uma única notificação. Devolve os mesmos detalhes da transação que a resposta de submissão, incluindo o bloco `action_required` atual (`null` assim que a ação for resolvida).", "operationId": "getTransactionFromSdk", "x-didit-sdk": { "resource": "transactions", "method": "retrieve_from_device", "auth": "device_token", "server": false }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID de transação estável da Didit (o `uuid` da resposta de submissão, **não** o seu `txnId`).", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "security": [ { "TransactionTokenAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v1/transactions/22222222-3333-4444-5555-666666666666/' \\\n -H 'X-Transaction-Token: SDK_TOKEN'" } ], "responses": { "200": { "description": "Os detalhes completos da transação, incluindo `action_required` (`null` assim que a ação pendente for resolvida).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" } } } }, "401": { "description": "O token de transação foi rejeitado: em falta, desconhecido, revogado, excedeu o respetivo `max_uses` ou expirou.", "content": { "application/json": { "examples": { "Expired token": { "value": { "detail": "Transaction token expired." } } } } } }, "404": { "description": "Não existe nenhuma transação com este UUID para a aplicação do token, ou o segmento de caminho não é um UUID válido.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } } } } }, "/v3/businesses/": { "get": { "summary": "Listar empresas", "description": "Listar [empresas](/entities/businesses) que a Didit reúne a partir de sessões de KYB que partilham o mesmo `vendor_data` (cadeia de carateres livre, NÃO um UUID), mais empresas criadas através da API. Paginado, ordenado por `last_session_at` desc. Este endpoint não suporta parâmetros de filtro ou pesquisa — obtenha as páginas e filtre do lado do cliente.", "operationId": "list_businesses", "x-didit-sdk": { "resource": "businesses", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Tamanho da página. A predefinição é 50 quando omitido. Não existe um limite máximo imposto, mas mantenha as páginas pequenas para reduzir a latência." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Offset de base zero do primeiro registo a devolver. Prefira seguir o URL `next` da página anterior em vez de calcular este valor manualmente." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/businesses/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.businesses.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.businesses.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Businesses.ListAutoPaging(ctx, didit.BusinessesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.businesses().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "businesses->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.businesses.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Businesses.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Lista paginada de empresas com estado, contagem de sessões e detalhe de funcionalidades.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número de linhas correspondentes — exato até 100, limitado a 100 acima disso por motivos de desempenho. Não o utilize para detetar a última página; em vez disso, confie no facto de `next` ser `null`." }, "next": { "type": "string", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessListItem" } } } }, "examples": { "Example": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "ACTIVE", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z" } ] } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode listar empresas para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/customization/": { "get": { "summary": "Obter personalização de marca", "description": "Devolve a imagem de marca de marca branca para a aplicação, determinada a partir da chave de API: cores, tipos de letra, raios de curvatura dos cantos, URLs de logótipos e opções de UI/UX. As definições de domínio personalizado e de e-mail de marca branca são geridas apenas na Business Console e não fazem parte desta resposta.", "operationId": "get_customization", "x-didit-sdk": { "resource": "customization", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Customization" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.customization.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.customization.retrieve();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Customization.Retrieve(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.customization().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "customization->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.customization.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Customization.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Personalização de marca atual para a aplicação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomization" }, "examples": { "Default branding": { "value": { "color_primary": "#000000", "color_secondary": "#9DA1A1", "color_background": "#FFFFFF", "color_panel": "#2567FF", "color_panel_10": "#1A1A1A", "color_on_panel_1": "#9DA1A1", "color_on_panel_2": "#F4F4F6", "color_on_background": "#000000", "color_button_1": "#2567FF", "color_button_2": "#F8F8F8", "color_button_text_1": "#FFFFFF", "color_button_text_2": "#000000", "color_pill_text": "#111827", "border_radius_panel": 10, "border_radius_buttons": 12, "font_family": "Inter", "font_weight": "regular", "font_url": "https://fonts.googleapis.com/css2?family=Inter", "logo_square": null, "logo_rectangular": null, "logo_rectangular_dark": null, "favicon": null, "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": false, "disable_login_with_didit": false, "hide_progress_bar": false, "callback_seconds": 3 } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar personalização de marca", "description": "Atualização parcial da personalização de marca branca da aplicação. Envie `application/json` para alterar cores, tipos de letra, raios e opções de interface do utilizador, ou `multipart/form-data` para carregar imagens de logótipos. Apenas os campos que incluir são alterados. Domínio personalizado e e-mail com marca branca não podem ser definidos através deste endpoint — utilize a Business Console para esses fins.", "operationId": "update_customization", "x-didit-sdk": { "resource": "customization", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Customization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomizationUpdate" }, "examples": { "Update colors and font": { "summary": "Alterar cores da marca e tipo de letra", "value": { "color_primary": "#123456", "color_button_1": "#2567FF", "font_family": "AR One Sans", "border_radius_buttons": 16 } }, "Update UI options": { "summary": "Alterar nome público e opções do fluxo", "value": { "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": true, "hide_progress_bar": true, "callback_seconds": 5 } }, "Remove a logo": { "summary": "Eliminar o logótipo retangular atual", "value": { "delete_logo_rectangular": true } }, "Remove the dark-mode logo": { "summary": "Eliminar o logótipo atual do modo escuro", "value": { "delete_logo_rectangular_dark": true } } } }, "multipart/form-data": { "schema": { "type": "object", "description": "Utilize multipart/form-data apenas para carregar imagens de logótipo. Os campos de marca acima também podem ser enviados como campos de formulário no mesmo pedido.", "properties": { "image_square": { "type": "string", "format": "binary", "description": "Logótipo quadrado (proporção 1:1). PNG, JPG ou WebP, com pelo menos 512 px no lado mais longo, no máximo **1 MB**." }, "image_rectangular": { "type": "string", "format": "binary", "description": "Logótipo retangular (proporção 2:1). PNG, JPG ou WebP, com pelo menos 512 px no lado mais longo, no máximo **1 MB**." }, "image_rectangular_dark": { "type": "string", "format": "binary", "description": "Logótipo retangular para o modo escuro (proporção 2:1), apresentado num fundo escuro. PNG, JPG ou WebP, com pelo menos 512 px no lado mais longo, no máximo **1 MB**. Devolvido como `logo_rectangular_dark`." }, "image_favicon": { "type": "string", "format": "binary", "description": "Imagem do favicon. Máx. **500 KB**." } } }, "example": { "image_rectangular": "(binary PNG logo, 2:1)", "image_rectangular_dark": "(binary PNG logo for dark mode, 2:1)", "image_favicon": "(binary favicon)" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"color_primary\": \"#123456\", \"font_family\": \"AR One Sans\"}'" }, { "lang": "curl", "label": "curl (logo upload)", "source": "curl -X PATCH 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'image_rectangular=@logo.png' \\\n -F 'image_rectangular_dark=@logo-dark.png' \\\n -F 'image_favicon=@favicon.ico'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.customization.update(\n image_rectangular=open(\"image_rectangular.jpg\", \"rb\"),\n image_rectangular_dark=open(\"image_rectangular_dark.jpg\", \"rb\"),\n image_favicon=open(\"image_favicon.jpg\", \"rb\"),\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.customization.update({\n image_rectangular: await fileFromPath(\"image_rectangular.jpg\"),\n image_rectangular_dark: await fileFromPath(\"image_rectangular_dark.jpg\"),\n image_favicon: await fileFromPath(\"image_favicon.jpg\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Customization.Update(ctx, didit.CustomizationUpdateParams{\n\tImageRectangular: didit.Some(didit.FileFromPath(\"image_rectangular.jpg\")),\n\tImageRectangularDark: didit.Some(didit.FileFromPath(\"image_rectangular_dark.jpg\")),\n\tImageFavicon: didit.Some(didit.FileFromPath(\"image_favicon.jpg\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.CustomizationUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.customization().update(CustomizationUpdateParams.builder()\n .imageRectangular(Path.of(\"image_rectangular.jpg\"))\n .imageRectangularDark(Path.of(\"image_rectangular_dark.jpg\"))\n .imageFavicon(Path.of(\"image_favicon.jpg\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "customization->update([\n 'image_rectangular' => File::fromPath('image_rectangular.jpg'),\n 'image_rectangular_dark' => File::fromPath('image_rectangular_dark.jpg'),\n 'image_favicon' => File::fromPath('image_favicon.jpg'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.customization.update(\n image_rectangular: Pathname(\"image_rectangular.jpg\"),\n image_rectangular_dark: Pathname(\"image_rectangular_dark.jpg\"),\n image_favicon: Pathname(\"image_favicon.jpg\")\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Customization.UpdateAsync(new CustomizationUpdateParams\n{\n ImageRectangular = FileUpload.FromPath(\"image_rectangular.jpg\"),\n ImageRectangularDark = FileUpload.FromPath(\"image_rectangular_dark.jpg\"),\n ImageFavicon = FileUpload.FromPath(\"image_favicon.jpg\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Identidade visual atualizada. É devolvido o objeto COMPLETO de identidade visual (todos os campos, não apenas os que alterou).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomization" }, "examples": { "Updated": { "value": { "color_primary": "#123456", "color_secondary": "#9DA1A1", "color_background": "#FFFFFF", "color_panel": "#2567FF", "color_panel_10": "#1A1A1A", "color_on_panel_1": "#9DA1A1", "color_on_panel_2": "#F4F4F6", "color_on_background": "#000000", "color_button_1": "#2567FF", "color_button_2": "#F8F8F8", "color_button_text_1": "#FFFFFF", "color_button_text_2": "#000000", "color_pill_text": "#111827", "border_radius_panel": 10, "border_radius_buttons": 16, "font_family": "AR One Sans", "font_weight": "400", "font_url": "https://fonts.googleapis.com/css2?family=AR+One+Sans", "logo_square": null, "logo_rectangular": "https://cdn.didit.me/white_label/logo_rectangular/...", "logo_rectangular_dark": null, "favicon": null, "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": true, "disable_login_with_didit": false, "hide_progress_bar": false, "callback_seconds": 3 } } } } } }, "400": { "description": "Corpo inválido. Por exemplo: uma cor hexadecimal malformatada, uma família ou peso de tipo de letra desconhecido, um campo exclusivo da Business Console (`domain`, `from_email`, `verify_domain`, `force_remove_domain`, `verify_email_domain`, `force_remove_email_domain` e os respetivos equivalentes de apenas leitura) ou um carregamento de logótipo que não seja uma imagem PNG, JPG ou WebP, tenha menos de 512 px no lado mais longo, tenha mais de 1 MB ou tenha uma proporção incorreta. Também devolvido ao definir `disable_login_with_didit` como `false` enquanto um domínio personalizado estiver configurado.", "content": { "application/json": { "examples": { "Bad color": { "value": { "color_primary": [ "Invalid color format. Use '#RRGGBB' or '#RRGGBBAA' format." ] } }, "Bad logo": { "value": { "image_rectangular": [ "Image aspect ratio must be 2:1. Got 1024x1024 image dimensions" ] } }, "Unsupported logo format": { "summary": "Não é uma imagem PNG, JPG ou WebP (um SVG, por exemplo)", "value": { "image_rectangular_dark": [ "Upload a PNG, JPG or WebP image." ] } }, "Logo too small": { "summary": "Inferior a 512 px no lado mais longo", "value": { "image_rectangular": [ "Image must be at least 512 px on its long side. Got 400x200 image dimensions" ] } }, "Logo too large": { "summary": "Mais de 1 MB", "value": { "image_square": [ "File size should not exceed 1 MB" ] } }, "Console-only field": { "value": { "domain": [ "Manage this field in the Business Console." ] } }, "Bad font weight": { "value": { "font_weight": [ "Font weight 950 is not available for Inter. Available weights are: 100, 200, 300, 400, 500, 600, 700, 800, 900" ] } } } } } }, "403": { "description": "Chave de API em falta, mal formatada, expirada ou com âmbito limitado a uma aplicação diferente. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido. Tente novamente com recuo exponencial." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/{vendor_data}/": { "get": { "summary": "Obter empresa", "description": "Obter uma [empresa](/entities/businesses) por `vendor_data` (correspondência exata). Adiciona `metadata` e `updated_at` à visualização em lista. Empresas eliminadas devolvem 404.", "operationId": "get_business", "x-didit-sdk": { "resource": "businesses", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O seu identificador exclusivo para a empresa — uma string de formato livre (NÃO um UUID), correspondida exatamente como enviada.", "example": "company-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/businesses/company-123/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.retrieve(\n \"company-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieve(\"company-123\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Retrieve(ctx, \"company-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieve(\"company-123\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieve('company-123');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve(\"company-123\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveAsync(\"company-123\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhe completo da empresa incluindo metadados e dados agregados da sessão.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Active business": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "ACTIVE", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode ler as empresas desta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhuma empresa (não eliminada) com o `vendor_data` fornecido para esta aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar empresa", "description": "Atualização parcial de uma empresa: `display_name`, `legal_name`, `registration_number`, `country_code`, `status`, `metadata`. `metadata` substitui completamente. Definir `status` como `BLOCKED` adiciona os `vendor_data` à lista de bloqueio do sistema; alterar para outro valor diferente de `BLOCKED` remove essa entrada. Cada edição é registada na atividade da empresa: uma alteração de estado com o `reason` opcional, e uma alteração em `display_name`, `legal_name`, `registration_number`, `country_code` ou `metadata` como uma atualização de perfil.", "operationId": "update_business", "x-didit-sdk": { "resource": "businesses", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O seu identificador exclusivo para a empresa (string de formato livre, NÃO um UUID).", "example": "company-123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Corpo de atualização parcial. Forneça apenas os campos que pretende alterar.", "properties": { "display_name": { "type": "string", "nullable": true, "description": "Nome de apresentação amigável apresentado na consola (tem precedência sobre `legal_name` para exibição na IU)." }, "legal_name": { "type": "string", "nullable": true, "description": "Denominação legal oficial proveniente do registo ou introduzida manualmente." }, "registration_number": { "type": "string", "nullable": true, "description": "Número de registo ou de constituição da empresa." }, "country_code": { "type": "string", "nullable": true, "description": "País de constituição (ISO 3166-1 alpha-2, por ex., `GB`, `US`)." }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Estado do ciclo de vida da empresa. Definir `BLOCKED` adiciona automaticamente o `vendor_data` à lista de bloqueio do sistema; alternar para outro valor diferente de `BLOCKED` remove essa entrada da lista de bloqueio." }, "metadata": { "type": "object", "nullable": true, "description": "Objeto JSON arbitrário que associa à empresa. **Substitui totalmente** os metadados existentes na atualização — faça a junção no lado do cliente se pretender apenas adicionar chaves." }, "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "O motivo da alteração de estado. Registado na entrada de alteração de estado em **Activity** da empresa na Business Console, apenas quando o estado realmente muda. Os webhooks não o transmitem." } } }, "examples": { "Update name": { "summary": "Atualizar nome de apresentação", "value": { "display_name": "Acme Corp" } }, "Flag for review": { "summary": "Alterar estado", "value": { "status": "FLAGGED" } }, "Add metadata": { "summary": "Substituir JSON de metadados", "value": { "metadata": { "industry": "fintech", "risk_level": "low" } } }, "Fix registry data": { "summary": "Campos extraídos corretos", "value": { "legal_name": "Acme Trading International Ltd", "registration_number": "12345678", "country_code": "GB" } }, "Flag with reason": { "summary": "Sinalizar a empresa e registar o motivo", "value": { "status": "FLAGGED", "reason": "Ownership structure under review" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"display_name\": \"Acme Corp\", \"status\": \"FLAGGED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.update(\n \"company-123\",\n display_name=\"Acme Corp\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.update(\"company-123\", {\n display_name: \"Acme Corp\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Update(ctx, \"company-123\", didit.BusinessesUpdateParams{\n\tDisplayName: didit.String(\"Acme Corp\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().update(\"company-123\", BusinessesUpdateParams.builder()\n .displayName(\"Acme Corp\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->update('company-123', [\n 'display_name' => 'Acme Corp',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.update(\n \"company-123\",\n display_name: \"Acme Corp\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.UpdateAsync(\"company-123\", new BusinessesUpdateParams\n{\n DisplayName = \"Acme Corp\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Empresa atualizada. O registo completo atualizado da empresa é devolvido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Updated": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": "Acme Corp", "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Corp", "status": "FLAGGED", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech", "risk_level": "low" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "Corpo inválido: normalmente um `status` desconhecido, um campo `metadata` malformado ou um `reason` com mais de 1000 carateres.", "content": { "application/json": { "examples": { "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode atualizar empresas para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhuma empresa (não eliminada) com o `vendor_data` fornecido para esta aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/{vendor_data}/update-status/": { "patch": { "summary": "Atualizar estado da empresa", "description": "Altera apenas o `status` do ciclo de vida de uma empresa: `ACTIVE`, `FLAGGED` ou `BLOCKED` (não os estados da sessão). `BLOCKED` adiciona o `vendor_data` à lista de bloqueio do sistema; sair de `BLOCKED` remove essa entrada. Cada alteração é registada na atividade da empresa, com o `reason` opcional. Enviar o estado atual não altera nada e não regista nenhum `reason`. O webhook `business.status.updated` não inclui o `reason`.", "operationId": "update_business_status", "x-didit-sdk": { "resource": "businesses", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O seu identificador exclusivo para a empresa (string de formato livre, NÃO um UUID).", "example": "company-123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityStatusUpdateRequest" }, { "type": "object", "properties": { "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "O motivo da alteração de estado. Registado na entrada de alteração de estado em **Activity** da empresa na Business Console, apenas quando o estado realmente muda. Os webhooks não o transmitem." } } } ] }, "examples": { "Flag": { "summary": "Sinalizar a empresa para revisão", "value": { "status": "FLAGGED" } }, "Block": { "summary": "Bloquear a empresa (adiciona à lista de bloqueio do sistema)", "value": { "status": "BLOCKED" } }, "Reactivate": { "summary": "Reativar a empresa", "value": { "status": "ACTIVE" } }, "Block with reason": { "summary": "Bloquear a empresa e registar o motivo", "value": { "status": "BLOCKED", "reason": "Registry shows the company dissolved" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/update-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"BLOCKED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.update_status(\n \"company-123\",\n status=\"FLAGGED\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.updateStatus(\"company-123\", {\n status: \"FLAGGED\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.UpdateStatus(ctx, \"company-123\", didit.BusinessesUpdateStatusParams{\n\tStatus: \"FLAGGED\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesUpdateStatusParams;\nimport me.didit.types.EntityStatusUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().updateStatus(\"company-123\", BusinessesUpdateStatusParams.builder()\n .status(EntityStatusUpdateRequest.Status.of(\"FLAGGED\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->updateStatus('company-123', [\n 'status' => 'FLAGGED',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.update_status(\n \"company-123\",\n status: \"FLAGGED\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.UpdateStatusAsync(\"company-123\", new BusinessesUpdateStatusParams\n{\n Status = \"FLAGGED\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Estado da empresa atualizado. Registo completo da empresa devolvido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Blocked": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "BLOCKED", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "`status` em falta ou inválido, ou um `reason` com mais de 1000 carateres.", "content": { "application/json": { "examples": { "Missing status": { "value": { "status": [ "This field is required." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode atualizar empresas para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhuma empresa (não eliminada) com o `vendor_data` fornecido para esta aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/delete/": { "post": { "summary": "Eliminar empresas em lote", "description": "**Elimine permanentemente** empresas — isto não pode ser anulado. Para bloqueio, prefira [Update Business Status](#patch-/v3/businesses/-vendor_data-/update-status/) com `BLOCKED`.\n\n**Relatórios regulamentares submetidos:** se os dados selecionados estiverem num relatório regulamentar finalizado, todo o pedido é recusado com `409` e nada é eliminado. O corpo utiliza `code: in_filed_report` e identifica cada relatório com `uuid`, `report_number`, `report_type` e `case_uuid`. Elimine os relatórios e repita o pedido.", "operationId": "batch_delete_businesses", "x-didit-sdk": { "resource": "businesses", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Forneça `vendor_data_list`, `didit_internal_id_list` ou `delete_all: true`. Ordem de precedência quando vários são enviados: `delete_all` > `vendor_data_list` > `didit_internal_id_list` (apenas o seletor com maior precedência é utilizado).", "properties": { "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "Os seus próprios identificadores a eliminar, correspondidos exatamente como foram enviados." }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "UUIDs internos da Didit (`didit_internal_id`) a eliminar." }, "delete_all": { "type": "boolean", "default": false, "description": "Se `true`, elimina todas as empresas na aplicação. Não pode ser combinado com os seletores de lista." } } }, "examples": { "Specific businesses": { "summary": "Eliminar por vendor_data", "value": { "vendor_data_list": [ "company-123", "company-456" ] } }, "Specific internal IDs": { "summary": "Eliminar por didit_internal_id", "value": { "didit_internal_id_list": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] } }, "All businesses": { "summary": "Apagar todas as empresas nesta aplicação", "value": { "delete_all": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data_list\": [\"company-123\", \"company-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.batch_delete(\n vendor_data_list=[\"company-123\", \"company-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.batchDelete({\n vendor_data_list: [\"company-123\", \"company-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.BatchDelete(ctx, didit.BusinessesBatchDeleteParams{\n\tVendorDataList: didit.Some([]string{\"company-123\", \"company-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().batchDelete(BusinessesBatchDeleteParams.builder()\n .vendorDataList(List.of(\"company-123\", \"company-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->batchDelete([\n 'vendor_data_list' => ['company-123', 'company-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.batch_delete(vendor_data_list: [\"company-123\", \"company-456\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.BatchDeleteAsync(new BusinessesBatchDeleteParams\n{\n VendorDataList = new string[] { \"company-123\", \"company-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Empresas eliminadas. Devolve o número de linhas efetivamente removidas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "Número de empresas eliminadas (exclui valores de vendor_data que não corresponderam a nada)." } } }, "examples": { "Deleted some": { "value": { "deleted": 2 } }, "Nothing matched": { "value": { "deleted": 0 } } } } } }, "400": { "description": "Nenhum seletor fornecido (todos os campos `vendor_data_list`, `didit_internal_id_list` e `delete_all` estão em falta ou vazios). O corpo do erro é um array JSON.", "content": { "application/json": { "examples": { "Missing selector": { "value": [ "Provide vendor_data_list, didit_internal_id_list, or set delete_all=true." ] } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode eliminar empresas para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } }, "409": { "description": "Nada é eliminado. O `code` indica o motivo: `in_filed_report` quando a seleção inclui uma empresa num relatório regulamentar finalizado, `subject_deletion_in_progress` quando outro pedido ainda está a eliminar uma das empresas selecionadas. Repita o pedido assim que essa eliminação estiver concluída.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InFiledReportError" }, { "$ref": "#/components/schemas/SubjectDeletionInProgressError" } ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/aml-monitoring/": { "post": { "summary": "Ativar ou desativar a monitorização AML contínua para utilizadores", "description": "Ativa ou desativa a monitorização AML contínua para os utilizadores selecionados, com a mesma semântica da Business Console. É mantida exatamente uma triagem AML monitorizada por utilizador, pelo que um perfil que tenha sido verificado várias vezes é monitorizado e faturado uma única vez; a desativação desliga a monitorização em todas as triagens do perfil. Os utilizadores sem qualquer triagem AML são analisados primeiro (faturados como uma triagem AML normal) quando possuem o nome completo, data de nascimento e país necessários; caso contrário, são reportados como `skipped_no_identity_data`.\n\nDefina `estimate_only: true` para pré-visualizar contagens e custos sem escrever nada. As seleções de 20 perfis ou menos são resolvidas imediatamente e devolvem `200` com a tarefa concluída; seleções maiores devolvem `202` e são executadas em segundo plano - faça pedidos repetidos a [Obter tarefa de monitorização AML](#get-/v3/aml-monitoring/jobs/-job_id-/) com o `job_id` devolvido. A ativação é recusada com `403` quando o saldo da organização não cobre a estimativa. Os identificadores que não correspondam a nenhum registo são listados em `unmatched` e nunca fazem falhar o pedido: uma seleção que não corresponda a nada conclui como uma tarefa vazia (`total` 0), a mesma convenção aplicada aos endpoints de eliminação em lote.", "operationId": "toggle_users_aml_monitoring", "x-didit-sdk": { "resource": "users", "method": "set_aml_monitoring", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "description": "Selecione utilizadores com `vendor_data_list`, `didit_internal_id_list` ou ambos (as duas listas são combinadas com o operador OR). No máximo 1000 identificadores por pedido no total, nas duas listas.", "properties": { "is_enabled": { "type": "boolean", "description": "true para ativar a monitorização, false para a desativar." }, "estimate_only": { "type": "boolean", "default": false, "description": "Quando for true, devolve a estimativa de custos e não realiza gravações: sem triagem, sem faturação e sem tarefa." }, "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "Os seus próprios identificadores dos utilizadores a alternar, correspondidos exatamente como foram enviados." }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs internos da Didit dos utilizadores a alternar - o `didit_internal_id` devolvido pelos endpoints de criação, obtenção e listagem." } } }, "examples": { "Estimate first": { "summary": "Pré-visualizar o custo sem efetuar alterações", "value": { "is_enabled": true, "estimate_only": true, "vendor_data_list": [ "user-123", "user-456" ] } }, "Enable": { "summary": "Ativar a monitorização para dois utilizadores", "value": { "is_enabled": true, "vendor_data_list": [ "user-123", "user-456" ] } }, "Disable": { "summary": "Desativar a monitorização pelo id interno da Didit", "value": { "is_enabled": false, "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/aml-monitoring/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"vendor_data_list\": [\"user-123\", \"user-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.set_aml_monitoring(\n is_enabled=True,\n estimate_only=True,\n vendor_data_list=[\"user-123\", \"user-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.setAmlMonitoring({\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"user-123\", \"user-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.SetAMLMonitoring(ctx, didit.UsersSetAMLMonitoringParams{\n\tIsEnabled: true,\n\tEstimateOnly: didit.Bool(true),\n\tVendorDataList: didit.Some([]string{\"user-123\", \"user-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.UsersSetAmlMonitoringParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().setAmlMonitoring(UsersSetAmlMonitoringParams.builder()\n .isEnabled(true)\n .estimateOnly(true)\n .vendorDataList(List.of(\"user-123\", \"user-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->setAmlMonitoring([\n 'is_enabled' => true,\n 'estimate_only' => true,\n 'vendor_data_list' => ['user-123', 'user-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.set_aml_monitoring(\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"user-123\", \"user-456\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.SetAmlMonitoringAsync(new UsersSetAmlMonitoringParams\n{\n IsEnabled = true,\n EstimateOnly = true,\n VendorDataList = new string[] { \"user-123\", \"user-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A estimativa (quando `estimate_only` é true) ou a tarefa concluída para uma seleção processada inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringToggleResult" } } } }, "202": { "description": "Seleções maiores são executadas em segundo plano. Consulte periodicamente o endpoint de tarefas com o `job_id`; o campo `results` vai sendo preenchido à medida que os perfis são processados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringJob" } } } }, "400": { "description": "Erro de validação: `is_enabled` em falta, nenhum seletor ou mais de 1000 identificadores em ambas as listas." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "Saldo insuficiente para ativar a monitorização para esta seleção. A resposta inclui o `estimate` para que possa carregar saldo com o montante correto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "estimate": { "type": "object", "description": "Pré-visualização do custo. Devolvida diretamente quando estimate_only é true (nada é gravado).", "properties": { "users_total": { "type": "integer", "description": "Perfis correspondidos pela seleção." }, "already_enabled": { "type": "integer", "description": "Perfis já monitorizados (nada a fazer ao ativar; são estes que a desativação desliga)." }, "with_existing_aml": { "type": "integer", "description": "Perfis cuja triagem AML existente será alterada para monitorizada (sem nova triagem)." }, "needing_screening": { "type": "integer", "description": "Perfis sem qualquer triagem AML que serão submetidos a triagem primeiro (faturada como uma triagem AML normal)." }, "skipped_no_identity_data": { "type": "integer", "description": "Perfis que não podem ser submetidos a triagem porque faltam dados de identidade." }, "skipped_blocked": { "type": "integer", "description": "Utilizadores bloqueados que serão ignorados (sempre 0 para empresas)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Custo único das novas triagens." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Custo anual de monitorização dos perfis que passarão a ser monitorizados." }, "balance_sufficient": { "type": "boolean", "description": "Se o saldo da organização cobre a triagem mais o primeiro ano de monitorização." } } } } } } } } } } }, "/v3/businesses/aml-monitoring/": { "post": { "summary": "Ativar ou desativar a monitorização AML contínua para empresas", "description": "Ativa ou desativa a monitorização AML contínua para as empresas selecionadas, com a mesma semântica da Business Console. É mantida exatamente uma triagem AML monitorizada por empresa, pelo que um perfil que tenha sido verificado várias vezes é monitorizado e faturado uma única vez; a desativação desliga a monitorização em todas as triagens do perfil. As empresas sem qualquer triagem AML são analisadas primeiro (faturadas como uma triagem AML normal) quando possuem a denominação social ou nome comercial necessário; caso contrário, são reportadas como `skipped_no_identity_data`.\n\nDefina `estimate_only: true` para pré-visualizar contagens e custos sem escrever nada. As seleções de 20 perfis ou menos são resolvidas imediatamente e devolvem `200` com a tarefa concluída; seleções maiores devolvem `202` e são executadas em segundo plano - faça pedidos repetidos a [Obter tarefa de monitorização AML](#get-/v3/aml-monitoring/jobs/-job_id-/) com o `job_id` devolvido. A ativação é recusada com `403` quando o saldo da organização não cobre a estimativa. Os identificadores que não correspondam a nenhum registo são listados em `unmatched` e nunca fazem falhar o pedido: uma seleção que não corresponda a nada conclui como uma tarefa vazia (`total` 0), a mesma convenção aplicada aos endpoints de eliminação em lote.", "operationId": "toggle_businesses_aml_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_aml_monitoring", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "description": "Selecione empresas com `vendor_data_list`, `didit_internal_id_list` ou ambos (as duas listas são combinadas com o operador OR). No máximo 1000 identificadores por pedido no total, nas duas listas.", "properties": { "is_enabled": { "type": "boolean", "description": "true para ativar a monitorização, false para a desativar." }, "estimate_only": { "type": "boolean", "default": false, "description": "Quando for true, devolve a estimativa de custos e não realiza gravações: sem triagem, sem faturação e sem tarefa." }, "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "Os seus próprios identificadores das empresas a alternar, correspondidos exatamente como foram enviados." }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs internos da Didit das empresas a alternar - o `didit_internal_id` devolvido pelos endpoints de criação, obtenção e listagem." } } }, "examples": { "Estimate first": { "summary": "Pré-visualizar o custo sem efetuar alterações", "value": { "is_enabled": true, "estimate_only": true, "vendor_data_list": [ "company-123", "company-456" ] } }, "Enable": { "summary": "Ativar a monitorização para duas empresas", "value": { "is_enabled": true, "vendor_data_list": [ "company-123", "company-456" ] } }, "Disable": { "summary": "Desativar a monitorização pelo id interno da Didit", "value": { "is_enabled": false, "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/aml-monitoring/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"vendor_data_list\": [\"company-123\", \"company-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.set_aml_monitoring(\n is_enabled=True,\n estimate_only=True,\n vendor_data_list=[\"company-123\", \"company-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setAmlMonitoring({\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"company-123\", \"company-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetAMLMonitoring(ctx, didit.BusinessesSetAMLMonitoringParams{\n\tIsEnabled: true,\n\tEstimateOnly: didit.Bool(true),\n\tVendorDataList: didit.Some([]string{\"company-123\", \"company-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesSetAmlMonitoringParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().setAmlMonitoring(BusinessesSetAmlMonitoringParams.builder()\n .isEnabled(true)\n .estimateOnly(true)\n .vendorDataList(List.of(\"company-123\", \"company-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setAmlMonitoring([\n 'is_enabled' => true,\n 'estimate_only' => true,\n 'vendor_data_list' => ['company-123', 'company-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_aml_monitoring(\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"company-123\", \"company-456\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetAmlMonitoringAsync(new BusinessesSetAmlMonitoringParams\n{\n IsEnabled = true,\n EstimateOnly = true,\n VendorDataList = new string[] { \"company-123\", \"company-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A estimativa (quando `estimate_only` é true) ou a tarefa concluída para uma seleção processada inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringToggleResult" } } } }, "202": { "description": "Seleções maiores são executadas em segundo plano. Consulte periodicamente o endpoint de tarefas com o `job_id`; o campo `results` vai sendo preenchido à medida que os perfis são processados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringJob" } } } }, "400": { "description": "Erro de validação: `is_enabled` em falta, nenhum seletor ou mais de 1000 identificadores em ambas as listas." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "Saldo insuficiente para ativar a monitorização para esta seleção. A resposta inclui o `estimate` para que possa carregar saldo com o montante correto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "estimate": { "type": "object", "description": "Pré-visualização do custo. Devolvida diretamente quando estimate_only é true (nada é gravado).", "properties": { "users_total": { "type": "integer", "description": "Perfis correspondidos pela seleção." }, "already_enabled": { "type": "integer", "description": "Perfis já monitorizados (nada a fazer ao ativar; são estes que a desativação desliga)." }, "with_existing_aml": { "type": "integer", "description": "Perfis cuja triagem AML existente será alterada para monitorizada (sem nova triagem)." }, "needing_screening": { "type": "integer", "description": "Perfis sem qualquer triagem AML que serão submetidos a triagem primeiro (faturada como uma triagem AML normal)." }, "skipped_no_identity_data": { "type": "integer", "description": "Perfis que não podem ser submetidos a triagem porque faltam dados de identidade." }, "skipped_blocked": { "type": "integer", "description": "Utilizadores bloqueados que serão ignorados (sempre 0 para empresas)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Custo único das novas triagens." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Custo anual de monitorização dos perfis que passarão a ser monitorizados." }, "balance_sufficient": { "type": "boolean", "description": "Se o saldo da organização cobre a triagem mais o primeiro ano de monitorização." } } } } } } } } } } }, "/v3/aml-monitoring/jobs/{job_id}/": { "get": { "summary": "Obter tarefa de monitorização AML contínua", "description": "Estado, contadores de resultados e resultados por registo de uma tarefa de ativação/desativação da monitorização iniciada a partir de `POST /v3/users/aml-monitoring/` ou `POST /v3/businesses/aml-monitoring/`. Consulte a cada dois segundos enquanto o `status` for `PENDING` ou `PROCESSING`; `results` estará completo assim que for `COMPLETED`.", "operationId": "get_aml_monitoring_job", "x-didit-sdk": { "resource": "aml_monitoring", "method": "retrieve_job", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O `job_id` devolvido pelo endpoint de ativação/desativação." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/aml-monitoring/jobs/JOB_ID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml_monitoring.retrieve_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.amlMonitoring.retrieveJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AMLMonitoring.RetrieveJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.amlMonitoring().retrieveJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "amlMonitoring->retrieveJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml_monitoring.retrieve_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AmlMonitoring.RetrieveJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A tarefa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "true quando o trabalho ativa a monitorização, false quando a desativa." }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "Qual a família de perfis que a tarefa ativa/desativa." }, "total": { "type": "integer", "description": "Perfis que a tarefa processa." }, "processed": { "type": "integer", "description": "Perfis processados até ao momento." }, "outcomes": { "type": "object", "description": "Contadores de resultados por registo. Cada perfil selecionado corresponde exatamente a um contador; nada é ignorado silenciosamente.", "properties": { "enabled": { "type": "integer", "description": "Monitorização ativada numa triagem AML existente." }, "screened_and_enabled": { "type": "integer", "description": "Foi criada uma nova triagem AML (faturada) e ativada a monitorização na mesma." }, "already_enabled": { "type": "integer", "description": "A monitorização já se encontrava ativa; nada foi alterado e nada foi faturado." }, "disabled": { "type": "integer", "description": "Monitorização desativada em todas as triagens AML do perfil." }, "skipped_no_identity_data": { "type": "integer", "description": "Ignorado: o perfil não tem o nome completo, a data de nascimento e o país (utilizadores) ou um nome (empresas) necessários para a triagem." }, "skipped_blocked": { "type": "integer", "description": "Ignorado: o utilizador está bloqueado." }, "skipped_sandbox": { "type": "integer", "description": "Ignorado: aplicação em sandbox, nenhuma triagem é criada." }, "failed_provider": { "type": "integer", "description": "Não foi possível concluir a triagem; tente novamente mais tarde." }, "failed_insufficient_balance": { "type": "integer", "description": "O saldo esgotou-se enquanto a tarefa estava em execução." } } }, "results": { "type": "array", "description": "Uma entrada por perfil processado, pela ordem de processamento. Aumenta enquanto a tarefa é executada; completa assim que o estado for COMPLETED. Registada para tarefas iniciadas através da API; uma tarefa iniciada a partir da Business Console reporta apenas contadores.", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "ID interno da Didit do perfil." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu próprio identificador para o perfil." }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "Mensagem genérica de falha quando o estado é FAILED; a causa detalhada é mantida do lado da plataforma." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "404": { "description": "Não existe essa tarefa para esta aplicação." } } } }, "/v3/users/{vendor_data}/update-status/": { "patch": { "summary": "Atualizar estado do utilizador", "description": "Altera apenas o `status` do ciclo de vida de um utilizador: `ACTIVE`, `FLAGGED` ou `BLOCKED` (não os estados da sessão). `BLOCKED` adiciona o `vendor_data` à lista de bloqueio do sistema; sair de `BLOCKED` remove essa entrada. Cada alteração é registada como uma atividade `STATUS_CHANGED` no utilizador, com o `reason` opcional como o seu `comment`. Enviar o estado atual não altera nada e não regista nenhum `reason`. O webhook `user.status.updated` não inclui o `reason`.", "operationId": "update_user_status", "x-didit-sdk": { "resource": "users", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O seu identificador exclusivo para o utilizador." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityStatusUpdateRequest" }, { "type": "object", "properties": { "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "O motivo da alteração de estado. Registado na entrada de alteração de estado da atividade do utilizador (`comments[].comment` e **Activity** na Business Console), apenas quando o estado realmente muda. Os webhooks não o transmitem." } } } ] }, "examples": { "Activate": { "summary": "Reativar o utilizador", "value": { "status": "ACTIVE" } }, "Flag": { "summary": "Sinalizar o utilizador para revisão", "value": { "status": "FLAGGED" } }, "Block": { "summary": "Bloquear o utilizador (adiciona à lista de bloqueio do sistema)", "value": { "status": "BLOCKED" } }, "Block with reason": { "summary": "Bloquear o utilizador e registar o motivo", "value": { "status": "BLOCKED", "reason": "Chargeback fraud pattern confirmed" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/update-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"BLOCKED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.update_status(\n \"user-123\",\n status=\"ACTIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.updateStatus(\"user-123\", {\n status: \"ACTIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.UpdateStatus(ctx, \"user-123\", didit.UsersUpdateStatusParams{\n\tStatus: \"ACTIVE\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EntityStatusUpdateRequest;\nimport me.didit.types.UsersUpdateStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().updateStatus(\"user-123\", UsersUpdateStatusParams.builder()\n .status(EntityStatusUpdateRequest.Status.of(\"ACTIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->updateStatus('user-123', [\n 'status' => 'ACTIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.update_status(\n \"user-123\",\n status: \"ACTIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UpdateStatusAsync(\"user-123\", new UsersUpdateStatusParams\n{\n Status = \"ACTIVE\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Estado do utilizador atualizado. Registo completo do utilizador devolvido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Blocked": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "BLOCKED", "metadata": { "tier": "premium", "source": "website" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "comment_type": "STATUS_CHANGED", "comment": "Chargeback fraud pattern confirmed", "actor_email": null, "actor_name": null, "previous_status": "ACTIVE", "new_status": "BLOCKED", "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "mentioned_emails": [], "created_at": "2025-06-15T10:30:00Z" } ], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "400": { "description": "`status` em falta ou inválido, ou um `reason` com mais de 1000 carateres.", "content": { "application/json": { "examples": { "Missing status": { "value": { "status": [ "This field is required." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "401": { "description": "Nenhuma credencial fornecida. Os pedidos para caminhos `/v3/users/*` sem um cabeçalho `x-api-key` (ou token `Authorization: Bearer`) são rejeitados pelo middleware de autenticação antes de chegarem à API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "A chave não pode atualizar utilizadores para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum utilizador (não eliminado) com o `vendor_data` fornecido para esta aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/create/": { "post": { "summary": "Criar empresa", "description": "Criar previamente uma [empresa](/entities/businesses) *sem* uma sessão de KYB. Todos os campos são opcionais, mas deve enviar sempre `vendor_data` — sem este, o registo não pode ser associado a sessões ou transações. Quando fornecido, `vendor_data` deve ser único entre empresas não eliminadas (correspondência exata; conflitos devolvem 400). Não idempotente.", "operationId": "create_business", "x-didit-sdk": { "resource": "businesses", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "O seu identificador exclusivo para esta empresa (string de formato livre, NÃO um UUID). Opcional, mas fortemente recomendado. Quando fornecido, deve ser exclusivo entre as empresas não eliminadas da aplicação; correspondido exatamente como enviado." }, "display_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Nome de apresentação amigável apresentado na consola (tem precedência sobre `legal_name` para exibição na IU)." }, "legal_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Denominação legal oficial da empresa." }, "registration_number": { "type": "string", "nullable": true, "maxLength": 100, "description": "Número de registo ou de constituição da empresa." }, "country_code": { "type": "string", "nullable": true, "maxLength": 10, "description": "País de constituição (ISO 3166-1 alpha-2, por ex., `GB`, `US`)." }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "default": "ACTIVE", "description": "Estado inicial do ciclo de vida. O padrão é `ACTIVE`." }, "metadata": { "type": "object", "nullable": true, "description": "Objeto JSON arbitrário que anexa à empresa. O valor predefinido é `{}`." } } }, "examples": { "Basic": { "summary": "Mínimo recomendado", "value": { "vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US" } }, "Full": { "summary": "Todos os campos", "value": { "vendor_data": "company-789", "display_name": "New Corp", "legal_name": "New Corp International Ltd", "registration_number": "98765432", "country_code": "DE", "status": "ACTIVE", "metadata": { "industry": "fintech", "tier": "enterprise" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/create/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"company-456\", \"legal_name\": \"New Corp Ltd\", \"country_code\": \"US\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.create(\n vendor_data=\"company-456\",\n legal_name=\"New Corp Ltd\",\n country_code=\"US\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.create({\n vendor_data: \"company-456\",\n legal_name: \"New Corp Ltd\",\n country_code: \"US\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Create(ctx, didit.BusinessesCreateParams{\n\tVendorData: didit.String(\"company-456\"),\n\tLegalName: didit.String(\"New Corp Ltd\"),\n\tCountryCode: didit.String(\"US\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().create(BusinessesCreateParams.builder()\n .vendorData(\"company-456\")\n .legalName(\"New Corp Ltd\")\n .countryCode(\"US\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->create([\n 'vendor_data' => 'company-456',\n 'legal_name' => 'New Corp Ltd',\n 'country_code' => 'US',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.create(\n vendor_data: \"company-456\",\n legal_name: \"New Corp Ltd\",\n country_code: \"US\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.CreateAsync(new BusinessesCreateParams\n{\n VendorData = \"company-456\",\n LegalName = \"New Corp Ltd\",\n CountryCode = \"US\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Empresa criada. Registo completo da empresa devolvido (mesmo formato que Obter empresa).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Created": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-456", "display_name": null, "legal_name": "New Corp Ltd", "registration_number": null, "country_code": "US", "effective_name": "New Corp Ltd", "status": "ACTIVE", "session_count": 0, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "features": {}, "features_list": [], "last_session_at": null, "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": null, "tags": [], "created_at": "2026-03-15T10:30:00Z", "metadata": {}, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "Corpo inválido — normalmente um `vendor_data` duplicado, um `status` desconhecido ou um campo `metadata` malformado.", "content": { "application/json": { "examples": { "Duplicate": { "value": { "vendor_data": [ "A business with this vendor_data already exists." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou a chave não pode criar empresas para esta aplicação. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/create/": { "post": { "summary": "Criar utilizador", "description": "Crie um [utilizador](/entities/users) com base em `vendor_data`, antes ou sem uma sessão de verificação. O `vendor_data` deve ser único entre os utilizadores da aplicação (um duplicado devolve `400`). Não idempotente.\n\n**Dados de contacto:** `email` e `phone_number` são guardados em `metadata.contact`, e `country` em `metadata.address`. Quando envia `first_name` ou `last_name` sem `full_name`, a Didit junta-os em `full_name`.\n\n**Ligação de verificação:** com `send_verification_link: true`, a Didit também cria uma sessão de verificação para a pessoa em `workflow_id` e envia-lhe a ligação por e-mail para `email`. A sessão executa as mesmas verificações que [Create Session](/pt/sessions-api/create-session), tais como a lista de bloqueio e o seu saldo de créditos. A pessoa e a sessão são criadas em conjunto ou nenhuma é criada: se alguma verificação falhar, nada é gravado e nenhum e-mail é enviado. O `verification_link` da resposta descreve a sessão, e é `null` quando não solicita uma ligação.\n\n**Acesso por chave de API:** uma chave de API com âmbito necessita de escrita em `users`. Com `send_verification_link: true`, também necessita de escrita em `sessions`, caso contrário a chamada responde com `403` antes de qualquer gravação. As chaves de acesso total não são afetadas. Consulte [Chaves de API](/pt/console/api-keys).", "operationId": "create_user", "x-didit-sdk": { "resource": "users", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "description": "O seu identificador exclusivo para este utilizador (string de formato livre, NÃO um UUID). Deve ser exclusivo entre os utilizadores da aplicação; correspondido exatamente como enviado." }, "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "Nome completo legal do utilizador." }, "display_name": { "type": "string", "nullable": true, "description": "Nome de apresentação amigável apresentado na consola (tem precedência sobre `full_name` para exibição na IU).", "maxLength": 255 }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento no formato `YYYY-MM-DD`." }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "default": "ACTIVE", "description": "Estado inicial do ciclo de vida. O padrão é `ACTIVE`." }, "metadata": { "type": "object", "nullable": true, "description": "Objeto JSON arbitrário que anexa ao utilizador. O valor predefinido é `{}`." }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "Endereços de e-mail previamente considerados fiáveis para este utilizador, por exemplo `[\"john@example.com\"]`." }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "Números de telefone previamente considerados fiáveis para este utilizador, por exemplo `[\"+14155551234\"]`." }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "Países emissores pré-registados (ISO 3166-1 alfa-3), por exemplo `[\"USA\"]`." }, "first_name": { "type": "string", "maxLength": 255, "description": "Nome próprio. Quando `full_name` não é enviado, a Didit junta `first_name` e `last_name` com um espaço em `full_name`. Não é devolvido como um campo separado." }, "last_name": { "type": "string", "maxLength": 255, "description": "Apelido. Juntado a `first_name` em `full_name` quando `full_name` não é enviado. Não é devolvido como um campo separado." }, "email": { "type": "string", "format": "email", "description": "E-mail de contacto, armazenado em `metadata.contact.email` (substitui um `email` enviado dentro de `metadata.contact`). Obrigatório quando `send_verification_link` for `true`: a ligação é enviada para este endereço. Se `metadata.contact` não for um objeto JSON, a chamada responde `400` neste campo." }, "phone_number": { "type": "string", "maxLength": 32, "description": "Número de telefone de contacto, guardado em `metadata.contact.phone_number`. Se `metadata.contact` não for um objeto JSON, a chamada responde com `400` neste campo." }, "country": { "type": "string", "maxLength": 3, "description": "País como código ISO 3166, alpha-2 ou alpha-3 (`ES` ou `ESP`). Armazenado em maiúsculas em `metadata.address.country`. Se `metadata.address` não for um objeto JSON, a chamada devolve `400` para este campo." }, "send_verification_link": { "type": "boolean", "default": false, "description": "Quando `true`, a Didit cria uma sessão de verificação para a pessoa em `workflow_id` e envia-lhe a ligação por e-mail para `email`. Requer `email` e `workflow_id`. Uma chave de API com âmbito também necessita de permissão de escrita em `sessions`." }, "workflow_id": { "type": "string", "format": "uuid", "description": "O fluxo da sessão de verificação. Obrigatório quando `send_verification_link` for `true`. Tem de verificar uma pessoa: um fluxo de Verificação de empresas (KYB) é recusado. Caso contrário, é ignorado." }, "language": { "type": "string", "maxLength": 10, "description": "Idioma do e-mail de verificação, sob a forma de um código de [idioma suportado](/pt/integration/supported-languages). Inglês quando omitido. Ignorado quando `send_verification_link` não for `true`." } } }, "examples": { "Basic": { "summary": "Criar com informações básicas", "value": { "vendor_data": "user-abc-123", "full_name": "John Doe" } }, "Full": { "summary": "Todos os campos", "value": { "vendor_data": "user-abc-456", "full_name": "Jane Smith", "display_name": "Jane S.", "date_of_birth": "1990-05-15", "status": "ACTIVE", "metadata": { "tier": "premium", "source": "api" }, "approved_emails": [ "jane@example.com" ] } }, "Contact details": { "summary": "Nome, e-mail, telefone e país", "value": { "vendor_data": "user-abc-789", "first_name": "Julia", "last_name": "Martin", "email": "julia.martin@example.com", "phone_number": "+34600000000", "country": "ES" } }, "With verification link": { "summary": "Criar a pessoa e enviar-lhe uma ligação de verificação por e-mail", "value": { "vendor_data": "user-abc-789", "first_name": "Julia", "last_name": "Martin", "email": "julia.martin@example.com", "send_verification_link": true, "workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "language": "es" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/create/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"user-abc-123\", \"full_name\": \"John Doe\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.create(\n vendor_data=\"user-abc-123\",\n full_name=\"John Doe\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.create({\n vendor_data: \"user-abc-123\",\n full_name: \"John Doe\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Create(ctx, didit.UsersCreateParams{\n\tVendorData: \"user-abc-123\",\n\tFullName: didit.String(\"John Doe\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().create(UsersCreateParams.builder()\n .vendorData(\"user-abc-123\")\n .fullName(\"John Doe\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->create([\n 'vendor_data' => 'user-abc-123',\n 'full_name' => 'John Doe',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.create(\n vendor_data: \"user-abc-123\",\n full_name: \"John Doe\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.CreateAsync(new UsersCreateParams\n{\n VendorData = \"user-abc-123\",\n FullName = \"John Doe\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Utilizador criado. O registo completo do utilizador (mesma estrutura que Obter utilizador), mais `verification_link`: a sessão de verificação que a Didit enviou por e-mail quando `send_verification_link` era `true`; caso contrário, `null`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserDetailItem" }, { "type": "object", "required": [ "verification_link" ], "properties": { "verification_link": { "type": "object", "nullable": true, "description": "A sessão de verificação que a Didit criou e enviou por e-mail à pessoa. Sempre presente: `null` se `send_verification_link` não foi `true`.", "required": [ "session_id", "session_number", "status", "url", "workflow_id", "email" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID da sessão de verificação." }, "session_number": { "type": "integer", "description": "Número sequencial da sessão dentro da sua aplicação." }, "status": { "type": "string", "description": "Estado da sessão, `Not Started` para uma sessão acabada de criar." }, "url": { "type": "string", "format": "uri", "description": "A ligação de verificação que a Didit enviou por e-mail à pessoa." }, "workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "O fluxo que a sessão executa." }, "email": { "type": "string", "format": "email", "description": "O endereço para o qual a ligação foi enviada." } } } } } ] }, "examples": { "Created": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Doe", "date_of_birth": null, "effective_name": "John Doe", "status": "ACTIVE", "metadata": {}, "portrait_image_url": null, "session_count": 0, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": {}, "features_list": [], "last_session_at": null, "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": null, "tags": [], "comments": [], "created_at": "2025-06-15T10:30:00Z", "updated_at": "2025-06-15T10:30:00Z", "verification_link": null } }, "Created with verification link": { "value": { "didit_internal_id": "9b2f6c1e-3d4a-4e5f-8a7b-1c2d3e4f5a6b", "vendor_data": "user-abc-789", "display_name": null, "full_name": "Julia Martin", "date_of_birth": null, "effective_name": "Julia Martin", "status": "ACTIVE", "metadata": { "contact": { "email": "julia.martin@example.com" } }, "portrait_image_url": null, "session_count": 1, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": {}, "features_list": [], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-15T10:30:00Z", "tags": [], "comments": [], "created_at": "2025-06-15T10:30:00Z", "updated_at": "2025-06-15T10:30:00Z", "verification_link": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa7", "session_number": 43762, "status": "Not Started", "url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz", "workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "email": "julia.martin@example.com" } } } } } } }, "400": { "description": "Corpo inválido, organizado por campo: normalmente um `vendor_data` duplicado, um campo obrigatório em falta ou um valor malformatado. Com `send_verification_link: true`, também um `email` ou `workflow_id` em falta, um fluxo desconhecido ou de Verificação de empresas (KYB), um `language` não suportado (com a chave `contact_details.email_lang`), um `vendor_data` na lista de bloqueio ou créditos insuficientes para iniciar a sessão. Nada é gravado.", "content": { "application/json": { "examples": { "Duplicate": { "value": { "vendor_data": [ "A user with this vendor_data already exists." ] } }, "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad country": { "value": { "country": [ "Use an ISO 3166 country code, like ES or ESP." ] } }, "Contact not an object": { "value": { "email": [ "metadata.contact must be a JSON object to store this value." ] } }, "Address not an object": { "value": { "country": [ "metadata.address must be a JSON object to store this value." ] } }, "Link without email or workflow": { "value": { "email": [ "An email address is required to send a verification link." ], "workflow_id": [ "Pick the workflow to send a verification link for." ] } }, "Unknown workflow": { "value": { "workflow_id": [ "Invalid workflow_id." ] } }, "Business workflow": { "value": { "workflow_id": [ "This workflow verifies a business. Pick a workflow that verifies a person to send them a verification link." ] } }, "Blocklisted vendor_data": { "value": { "vendor_data": "This user or business has been blocked and cannot create new verification sessions." } }, "Insufficient credits": { "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "401": { "description": "Nenhuma credencial fornecida. Os pedidos para caminhos `/v3/users/*` sem um cabeçalho `x-api-key` (ou token `Authorization: Bearer`) são rejeitados pelo middleware de autenticação antes de chegarem à API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "Chave de API inválida ou revogada, ou a chave não pode criar utilizadores para esta aplicação. Uma chave de API com âmbito necessita de permissão de escrita em `users`, e também de permissão de escrita em `sessions` quando `send_verification_link` for `true`; nada é gravado. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } }, "No sessions write": { "summary": "Chave com âmbito solicita uma ligação de verificação sem permissão de escrita em sessions", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/": { "post": { "summary": "Carregar rosto do utilizador", "description": "Anexe uma imagem facial fidedigna importada a um perfil de Utilizador existente. Utilize isto após criar ou recuperar um Utilizador por `vendor_data` e ler o seu `didit_internal_id`. O rosto carregado é guardado no perfil do Utilizador e indexado para deteção de duplicados e pesquisa facial. Não é adicionado a uma lista de bloqueio de rostos.", "operationId": "upload_user_face", "x-didit-sdk": { "resource": "users", "method": "upload_face", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização à qual pertence a aplicação." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação que detém o perfil de Utilizador." }, { "name": "didit_internal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID interno de utilizador da Didit, devolvido como `didit_internal_id` por `GET /v3/users/{vendor_data}/` e `POST /v3/users/create/`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "byte", "description": "Imagem facial em bruto codificada em base64 (JPG ou PNG). Não inclua o prefixo `data:image/...;base64,`. Tamanho máximo descodificado: 2 MB." }, "comment": { "type": "string", "description": "Nota opcional, visível para o operador, sobre o rosto carregado.", "default": "" } } }, "examples": { "Imported face": { "summary": "Anexar um rosto importado de um fornecedor anterior", "value": { "image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"image\": \"/9j/4AAQSkZJRgABAQEA...\", \"comment\": \"Imported from previous KYC provider\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image=\"/9j/4AAQSkZJRgABAQEA...\",\n comment=\"Imported from previous KYC provider\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.uploadFace(\"11111111-2222-3333-4444-555555555555\", {\n image: \"/9j/4AAQSkZJRgABAQEA...\",\n comment: \"Imported from previous KYC provider\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.UsersUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQEA...\",\n\tComment: didit.String(\"Imported from previous KYC provider\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersUploadFaceParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().uploadFace(\"11111111-2222-3333-4444-555555555555\", UsersUploadFaceParams.builder()\n .image(\"/9j/4AAQSkZJRgABAQEA...\")\n .comment(\"Imported from previous KYC provider\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->uploadFace('11111111-2222-3333-4444-555555555555', [\n 'image' => '/9j/4AAQSkZJRgABAQEA...',\n 'comment' => 'Imported from previous KYC provider',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image: \"/9j/4AAQSkZJRgABAQEA...\",\n comment: \"Imported from previous KYC provider\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UploadFaceAsync(\"11111111-2222-3333-4444-555555555555\", new UsersUploadFaceParams\n{\n Image = \"/9j/4AAQSkZJRgABAQEA...\",\n Comment = \"Imported from previous KYC provider\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Rosto carregado e associado ao perfil do Utilizador.", "content": { "application/json": { "schema": { "type": "object", "required": [ "uuid", "image_url", "comment", "uploaded_by", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID do registo facial de utilizador carregado." }, "image_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL assinado para a imagem de rosto carregada." }, "comment": { "type": "string", "nullable": true, "description": "Comentário fornecido quando o rosto foi carregado." }, "uploaded_by": { "type": "string", "nullable": true, "description": "E-mail ou identificador do ator que fez o carregamento, quando disponível." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora do carregamento." } } }, "examples": { "Uploaded": { "value": { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "image_url": "https://signed-url.example/face.jpg", "comment": "Imported from previous KYC provider", "uploaded_by": "api", "created_at": "2026-05-18T12:00:00Z" } } } } } }, "400": { "description": "Corpo do pedido ou imagem inválidos. Causas comuns: base64 inválido, imagem inválida, nenhum rosto detetável, imagem com mais de 2 MB, embedding em falta ou o utilizador já tem 5 rostos carregados.", "content": { "application/json": { "examples": { "No face": { "value": { "image": "No face detected in the image. Please upload a clear photo with a visible face." } }, "Too many faces": { "value": { "detail": "Maximum of 5 faces per user reached." } }, "Too large": { "value": { "image": "Image exceeds maximum size of 2 MB." } } } } } }, "401": { "description": "Chave de API em falta ou inválida.", "content": { "application/json": { "examples": { "Missing key": { "value": { "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "A credencial é válida, mas não permite escrever perfis de utilizador para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não existe nenhum utilizador para esse `didit_internal_id` na aplicação.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite de pedidos excedido; reduza a frequência e tente novamente.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/update-data/": { "patch": { "summary": "Atualizar dados de KYC extraídos do documento de identificação numa sessão de verificação", "description": "Corrija os campos de identidade que foram extraídos (OCR / NFC) do documento de identificação do utilizador — nomes incorretamente lidos, datas, números de documento, e assim sucessivamente — após a verificação ter terminado. Quem normalmente faz estas chamadas são analistas de conformidade que trabalham a partir do seu próprio sistema interno ou tarefas automatizadas de reconciliação. Todos os campos no corpo são opcionais: apenas as chaves enviadas são gravadas, mantendo-se tudo o resto inalterado (semântica de `PATCH`).\n\nA sessão deve pertencer à sua aplicação e estar no estado `Approved`, `Declined`, `In Review` ou `Kyc Expired`. Sessões em qualquer outro estado (por exemplo, ainda `In Progress`) devolvem `404` com `\"No Session matches the given query.\"` — distinto de `\"Not found.\"` devolvido para um `sessionId` desconhecido ou eliminado. A sessão deve também conter um registo de verificação de identidade (KYC): sessões cujo fluxo nunca executou um passo de verificação de identidade devolvem `404` (`\"The session does not have a KYC.\"`). Para fluxos em grafo com múltiplos passos de verificação de identidade, direcione um passo específico com `node_id` (parâmetro de consulta ou campo do corpo); quando omitido, o registo de KYC mais recente é atualizado.\n\nDois campos derivados são recalculados em cada chamada: `full_name` (a partir de `first_name` + `last_name`) e `issuing_state_name` (a partir de `issuing_state`). Se o texto livre de `address` mudar, o servidor também pode voltar a geocodificá-lo e atualizar `parsed_address` (ignorado em sessões de sandbox). `extra_fields` e `parsed_address` são combinados chave a chave em vez de substituídos — consulte as descrições de cada campo para conhecer a semântica de `null`, que permite eliminar valores.\n\nEnviar pelo menos um campo válido aciona o [webhook](/pt/integration/webhooks) `data.updated` (acionador `manual_review`) — mesmo quando os valores submetidos são iguais aos armazenados. Quando os valores mudam efetivamente, uma entrada de atividade `KYC_DATA_UPDATED`, que regista os campos alterados com os valores anteriores e novos, é adicionada às `reviews` da sessão, visível em [Get Decision](#get-/v3/session/-sessionId-/decision/) e na cronologia de atividade da consola. O estado e a decisão da sessão **não** são reavaliados — utilize [Update Status](#patch-/v3/session/-sessionId-/update-status/) para alterar o resultado. Um corpo JSON vazio (`{}`) é aceite e simplesmente devolve os dados de KYC atuais sem acionar o webhook.\n\nAceita uma chave de API ou um token de utilizador da consola; em qualquer dos casos, a credencial necessita da permissão `write:sessions`. Falhas de autenticação e de permissão devolvem ambas `403` — esta API nunca responde `401`. Tenha em conta que a pesquisa da sessão é executada antes das verificações de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo com credenciais em falta. Este endpoint tem um limite de pedidos dedicado de 10 pedidos por minuto por chave de API (pedidos inválidos também contam); o limite partilhado de escrita de 300 pedidos por minuto também se aplica.", "operationId": "patch_v3_session_update_data", "x-didit-sdk": { "resource": "sessions", "method": "update_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de utilizadores (KYC) da qual está a corrigir os dados extraídos do documento. Os IDs de sessão de empresas (KYB) não são válidos aqui — para dados da empresa, utilize [Update KYB Company Data](#patch-/v3/session/-sessionId-/kyb/-companyUuid-/update-data/).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do grafo do fluxo cujo registo de KYC deve ser atualizado via patch, para fluxos em grafo com múltiplos passos de verificação de identidade (também aceite como campo `node_id` no corpo). Quando omitido, o registo de KYC mais recente da sessão é atualizado via patch. Se não existir KYC para o nó indicado, a chamada devolve `404` (`\"The session does not have a KYC for node ''.\"`).", "schema": { "type": "string", "example": "feature_ocr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Todos os campos são opcionais — envie apenas o que pretende alterar.", "properties": { "document_type": { "type": "string", "description": "Código do tipo de documento. Aceita os códigos curtos listados no enum, além de seis aliases por extenso normalizados no lado do servidor antes da validação: `Passport` → `P`, `Identity Card` → `ID`, `Driver's License` → `DL`, `Residence Permit` → `RP`, `Health Insurance Card` → `HIC`, `Tax Card` → `TC`. Qualquer outro valor (incluindo `PASSPORT` em maiúsculas) devolve `400`.", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "nullable": true, "example": "P" }, "document_subtype": { "type": "string", "maxLength": 128, "nullable": true, "description": "Subtipo de documento do registo de documentos, incluindo o prefixo da região quando o registo distingue variantes regionais." }, "document_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Número do documento tal como impresso no documento de identificação.", "example": "PAB123456" }, "personal_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Número de identificação pessoal / nacional onde o documento inclua um (por exemplo, DNI espanhol num passaporte).", "example": "99999999R" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento em `YYYY-MM-DD`. Qualquer outro formato devolve `400`.", "example": "1980-01-01" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "description": "Data de emissão do documento no formato `YYYY-MM-DD`." }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade do documento em `YYYY-MM-DD`." }, "issuing_state": { "type": "string", "nullable": true, "description": "País emissor como um código ISO 3166-1 alfa-3. Não sensível a maiúsculas/minúsculas (`esp` é guardado como `ESP`); o valor legível por humanos `issuing_state_name` apresentado em [Get Decision](#get-/v3/session/-sessionId-/decision/) é recalculado a partir deste valor. Códigos inválidos devolvem `400`.", "example": "ESP" }, "first_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Nome(s) próprio(s). O `full_name` armazenado é recalculado como `first_name + ' ' + last_name` em cada chamada a este endpoint.", "example": "Carmen" }, "last_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Apelido(s). Também alimenta o `full_name` recalculado.", "example": "Espanola Espanola" }, "gender": { "type": "string", "enum": [ "M", "F", "U" ], "nullable": true, "description": "Sexo conforme impresso no documento: `M` (masculino), `F` (feminino) ou `U` (desconhecido). Qualquer outro valor — incluindo `X` — devolve `400`." }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "Morada em texto livre tal como impressa no documento. Quando este valor muda (apenas em sessões fora da sandbox) e a morada estruturada continua em falta ou incompleta, o servidor volta a geocodificá-la de forma síncrona antes de responder — o corpo da resposta 200 já reflete o `parsed_address` atualizado. A nova geocodificação também exige que `issuing_state` esteja presente no registo de KYC." }, "place_of_birth": { "type": "string", "maxLength": 255, "nullable": true, "description": "Local de nascimento conforme impresso no documento." }, "nationality": { "type": "string", "maxLength": 32, "nullable": true, "description": "Nacionalidade tal como impressa no documento. Texto livre até 32 carateres — tipicamente um código ISO 3166-1 alpha-3 (por ex., `ESP`), mas não validado como tal." }, "marital_status": { "type": "string", "enum": [ "SINGLE", "MARRIED", "DIVORCED", "WIDOWED", "UNKNOWN" ], "description": "Estado civil quando o documento o contenha. Qualquer outro valor devolve `400`." }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Substituições por chave para campos adicionais específicos do documento (por exemplo, `blood_group`, `dl_categories`, `mrz_string`). As chaves são combinadas no mapa de substituições existente: envie uma chave com um valor para defini-la, ou com `null` / `\"\"` para remover essa chave da visualização combinada. Envie o campo inteiro como `null` para limpar todas as substituições aplicadas anteriormente. Tem de ser um objeto JSON, caso contrário devolve `400`. A resposta devolve sempre a visualização combinada (valores extraídos por OCR com as suas substituições aplicadas)." }, "parsed_address": { "type": "object", "nullable": true, "description": "Morada estruturada. Apenas estas chaves aninhadas são aceites: `address_type`, `city`, `region`, `street_1`, `street_2`, `postal_code`, `country` — qualquer outra chave devolve `400`. Semântica por chave: um valor define a chave, `null` remove-a. `formatted_address` é recalculado no servidor juntando `street_1`, `street_2`, `city`, `region`, `postal_code` e `country` e é devolvido na resposta — não é possível defini-lo diretamente.", "properties": { "address_type": { "type": "string", "nullable": true, "description": "Classificação da morada em formato livre (ex.: `home`)." }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "Estado / província / comunidade autónoma." }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "Código de país ISO 3166-1 alpha-2. Os dados de entrada em minúsculas são normalizados para maiúsculas; os códigos alpha-3 são rejeitados com `400`.", "example": "ES" } } } } }, "examples": { "Correct name and DOB": { "summary": "Corrigir nome mal lido por OCR, data de nascimento e morada estruturada", "value": { "first_name": "Carmen", "last_name": "Espanola Espanola", "date_of_birth": "1980-01-01", "issuing_state": "ESP", "marital_status": "MARRIED", "extra_fields": { "blood_group": "O+" }, "parsed_address": { "street_1": "Avda de Madrid 34", "city": "Madrid", "postal_code": "28013", "country": "ES" } } }, "Remove an extra field": { "summary": "Eliminar uma chave de campos adicionais, mantendo as restantes", "value": { "extra_fields": { "blood_group": null } } }, "Long-form document type": { "summary": "O alias em formato longo é normalizado para o código curto (aqui P)", "value": { "document_type": "Passport" } } } } } }, "responses": { "200": { "description": "Dados de KYC atualizados. Devolve o **registo KYC atual completo** (todos os campos atualizáveis com o respetivo valor guardado, além dos `extra_fields` combinados e da `parsed_address` atual) — e não apenas os campos submetidos por si. O webhook `data.updated` é acionado quando o payload continha pelo menos um campo válido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document_type": { "type": "string", "description": "Código do tipo de documento. Aceita os códigos curtos listados no enum, além de seis aliases por extenso normalizados no lado do servidor antes da validação: `Passport` → `P`, `Identity Card` → `ID`, `Driver's License` → `DL`, `Residence Permit` → `RP`, `Health Insurance Card` → `HIC`, `Tax Card` → `TC`. Qualquer outro valor (incluindo `PASSPORT` em maiúsculas) devolve `400`.", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "nullable": true, "example": "P" }, "document_subtype": { "type": "string", "maxLength": 128, "nullable": true, "description": "Subtipo de documento do registo de documentos, incluindo o prefixo da região quando o registo distingue variantes regionais." }, "document_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Número do documento tal como impresso no documento de identificação.", "example": "PAB123456" }, "personal_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Número de identificação pessoal / nacional onde o documento inclua um (por exemplo, DNI espanhol num passaporte).", "example": "99999999R" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento em `YYYY-MM-DD`. Qualquer outro formato devolve `400`.", "example": "1980-01-01" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "description": "Data de emissão do documento no formato `YYYY-MM-DD`." }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade do documento em `YYYY-MM-DD`." }, "issuing_state": { "type": "string", "nullable": true, "description": "País emissor como um código ISO 3166-1 alfa-3. Não sensível a maiúsculas/minúsculas (`esp` é guardado como `ESP`); o valor legível por humanos `issuing_state_name` apresentado em [Get Decision](#get-/v3/session/-sessionId-/decision/) é recalculado a partir deste valor. Códigos inválidos devolvem `400`.", "example": "ESP" }, "first_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Nome(s) próprio(s). O `full_name` armazenado é recalculado como `first_name + ' ' + last_name` em cada chamada a este endpoint.", "example": "Carmen" }, "last_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Apelido(s). Também alimenta o `full_name` recalculado.", "example": "Espanola Espanola" }, "gender": { "type": "string", "enum": [ "M", "F", "U" ], "nullable": true, "description": "Sexo conforme impresso no documento: `M` (masculino), `F` (feminino) ou `U` (desconhecido). Qualquer outro valor — incluindo `X` — devolve `400`." }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "Morada em texto livre tal como impressa no documento. Quando este valor muda (apenas em sessões fora da sandbox) e a morada estruturada continua em falta ou incompleta, o servidor volta a geocodificá-la em segundo plano no mesmo pedido e pode substituir `parsed_address` pelo resultado do geocodificador." }, "place_of_birth": { "type": "string", "maxLength": 255, "nullable": true, "description": "Local de nascimento conforme impresso no documento." }, "nationality": { "type": "string", "maxLength": 32, "nullable": true, "description": "Nacionalidade tal como impressa no documento. Texto livre até 32 carateres — tipicamente um código ISO 3166-1 alpha-3 (por ex., `ESP`), mas não validado como tal." }, "marital_status": { "type": "string", "enum": [ "SINGLE", "MARRIED", "DIVORCED", "WIDOWED", "UNKNOWN" ], "description": "Estado civil quando o documento o contenha. Qualquer outro valor devolve `400`." }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Vista fundida dos campos adicionais do documento: os valores extraídos por OCR com todas as sobreposições do operador aplicadas. As chaves removidas através de uma sobreposição `null` estão ausentes deste mapa." }, "parsed_address": { "type": "object", "nullable": true, "description": "Morada estruturada atual (sem as chaves internas de controlo), ou `null` quando não existe nenhuma. Inclui a `formatted_address` recalculada juntamente com as sete chaves editáveis.", "properties": { "address_type": { "type": "string", "nullable": true, "description": "Classificação da morada em formato livre (ex.: `home`)." }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "Estado / província / comunidade autónoma." }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "Código de país ISO 3166-1 alpha-2. Os dados de entrada em minúsculas são normalizados para maiúsculas; os códigos alpha-3 são rejeitados com `400`.", "example": "ES" }, "formatted_address": { "type": "string", "nullable": true, "description": "Forma unificada e legível por humanos da morada estruturada. Recalculada no servidor após cada edição de `parsed_address`.", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } } } }, "examples": { "Updated KYC": { "summary": "Registo completo de KYC após a correção", "value": { "document_type": "P", "document_subtype": null, "document_number": "PAB123456", "personal_number": "99999999R", "date_of_birth": "1980-01-01", "date_of_issue": "2021-02-09", "expiration_date": "2031-02-08", "issuing_state": "ESP", "first_name": "Carmen", "last_name": "Espanola Espanola", "gender": "F", "address": "AVDA DE MADRID 34, MADRID, MADRID 28013", "place_of_birth": "MADRID", "nationality": "ESP", "marital_status": "MARRIED", "extra_fields": { "mrz_string": "P\": [\"\"]}`; os erros em chaves aninhadas de `parsed_address` / `extra_fields` utilizam um valor de objeto: `{\"parsed_address\": {\"\": \"\"}}`.", "content": { "application/json": { "examples": { "Invalid gender": { "summary": "gender tem de ser M, F ou U", "value": { "gender": [ "\"X\" is not a valid choice." ] } }, "Invalid document type": { "summary": "Não é um código curto nem um alias longo", "value": { "document_type": [ "\"PASSPORT\" is not a valid choice." ] } }, "Invalid issuing state": { "summary": "issuing_state não é ISO 3166-1 alpha-3", "value": { "issuing_state": [ "Invalid ISO 3166-1 alpha-3 country code for issuing_state." ] } }, "Invalid marital status": { "summary": "marital_status não se encontra no enum", "value": { "marital_status": [ "\"ENGAGED\" is not a valid choice." ] } }, "Bad date format": { "summary": "As datas têm de estar no formato AAAA-MM-DD", "value": { "date_of_birth": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Unsupported parsed_address key": { "summary": "Apenas as sete chaves documentadas são permitidas", "value": { "parsed_address": { "zipcode": "Unsupported key. Allowed keys: address_type, city, region, street_1, street_2, postal_code, country" } } }, "Invalid parsed_address country": { "summary": "O país aninhado tem de ser alpha-2, não alpha-3", "value": { "parsed_address": { "country": "Invalid ISO 3166-1 alpha-2 country code." } } }, "extra_fields not an object": { "summary": "extra_fields tem de ser um objeto JSON", "value": { "extra_fields": [ "This field must be a JSON object." ] } } } } } }, "403": { "description": "Credenciais em falta ou permissões insuficientes. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "A credencial não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Sessão desconhecida, sessão num estado não editável ou nenhum registo de KYC para atualizar. Cada caso tem uma mensagem `detail` distinta (ver exemplos). A pesquisa de sessão desconhecida é executada antes das verificações de credenciais.", "content": { "application/json": { "examples": { "Unknown session": { "summary": "Nenhuma sessão com este ID na sua aplicação (ou foi eliminada)", "value": { "detail": "Not found." } }, "Wrong session state": { "summary": "A sessão existe, mas não está Approved / Declined / In Review / Kyc Expired", "value": { "detail": "No Session matches the given query." } }, "No KYC record": { "summary": "O fluxo nunca executou um passo de verificação de identidade", "value": { "detail": "The session does not have a KYC." } }, "No KYC for node": { "summary": "node_id fornecido, mas não existe KYC para ele", "value": { "detail": "The session does not have a KYC for node 'feature_missing'." } } } } } }, "429": { "description": "Limite de pedidos dedicado excedido — 10 atualizações de dados de KYC por minuto por chave de API (pedidos rejeitados contam para o orçamento). O orçamento de escrita partilhado de 300/min também pode ser acionado com a sua própria mensagem. Inspecione os cabeçalhos de resposta `Retry-After` e `X-RateLimit-*` antes de tentar novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Orçamento de atualizações de KYC esgotado", "value": { "detail": "Session KYC data update rate limit exceeded. You can make up to 10 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"first_name\": \"Carmen\",\n \"last_name\": \"Espanola Espanola\",\n \"date_of_birth\": \"1980-01-01\",\n \"issuing_state\": \"ESP\",\n \"parsed_address\": {\n \"street_1\": \"Avda de Madrid 34\",\n \"city\": \"Madrid\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_data(\n \"11111111-2222-3333-4444-555555555555\",\n date_of_birth=\"1980-01-01\",\n issuing_state=\"ESP\",\n first_name=\"Carmen\",\n last_name=\"Espanola Espanola\",\n marital_status=\"MARRIED\",\n extra_fields={\"blood_group\": \"O+\"},\n parsed_address={\n \"city\": \"Madrid\",\n \"street_1\": \"Avda de Madrid 34\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateData(\"11111111-2222-3333-4444-555555555555\", {\n date_of_birth: \"1980-01-01\",\n issuing_state: \"ESP\",\n first_name: \"Carmen\",\n last_name: \"Espanola Espanola\",\n marital_status: \"MARRIED\",\n extra_fields: { blood_group: \"O+\" },\n parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateData(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateDataParams{\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tIssuingState: didit.String(\"ESP\"),\n\tFirstName: didit.String(\"Carmen\"),\n\tLastName: didit.String(\"Espanola Espanola\"),\n\tMaritalStatus: didit.Some(didit.SessionsUpdateDataParamsMaritalStatus(\"MARRIED\")),\n\tExtraFields: didit.Some(map[string]any{\"blood_group\": \"O+\"}),\n\tParsedAddress: didit.Some(didit.SessionsUpdateDataParamsParsedAddress{\n\t\tCity: didit.String(\"Madrid\"),\n\t\tStreet1: didit.String(\"Avda de Madrid 34\"),\n\t\tPostalCode: didit.String(\"28013\"),\n\t\tCountry: didit.String(\"ES\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateData(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateDataParams.builder()\n .dateOfBirth(LocalDate.parse(\"1980-01-01\"))\n .issuingState(\"ESP\")\n .firstName(\"Carmen\")\n .lastName(\"Espanola Espanola\")\n .maritalStatus(SessionsUpdateDataParams.MaritalStatus.of(\"MARRIED\"))\n .extraFields(Map.of(\"blood_group\", \"O+\"))\n .parsedAddress(SessionsUpdateDataParams.ParsedAddress.builder()\n .city(\"Madrid\")\n .street1(\"Avda de Madrid 34\")\n .postalCode(\"28013\")\n .country(\"ES\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateData('11111111-2222-3333-4444-555555555555', [\n 'date_of_birth' => '1980-01-01',\n 'issuing_state' => 'ESP',\n 'first_name' => 'Carmen',\n 'last_name' => 'Espanola Espanola',\n 'marital_status' => 'MARRIED',\n 'extra_fields' => ['blood_group' => 'O+'],\n 'parsed_address' => [\n 'city' => 'Madrid',\n 'street_1' => 'Avda de Madrid 34',\n 'postal_code' => '28013',\n 'country' => 'ES',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_data(\n \"11111111-2222-3333-4444-555555555555\",\n date_of_birth: \"1980-01-01\",\n issuing_state: \"ESP\",\n first_name: \"Carmen\",\n last_name: \"Espanola Espanola\",\n marital_status: \"MARRIED\",\n extra_fields: { blood_group: \"O+\" },\n parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateDataAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateDataParams\n{\n DateOfBirth = \"1980-01-01\",\n IssuingState = \"ESP\",\n FirstName = \"Carmen\",\n LastName = \"Espanola Espanola\",\n MaritalStatus = new SessionsUpdateDataParamsMaritalStatus(\"MARRIED\"),\n ExtraFields = new Dictionary { [\"blood_group\"] = \"O+\" },\n ParsedAddress = new SessionsUpdateDataParamsParsedAddress\n {\n City = \"Madrid\",\n Street1 = \"Avda de Madrid 34\",\n PostalCode = \"28013\",\n Country = \"ES\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/features/{nodeId}/update-status/": { "patch": { "summary": "Atualizar o estado de uma funcionalidade (passo) individual", "description": "Defina o estado de uma única funcionalidade (passo) de verificação dentro de uma sessão. Indique a funcionalidade pelo respetivo `nodeId` do grafo de fluxo. Em fluxos sem grafo, cujos passos não têm nó, utilize `default` e passe também `feature_type` para indicar a que passo se refere.\n\nFunciona tanto para sessões de Verificação de utilizadores (KYC) como de Verificação de empresas (KYB) e para todos os tipos de passos: ID/OCR, Prova de vida, Correspondência facial, NFC, Triagem AML, Comprovativo de morada, Telefone, E-mail, Validação de base de dados, Questionário e as verificações de registo / documentos / pessoas-chave de KYB. Este endpoint **não** está disponível para sessões de API autónomas (`session_type = API`).\n\n`new_status` tem de ser `Approved`, `Declined` ou `In Review`, e tem de ser diferente do estado atual da funcionalidade.\n\n**Quando a sobreposição se aplica.** Sem `defer_until_flow_finishes` (ou com `false`), a sobreposição aplica-se imediatamente, como sempre aconteceu; quando a pessoa ainda se encontra no fluxo, é registada como `forced`. Com `defer_until_flow_finishes: true` enquanto a pessoa ainda se encontra no fluxo (a sessão está como `Not Started`, `In Progress` ou `Resubmitted` e não terminou), a sobreposição é guardada como `pending_until_flow_finishes` e aplica-se quando o fluxo terminar, após o fluxo atingir a sua própria decisão. Numa sessão cujo fluxo já terminou, aplica-se imediatamente de qualquer forma. Uma sobreposição pendente é cancelada se a pessoa repetir o respetivo passo antes de terminar, quando uma sobreposição mais recente na mesma verificação a substituir, quando a sessão deixar o fluxo inacabado (abandonada, expirada ou com decisão a meio do fluxo), ou quando a cancelar com `POST /v3/session/{sessionId}/features/overrides/{overrideId}/cancel/`. Liste as sobreposições de uma sessão com `GET /v3/session/{sessionId}/features/overrides/`.\n\n**Efeito na sessão.** Uma sessão que já tem uma decisão mantém-na: apenas a verificação é alterada. Quando a sessão ainda não tiver uma decisão e o respetivo fluxo estiver a aguardar exatamente por este passo, a aplicação da sobreposição conclui o passo: o fluxo avança, os passos posteriores são executados e um nó de estado pode definir a decisão da sessão e acionar `status.updated`.\n\n**Webhooks e atividade.** Um webhook `data.updated` é acionado quando a sobreposição é aplicada (imediatamente ou quando o fluxo termina), nunca enquanto aguarda nem quando é cancelada. Cada sobreposição é registada na atividade da sessão como `FEATURE_OVERRIDE_PENDING`, `FEATURE_OVERRIDE_APPLIED` ou `FEATURE_OVERRIDE_CANCELLED`, com a indicação de quem a realizou; o registo do pedido inclui o seu `comment`.\n\nAutentique-se com a sua chave de API (`x-api-key`) ou com um cabeçalho de autorização de utilizador com o privilégio `write:sessions`; uma chave de API com âmbito limitado necessita de acesso de escrita a decisões.", "operationId": "patch_v3_session_update_feature_status", "x-didit-sdk": { "resource": "sessions", "method": "update_feature_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB) — o serviço resolve o ID em ambos os tipos de sessão.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "path", "name": "nodeId", "required": true, "description": "ID do nó do grafo do fluxo da funcionalidade a atualizar (por exemplo, `feature_ocr_1`). Utilize o valor literal `default` para fluxos que não utilizem grafos (passo único), onde a funcionalidade não tem ID de nó.", "schema": { "type": "string", "example": "feature_ocr_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "description": "Estado de destino para esta funcionalidade. Deve diferir do valor atual.", "enum": [ "Approved", "Declined", "In Review" ], "example": "Approved" }, "comment": { "type": "string", "description": "Nota de texto livre opcional registada no histórico de revisão da sessão para esta alteração de funcionalidade.", "example": "Document manually verified by compliance." }, "feature_type": { "type": "string", "enum": [ "ID_VERIFICATION", "OCR", "OCR_BACK", "NFC", "LIVENESS", "FACE", "AGE_ESTIMATION", "AGE_VERIFICATION", "FACE_SEARCH", "FACE_MATCH", "IP_ANALYSIS", "AML", "PHONE", "PHONE_VERIFICATION", "EMAIL", "EMAIL_VERIFICATION", "POA", "PROOF_OF_ADDRESS", "DATABASE_VALIDATION", "DATA_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "BANK_VERIFICATION", "GEOLOCATION" ], "description": "Qual o tipo de passo a definir como alvo. Necessário em fluxos sem grafo (`nodeId` = `default`), onde nenhum passo partilha nós; caso contrário, é opcional. Um valor desconhecido devolve `400`.", "example": "LIVENESS" }, "defer_until_flow_finishes": { "type": "boolean", "default": false, "description": "Enquanto a pessoa ainda estiver no fluxo, armazene a substituição como `pending_until_flow_finishes` e aplique-a quando o fluxo terminar, em vez de imediatamente. Omitido ou `false`, a substituição é aplicada imediatamente. Numa sessão cujo fluxo já terminou, aplica-se imediatamente de qualquer forma.", "example": false } } }, "examples": { "Apply Now": { "summary": "Aprovar imediatamente o passo de ID", "value": { "new_status": "Approved", "comment": "Document manually verified by compliance." } }, "Wait For The Flow": { "summary": "Aprovar o passo de prova de vida assim que a pessoa concluir o fluxo", "value": { "new_status": "Approved", "comment": "Liveness retried with a reviewer present.", "defer_until_flow_finishes": true } }, "Non-graph Workflow": { "summary": "Direcionar para o passo de prova de vida de um fluxo sem nós (nodeId = default)", "value": { "new_status": "In Review", "feature_type": "LIVENESS" } } } } } }, "responses": { "200": { "description": "A substituição foi registada. `new_status` é o estado da verificação conforme armazenado: o solicitado assim que a substituição for aplicada, ou o estado inalterado enquanto aguarda a conclusão do fluxo. `override` indica o que ocorreu.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "nullable": true, "description": "O nó de fluxo do passo atualizado, ou `null` para um passo sem nó (o caminho `default` num fluxo sem grafo).", "example": "feature_ocr_1" }, "feature_type": { "type": "string", "description": "Nome do modelo da funcionalidade atualizada (p. ex., `KYC`, `Face`, `FaceMatch`, `AML`, `POA`).", "example": "KYC" }, "new_status": { "type": "string", "description": "O estado armazenado da verificação: o solicitado assim que a substituição for aplicada, e o estado inalterado enquanto a substituição aguarda que o fluxo termine.", "example": "Approved" }, "override": { "$ref": "#/components/schemas/FeatureStatusOverride" } }, "required": [ "session_id", "node_id", "feature_type", "new_status", "override" ] }, "examples": { "Applied": { "summary": "A substituição foi aplicada imediatamente", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "node_id": "feature_ocr_1", "feature_type": "KYC", "new_status": "Approved", "override": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "node_id": "feature_ocr_1", "feature_type": "", "feature_model": "KYC", "previous_status": "In Review", "new_status": "Approved", "state": "applied", "forced": false, "reason": "Document manually verified by compliance.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": "2026-10-13T09:15:00Z", "cancelled_at": null, "cancel_reason": null } } }, "Waiting For The Flow": { "summary": "defer_until_flow_finishes enquanto a pessoa ainda se encontra no fluxo", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "node_id": "feature_liveness_1", "feature_type": "Face", "new_status": "Declined", "override": { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "pending_until_flow_finishes", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": null, "cancel_reason": null } } } } } } }, "400": { "description": "Erro de validação. Devolvido quando `new_status` é inválido ou inalterado, quando `feature_type` é desconhecido ou quando a sessão é uma sessão de API autónoma.", "content": { "application/json": { "examples": { "Same Status": { "summary": "new_status é igual ao estado atual", "value": { "new_status": [ "The new status is the same as the current status." ] } }, "API Session": { "summary": "O estado da funcionalidade não pode ser alterado em sessões de API autónomas", "value": [ "Cannot change feature status for API sessions." ] }, "Unknown feature_type": { "summary": "feature_type não é um tipo de passo conhecido", "value": { "feature_type": [ "Unknown feature_type 'SELFIE'." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chave de API com âmbito cuja data de validade já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenciais em falta ou permissões insuficientes.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "A chave de API não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chave de API com âmbito sem acesso de escrita a decisões", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "A sessão não foi encontrada ou não tem nenhuma funcionalidade com o `nodeId` indicado.", "content": { "application/json": { "examples": { "Session Not Found": { "summary": "session_id desconhecido", "value": { "detail": "Session not found." } }, "Feature Not Found": { "summary": "Nenhuma funcionalidade para este node_id", "value": { "detail": "No feature found with node_id 'feature_ocr_1' in this session." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/features/feature_ocr_1/update-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"Approved\",\n \"comment\": \"Document manually verified by compliance.\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_feature_status(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n new_status=\"Approved\",\n comment=\"Document manually verified by compliance.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateFeatureStatus(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n {\n new_status: \"Approved\",\n comment: \"Document manually verified by compliance.\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateFeatureStatus(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", didit.SessionsUpdateFeatureStatusParams{\n\tNewStatus: \"Approved\",\n\tComment: didit.String(\"Document manually verified by compliance.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateFeatureStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateFeatureStatus(\"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", SessionsUpdateFeatureStatusParams.builder()\n .newStatus(SessionsUpdateFeatureStatusParams.NewStatus.of(\"Approved\"))\n .comment(\"Document manually verified by compliance.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateFeatureStatus('11111111-2222-3333-4444-555555555555', 'feature_ocr_1', [\n 'new_status' => 'Approved',\n 'comment' => 'Document manually verified by compliance.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_feature_status(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n new_status: \"Approved\",\n comment: \"Document manually verified by compliance.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateFeatureStatusAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", new SessionsUpdateFeatureStatusParams\n{\n NewStatus = \"Approved\",\n Comment = \"Document manually verified by compliance.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/update-aml-hit-status/": { "patch": { "summary": "Atualizar o estado de revisão de uma ocorrência AML", "description": "Defina o estado de revisão de um **único hit AML** (uma potencial correspondência de sanções / PEP / lista de vigilância / notícias adversas) devolvido pela triagem AML, sem alterar a decisão global da sessão. Identifique o hit pelo seu `hit_id` (o `id` de uma entrada no array `hits` da verificação AML — consulte a decisão da sessão). Um id de hit devolvido no formato anterior continua a ser aceite; a resposta identifica sempre o hit pelo seu `id` atual.\n\n`review_status` é um de `Unreviewed`, `Confirmed Match`, `False Positive` ou `Inconclusive`. As decisões do revisor são preservadas ao longo das atualizações de monitorização contínua, pelo que um hit que marque como `False Positive` permanece assim quando o fornecedor realizar uma nova triagem.\n\nUma chamada bem-sucedida aciona um webhook `data.updated` e adiciona uma entrada de atividade (com atribuição do autor) ao histórico de revisão da sessão. Para fluxos em grafo com múltiplas verificações AML, passe `node_id` para direcionar para uma verificação específica.\n\nAutentique-se com a sua chave de API (`x-api-key`) ou com um cabeçalho de autorização de utilizador — qualquer um deles deve ter o privilégio `write:sessions`.", "operationId": "patch_v3_session_update_aml_hit_status", "x-didit-sdk": { "resource": "sessions", "method": "update_aml_hit_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB) — o serviço resolve o ID em ambos os tipos de sessão.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "query", "name": "node_id", "required": false, "description": "ID do nó do grafo do fluxo. Obrigatório apenas quando a sessão possui múltiplas verificações AML (uma por nó); omita-o para sessões com apenas uma verificação AML.", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hit_id", "review_status" ], "properties": { "hit_id": { "type": "string", "description": "O `id` da ocorrência no array `hits` da verificação AML (`hit_...`). Um id de ocorrência retornado no formato anterior ainda é aceite.", "example": "hit_7c1e9a40b2d35f86e0a4c912" }, "review_status": { "type": "string", "description": "O novo estado de revisão para o resultado.", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "example": "False Positive" }, "node_id": { "type": "string", "description": "ID do nó do grafo opcional. Utilize-o (aqui ou como parâmetro de consulta) quando a sessão tiver várias verificações AML.", "example": "feature_aml_1" } } }, "example": { "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "False Positive" } } } }, "responses": { "200": { "description": "Estado de revisão de ocorrências atualizado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "hit_id", "review_status" ], "properties": { "message": { "type": "string", "description": "Sempre `Hit status updated successfully`." }, "hit_id": { "type": "string", "description": "O `id` da ocorrência atualizada, conforme retornado pela decisão da sessão, também quando o pedido indicou a ocorrência por um id no formato anterior." }, "review_status": { "type": "string", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "description": "O estado de revisão agora armazenado na ocorrência." } } }, "example": { "message": "Hit status updated successfully", "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "False Positive" } } } }, "400": { "description": "Erro de validação — `hit_id` vazio ou `review_status` não é um dos valores permitidos.", "content": { "application/json": { "example": { "review_status": [ "\"Maybe\" is not a valid choice." ] } } } }, "403": { "description": "Credenciais em falta ou permissões insuficientes. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "A chave de API não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "A sessão não foi encontrada, a sessão não tem verificação AML (opcionalmente para o `node_id` indicado) ou nenhuma ocorrência corresponde a `hit_id`.", "content": { "application/json": { "examples": { "No AML Check": { "summary": "A sessão não tem verificação AML", "value": { "detail": "The session does not have an AML check." } }, "Hit Not Found": { "summary": "hit_id desconhecido", "value": { "detail": "Hit with ID 'hit_9d2e7f41c0a8b3e65d1f0c47' not found in the AML check." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-hit-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"hit_id\": \"abc123\",\n \"review_status\": \"False Positive\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_id=\"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status=\"False Positive\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", {\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"False Positive\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateAMLHitStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateAMLHitStatusParams{\n\tHitID: \"hit_7c1e9a40b2d35f86e0a4c912\",\n\tReviewStatus: \"False Positive\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateAmlHitStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateAmlHitStatusParams.builder()\n .hitId(\"hit_7c1e9a40b2d35f86e0a4c912\")\n .reviewStatus(SessionsUpdateAmlHitStatusParams.ReviewStatus.of(\"False Positive\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateAmlHitStatus('11111111-2222-3333-4444-555555555555', [\n 'hit_id' => 'hit_7c1e9a40b2d35f86e0a4c912',\n 'review_status' => 'False Positive',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"False Positive\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateAmlHitStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateAmlHitStatusParams\n{\n HitId = \"hit_7c1e9a40b2d35f86e0a4c912\",\n ReviewStatus = \"False Positive\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/bulk-update-aml-hit-status/": { "patch": { "summary": "Atualizar em massa estados de revisão de resultados AML", "description": "Atualizar o estado de revisão de **múltiplos resultados AML** numa única chamada. Forneça `hit_updates`, uma lista de pares `{ hit_id, review_status }`. `review_status` é um de `Unreviewed`, `Confirmed Match`, `False Positive` ou `Inconclusive`.\n\nA atualização funciona em regime tudo-ou-nada: se algum `hit_id` não for encontrado na verificação AML, o pedido devolve `404` e nenhum resultado é alterado. Uma chamada bem-sucedida aciona um único webhook `data.updated` e regista uma entrada de atividade que abrange todas as alterações. Para fluxos em grafo com múltiplas verificações AML, passe `node_id` para direcionar uma verificação específica.\n\nAutentique-se com a sua chave de API (`x-api-key`) ou com um cabeçalho de autorização de utilizador — qualquer um deve conter o privilégio `write:sessions`.", "operationId": "patch_v3_session_bulk_update_aml_hit_status", "x-didit-sdk": { "resource": "sessions", "method": "bulk_update_aml_hit_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB) — o serviço resolve o ID em ambos os tipos de sessão.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "query", "name": "node_id", "required": false, "description": "ID do nó do grafo do fluxo. Obrigatório apenas quando a sessão possui múltiplas verificações AML (uma por nó); omita-o para sessões com apenas uma verificação AML.", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hit_updates" ], "properties": { "hit_updates": { "type": "array", "description": "Lista não vazia de atualizações de ocorrências.", "items": { "type": "object", "required": [ "hit_id", "review_status" ], "properties": { "hit_id": { "type": "string", "example": "hit_7c1e9a40b2d35f86e0a4c912", "description": "O `id` da ocorrência no array `hits` da verificação AML (`hit_...`). Um id de ocorrência retornado no formato anterior ainda é aceite." }, "review_status": { "type": "string", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "example": "Confirmed Match" } } } }, "node_id": { "type": "string", "description": "ID do nó do grafo opcional. Utilize-o (aqui ou como parâmetro de consulta) quando a sessão tiver várias verificações AML.", "example": "feature_aml_1" } } }, "example": { "hit_updates": [ { "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "Confirmed Match" }, { "hit_id": "hit_3b8f20d6a91c4e75f0b2d6a8", "review_status": "False Positive" } ] } } } }, "responses": { "200": { "description": "Todas as correspondências atualizadas.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "updated_hits" ], "properties": { "message": { "type": "string", "description": "`Updated {n} hit(s) successfully`, onde `n` é o número de entradas em `hit_updates`." }, "updated_hits": { "type": "array", "items": { "type": "string" }, "description": "O `id` da ocorrência identificada por cada entrada em `hit_updates`, conforme retornado pela decisão da sessão, na ordem do pedido, incluindo ocorrências cujo estado não mudou." } } }, "example": { "message": "Updated 2 hit(s) successfully", "updated_hits": [ "hit_7c1e9a40b2d35f86e0a4c912", "hit_3b8f20d6a91c4e75f0b2d6a8" ] } } } }, "400": { "description": "Erro de validação — `hit_updates` vazio, ou uma entrada não tem `hit_id` / `review_status` ou contém um valor inválido.", "content": { "application/json": { "example": { "hit_updates": [ "hit_updates cannot be empty" ] } } } }, "403": { "description": "Credenciais em falta ou permissões insuficientes. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "A chave de API não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "A sessão não foi encontrada, a sessão não tem verificação AML ou um ou mais `hit_id`s não existem (nenhuma ocorrência é alterada nesse caso).", "content": { "application/json": { "example": { "detail": "Hits not found: hit_9d2e7f41c0a8b3e65d1f0c47" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/bulk-update-aml-hit-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"hit_updates\": [\n { \"hit_id\": \"abc123\", \"review_status\": \"Confirmed Match\" },\n { \"hit_id\": \"def456\", \"review_status\": \"False Positive\" }\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.bulk_update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_updates=[{\n \"hit_id\": \"hit_7c1e9a40b2d35f86e0a4c912\",\n \"review_status\": \"Confirmed Match\",\n }, {\n \"hit_id\": \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n \"review_status\": \"False Positive\",\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.bulkUpdateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", {\n hit_updates: [{\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"Confirmed Match\",\n }, {\n hit_id: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n review_status: \"False Positive\",\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.BulkUpdateAMLHitStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsBulkUpdateAMLHitStatusParams{\n\tHitUpdates: []didit.SessionsBulkUpdateAMLHitStatusParamsHitUpdates{{\n\t\tHitID: \"hit_7c1e9a40b2d35f86e0a4c912\",\n\t\tReviewStatus: \"Confirmed Match\",\n\t}, {\n\t\tHitID: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n\t\tReviewStatus: \"False Positive\",\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsBulkUpdateAmlHitStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().bulkUpdateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", SessionsBulkUpdateAmlHitStatusParams.builder()\n .hitUpdates(List.of(\n SessionsBulkUpdateAmlHitStatusParams.HitUpdates.builder()\n .hitId(\"hit_7c1e9a40b2d35f86e0a4c912\")\n .reviewStatus(SessionsBulkUpdateAmlHitStatusParams.HitUpdates.ReviewStatus.of(\"Confirmed Match\"))\n .build(),\n SessionsBulkUpdateAmlHitStatusParams.HitUpdates.builder()\n .hitId(\"hit_3b8f20d6a91c4e75f0b2d6a8\")\n .reviewStatus(SessionsBulkUpdateAmlHitStatusParams.HitUpdates.ReviewStatus.of(\"False Positive\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->bulkUpdateAmlHitStatus('11111111-2222-3333-4444-555555555555', [\n 'hit_updates' => [[\n 'hit_id' => 'hit_7c1e9a40b2d35f86e0a4c912',\n 'review_status' => 'Confirmed Match',\n ], [\n 'hit_id' => 'hit_3b8f20d6a91c4e75f0b2d6a8',\n 'review_status' => 'False Positive',\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.bulk_update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_updates: [{\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"Confirmed Match\",\n }, {\n hit_id: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n review_status: \"False Positive\",\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.BulkUpdateAmlHitStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsBulkUpdateAmlHitStatusParams\n{\n HitUpdates = new SessionsBulkUpdateAmlHitStatusParamsHitUpdates[]\n {\n new()\n {\n HitId = \"hit_7c1e9a40b2d35f86e0a4c912\",\n ReviewStatus = \"Confirmed Match\",\n },\n new()\n {\n HitId = \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n ReviewStatus = \"False Positive\",\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/update-poa-data/": { "patch": { "summary": "Atualizar dados de Comprovativo de morada extraídos do documento de POA numa sessão de verificação", "description": "Corrija os campos extraídos do documento de Comprovativo de morada do utilizador — fatura de serviços públicos, extrato bancário ou outro comprovativo de morada — após a verificação ter terminado: emissor, datas, o nome impresso, a própria morada e dados bancários. Todos os campos no corpo são opcionais: apenas as chaves que enviar são gravadas, tudo o resto permanece inalterado (semântica `PATCH`).\n\nA sessão tem de pertencer à sua aplicação e estar no estado `Approved`, `Declined`, `In Review` ou `Kyc Expired`. Sessões em qualquer outro estado (por exemplo, ainda `In Progress`) devolvem `404` com `\"No Session matches the given query.\"` — diferente do `\"Not found.\"` devolvido para um `sessionId` desconhecido ou eliminado. A sessão também tem de conter um registo de POA: sessões cujo fluxo nunca executou um passo de Comprovativo de morada devolvem `404` (`\"The session does not have a POA.\"`). Para fluxos de grafo com múltiplos passos de POA, aponte para um passo específico com `node_id` (parâmetro de consulta ou campo no corpo); quando omitido, o registo de POA mais recente é atualizado.\n\n`extra_fields` é fundido chave a chave: nove chaves conhecidas (`bank_iban`, `additional_names`, …) são gravadas em colunas dedicadas de POA, qualquer outra chave é mantida como um campo extra personalizado, e `null` / `\"\"` elimina uma chave. `poa_parsed_address` aceita apenas as sete chaves documentadas e recalcula `formatted_address` / `poa_formatted_address` após cada edição. Se o texto livre de `poa_address` for alterado, o servidor também poderá voltar a geocodificá-lo e atualizar a morada estruturada (ignorado em sessões na sandbox).\n\nAo contrário da variante KYC deste endpoint, o [webhook](/pt/integration/webhooks) `data.updated` (acionador `manual_review`) só é disparado quando pelo menos um valor armazenado foi **efetivamente alterado** — reenviar valores idênticos é uma não-operação silenciosa. Quando os valores mudam, uma entrada de atividade `POA_DATA_UPDATED` registando os campos alterados com os valores anteriores e novos é anexada às `reviews` da sessão, visível em [Get Decision](#get-/v3/session/-sessionId-/decision/) e no histórico de atividade da consola. O estado e a decisão da sessão **não** são reavaliados — utilize [Update Status](#patch-/v3/session/-sessionId-/update-status/) para alterar o resultado.\n\nAceita uma chave de API ou um token de utilizador da consola; em qualquer dos casos, a credencial necessita da permissão `write:sessions`. Falhas de autenticação e de permissão devolvem ambas `403` — esta API nunca responde com `401`. Tenha em atenção que a pesquisa da sessão é executada antes das verificações de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo com credenciais em falta. Este endpoint tem um limite de pedidos dedicado de 10 pedidos por minuto por chave de API (pedidos inválidos também contam); o limite partilhado de escrita de 300 pedidos por minuto também se aplica.\n\nUm corpo JSON vazio `{}` é uma não-operação: devolve `200` reproduzindo o registo de POA atual sem disparar o webhook (`has_changes` permanece falso).", "operationId": "patch_v3_session_update_poa_data", "x-didit-sdk": { "resource": "sessions", "method": "update_poa_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de utilizadores (KYC) cujo registo de POA anexado está a corrigir.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do grafo do fluxo cujo registo de comprovativo de morada deve ser atualizado via patch, para fluxos em grafo com múltiplos passos de comprovativo de morada (também aceite como campo `node_id` no corpo). Quando omitido, o registo de comprovativo de morada mais recente da sessão é atualizado via patch. Se não existir comprovativo de morada para o nó indicado, a chamada devolve `404` (`\"The session does not have a POA for node ''.\"`).", "schema": { "type": "string", "example": "feature_poa" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Todos os campos são opcionais — envie apenas o que pretende alterar.", "properties": { "issuing_state": { "type": "string", "nullable": true, "description": "País que emitiu o documento de comprovativo de morada (POA), ISO 3166-1 alpha-3. Não sensível a maiúsculas/minúsculas (normalizado para maiúsculas); códigos inválidos devolvem `400`.", "example": "ESP" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "Categoria do documento de POA. Os valores são em maiúsculas — variantes em minúsculas como `utility_bill` devolvem `400`.", "example": "UTILITY_BILL" }, "document_language": { "type": "string", "maxLength": 50, "nullable": true, "description": "Idioma do documento, normalmente um código ISO 639-1 (por exemplo, `es`). Texto livre — não validado como código de idioma.", "example": "es" }, "issuer": { "type": "string", "maxLength": 255, "nullable": true, "description": "Organização que emitiu o documento (empresa de serviços públicos, banco, agência governamental).", "example": "Energy Provider S.A." }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "Data de emissão do documento de comprovativo de morada em `YYYY-MM-DD`. Qualquer outro formato devolve `400`.", "example": "2026-04-12" }, "poa_address": { "type": "string", "nullable": true, "description": "Morada em texto livre tal como impressa no documento. Quando este valor muda (apenas em sessões fora da sandbox) e a morada estruturada continua em falta ou incompleta, o servidor volta a geocodificá-la em segundo plano no mesmo pedido e pode substituir `poa_parsed_address` / `poa_formatted_address` pelo resultado do geocodificador. A nova geocodificação também exige que `issuing_state` esteja presente no registo de POA.", "example": "Avda de Madrid 34, 28013 Madrid" }, "name_on_document": { "type": "string", "maxLength": 255, "nullable": true, "description": "Nome do destinatário tal como impresso no documento.", "example": "Carmen Espanola" }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Dados adicionais específicos do documento, intercalados chave a chave. Nove chaves mapeiam para colunas de POA dedicadas: `bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`, `document_phone_number` e `additional_names` (deve ser uma lista de strings ou `null`, caso contrário `400`). Qualquer outra chave é armazenada como um campo adicional personalizado. Semântica por chave: um valor define a chave; `null` ou `\"\"` elimina-a. Deve ser um objeto JSON, caso contrário `400`." }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "Morada estruturada. Apenas estas chaves aninhadas são aceites: `address_type`, `city`, `region`, `street_1`, `street_2`, `postal_code`, `country` — qualquer outra chave devolve `400`. Semântica por chave: um valor define a chave, `null` remove-a. `formatted_address` (e o campo de nível superior `poa_formatted_address`) é recalculado no servidor juntando `street_1`, `street_2`, `city`, `region`, `postal_code` e `country` — não é possível defini-lo diretamente.", "properties": { "address_type": { "type": "string", "nullable": true, "description": "Classificação da morada em formato livre (ex.: `home`)." }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "Estado / província / comunidade autónoma." }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "Código de país ISO 3166-1 alpha-2. Os dados de entrada em minúsculas são normalizados para maiúsculas; os códigos alpha-3 são rejeitados com `400`.", "example": "ES" } } } } }, "examples": { "Correct issuer and address": { "summary": "Corrigir classificação do documento, emissor e a morada estruturada", "value": { "issuing_state": "ESP", "document_type": "BANK_STATEMENT", "issuer": "Banco Example S.A.", "issue_date": "2026-05-02", "name_on_document": "Carmen Espanola", "poa_address": "Avda de Madrid 34, 28013 Madrid", "extra_fields": { "bank_iban": "ES9121000418450200051332", "additional_names": [ "Carmen E. Espanola" ] }, "poa_parsed_address": { "street_1": "Avda de Madrid 34", "city": "Madrid", "postal_code": "28013", "country": "ES" } } }, "Remove a banking detail": { "summary": "Eliminar uma chave de campos adicionais, mantendo as restantes", "value": { "extra_fields": { "bank_iban": null } } } } } } }, "responses": { "200": { "description": "Dados de POA atualizados. Devolve o **registo completo e atual de POA** (todos os campos atualizáveis com o respetivo valor armazenado, mais o mapa completo de `extra_fields`, `poa_parsed_address` e `poa_formatted_address`) — não apenas os campos que submeteu. O webhook `data.updated` é acionado apenas quando pelo menos um valor é efetivamente alterado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuing_state": { "type": "string", "nullable": true, "description": "País que emitiu o documento de comprovativo de morada (POA), ISO 3166-1 alpha-3. Não sensível a maiúsculas/minúsculas (normalizado para maiúsculas); códigos inválidos devolvem `400`.", "example": "ESP" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "Categoria do documento de POA. Os valores são em maiúsculas — variantes em minúsculas como `utility_bill` devolvem `400`.", "example": "UTILITY_BILL" }, "document_language": { "type": "string", "maxLength": 50, "nullable": true, "description": "Idioma do documento, normalmente um código ISO 639-1 (por exemplo, `es`). Texto livre — não validado como código de idioma.", "example": "es" }, "issuer": { "type": "string", "maxLength": 255, "nullable": true, "description": "Organização que emitiu o documento (empresa de serviços públicos, banco, agência governamental).", "example": "Energy Provider S.A." }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "Data de emissão do documento de comprovativo de morada em `YYYY-MM-DD`. Qualquer outro formato devolve `400`.", "example": "2026-04-12" }, "poa_address": { "type": "string", "nullable": true, "description": "Morada em texto livre tal como impressa no documento. Quando este valor muda (apenas em sessões fora da sandbox) e a morada estruturada continua em falta ou incompleta, o servidor volta a geocodificá-la em segundo plano no mesmo pedido e pode substituir `poa_parsed_address` / `poa_formatted_address` pelo resultado do geocodificador.", "example": "Avda de Madrid 34, 28013 Madrid" }, "name_on_document": { "type": "string", "maxLength": 255, "nullable": true, "description": "Nome do destinatário tal como impresso no documento.", "example": "Carmen Espanola" }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Sempre presente na resposta: as nove chaves conhecidas (com `null` para as não definidas, `additional_names` por defeito como `[]`) mais quaisquer chaves personalizadas armazenadas anteriormente." }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "Morada estruturada atual, ou `null` quando não existe nenhuma. Inclui a `formatted_address` recalculada juntamente com as sete chaves editáveis. Devolvida tal como armazenada — após uma geocodificação no servidor pode conter chaves de controlo (por exemplo, `raw_results`) juntamente com as chaves editáveis.", "properties": { "address_type": { "type": "string", "nullable": true, "description": "Classificação da morada em formato livre (ex.: `home`)." }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "Estado / província / comunidade autónoma." }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "Código de país ISO 3166-1 alpha-2. Os dados de entrada em minúsculas são normalizados para maiúsculas; os códigos alpha-3 são rejeitados com `400`.", "example": "ES" }, "formatted_address": { "type": "string", "nullable": true, "description": "Forma unificada e legível por humanos da morada estruturada. Recalculada no servidor após cada edição de `poa_parsed_address`.", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } }, "poa_formatted_address": { "type": "string", "nullable": true, "description": "Cópia de nível superior do `formatted_address` recalculado, mantida sincronizada quando a morada estruturada é alterada.", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } }, "examples": { "Updated POA": { "summary": "Registo completo de comprovativo de morada (POA) após a correção", "value": { "issuing_state": "ESP", "document_type": "BANK_STATEMENT", "document_language": "es", "issuer": "Banco Example S.A.", "issue_date": "2026-05-02", "poa_address": "Avda de Madrid 34, 28013 Madrid", "name_on_document": "Carmen Espanola", "extra_fields": { "bank_account_number": null, "bank_iban": "ES9121000418450200051332", "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "Carmen E. Espanola" ] }, "poa_parsed_address": { "city": "Madrid", "street_1": "Avda de Madrid 34", "postal_code": "28013", "country": "ES", "formatted_address": "Avda de Madrid 34, Madrid, 28013, ES" }, "poa_formatted_address": "Avda de Madrid 34, Madrid, 28013, ES" } } } } } }, "400": { "description": "Erro de validação. Os erros de campo chegam como `{\"\": [\"\"]}`; os erros em chaves aninhadas de `poa_parsed_address` / `extra_fields` utilizam um valor de objeto: `{\"extra_fields\": {\"\": \"\"}}`.", "content": { "application/json": { "examples": { "Invalid document type": { "summary": "O enum está em maiúsculas — variantes em minúsculas são rejeitadas", "value": { "document_type": [ "\"utility_bill\" is not a valid choice." ] } }, "Invalid issuing state": { "summary": "issuing_state não é ISO 3166-1 alpha-3", "value": { "issuing_state": [ "Invalid ISO 3166-1 alpha-3 country code for issuing_state." ] } }, "additional_names not a list": { "summary": "additional_names aceita uma lista de strings ou null", "value": { "extra_fields": { "additional_names": "Must be a list or null." } } }, "Unsupported poa_parsed_address key": { "summary": "Apenas as sete chaves documentadas são permitidas", "value": { "poa_parsed_address": { "zipcode": "Unsupported key. Allowed keys: address_type, city, region, street_1, street_2, postal_code, country" } } }, "Bad date format": { "summary": "As datas têm de estar no formato AAAA-MM-DD", "value": { "issue_date": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } } } } } }, "403": { "description": "Credenciais em falta ou permissões insuficientes. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "A credencial não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Sessão desconhecida, sessão num estado não editável ou nenhum registo de comprovativo de morada para atualizar. Cada caso tem uma mensagem `detail` distinta (ver exemplos). A pesquisa de sessão desconhecida é executada antes das verificações de credenciais.", "content": { "application/json": { "examples": { "Unknown session": { "summary": "Nenhuma sessão com este ID na sua aplicação (ou foi eliminada)", "value": { "detail": "Not found." } }, "Wrong session state": { "summary": "A sessão existe, mas não está Approved / Declined / In Review / Kyc Expired", "value": { "detail": "No Session matches the given query." } }, "No POA record": { "summary": "O fluxo nunca executou um passo de Comprovativo de morada", "value": { "detail": "The session does not have a POA." } }, "No POA for node": { "summary": "node_id fornecido, mas não existe POA para ele", "value": { "detail": "The session does not have a POA for node 'feature_missing'." } } } } } }, "429": { "description": "Limite de pedidos dedicado excedido — 10 atualizações de dados de POA por minuto por chave de API (pedidos rejeitados contam para o orçamento). O orçamento de escrita partilhado de 300/min também pode ser acionado com a sua própria mensagem. Inspecione os cabeçalhos de resposta `Retry-After` e `X-RateLimit-*` antes de tentar novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Orçamento de atualização de POA esgotado", "value": { "detail": "Session POA data update rate limit exceeded. You can make up to 10 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-poa-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"issuing_state\": \"ESP\",\n \"document_type\": \"BANK_STATEMENT\",\n \"issuer\": \"Banco Example S.A.\",\n \"issue_date\": \"2026-05-02\",\n \"name_on_document\": \"Carmen Espanola\",\n \"poa_address\": \"Avda de Madrid 34, 28013 Madrid\",\n \"extra_fields\": {\n \"bank_iban\": \"ES9121000418450200051332\"\n },\n \"poa_parsed_address\": {\n \"city\": \"Madrid\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_poa_data(\n \"11111111-2222-3333-4444-555555555555\",\n issuing_state=\"ESP\",\n document_type=\"BANK_STATEMENT\",\n issuer=\"Banco Example S.A.\",\n issue_date=\"2026-05-02\",\n poa_address=\"Avda de Madrid 34, 28013 Madrid\",\n name_on_document=\"Carmen Espanola\",\n extra_fields={\"bank_iban\": \"ES9121000418450200051332\", \"additional_names\": [\"Carmen E. Espanola\"]},\n poa_parsed_address={\n \"city\": \"Madrid\",\n \"street_1\": \"Avda de Madrid 34\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updatePoaData(\"11111111-2222-3333-4444-555555555555\", {\n issuing_state: \"ESP\",\n document_type: \"BANK_STATEMENT\",\n issuer: \"Banco Example S.A.\",\n issue_date: \"2026-05-02\",\n poa_address: \"Avda de Madrid 34, 28013 Madrid\",\n name_on_document: \"Carmen Espanola\",\n extra_fields: { bank_iban: \"ES9121000418450200051332\", additional_names: [\"Carmen E. Espanola\"] },\n poa_parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdatePOAData(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdatePOADataParams{\n\tIssuingState: didit.String(\"ESP\"),\n\tDocumentType: didit.Some(didit.SessionsUpdatePOADataParamsDocumentType(\"BANK_STATEMENT\")),\n\tIssuer: didit.String(\"Banco Example S.A.\"),\n\tIssueDate: didit.String(\"2026-05-02\"),\n\tPOAAddress: didit.String(\"Avda de Madrid 34, 28013 Madrid\"),\n\tNameOnDocument: didit.String(\"Carmen Espanola\"),\n\tExtraFields: didit.Some(map[string]any{\"bank_iban\": \"ES9121000418450200051332\", \"additional_names\": []any{\"Carmen E. Espanola\"}}),\n\tPOAParsedAddress: didit.Some(didit.SessionsUpdatePOADataParamsPOAParsedAddress{\n\t\tCity: didit.String(\"Madrid\"),\n\t\tStreet1: didit.String(\"Avda de Madrid 34\"),\n\t\tPostalCode: didit.String(\"28013\"),\n\t\tCountry: didit.String(\"ES\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdatePoaDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updatePoaData(\"11111111-2222-3333-4444-555555555555\", SessionsUpdatePoaDataParams.builder()\n .issuingState(\"ESP\")\n .documentType(SessionsUpdatePoaDataParams.DocumentType.of(\"BANK_STATEMENT\"))\n .issuer(\"Banco Example S.A.\")\n .issueDate(LocalDate.parse(\"2026-05-02\"))\n .poaAddress(\"Avda de Madrid 34, 28013 Madrid\")\n .nameOnDocument(\"Carmen Espanola\")\n .extraFields(Map.of(\"bank_iban\", \"ES9121000418450200051332\", \"additional_names\", List.of(\"Carmen E. Espanola\")))\n .poaParsedAddress(SessionsUpdatePoaDataParams.PoaParsedAddress.builder()\n .city(\"Madrid\")\n .street1(\"Avda de Madrid 34\")\n .postalCode(\"28013\")\n .country(\"ES\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updatePoaData('11111111-2222-3333-4444-555555555555', [\n 'issuing_state' => 'ESP',\n 'document_type' => 'BANK_STATEMENT',\n 'issuer' => 'Banco Example S.A.',\n 'issue_date' => '2026-05-02',\n 'poa_address' => 'Avda de Madrid 34, 28013 Madrid',\n 'name_on_document' => 'Carmen Espanola',\n 'extra_fields' => ['bank_iban' => 'ES9121000418450200051332', 'additional_names' => ['Carmen E. Espanola']],\n 'poa_parsed_address' => [\n 'city' => 'Madrid',\n 'street_1' => 'Avda de Madrid 34',\n 'postal_code' => '28013',\n 'country' => 'ES',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_poa_data(\n \"11111111-2222-3333-4444-555555555555\",\n issuing_state: \"ESP\",\n document_type: \"BANK_STATEMENT\",\n issuer: \"Banco Example S.A.\",\n issue_date: \"2026-05-02\",\n poa_address: \"Avda de Madrid 34, 28013 Madrid\",\n name_on_document: \"Carmen Espanola\",\n extra_fields: { bank_iban: \"ES9121000418450200051332\", additional_names: [\"Carmen E. Espanola\"] },\n poa_parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdatePoaDataAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdatePoaDataParams\n{\n IssuingState = \"ESP\",\n DocumentType = new SessionsUpdatePoaDataParamsDocumentType(\"BANK_STATEMENT\"),\n Issuer = \"Banco Example S.A.\",\n IssueDate = \"2026-05-02\",\n PoaAddress = \"Avda de Madrid 34, 28013 Madrid\",\n NameOnDocument = \"Carmen Espanola\",\n ExtraFields = new Dictionary { [\"bank_iban\"] = \"ES9121000418450200051332\", [\"additional_names\"] = new object[] { \"Carmen E. Espanola\" } },\n PoaParsedAddress = new SessionsUpdatePoaDataParamsPoaParsedAddress\n {\n City = \"Madrid\",\n Street1 = \"Avda de Madrid 34\",\n PostalCode = \"28013\",\n Country = \"ES\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/{companyUuid}/update-data/": { "patch": { "summary": "Atualizar dados da empresa extraídos do registo numa sessão de Verificação de empresas (KYB)", "description": "Corrija os dados da empresa extraídos do registo numa sessão de Verificação de empresas (KYB) — nome da empresa, número de registo, moradas, estado, detalhes de contacto — identificada por `companyUuid`. Os autores típicos das chamadas são um analista de conformidade a corrigir uma leitura incorreta do registo, ou a sua equipa de back office a sincronizar dados corrigidos da empresa. Todos os campos no corpo são opcionais (semântica de `PATCH`); um corpo JSON vazio (`{}`) é uma operação nula (no-op) que apenas ecoa o registo atual da empresa.\n\nAs edições são gravadas em dois locais em simultâneo: os campos com uma coluna canónica da empresa (nome, número de registo, país, data de constituição, número de identificação fiscal, tipo, estados, campos de capital (`registered_capital`, `registered_capital_amount`, `registered_capital_currency`), nomes alternativos, natureza do negócio, website, e-mail, telefone, LEI, localização e `legal_address` → `registered_address`) atualizam essa coluna, e **todas** as chaves submetidas também são integradas no instantâneo de `registry_data` (datas como strings ISO) para que a vista \"extraído do registo\" reflita a correção. Campos sem uma coluna — `region`, `registration_date`, `dissolution_date`, `control_scheme` — são guardados apenas em `registry_data`. `user_provided_data` (o que o utilizador final confirmou no fluxo alojado) nunca é alterado, e `last_console_edit_at` é carimbado em cada PATCH não vazio.\n\nAo contrário dos endpoints de atualização de KYC/POA, **não existe qualquer restrição quanto ao estado da sessão**: a empresa pode ser editada em qualquer ponto do ciclo de vida da sessão da empresa. A empresa deve pertencer à sessão indicada no caminho (caso contrário, `404` com `\"KYB company does not belong to the given session.\"`) e à sua aplicação. Cada PATCH não vazio aciona o [webhook](/pt/integration/webhooks) `data.updated` na sessão da empresa (acionador `console_registry_edit`) — mesmo quando os valores submetidos são iguais aos armazenados. O estado e a decisão da sessão **não** são reavaliados, e nenhuma entrada de revisão/auditoria é registada.\n\nAceita uma chave de API ou um token de utilizador da consola; em qualquer dos casos, a credencial necessita da permissão `write:businesses`. Falhas de autenticação e de permissão devolvem ambas `403` — esta API nunca responde com `401`. Tenha em atenção que a pesquisa da sessão é executada antes das verificações de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo com credenciais em falta. Aplica-se o orçamento partilhado de escrita de 300 pedidos por minuto por chave de API.\n\nPara sessões de Verificação de utilizadores, o equivalente em KYC é `PATCH /v3/session/{sessionId}/update-data/`; para alterar a própria decisão da sessão, utilize `PATCH /v3/session/{sessionId}/update-status/`.", "operationId": "patch_v3_session_kyb_company_update_data", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_company_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão-pai de Verificação de empresas (KYB).", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "companyUuid", "in": "path", "required": true, "description": "UUID do registo da empresa a atualizar (`registry_checks[].company.uuid` na decisão da sessão de empresa). Tem de pertencer à sessão referenciada por `sessionId`.", "schema": { "type": "string", "format": "uuid", "example": "88888888-9999-aaaa-bbbb-cccccccccccc" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Todos os campos são opcionais — envie apenas o que pretende alterar. Os campos fornecidos atualizam as colunas canónicas da empresa (onde existir uma) e são fundidos no instantâneo de `registry_data`.", "properties": { "company_name": { "type": "string", "maxLength": 255, "description": "Nome legal da empresa. Gravado na coluna canónica e no instantâneo do registo.", "example": "Docs Probe Corp" }, "registration_number": { "type": "string", "maxLength": 100, "description": "Número de registo oficial no registo de empresas.", "example": "DPC-001" }, "country_code": { "type": "string", "maxLength": 2, "description": "País de constituição, ISO 3166-1 alpha-2. Não sensível a maiúsculas/minúsculas (`us` é guardado como `US`). Códigos alpha-3 falham o limite de 2 carateres com `400`.", "example": "US" }, "region": { "type": "string", "maxLength": 10, "nullable": true, "description": "Etiqueta de subdivisão / região onde o registo tem uma (p. ex., estado dos EUA). Guardada apenas no instantâneo do registo — não tem coluna canónica." }, "incorporation_date": { "type": "string", "format": "date", "description": "Data de constituição em `YYYY-MM-DD`. Opcional como qualquer outro campo — o `PATCH` é parcial. Qualquer outro formato de data devolve `400`.", "example": "2015-04-12" }, "registration_date": { "type": "string", "format": "date", "nullable": true, "description": "Data de registo caso o registo de empresas a distinga da data de constituição. Armazenada apenas no snapshot do registo de empresas." }, "dissolution_date": { "type": "string", "format": "date", "nullable": true, "description": "Data de dissolução para empresas que já não se encontram ativas. Armazenada apenas no instantâneo do registo." }, "tax_number": { "type": "string", "maxLength": 100, "description": "Número de identificação fiscal." }, "legal_address": { "type": "string", "description": "Sede social / morada registada. Tem como alias no lado do servidor a coluna canónica `registered_address` — a resposta devolve-a sob `registered_address`, enquanto o snapshot do registo mantém a chave `legal_address` que enviou.", "example": "1 Example Plaza, Wilmington, DE 19801" }, "company_type": { "type": "string", "maxLength": 100, "description": "Tipo de entidade jurídica (por exemplo, `Limited Liability Company`, `PLC`, `GmbH`).", "example": "Limited Liability Company" }, "registry_status": { "type": "string", "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off" ], "nullable": true, "description": "Estado da empresa reportado pelo registo de empresas. Em minúsculas, alguns valores contêm espaços (ex.: `struck off`, `no longer authorised`). Qualquer outro valor devolve `400`.", "example": "active" }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "Resultado da verificação no registo. Qualquer outro valor devolve `400`.", "example": "verified" }, "alternative_names": { "type": "string", "description": "Nomes comerciais, denominações sociais anteriores, designações comerciais (DBA) (texto livre)." }, "nature_of_business": { "type": "string", "description": "Breve descrição da atividade da empresa.", "example": "Software development" }, "registered_capital": { "type": "string", "maxLength": 100, "description": "Capital social registado legível por humanos (ex.: `USD 50000`). Utilize `registered_capital_amount` + `registered_capital_currency` para valores estruturados, ou este campo para texto livre.", "example": "USD 50000" }, "registered_capital_amount": { "type": "number", "format": "double", "nullable": true, "description": "Valor numérico do capital social registado (até 20 dígitos, 2 casas decimais). Define a coluna `registered_capital_amount` e é refletido em `registry_data` como uma string decimal; a resposta repete-o como uma string decimal (por exemplo, `\"1500000.50\"`)." }, "registered_capital_currency": { "type": "string", "maxLength": 3, "nullable": true, "description": "Código de moeda ISO 4217 para `registered_capital_amount`. Não diferencia maiúsculas de minúsculas (`usd` é guardado como `USD`); valores que não tenham exatamente 3 letras devolvem `400` com a mensagem ISO 4217. Define a coluna canónica `registered_capital_currency` e é espelhado em `registry_data`.", "example": "USD" }, "website": { "type": "string", "maxLength": 500, "description": "Website da empresa. São aceites domínios simples e normalizados com um prefixo `https://` (`docsprobe.example.com` é guardado como `https://docsprobe.example.com`); os valores que continuem a falhar a validação de URL devolvem `400`.", "example": "https://docsprobe.example.com" }, "email": { "type": "string", "format": "email", "description": "E-mail de contacto registado no registo de empresas.", "example": "legal@docsprobe.example.com" }, "phone": { "type": "string", "maxLength": 50, "description": "Telefone de contacto. Deve corresponder a `+`, dígitos, espaços, traços, pontos ou parênteses, com 7-15 dígitos no total — caso contrário, `400`.", "example": "+1 302 555 0143" }, "legal_entity_identifier": { "type": "string", "maxLength": 50, "description": "LEI, caso a empresa possua um." }, "location_of_registration": { "type": "string", "maxLength": 255, "description": "Cidade / subdivisão do registo oficial." }, "vat_number": { "type": "string", "maxLength": 64, "description": "Número de IVA da UE. Apenas integrado no instantâneo de `registry_data` — editá-lo aqui não volta a executar a validação de IVA e do número de identificação fiscal, pelo que `vat_validation_status` e os restantes campos de resultado `vat_*` permanecem inalterados." }, "control_scheme": { "type": "string", "description": "Esquema de controlo / governação quando o registo o disponibiliza. Guardado apenas no instantâneo do registo." } } }, "examples": { "Correct registry data": { "summary": "Corrigir os campos da empresa extraídos do registo", "value": { "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "incorporation_date": "2015-04-12", "company_type": "Limited Liability Company", "legal_address": "1 Example Plaza, Wilmington, DE 19801", "registry_status": "active", "verification_status": "verified", "website": "docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143", "registered_capital": "USD 50000", "nature_of_business": "Software development" } }, "Single field": { "summary": "Apenas as chaves enviadas por si são gravadas", "value": { "registry_status": "dissolved" } }, "No-op": { "summary": "Um corpo vazio repete o registo atual sem acionar o webhook", "value": {} } } } } }, "responses": { "200": { "description": "Dados da empresa atualizados (ou devolvidos inalterados para um corpo vazio). Devolve o registo completo da empresa em KYB — a mesma estrutura que `registry_checks[].company` na decisão da sessão de empresa. Note como `legal_address` é devolvido como `registered_address`. `registered_capital_amount`/`registered_capital_currency` preenchem as suas colunas canónicas e são refletidos em `registry_data`.", "content": { "application/json": { "schema": { "type": "object", "description": "Registo completo da empresa de KYB — a mesma estrutura do objeto `company` dentro de `registry_checks[]` na decisão da sessão de empresa.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador do registo da empresa (o parâmetro de caminho `companyUuid`)." }, "node_id": { "type": "string", "nullable": true, "description": "Nó do grafo do fluxo ao qual pertence este registo de empresa, quando o fluxo é baseado em grafo." }, "status": { "type": "string", "description": "Estado do ciclo de vida da funcionalidade da verificação no registo (por exemplo, `Not Finished`, `Approved`, `Declined`, `In Review`)." }, "registry_status": { "type": "string", "nullable": true, "description": "Estado da empresa reportado pelo registo de empresas (ex.: `active`, `dissolved`, `struck off`)." }, "data_resolved": { "type": "boolean", "description": "`true` quando os dados da empresa estão completos — sempre `true` para empresas introduzidas manualmente; para empresas obtidas a partir do registo, `true` assim que a obtenção no registo for concluída." }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true, "description": "País de constituição ISO 3166-1 alpha-2." }, "region": { "type": "string", "nullable": true }, "company_type": { "type": "string", "nullable": true }, "incorporation_date": { "type": "string", "format": "date", "nullable": true }, "registered_address": { "type": "string", "nullable": true, "description": "Morada registada canónica — atualizada quando envia `legal_address`." }, "tax_number": { "type": "string", "nullable": true }, "risk_level": { "type": "string", "nullable": true }, "verification_status": { "type": "string", "nullable": true, "description": "`verified`, `failed` ou `unknown`." }, "is_from_registry": { "type": "boolean", "description": "`true` quando a empresa foi pré-preenchida a partir de uma pesquisa no registo em vez de introduzida manualmente." }, "fetch_status": { "type": "string", "nullable": true, "description": "Ciclo de vida de obtenção do registo de empresas para empresas obtidas via registo (`pending` / `resolved`); `null` para entradas manuais." }, "alternative_names": { "type": "string", "nullable": true, "description": "Nomes alternativos, comerciais, anteriores ou no idioma original da empresa em texto, quando comunicados." }, "nature_of_business": { "type": "string", "nullable": true }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "Coluna canónica. Devolvida como uma string decimal (por exemplo, `\"2750000.00\"`)." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Coluna canónica. Definida pelo fluxo do registo ou por edições na consola/API através deste endpoint." }, "website": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "legal_entity_identifier": { "type": "string", "nullable": true }, "location_of_registration": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true, "description": "Número de IVA da UE, quando recolhido durante o passo de registo alojado ou editado posteriormente." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Resultado da validação do número de IVA ou, quando inexistente, do `tax_number`, no envio do registo. `valid` / `invalid`: decidido pelo registo oficial do país (VIES da UE, Noruega, Suíça, Brasil, Colômbia, Costa Rica, Equador, Paraguai; Polónia também pelo seu registo doméstico de IVA). `format_valid` / `invalid_format`: decidido pelas regras de formato e de dígito de controlo do país quando nenhum registo pode ser consultado. `could_not_validate`: o registo estava indisponível. `not_applicable`: sem número, um país sem registo ou regras, ou uma sessão de sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "O número que foi verificado, tal como a fonte o conhece (por exemplo, o número de IVA derivado de um SIREN francês ou de um RSIN neerlandês). `null` quando nenhuma verificação foi executada." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "A origem que determinou o `vat_validation_status`: um registo oficial ou `format_rules`. `null` quando nenhuma verificação foi executada." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registado na fonte que validou o número, quando esta o divulga. Apenas definido quando o estado for `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Morada registada junto da fonte que validou o número, quando esta a divulga. Apenas definida quando o estado é `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da verificação. `null` quando nenhuma verificação foi executada." }, "financial_summary": { "type": "object", "nullable": true, "additionalProperties": true }, "officers": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Administradores / responsáveis associados à empresa, incluindo o progresso de KYC individual." }, "beneficial_owners": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Beneficiários efetivos associados à empresa, incluindo o progresso de KYC por pessoa." }, "addresses": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Detalhe da morada do registo de empresas, caso tenha sido devolvido algum." }, "industries": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Classificação da indústria no registo de empresas, quando disponível." }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Datas de submissão no registo de empresas, quando disponíveis. As declarações anuais e assembleias gerais utilizam last_annual_return_date e last_agm_date; são distintas das contas financeiras." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "O que o utilizador final introduziu durante o passo de confirmação de registo alojado. Nunca modificado por este endpoint." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o utilizador final confirmou os dados da empresa no fluxo alojado." }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Marcado em cada PATCH não vazio bem-sucedido, para que as interfaces de utilizador possam apresentar o contexto \"editado pelo operador\"." }, "is_editable": { "type": "boolean", "description": "`true` enquanto o utilizador final ainda pode editar os dados obtidos a partir do registo no fluxo alojado (obtidos a partir do registo e ainda não confirmados)." } } }, "examples": { "Updated company": { "summary": "Registo completo da empresa após a correção", "value": { "uuid": "6b9479f5-6769-46c8-baf1-df63bbbc5f8c", "node_id": null, "status": "Not Finished", "registry_status": "active", "data_resolved": true, "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "region": null, "company_type": "Limited Liability Company", "incorporation_date": "2015-04-12", "registered_address": "1 Example Plaza, Wilmington, DE 19801", "tax_number": null, "risk_level": null, "verification_status": "verified", "is_from_registry": false, "fetch_status": null, "alternative_names": null, "nature_of_business": "Software development", "registered_capital": "USD 50000", "registered_capital_amount": null, "registered_capital_currency": "USD", "website": "https://docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": null, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": { "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "incorporation_date": "2015-04-12", "legal_address": "1 Example Plaza, Wilmington, DE 19801", "company_type": "Limited Liability Company", "registry_status": "active", "verification_status": "verified", "nature_of_business": "Software development", "registered_capital": "USD 50000", "registered_capital_currency": "USD", "website": "https://docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143" }, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": "2026-06-12T00:02:34.276061Z", "is_editable": false } } } } } }, "400": { "description": "Erro de validação. Os erros de campo chegam como `{\"\": [\"\"]}`. As verificações de comprimento máximo são executadas antes das verificações de formato, pelo que `country_code: \"USA\"` reporta o limite de 2 carateres em vez da mensagem ISO.", "content": { "application/json": { "examples": { "Alpha-3 country code": { "summary": "country_code tem de ser alpha-2 — a verificação de comprimento é acionada primeiro", "value": { "country_code": [ "Ensure this field has no more than 2 characters." ] } }, "Non-alphabetic country code": { "summary": "2 carateres, mas não letras", "value": { "country_code": [ "country_code must be a 2-letter ISO 3166-1 alpha-2 code." ] } }, "Invalid currency": { "summary": "3 carateres, mas não um código ISO 4217", "value": { "registered_capital_currency": [ "Currency must be a 3-letter ISO 4217 code (e.g. USD, EUR, GBP)." ] } }, "Invalid phone": { "summary": "O telefone não passa na verificação de formato / contagem de dígitos", "value": { "phone": [ "Invalid phone number format." ] } }, "Invalid registry status": { "summary": "registry_status não se encontra no enum", "value": { "registry_status": [ "\"liquidated\" is not a valid choice." ] } }, "Invalid email": { "summary": "Endereço de e-mail mal formatado", "value": { "email": [ "Enter a valid email address." ] } }, "Invalid website": { "summary": "O valor falha na validação de URL mesmo após a normalização de https://", "value": { "website": [ "Enter a valid URL." ] } }, "Bad date format": { "summary": "As datas têm de estar no formato AAAA-MM-DD", "value": { "incorporation_date": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } } } } } }, "403": { "description": "Credenciais em falta ou permissões insuficientes. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "A credencial não tem write:businesses", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Sessão desconhecida, empresa desconhecida ou uma empresa que pertence a uma sessão diferente. Cada caso tem uma mensagem `detail` distinta (ver exemplos). A pesquisa de sessão desconhecida é executada antes das verificações de credenciais.", "content": { "application/json": { "examples": { "Unknown session": { "summary": "Nenhuma sessão com este ID na sua aplicação (ou foi eliminada)", "value": { "detail": "Not found." } }, "Unknown company": { "summary": "Nenhuma empresa com este UUID na sua aplicação", "value": { "detail": "No KYBCompany matches the given query." } }, "Company / session mismatch": { "summary": "companyUuid existe, mas pertence a outra sessão", "value": { "detail": "KYB company does not belong to the given session." } } } } } }, "429": { "description": "Limite de pedidos de escrita partilhado excedido (300 pedidos POST/PATCH/DELETE por minuto por chave de API). Inspecione o cabeçalho `Retry-After` e os cabeçalhos de resposta `X-RateLimit-*` antes de tentar novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Orçamento de escrita esgotado", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/33333333-4444-5555-6666-777777777777/kyb/88888888-9999-aaaa-bbbb-cccccccccccc/update-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"company_name\": \"Docs Probe Corp\",\n \"registration_number\": \"DPC-001\",\n \"country_code\": \"US\",\n \"incorporation_date\": \"2015-04-12\",\n \"company_type\": \"Limited Liability Company\",\n \"legal_address\": \"1 Example Plaza, Wilmington, DE 19801\",\n \"registry_status\": \"active\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_company_data(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n company_name=\"Docs Probe Corp\",\n registration_number=\"DPC-001\",\n country_code=\"US\",\n incorporation_date=\"2015-04-12\",\n legal_address=\"1 Example Plaza, Wilmington, DE 19801\",\n company_type=\"Limited Liability Company\",\n registry_status=\"active\",\n verification_status=\"verified\",\n nature_of_business=\"Software development\",\n registered_capital=\"USD 50000\",\n website=\"docsprobe.example.com\",\n email=\"legal@docsprobe.example.com\",\n phone=\"+1 302 555 0143\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybCompanyData(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n {\n company_name: \"Docs Probe Corp\",\n registration_number: \"DPC-001\",\n country_code: \"US\",\n incorporation_date: \"2015-04-12\",\n legal_address: \"1 Example Plaza, Wilmington, DE 19801\",\n company_type: \"Limited Liability Company\",\n registry_status: \"active\",\n verification_status: \"verified\",\n nature_of_business: \"Software development\",\n registered_capital: \"USD 50000\",\n website: \"docsprobe.example.com\",\n email: \"legal@docsprobe.example.com\",\n phone: \"+1 302 555 0143\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBCompanyData(ctx, \"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", didit.SessionsUpdateKYBCompanyDataParams{\n\tCompanyName: didit.String(\"Docs Probe Corp\"),\n\tRegistrationNumber: didit.String(\"DPC-001\"),\n\tCountryCode: didit.String(\"US\"),\n\tIncorporationDate: didit.String(\"2015-04-12\"),\n\tLegalAddress: didit.String(\"1 Example Plaza, Wilmington, DE 19801\"),\n\tCompanyType: didit.String(\"Limited Liability Company\"),\n\tRegistryStatus: didit.Some(didit.SessionsUpdateKYBCompanyDataParamsRegistryStatus(\"active\")),\n\tVerificationStatus: didit.Some(didit.SessionsUpdateKYBCompanyDataParamsVerificationStatus(\"verified\")),\n\tNatureOfBusiness: didit.String(\"Software development\"),\n\tRegisteredCapital: didit.String(\"USD 50000\"),\n\tWebsite: didit.String(\"docsprobe.example.com\"),\n\tEmail: didit.String(\"legal@docsprobe.example.com\"),\n\tPhone: didit.String(\"+1 302 555 0143\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybCompanyDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybCompanyData(\"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", SessionsUpdateKybCompanyDataParams.builder()\n .companyName(\"Docs Probe Corp\")\n .registrationNumber(\"DPC-001\")\n .countryCode(\"US\")\n .incorporationDate(LocalDate.parse(\"2015-04-12\"))\n .legalAddress(\"1 Example Plaza, Wilmington, DE 19801\")\n .companyType(\"Limited Liability Company\")\n .registryStatus(SessionsUpdateKybCompanyDataParams.RegistryStatus.of(\"active\"))\n .verificationStatus(SessionsUpdateKybCompanyDataParams.VerificationStatus.of(\"verified\"))\n .natureOfBusiness(\"Software development\")\n .registeredCapital(\"USD 50000\")\n .website(\"docsprobe.example.com\")\n .email(\"legal@docsprobe.example.com\")\n .phone(\"+1 302 555 0143\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybCompanyData('33333333-4444-5555-6666-777777777777', '88888888-9999-aaaa-bbbb-cccccccccccc', [\n 'company_name' => 'Docs Probe Corp',\n 'registration_number' => 'DPC-001',\n 'country_code' => 'US',\n 'incorporation_date' => '2015-04-12',\n 'legal_address' => '1 Example Plaza, Wilmington, DE 19801',\n 'company_type' => 'Limited Liability Company',\n 'registry_status' => 'active',\n 'verification_status' => 'verified',\n 'nature_of_business' => 'Software development',\n 'registered_capital' => 'USD 50000',\n 'website' => 'docsprobe.example.com',\n 'email' => 'legal@docsprobe.example.com',\n 'phone' => '+1 302 555 0143',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_company_data(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n company_name: \"Docs Probe Corp\",\n registration_number: \"DPC-001\",\n country_code: \"US\",\n incorporation_date: \"2015-04-12\",\n legal_address: \"1 Example Plaza, Wilmington, DE 19801\",\n company_type: \"Limited Liability Company\",\n registry_status: \"active\",\n verification_status: \"verified\",\n nature_of_business: \"Software development\",\n registered_capital: \"USD 50000\",\n website: \"docsprobe.example.com\",\n email: \"legal@docsprobe.example.com\",\n phone: \"+1 302 555 0143\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybCompanyDataAsync(\"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", new SessionsUpdateKybCompanyDataParams\n{\n CompanyName = \"Docs Probe Corp\",\n RegistrationNumber = \"DPC-001\",\n CountryCode = \"US\",\n IncorporationDate = \"2015-04-12\",\n LegalAddress = \"1 Example Plaza, Wilmington, DE 19801\",\n CompanyType = \"Limited Liability Company\",\n RegistryStatus = new SessionsUpdateKybCompanyDataParamsRegistryStatus(\"active\"),\n VerificationStatus = new SessionsUpdateKybCompanyDataParamsVerificationStatus(\"verified\"),\n NatureOfBusiness = \"Software development\",\n RegisteredCapital = \"USD 50000\",\n Website = \"docsprobe.example.com\",\n Email = \"legal@docsprobe.example.com\",\n Phone = \"+1 302 555 0143\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/{partyUuid}/": { "patch": { "summary": "Ignorar (ou voltar a exigir) um interveniente de pessoas-chave numa sessão de Verificação de empresas (KYB)", "description": "Isente uma parte das pessoas-chave da verificação ou coloque-a novamente no âmbito. Esta é a saída de emergência do operador para uma parte que nunca consiga concluir a sua própria verificação - mais frequentemente porque a sessão individual de KYC atribuída a um UBO ou administrador foi eliminada, o que congela o estado dessa sessão subordinada e deixa o KYB parado em `Awaiting User` sem nada que o possa desbloquear.\n\nDefinir `is_skipped: true` remove a parte da agregação de pessoas-chave e recalcula imediatamente o `KYBKeyPeopleCheck` e o estado da sessão principal, para que a sessão da empresa possa ser concluída e, posteriormente, aprovada ou recusada. Enviar `is_skipped: false` coloca a parte novamente no âmbito e a verificação volta a aguardar por ela.\n\nAo contrário da opção de ignorar visível para o candidato no ecrã alojado de pessoas-chave, este endpoint **não** está condicionado pela definição `allow_skip` da função - esse sinalizador limita o que o candidato pode decidir, e não o que o seu analista pode substituir. O campo `requires_verification` permanece deliberadamente inalterado, pelo que uma parte sobreposta é apresentada como `requires_verification: true` **e** `is_skipped: true`, e o registo continua a mostrar o que as regras exigiam.\n\nA parte deve pertencer à sessão indicada no caminho (`404` com `\"Party does not belong to the given session.\"` caso contrário) e à sua aplicação. Um PATCH que altere efetivamente o sinalizador aciona o [webhook](/pt/integration/webhooks) `data.updated` na sessão da empresa com o acionador `console_key_people_skip`; um PATCH que defina o sinalizador com o seu valor atual é uma operação sem efeito que devolve a parte sem alterações.\n\nAceita uma chave de API ou um token de utilizador da consola; em ambos os casos, a credencial necessita da permissão `write:businesses`.", "operationId": "patch_v3_session_kyb_party_update", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_party", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão-pai de Verificação de empresas (KYB).", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "partyUuid", "in": "path", "required": true, "description": "UUID da parte de Pessoas-chave a atualizar (`key_people_checks[].submitted.parties[].uuid` na decisão da sessão de empresa). Tem de pertencer à sessão referenciada por `sessionId`.", "schema": { "type": "string", "format": "uuid", "example": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_skipped" ], "properties": { "is_skipped": { "type": "boolean", "description": "`true` isenta a parte da verificação para que a verificação de pessoas-chave possa ser concluída sem ela; `false` volta a colocá-la no âmbito.", "example": true } } } } } }, "responses": { "200": { "description": "Parte atualizada (ou devolvida inalterada quando o indicador já tinha este valor). Devolve a parte - com a mesma estrutura que uma entrada de `key_people_checks[].submitted.parties[]` na decisão da sessão de empresa.", "content": { "application/json": { "schema": { "type": "object", "description": "Registo de parte das Pessoas-Chave - o mesmo formato que uma entrada de `key_people_checks[].submitted.parties[]` na decisão da sessão de empresa.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador da parte." }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se a parte é uma pessoa singular ou uma empresa." }, "name": { "type": "string", "description": "Nome de apresentação da parte." }, "is_skipped": { "type": "boolean", "description": "Se a parte está isenta de verificação." }, "requires_verification": { "type": "boolean", "description": "O que as regras de função e limiar solicitaram. Não é modificado por este endpoint." }, "kyc_session_status": { "type": "string", "nullable": true, "description": "Estado da sessão KYC individual associada, congelado no momento da eliminação quando a sessão foi eliminada." }, "kyc_session_url": { "type": "string", "nullable": true, "description": "Ligação para a sessão individual de KYC vinculada. `null` quando não existir nenhuma ou quando tiver sido eliminada." }, "kyc_session_deleted": { "type": "boolean", "description": "A sessão de KYC individual associada foi eliminada, pelo que nunca poderá ser concluída." }, "kyb_sub_session_deleted": { "type": "boolean", "description": "Contraparte empresarial de `kyc_session_deleted`." } } } } } }, "400": { "description": "Erro de validação no corpo do pedido. `is_skipped` é o único campo lido por este endpoint e é obrigatório. Os erros de campo chegam como `{\"\": [\"\"]}`. A validação do corpo é executada *após* a pesquisa da parte, pelo que um `is_skipped` malformado enviado para uma parte inexistente devolve `404`, e não `400`.", "content": { "application/json": { "examples": { "Missing is_skipped": { "summary": "Corpo vazio, ou um corpo que omite `is_skipped`", "value": { "is_skipped": [ "This field is required." ] } }, "Non-boolean is_skipped": { "summary": "O valor não é um booleano — `\"maybe\"`, `2`, `[]`. Booleanos, bem como `\"true\"`/`\"false\"`, `1`/`0` e `\"yes\"`/`\"no\"` são todos aceites", "value": { "is_skipped": [ "Must be a valid boolean." ] } }, "Null is_skipped": { "summary": "`is_skipped` está presente mas é `null`", "value": { "is_skipped": [ "This field may not be null." ] } } } } } }, "403": { "description": "Credenciais em falta ou permissões insuficientes. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "A credencial não tem write:businesses", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Parte desconhecida, ou uma parte que pertence a uma sessão diferente. Cada caso tem uma mensagem `detail` distinta (ver exemplos). As verificações de credenciais e permissões são executadas antes da pesquisa da parte, pelo que uma chamada não autorizada devolve `403` em vez de `404`. Não existe uma pesquisa de sessão separada: um `sessionId` desconhecido emparelhado com uma parte sua devolve a mensagem de não correspondência.", "content": { "application/json": { "examples": { "Unknown party": { "summary": "Nenhuma parte com este UUID na sua aplicação", "value": { "detail": "Not found." } }, "Party / session mismatch": { "summary": "partyUuid existe, mas está associado a outra sessão", "value": { "detail": "Party does not belong to the given session." } } } } } }, "429": { "description": "Limite de pedidos de escrita partilhado excedido (300 pedidos POST/PATCH/DELETE por minuto por chave de API). Inspecione o cabeçalho `Retry-After` e os cabeçalhos de resposta `X-RateLimit-*` antes de tentar novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Orçamento de escrita esgotado", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n is_skipped=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybParty(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n {\n is_skipped: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBParty(ctx, \"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", didit.SessionsUpdateKYBPartyParams{\n\tIsSkipped: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybPartyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybParty(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", SessionsUpdateKybPartyParams.builder()\n .isSkipped(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybParty('33333333-4444-5555-6666-777777777777', '0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41', [\n 'is_skipped' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n is_skipped: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybPartyAsync(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", new SessionsUpdateKybPartyParams\n{\n IsSkipped = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/travel-rule/settings/": { "get": { "summary": "Obter definições de Travel Rule", "description": "Leia as definições de Travel Rule da aplicação e o perfil VASP. Cria automaticamente uma linha de definições predefinida (desativada) e um perfil vazio na primeira leitura.", "operationId": "getTravelRuleSettings", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_settings", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/settings/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_settings()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveSettings();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveSettings(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveSettings();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveSettings();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_settings\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveSettingsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Definições atuais da Travel Rule e perfil de VASP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" }, "examples": { "Disabled (default)": { "value": { "is_enabled": false, "jurisdiction": "EU", "name_matching_strictness": "DEFAULT", "confirmation_timeout_hours": 48, "timeout_outcome": "HOLD", "threshold_amount": "0.00", "inbound_auto_accept": true, "allow_self_declaration": true, "allow_screenshot_proof": true, "auto_wallet_verification": true, "vasp_attribution_enabled": true, "legal_name": "", "lei": "", "compliance_email": "", "is_discoverable": true, "counterparty_screening_enabled": false, "sunrise_policy": "", "sunrise_jurisdictions": [ "CO", "KH", "VN" ], "non_responsive_policy": "", "travel_address": "", "disabled_networks": [], "networks": { "gtr": { "rail": "GTR", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "trust": { "rail": "TRUST", "mode": "unavailable", "state": "unavailable", "reason": "own_membership_only", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "verifyvasp": { "rail": "VERIFYVASP", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "sygna": { "rail": "SYGNA", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 } }, "didit_network": { "listed": false, "missing": [ "travel_rule_off", "legal_name_missing", "compliance_email_missing" ], "compliance_email_confirmed": false } } } } } } } } }, "put": { "summary": "Atualizar definições de Travel Rule", "description": "Cria ou atualiza (upsert) as definições de Travel Rule e o perfil de VASP da aplicação. Atualização parcial — envie apenas os campos que pretende alterar. Definir `is_enabled: true` requer um `legal_name` não vazio (já armazenado ou incluído no mesmo pedido); caso contrário, devolve 400.", "operationId": "updateTravelRuleSettings", "x-didit-sdk": { "resource": "travel_rule", "method": "update_settings", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsUpdate" }, "example": { "is_enabled": true, "legal_name": "Origin CASP SL", "jurisdiction": "EU", "name_matching_strictness": "DEFAULT", "confirmation_timeout_hours": 48, "timeout_outcome": "HOLD", "is_discoverable": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/settings/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"legal_name\": \"Origin CASP SL\", \"jurisdiction\": \"EU\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.update_settings(\n is_enabled=True,\n legal_name=\"Origin CASP SL\",\n jurisdiction=\"EU\",\n name_matching_strictness=\"DEFAULT\",\n confirmation_timeout_hours=48,\n timeout_outcome=\"HOLD\",\n is_discoverable=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.updateSettings({\n is_enabled: true,\n legal_name: \"Origin CASP SL\",\n jurisdiction: \"EU\",\n name_matching_strictness: \"DEFAULT\",\n confirmation_timeout_hours: 48,\n timeout_outcome: \"HOLD\",\n is_discoverable: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UpdateSettings(ctx, didit.TravelRuleSettingsUpdate{\n\tIsEnabled: didit.Bool(true),\n\tLegalName: didit.String(\"Origin CASP SL\"),\n\tJurisdiction: didit.String(\"EU\"),\n\tNameMatchingStrictness: didit.Some(didit.TravelRuleSettingsUpdateNameMatchingStrictness(\"DEFAULT\")),\n\tConfirmationTimeoutHours: didit.Int(48),\n\tTimeoutOutcome: didit.Some(didit.TravelRuleSettingsUpdateTimeoutOutcome(\"HOLD\")),\n\tIsDiscoverable: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleSettingsUpdate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().updateSettings(TravelRuleSettingsUpdate.builder()\n .isEnabled(true)\n .legalName(\"Origin CASP SL\")\n .jurisdiction(\"EU\")\n .nameMatchingStrictness(TravelRuleSettingsUpdate.NameMatchingStrictness.of(\"DEFAULT\"))\n .confirmationTimeoutHours(48L)\n .timeoutOutcome(TravelRuleSettingsUpdate.TimeoutOutcome.of(\"HOLD\"))\n .isDiscoverable(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->updateSettings([\n 'is_enabled' => true,\n 'legal_name' => 'Origin CASP SL',\n 'jurisdiction' => 'EU',\n 'name_matching_strictness' => 'DEFAULT',\n 'confirmation_timeout_hours' => 48,\n 'timeout_outcome' => 'HOLD',\n 'is_discoverable' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.update_settings(\n is_enabled: true,\n legal_name: \"Origin CASP SL\",\n jurisdiction: \"EU\",\n name_matching_strictness: \"DEFAULT\",\n confirmation_timeout_hours: 48,\n timeout_outcome: \"HOLD\",\n is_discoverable: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UpdateSettingsAsync(new TravelRuleSettingsUpdate\n{\n IsEnabled = true,\n LegalName = \"Origin CASP SL\",\n Jurisdiction = \"EU\",\n NameMatchingStrictness = new TravelRuleSettingsUpdateNameMatchingStrictness(\"DEFAULT\"),\n ConfirmationTimeoutHours = 48,\n TimeoutOutcome = new TravelRuleSettingsUpdateTimeoutOutcome(\"HOLD\"),\n IsDiscoverable = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Definições e perfil atualizados, na mesma estrutura do GET.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" } } } }, "400": { "description": "Erro de validação, por ex., ativação sem um legal_name, uma sunrise_policy ou non_responsive_policy diferente de HOLD, REJECT, PROCEED ou vazia, um campo desconhecido em `matching_rules` ou uma escolha de `data_sharing_fields` que não cumpre as obrigações do ordenante do regime da sua jurisdição (os erros são indexados por tipo de entidade sob `data_sharing_fields`).", "content": { "application/json": { "schema": { "type": "object" }, "example": { "legal_name": [ "legal_name is required to enable travel rule." ] } } } } } } }, "/v3/travel-rule/settings/compliance-email/confirmation/": { "post": { "summary": "Envie a confirmação por e-mail de conformidade", "description": "Envia uma ligação de confirmação de utilização única para o compliance_email do seu perfil VASP. Abrir a ligação e premir o botão de confirmação confirma o endereço, algo de que a rede Didit necessita antes de listar o seu perfil. Um novo pedido substitui a ligação anterior; a ligação deixa de funcionar quando o e-mail de conformidade é alterado. Um e-mail por minuto por endereço.", "operationId": "sendTravelRuleComplianceEmailConfirmation", "x-didit-sdk": { "resource": "travel_rule", "method": "send_compliance_email_confirmation", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/settings/compliance-email/confirmation/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.send_compliance_email_confirmation()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.sendComplianceEmailConfirmation();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.SendComplianceEmailConfirmation(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().sendComplianceEmailConfirmation();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->sendComplianceEmailConfirmation();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.send_compliance_email_confirmation\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.SendComplianceEmailConfirmationAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "O e-mail de confirmação foi enviado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent_to": { "type": "string", "format": "email" } } }, "example": { "sent_to": "compliance@your-vasp.example" } } } }, "400": { "description": "Nenhum e-mail de conformidade está configurado, ou já se encontra confirmado.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "No compliance email": { "value": { "compliance_email": [ "Set a compliance email before confirming it." ] } }, "Already confirmed": { "value": { "compliance_email": [ "This compliance email is already confirmed." ] } } } } } }, "429": { "description": "Foi enviada uma confirmação para este endereço há menos de um minuto." }, "503": { "description": "Não foi possível enviar o e-mail. Nada foi alterado; tente novamente dentro de momentos." } } } }, "/v3/travel-rule/wallet-addresses/": { "get": { "summary": "Listar entradas do livro de endereços de carteiras", "description": "Lista paginada do catálogo de endereços de carteiras da Travel Rule da sua aplicação, os mais recentes primeiro.", "operationId": "listTravelRuleWalletAddresses", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/wallet-addresses/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.wallet_addresses.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.walletAddresses.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.WalletAddresses.ListAutoPaging(ctx, didit.TravelRuleWalletAddressesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().walletAddresses().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_addresses.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.WalletAddresses.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Entradas do livro de endereços de carteiras paginadas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WalletAddressEntry" } } } } } } } } }, "post": { "summary": "Registar um endereço de carteira", "description": "Adicione uma entrada ao seu livro de endereços de carteiras da Travel Rule para que as transferências recebidas pela rail INTERNAL possam ser associadas a essa entrada.", "operationId": "createTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryCreate" }, "example": { "address": "0xBeneficiaryWallet01", "chain": "ETH", "holder_name": "Ana Diaz", "holder_vendor_data": "user-042", "self_declared": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"address\": \"0xBeneficiaryWallet01\", \"chain\": \"ETH\", \"holder_name\": \"Ana Diaz\", \"self_declared\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.create(\n address=\"0xBeneficiaryWallet01\",\n chain=\"ETH\",\n holder_vendor_data=\"user-042\",\n holder_name=\"Ana Diaz\",\n self_declared=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.create({\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_vendor_data: \"user-042\",\n holder_name: \"Ana Diaz\",\n self_declared: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.Create(ctx, didit.WalletAddressEntryCreate{\n\tAddress: \"0xBeneficiaryWallet01\",\n\tChain: didit.String(\"ETH\"),\n\tHolderVendorData: didit.String(\"user-042\"),\n\tHolderName: didit.String(\"Ana Diaz\"),\n\tSelfDeclared: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletAddressEntryCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().create(WalletAddressEntryCreate.builder()\n .address(\"0xBeneficiaryWallet01\")\n .chain(\"ETH\")\n .holderVendorData(\"user-042\")\n .holderName(\"Ana Diaz\")\n .selfDeclared(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->create([\n 'address' => '0xBeneficiaryWallet01',\n 'chain' => 'ETH',\n 'holder_vendor_data' => 'user-042',\n 'holder_name' => 'Ana Diaz',\n 'self_declared' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.create(\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_vendor_data: \"user-042\",\n holder_name: \"Ana Diaz\",\n self_declared: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.CreateAsync(new WalletAddressEntryCreate\n{\n Address = \"0xBeneficiaryWallet01\",\n Chain = \"ETH\",\n HolderVendorData = \"user-042\",\n HolderName = \"Ana Diaz\",\n SelfDeclared = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "O registo criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntry" } } } }, "400": { "description": "Carteira duplicada (endereço, blockchain e memo) para esta aplicação, um memo ou X-address que a blockchain não suporta, um `address` em falta, um `travel_address` inválido, `self_declared: true` enquanto `allow_self_declaration` está desativado, ou `self_declared: true` enquanto `ownership_validation_mode` está definido como `FULL`.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Duplicate entry": { "value": { "address": [ "A wallet address entry with this address and chain already exists." ] } }, "Invalid travel address": { "value": { "travel_address": [ "Invalid travel address." ] } }, "Self-declaration disabled": { "value": { "self_declared": [ "Self-declared ownership is disabled for this application." ] } } } } } } } } }, "/v3/travel-rule/wallet-addresses/{entry_uuid}/": { "patch": { "summary": "Atualizar metadados do titular do endereço de carteira", "description": "Atualização parcial de holder_name, holder_vendor_data, entity_type e travel_address. Definir travel_address associa um endereço de encaminhamento TRP à entrada; valores inválidos são rejeitados com 400. A resposta reproduz apenas estes quatro campos.", "operationId": "updateTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entry_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryUpdate" }, "example": { "holder_name": "Ana Updated", "travel_address": "ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH https://verification.didit.me/v3/travel-rule/wallet-addresses/{entry_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"holder_name\": \"Ana Updated\", \"travel_address\": \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.update(\n \"11111111-2222-3333-4444-555555555555\",\n holder_name=\"Ana Updated\",\n travel_address=\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.update(\"11111111-2222-3333-4444-555555555555\", {\n holder_name: \"Ana Updated\",\n travel_address: \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WalletAddressEntryUpdateParam{\n\tHolderName: didit.String(\"Ana Updated\"),\n\tTravelAddress: didit.String(\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletAddressEntryUpdate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().update(\"11111111-2222-3333-4444-555555555555\", WalletAddressEntryUpdate.builder()\n .holderName(\"Ana Updated\")\n .travelAddress(\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->update('11111111-2222-3333-4444-555555555555', [\n 'holder_name' => 'Ana Updated',\n 'travel_address' => 'ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.update(\n \"11111111-2222-3333-4444-555555555555\",\n holder_name: \"Ana Updated\",\n travel_address: \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new WalletAddressEntryUpdate\n{\n HolderName = \"Ana Updated\",\n TravelAddress = \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Os campos atualizados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryUpdate" } } } }, "400": { "description": "`travel_address` não é um Travel Address válido.", "content": { "application/json": { "examples": { "Invalid travel address": { "value": { "travel_address": [ "Invalid travel address." ] } } } } } }, "404": { "description": "Entrada desconhecida ou eliminada." } } }, "delete": { "summary": "Eliminar um endereço de carteira", "description": "Elimina a entrada juntamente com os respetivos comprovativos de propriedade e as capturas de ecrã aí armazenadas. Deixa de fazer correspondência com novas transferências de imediato e o endereço fica livre para novo registo. As transferências que já tenham utilizado a carteira mantêm o seu próprio registo da mesma e apresentam os mesmos dados. A eliminação é irreversível.", "operationId": "deleteTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entry_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/wallet-addresses/{entry_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.travel_rule.wallet_addresses.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.travelRule.walletAddresses.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.TravelRule.WalletAddresses.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.travelRule().walletAddresses().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_addresses.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.TravelRule.WalletAddresses.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "Eliminado." }, "404": { "description": "Entrada desconhecida ou já eliminada." }, "503": { "description": "`wallet_address_deletion_incomplete`: não foi possível eliminar um ficheiro armazenado, pelo que a eliminação foi interrompida antes de terminar. A entrada do livro de endereços continua lá; tente novamente o mesmo pedido para a concluir.", "content": { "application/json": { "example": { "detail": "A stored file could not be deleted, so the deletion stopped before it finished. Try again.", "code": "wallet_address_deletion_incomplete" } } } } } } }, "/v3/travel-rule/vasps/": { "get": { "summary": "Pesquisar o diretório de VASP", "description": "Pesquisa paginada e ordenada por nome do diretório de VASP: as entradas do diretório partilhado, que a Didit compila a partir do registo MiCA provisório da ESMA, do diretório público TRISA, do registo global LEI e da sua própria curadoria, além dos membros da rede Didit. Cada linha inclui as rotas que a sua aplicação tem atualmente para ela. O perfil da sua própria aplicação nunca é listado. As linhas incluem também a avaliação partilhada de diligência devida e a própria decisão, triagem de entidades e questionários da sua aplicação.", "operationId": "listTravelRuleVasps", "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "Um fragmento de nome ou pseudónimo (sem distinção entre maiúsculas e minúsculas), um LEI exato ou um domínio (exemplo.com ou um URL no mesmo). Os membros da rede Didit correspondem pelo seu nome legal, LEI ou domínio do seu e-mail de conformidade." }, { "name": "network", "in": "query", "schema": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "description": "Apenas entradas de diretório atualmente listadas pelo diretório de membros de uma rede." }, { "name": "jurisdiction", "in": "query", "schema": { "type": "string" }, "description": "Código de país ISO 3166 alpha-2 ou alpha-3. 400 para qualquer outro valor." }, { "name": "reachable", "in": "query", "schema": { "type": "boolean" }, "description": "true: apenas VASPs para os quais a sua aplicação dispõe de uma rota disponível (incluindo membros da rede Didit). false: apenas entradas do diretório que não consegue alcançar atualmente." }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "directory", "didit" ] }, "description": "Apenas entradas de diretório ou apenas membros da rede Didit." }, { "name": "risk", "in": "query", "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "description": "Apenas entradas de diretório cujo risk_level seja este escalão. Os membros da rede Didit, que não são pontuados, nunca correspondem." }, { "name": "responsiveness", "in": "query", "schema": { "type": "string", "enum": [ "RESPONSIVE", "UNRESPONSIVE", "UNKNOWN" ] }, "description": "Apenas entradas de diretório cujo responsiveness.status seja este valor. Os membros da rede Didit nunca correspondem." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/vasps/?search=counterparty&reachable=true' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.list_vasps():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.listVasps()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.ListVASPsAutoPaging(ctx, didit.TravelRuleListVASPsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().listVasps()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->listVasps() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.list_vasps.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.ListVaspsAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Resultados paginados do diretório de VASP, ordenados por nome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VaspDirectoryEntry" } } } } } } }, "400": { "description": "Um filtro não é válido: o corpo indica cada campo, por exemplo, uma rede, código de país, faixa de risco ou estado de resposta desconhecido.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "jurisdiction": [ "Use an ISO 3166 alpha-2 or alpha-3 country code." ], "network": [ "\"SWIFT\" is not a valid choice." ] } } } } }, "x-didit-sdk": { "resource": "travel_rule", "method": "list_vasps", "auth": "api_key", "server": true } } }, "/v3/travel-rule/vasps/{vasp_id}/": { "get": { "summary": "Obter entrada do diretório de VASP", "description": "Uma entrada de diretório ou membro da rede Didit pelo id devolvido pela pesquisa, com os mesmos campos e as rotas que a sua aplicação tem para ele.", "operationId": "getTravelRuleVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O id de uma linha de GET /v3/travel-rule/vasps/." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVasp(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASP(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVasp(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVasp('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A entrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaspDirectoryEntry" } } } }, "404": { "description": "Nenhuma entrada ou membro listado da rede Didit tem este id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry has this id." } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/decision/": { "get": { "summary": "Obter a sua decisão sobre um VASP", "description": "A decisão da sua aplicação sobre uma contraparte (uma entrada do diretório ou um membro da rede Didit): aprovada, restrita ou bloqueada. Uma entidade de uma marca sem decisão própria segue a decisão da marca, indicada em inherited_from. Privada para a sua aplicação.", "operationId": "getTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O id de uma linha de GET /v3/travel-rule/vasps/: uma entrada do diretório ou um membro da rede Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVaspDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A decisão aplicável, ou null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "examples": { "Own decision": { "value": { "decision": { "decision": "APPROVED", "reason": "Licensed in DE, questionnaire reviewed", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null } } }, "Inherited from the brand": { "value": { "decision": { "decision": "BLOCKED", "reason": "Group refused after review", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": { "id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b", "name": "Example Group" } } } }, "No decision": { "value": { "decision": null } } } } } }, "404": { "description": "Nenhuma entrada do diretório ou membro listado da rede Didit tem este id. O seu próprio perfil VASP nunca é uma contraparte sua.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "put": { "summary": "Defina a sua decisão relativa a um VASP", "description": "Defina ou altere a decisão da sua aplicação relativamente a uma contraparte: APPROVED, RESTRICTED ou BLOCKED, com um motivo opcional. Nunca altera a entrada no diretório partilhado e atua apenas através das suas regras de transação (counterparty_dd_status). Uma decisão sobre uma marca também abrange cada uma das suas entidades que não tenha uma decisão própria.", "operationId": "updateTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "update_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O id de uma linha de GET /v3/travel-rule/vasps/: uma entrada do diretório ou um membro da rede Didit." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionRequest" }, "example": { "decision": "BLOCKED", "reason": "Unlicensed in its home jurisdiction" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"BLOCKED\", \"reason\": \"Unlicensed in its home jurisdiction\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.update_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n decision=\"BLOCKED\",\n reason=\"Unlicensed in its home jurisdiction\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.updateVaspDecision(\"11111111-2222-3333-4444-555555555555\", {\n decision: \"BLOCKED\",\n reason: \"Unlicensed in its home jurisdiction\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UpdateVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyDecisionRequest{\n\tDecision: \"BLOCKED\",\n\tReason: didit.String(\"Unlicensed in its home jurisdiction\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyDecisionRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().updateVaspDecision(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyDecisionRequest.builder()\n .decision(TravelRuleCounterpartyDecisionRequest.Decision.of(\"BLOCKED\"))\n .reason(\"Unlicensed in its home jurisdiction\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->updateVaspDecision('11111111-2222-3333-4444-555555555555', [\n 'decision' => 'BLOCKED',\n 'reason' => 'Unlicensed in its home jurisdiction',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.update_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n decision: \"BLOCKED\",\n reason: \"Unlicensed in its home jurisdiction\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UpdateVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyDecisionRequest\n{\n Decision = \"BLOCKED\",\n Reason = \"Unlicensed in its home jurisdiction\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A decisão tal como se aplica atualmente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "example": { "decision": { "decision": "BLOCKED", "reason": "Unlicensed in its home jurisdiction", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null } } } } }, "400": { "description": "A decisão está em falta ou não é APPROVED, RESTRICTED nem BLOCKED, ou o motivo tem mais de 255 carateres.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "decision": [ "\"MAYBE\" is not a valid choice." ] } } } }, "404": { "description": "Nenhuma entrada do diretório ou membro listado da rede Didit tem este id. O seu próprio perfil VASP nunca é uma contraparte sua.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "delete": { "summary": "Limpar a sua decisão sobre um VASP", "description": "Limpar a decisão da sua própria aplicação sobre uma contraparte. A resposta mostra a decisão aplicável a seguir: nula ou, no caso de uma entidade pertencente a uma marca, a decisão da marca, que a entidade volta a seguir.", "operationId": "clearTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "clear_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O id de uma linha de GET /v3/travel-rule/vasps/: uma entrada do diretório ou um membro da rede Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.clear_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.clearVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ClearVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().clearVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->clearVaspDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.clear_vasp_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ClearVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A decisão foi removida; o corpo apresenta a decisão que se aplica atualmente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "example": { "decision": null } } } }, "404": { "description": "Nenhuma contraparte tem este id, ou a sua aplicação não tem uma decisão própria sobre ela (uma decisão que apenas herde da sua marca não pode ser limpa aqui: limpe a da marca).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Unknown id": { "value": { "detail": "No directory entry or Didit network member has this id." } }, "No decision of its own": { "value": { "detail": "This application has no decision of its own on this counterparty." } } } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/screening/": { "get": { "summary": "Obter triagem de entidade de um VASP", "description": "Se a triagem de contrapartes está ativa para a sua aplicação, quanto custa uma triagem à sua organização, quanto tempo um resultado se mantém atualizado e a sua triagem mais recente de sanções e notícias adversas da contraparte. A consulta é gratuita.", "operationId": "getTravelRuleVaspScreening", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp_screening", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O id de uma linha de GET /v3/travel-rule/vasps/: uma entrada do diretório ou um membro da rede Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/screening/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp_screening(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVaspScreening(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASPScreening(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVaspScreening(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVaspScreening('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp_screening(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspScreeningAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A sua definição de triagem, o respetivo preço e a sua triagem mais recente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningStatus" }, "example": { "enabled": true, "price": "0.20", "fresh_days": 30, "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false } } } } }, "403": { "description": "O contrato da sua organização não tem uma tarifa configurada para triagem de contrapartes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No contract rate is configured for this usage type." } } } }, "404": { "description": "Nenhuma entrada do diretório ou membro listado da rede Didit tem este id. O seu próprio perfil VASP nunca é uma contraparte sua.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "post": { "summary": "Fazer a triagem de um VASP", "description": "Faça a triagem da entidade contraparte contra sanções e notícias adversas para a sua aplicação. Requer adesão voluntária: counterparty_screening_enabled tem de estar ativo nas suas definições de Travel Rule. Cada nova triagem é faturada ao preço de Triagem AML de Empresas da sua organização; em vez disso, é devolvida uma triagem com menos de 30 dias (200, não faturada), exceto se enviar refresh: true. É executada uma triagem de contraparte de cada vez por aplicação. O resultado é privado para a sua aplicação. As aplicações em sandbox nunca são submetidas a triagem.", "operationId": "screenTravelRuleVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "screen_vasp", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O id de uma linha de GET /v3/travel-rule/vasps/: uma entrada do diretório ou um membro da rede Didit." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningRequest" }, "example": { "refresh": false } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/screening/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"refresh\": false}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.screen_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n refresh=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.screenVasp(\"11111111-2222-3333-4444-555555555555\", {\n refresh: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ScreenVASP(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyScreeningRequest{\n\tRefresh: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyScreeningRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().screenVasp(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyScreeningRequest.builder()\n .refresh(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->screenVasp('11111111-2222-3333-4444-555555555555', [\n 'refresh' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.screen_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n refresh: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ScreenVaspAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyScreeningRequest\n{\n Refresh = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Já existia uma triagem recente que foi devolvida. Nada foi faturado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningResult" }, "example": { "outcome": "reused", "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false } } } } }, "201": { "description": "Uma nova triagem foi executada e faturada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningResult" }, "example": { "outcome": "screened", "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "In Review", "total_hits": 2, "score": 85.0, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": true } } } } }, "400": { "description": "O corpo não é válido ou a contraparte não tem nenhum nome para triagem.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "detail": [ "This counterparty has no name to screen." ] } } } }, "403": { "description": "O saldo da sua organização não é suficiente para cobrir a triagem (código insufficient_credits; nada foi executado e nada foi faturado), ou o seu contrato não tem uma tarifa configurada para a mesma.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } } } }, "404": { "description": "Nenhuma entrada do diretório ou membro listado da rede Didit tem este id. O seu próprio perfil VASP nunca é uma contraparte sua.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } }, "409": { "description": "Nada foi executado e nada foi faturado: a triagem de contrapartes está desativada para a sua aplicação, a aplicação é de sandbox ou já está em execução uma triagem desta contraparte.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Screening off": { "value": { "detail": "Counterparty screening is turned off. Enable it in the Travel Rule settings first." } }, "Sandbox application": { "value": { "detail": "Counterparty screening does not run for sandbox applications." } }, "Already running": { "value": { "detail": "A screening of this counterparty is already running. Try again in a moment." } } } } } }, "502": { "description": "Não foi possível concluir a triagem. Nada foi faturado; tente novamente dentro de momentos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "The screening provider did not answer. Try again in a moment." } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/questionnaires/": { "get": { "summary": "Listar questionários de diligência devida com um VASP", "description": "Cada questionário de diligência devida que a sua aplicação enviou à contraparte, do mais recente para o mais antigo, com o respetivo estado e, uma vez respondido, as respostas. Privado para a sua aplicação.", "operationId": "listTravelRuleVaspQuestionnaires", "x-didit-sdk": { "resource": "travel_rule", "method": "list_vasp_questionnaires", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O id de uma linha de GET /v3/travel-rule/vasps/: uma entrada do diretório ou um membro da rede Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/questionnaires/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.list_vasp_questionnaires(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.listVaspQuestionnaires(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ListVASPQuestionnaires(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().listVaspQuestionnaires(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->listVaspQuestionnaires('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.list_vasp_questionnaires(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ListVaspQuestionnairesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Os seus questionários com esta contraparte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaireList" }, "example": { "questionnaires": [ { "id": "3f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f", "status": "SENT", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-10-14T10:00:00Z", "expires_at": "2026-11-13T10:00:00Z", "answered_at": null, "valid_until": null, "current": false, "answers": {} }, { "id": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "status": "ANSWERED", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-09-02T08:00:00Z", "expires_at": "2026-10-02T08:00:00Z", "answered_at": "2026-09-04T15:20:00Z", "valid_until": "2027-09-04T15:20:00Z", "current": true, "answers": { "legal_name": "Example Counterparty VASP, incorporated in the example jurisdiction.", "licensing": "Crypto-asset service provider authorised under MiCA by its national regulator, licence active.", "jurisdictions": "EU and EEA. We do not serve the United States.", "aml_program": "Written AML/CFT policy, annual independent review, last completed in March 2026.", "compliance_officer": "Head of Compliance, reachable at compliance@counterparty.example.", "sanctions_screening": "Customers at onboarding and daily; counterparties on every transfer.", "transaction_monitoring": "Rule-based monitoring with analyst review; suspicious activity reports filed with the FIU.", "travel_rule": "TRP and email; we answer requests within one business day.", "custody": "Segregated customer wallets held with a qualified custodian, insured.", "ownership": "No shareholder holds 25 percent or more; parent company Example Holding Group.", "record_keeping": "Five-year record-keeping for Travel Rule and transaction data, as our regulator requires.", "data_protection": "Encrypted at rest and in transit, stored in the EU." } } ] } } } }, "404": { "description": "Nenhuma entrada do diretório ou membro listado da rede Didit tem este id. O seu próprio perfil VASP nunca é uma contraparte sua.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "post": { "summary": "Enviar um questionário de diligência devida a um VASP", "description": "Envia por e-mail o questionário padrão de diligência devida da Didit para um endereço de conformidade registado da contraparte, com uma ligação de resposta de utilização única. A contraparte tem 30 dias para responder a todas as perguntas; as respostas permanecem válidas durante 365 dias. Um novo envio substitui o seu questionário anterior não respondido à mesma contraparte, cuja ligação deixa de funcionar. Um e-mail por minuto por endereço.", "operationId": "sendTravelRuleVaspQuestionnaire", "x-didit-sdk": { "resource": "travel_rule", "method": "send_vasp_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O id de uma linha de GET /v3/travel-rule/vasps/: uma entrada do diretório ou um membro da rede Didit." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaireRequest" }, "example": { "sent_to": "travelrule@counterparty.example" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/questionnaires/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"sent_to\": \"travelrule@counterparty.example\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.send_vasp_questionnaire(\n \"11111111-2222-3333-4444-555555555555\",\n sent_to=\"travelrule@counterparty.example\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.sendVaspQuestionnaire(\"11111111-2222-3333-4444-555555555555\", {\n sent_to: \"travelrule@counterparty.example\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.SendVASPQuestionnaire(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyQuestionnaireRequest{\n\tSentTo: didit.String(\"travelrule@counterparty.example\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyQuestionnaireRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().sendVaspQuestionnaire(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyQuestionnaireRequest.builder()\n .sentTo(\"travelrule@counterparty.example\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->sendVaspQuestionnaire('11111111-2222-3333-4444-555555555555', [\n 'sent_to' => 'travelrule@counterparty.example',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.send_vasp_questionnaire(\n \"11111111-2222-3333-4444-555555555555\",\n sent_to: \"travelrule@counterparty.example\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.SendVaspQuestionnaireAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyQuestionnaireRequest\n{\n SentTo = \"travelrule@counterparty.example\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "O questionário foi enviado por e-mail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "example": { "id": "3f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f", "status": "SENT", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-10-14T10:00:00Z", "expires_at": "2026-11-13T10:00:00Z", "answered_at": null, "valid_until": null, "current": false, "answers": {} } } } }, "400": { "description": "sent_to não é um endereço de e-mail válido ou não é um endereço de conformidade registado para a contraparte, ou a contraparte não tem um endereço de conformidade registado.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Not on record": { "value": { "sent_to": [ "Send the questionnaire to a compliance address on record for this counterparty." ] } }, "No address": { "value": { "sent_to": [ "No compliance address is on record for this counterparty. Add a contact for it first." ] } } } } } }, "404": { "description": "Nenhuma entrada do diretório ou membro listado da rede Didit tem este id. O seu próprio perfil VASP nunca é uma contraparte sua.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } }, "429": { "description": "Um questionário foi enviado para este endereço há menos de um minuto." }, "503": { "description": "Não foi possível enviar o e-mail e nenhum questionário foi criado. Tente novamente dentro de momentos." } } } }, "/v3/transactions/{transaction_id}/travel-rule/": { "patch": { "summary": "Concluir, cancelar, reenviar ou atualizar a carteira do ordenante de uma transferência da Travel Rule", "description": "Forneça `payment_txn_id` para comunicar o hash on-chain e mover uma transferência de saída COMPLETED para FINISHED (a sua contraparte no canal INTERNAL também passa para FINISHED), `{\"action\": \"cancel\"}` para cancelar uma transferência não terminal, ou `{\"action\": \"resend\"}` para reencaminhar uma transferência de saída bloqueada em COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA (melhore primeiro os dados da contraparte, por exemplo adicionando um travel_address à entrada da carteira de destino). O resend aplica-se apenas a transferências de saída. `{\"action\": \"update_compliance_email\", \"compliance_email\": \"desk@example.com\"}` substitui o e-mail de conformidade de uma transferência de saída num desses três estados, a correção para `reason: email_undeliverable`: o estado não se altera e o próximo `resend` envia o pedido para esse endereço. Um reenvio é colocado em fila, não executado dentro do pedido: a resposta mostra a transferência novamente em AWAITING_COUNTERPARTY com uma entrada na cronologia `resend queued` e uma `delivery` em fila, e o respetivo destino é recebido através de um webhook `travel_rule.status.updated`. Quando a transferência tiver sido realizada através do GTR, VerifyVASP ou Sygna Bridge, a rede toma conhecimento do hash on-chain ou do cancelamento após a resposta, com novas tentativas; `delivery` mostra o estado dessa mensagem. `{\"action\": \"update_originator_wallet\", \"wallet_address\": \"...\"}` regista a carteira da qual os fundos realmente saíram numa transferência de saída, por exemplo o endereço a partir do qual um levantamento de UTXO foi emitido em vez da carteira principal que declarou. Altera apenas o registo: nada é enviado novamente para a contraparte e o estado mantém-se. O ordenante passa a ser `chain_details.originator` com `source: updated`, a alteração é adicionada à `timeline` com a carteira anterior e a nova, e a contraparte no canal INTERNAL da transferência é atualizada da mesma forma. `{\"action\": \"beneficiary_vasp\", \"beneficiary_vasp\": \"\"}` indique pessoalmente a contraparte quando a deteção automática não foi possível, numa transferência de saída em COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA: a transferência é encaminhada para esse VASP e enviada novamente.", "operationId": "patchTravelRuleTransfer", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "update_transfer", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID de transação estável da Didit proprietário da transferência.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferPatchRequest" }, "examples": { "Finish": { "value": { "payment_txn_id": "0xchainhash" } }, "Cancel": { "value": { "action": "cancel" } }, "Resend": { "value": { "action": "resend" } }, "Update compliance email": { "value": { "action": "update_compliance_email", "compliance_email": "desk@example.com" } }, "Update originator wallet": { "value": { "action": "update_originator_wallet", "wallet_address": "bc1qOriginatorInputAddress01" } }, "Name the counterparty": { "value": { "action": "beneficiary_vasp", "beneficiary_vasp": "9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"payment_txn_id\": \"0xchainhash\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.update_transfer(\n \"11111111-2222-3333-4444-555555555555\",\n payment_txn_id=\"0xchainhash\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.updateTransfer(\"11111111-2222-3333-4444-555555555555\", {\n payment_txn_id: \"0xchainhash\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.UpdateTransfer(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleTransferPatchRequest{\n\tPaymentTxnID: didit.String(\"0xchainhash\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleTransferPatchRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().updateTransfer(\"11111111-2222-3333-4444-555555555555\", TravelRuleTransferPatchRequest.builder()\n .paymentTxnId(\"0xchainhash\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->updateTransfer('11111111-2222-3333-4444-555555555555', [\n 'payment_txn_id' => '0xchainhash',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.update_transfer(\n \"11111111-2222-3333-4444-555555555555\",\n payment_txn_id: \"0xchainhash\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.UpdateTransferAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleTransferPatchRequest\n{\n PaymentTxnId = \"0xchainhash\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A transferência atualizada. Após `update_compliance_email`, o respetivo estado permanece inalterado e mantém `reason: email_undeliverable` até ao próximo `resend`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } } }, "400": { "description": "Nem payment_txn_id nem uma ação suportada foram fornecidos, `compliance_email` está em falta ou não é um endereço de e-mail em `update_compliance_email`, ou, para `update_originator_wallet`, nenhum wallet_address, uma carteira ou memo que a blockchain da transferência não consiga suportar, ou uma carteira que não seja uma das entradas UTXO da transferência, ou `beneficiary_vasp` está em falta ou não é um ID de VASP válido no diretório.", "content": { "application/json": { "examples": { "No action": { "value": { "detail": [ "Provide payment_txn_id, action=cancel, action=resend, action=beneficiary_vasp, action=update_originator_wallet or action=update_compliance_email." ] } }, "Invalid compliance email": { "value": { "compliance_email": [ "Enter a valid email address." ] } } } } } }, "404": { "description": "Transação desconhecida, a transação não tem nenhuma transferência Travel Rule, ou (ação `beneficiary_vasp`) nenhuma entrada do diretório tem esse id." }, "409": { "description": "A transferência não está num estado que permita esta operação (por exemplo, não está em COMPLETED/outbound para finalizar, já se encontra num estado terminal para cancelar ou não é uma transferência de saída num estado reenviável para reenviar). `update_compliance_email` responde com `409` para uma transferência de entrada e para uma transferência de saída fora de COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE e NOT_ENOUGH_COUNTERPARTY_DATA. `update_originator_wallet` responde com `409` para uma transferência de entrada, cancelada ou expirada. `beneficiary_vasp` responde com `409`, a menos que a transferência seja de saída e esteja em COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA.", "content": { "application/json": { "examples": { "Cancel from a terminal status": { "value": { "detail": "Transfer is already in a terminal state." } }, "Resend not allowed": { "value": { "detail": "Transfer cannot be resent from its current state." } }, "Finish not allowed": { "value": { "detail": "Transfer must be an outbound transfer in COMPLETED status to finish." } }, "Compliance email cannot change": { "value": { "detail": "The compliance email of this transfer cannot change from its current state." } } } } } } } } }, "/v3/transactions/{transaction_id}/travel-rule/ownership/": { "post": { "summary": "Confirmar ou negar a propriedade da carteira", "description": "Resolva uma transferência que aguarda a propriedade da carteira: chame-a do seu próprio lado da transferência quando estiver em UNCONFIRMED_OWNERSHIP, ou quando for uma transferência recebida em ON_HOLD. A confirmação marca a entrada correspondente no livro de endereços de carteiras como propriedade verificada (para uma transferência recebida em ON_HOLD sem nenhuma entrada, a Didit cria uma a partir de beneficiary_data.wallet_address) e executa a correspondência do nome do beneficiário em ambos os lados da transferência; a rejeição recusa ambos os lados. Uma transferência recebida cujo depósito já foi liquidado avança para FINISHED quando a correspondência é bem-sucedida. Quando a carteira da contraparte foi declarada como autocustodiada (counterparty.payment_method.method_type: unhosted_wallet), a confirmação regista que o cliente verificou quem controla essa carteira e conclui a transferência (COMPLETED) em ambas as direções, ou FINISHED para um depósito recebido cujo hash on-chain já seja conhecido. A carteira verificada é a da contraparte: o destino de um levantamento enviado, ou a origem (carteira do ordenante) de um depósito recebido. Se ainda não constar do seu livro de endereços de carteiras, a Didit adiciona-a com propriedade verificada sob o nome da contraparte; se o livro já a contiver sob um nome de titular diferente, a transferência muda para COUNTERPARTY_MISMATCHED_DATA. Para uma transferência TRP recebida em UNCONFIRMED_OWNERSHIP, ON_HOLD ou COUNTERPARTY_MISMATCHED_DATA, a Didit envia a sua decisão para o VASP de origem: a aprovação devolve o endereço de pagamento (wallet_address, ou o endereço da entrada correspondente) e avança a transferência para COMPLETED, e a rejeição recusa-a. A mesma chamada também decide uma transferência recebida enviada por uma contraparte da GTR ou Sygna Bridge que aguarda a sua revisão (`UNCONFIRMED_OWNERSHIP`, `ON_HOLD` ou `COUNTERPARTY_MISMATCHED_DATA`): `confirmed: true` aprova-a (forneça `wallet_address` se a transferência não indicar nenhum) e `confirmed: false` recusa-a, e a resposta é enviada à rede depois, com novas tentativas. O VerifyVASP obtém a sua resposta quando a solicita, pelo que uma transferência VerifyVASP que necessitasse da sua revisão é recusada imediatamente e não pode ser decidida posteriormente.", "operationId": "confirmTravelRuleOwnership", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "confirm_ownership", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID estável da Didit da transação que a sua aplicação detém para esta transferência: a transação do lado do beneficiário numa transferência por via INTERNAL, ou a transação que criou (de saída ou de entrada) quando a carteira da contraparte foi declarada como autocustodiada.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleOwnershipConfirmRequest" }, "example": { "confirmed": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/ownership/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"confirmed\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.confirm_ownership(\n \"11111111-2222-3333-4444-555555555555\",\n confirmed=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.confirmOwnership(\"11111111-2222-3333-4444-555555555555\", {\n confirmed: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.ConfirmOwnership(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleOwnershipConfirmRequest{\n\tConfirmed: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleOwnershipConfirmRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().confirmOwnership(\"11111111-2222-3333-4444-555555555555\", TravelRuleOwnershipConfirmRequest.builder()\n .confirmed(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->confirmOwnership('11111111-2222-3333-4444-555555555555', [\n 'confirmed' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.confirm_ownership(\n \"11111111-2222-3333-4444-555555555555\",\n confirmed: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.ConfirmOwnershipAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleOwnershipConfirmRequest\n{\n Confirmed = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A transferência atualizada. Para uma transferência recebida, os dados originator_data/beneficiary_data da contraparte permanecem mascarados (`data_masked: true`) até que a propriedade seja confirmada; em seguida, `data_unmasked` regista quando, porquê e por quem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } } }, "409": { "description": "A transferência não está a aguardar confirmação de propriedade, nenhuma entrada no livro de endereços de carteiras corresponde à carteira da contraparte, uma transferência INTERNAL de outro cliente Didit necessita de um comprovativo de controlo (uma mensagem assinada ou um depósito de teste) antes de poder ser confirmada, ou uma transferência de rede já foi respondida através da respetiva rede (uma transferência VerifyVASP, ou uma transferência GTR ou Sygna Bridge sobre a qual você ou a Didit já decidiram).", "content": { "application/json": { "examples": { "Not awaiting confirmation": { "value": { "detail": "Transfer is not awaiting ownership confirmation." } }, "No matching address book entry": { "value": { "detail": "wallet address entry no longer available" } } } } } }, "400": { "description": "Erro de validação: confirmed está em falta, uma aprovação TRP de entrada não tem wallet_address nem endereço alternativo, ou `confirmed: true` numa transferência declarada de carteira autocustodiada que não indica uma carteira de contraparte e nenhum `wallet_address` foi enviado.", "content": { "application/json": { "examples": { "No payment address": { "value": { "wallet_address": [ "wallet_address is required to approve." ] } } } } } }, "404": { "description": "Transação desconhecida, ou a transação não tem nenhuma transferência Travel Rule." }, "502": { "description": "Apenas para transferências TRP de entrada: a Didit não conseguiu entregar a sua decisão ao VASP de origem, pelo que o estado da transferência não muda.", "content": { "application/json": { "examples": { "Callback not delivered": { "value": { "detail": "Counterparty inquiry-resolution callback could not be delivered." } } } } } } } } }, "/v3/transactions/{transaction_id}/travel-rule/messages/": { "get": { "summary": "Listar mensagens de Travel Rule", "description": "Mensagens e pedidos de documentos trocados com o VASP da contraparte sobre esta transferência.", "operationId": "listTravelRuleMessages", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "list_messages", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID de transação estável da Didit proprietário da transferência.", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/messages/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.list_messages(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.listMessages(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.ListMessages(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().listMessages(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->listMessages('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.travel_rule.list_messages(\"11111111-2222-3333-4444-555555555555\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.ListMessagesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "As mensagens, da mais antiga para a mais recente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleMessage" } } } } }, "404": { "description": "Transação ou token desconhecido, ou nenhuma transferência Travel Rule na transação." } } }, "post": { "summary": "Enviar uma mensagem ou pedido de documentos de Travel Rule", "description": "Envia uma mensagem ou um pedido de documentos para o VASP de contraparte. Funciona em transferências INTERNAL (o outro cliente da Didit visualiza-a no seu lado do par) e em transferências EMAIL (a contraparte recebe um e-mail e responde no portal de recolha). Uma transferência através de TRP, GTR, TRUST, VerifyVASP ou Sygna não transporta mensagens, porque esses protocolos não as suportam. Limites: 100 mensagens por transferência, 5000 carateres por corpo, 10 documentos solicitados, 5 ficheiros de 10 MB cada.", "operationId": "createTravelRuleMessage", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "create_message", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID de transação estável da Didit proprietário da transferência.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" }, "example": { "kind": "DOCUMENT_REQUEST", "body": "Please confirm the date of birth of the beneficiary.", "requested_documents": [ "Proof of address" ] } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/messages/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"kind\": \"DOCUMENT_REQUEST\", \"body\": \"Please confirm the date of birth of the beneficiary.\", \"requested_documents\": [\"Proof of address\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.create_message(\n \"11111111-2222-3333-4444-555555555555\",\n kind=\"DOCUMENT_REQUEST\",\n body=\"Please confirm the date of birth of the beneficiary.\",\n requested_documents=[\"Proof of address\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.createMessage(\"11111111-2222-3333-4444-555555555555\", {\n kind: \"DOCUMENT_REQUEST\",\n body: \"Please confirm the date of birth of the beneficiary.\",\n requested_documents: [\"Proof of address\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.CreateMessage(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleMessageCreateRequest{\n\tKind: didit.Some(didit.TravelRuleMessageCreateRequestKind(\"DOCUMENT_REQUEST\")),\n\tBody: didit.String(\"Please confirm the date of birth of the beneficiary.\"),\n\tRequestedDocuments: didit.Some([]string{\"Proof of address\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleMessageCreateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().createMessage(\"11111111-2222-3333-4444-555555555555\", TravelRuleMessageCreateRequest.builder()\n .kind(TravelRuleMessageCreateRequest.Kind.of(\"DOCUMENT_REQUEST\"))\n .body(\"Please confirm the date of birth of the beneficiary.\")\n .requestedDocuments(List.of(\"Proof of address\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->createMessage('11111111-2222-3333-4444-555555555555', [\n 'kind' => 'DOCUMENT_REQUEST',\n 'body' => 'Please confirm the date of birth of the beneficiary.',\n 'requested_documents' => ['Proof of address'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.create_message(\n \"11111111-2222-3333-4444-555555555555\",\n kind: \"DOCUMENT_REQUEST\",\n body: \"Please confirm the date of birth of the beneficiary.\",\n requested_documents: [\"Proof of address\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.CreateMessageAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleMessageCreateRequest\n{\n Kind = new TravelRuleMessageCreateRequestKind(\"DOCUMENT_REQUEST\"),\n Body = \"Please confirm the date of birth of the beneficiary.\",\n RequestedDocuments = new string[] { \"Proof of address\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A mensagem armazenada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessage" } } } }, "400": { "description": "Corpo inválido, um tipo ou tamanho de ficheiro não aceite, mais de 100 mensagens na transferência ou um `reply_to` que não seja uma mensagem desta transferência.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "requested_documents": [ "Name at least one document the counterparty should send." ] } } } }, "404": { "description": "Transação ou token desconhecido, ou nenhuma transferência Travel Rule na transação." }, "409": { "description": "Nenhuma mensagem consegue alcançar a contraparte. `detail` indica a razão: a transferência decorre sobre um canal de rede (TRP, GTR, TRUST, VerifyVASP ou Sygna), ainda não tem contraparte, os dados de uma transferência INTERNAL não corresponderam ao titular da carteira pelo que nada chegou ao destinatário, ou a ligação de levantamento de uma transferência EMAIL expirou ou a transferência está fechada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/travel-rule/pickup/{token}/": { "get": { "summary": "Obter informações de recolha do canal de e-mail", "description": "Público, não autenticado. Permite que um VASP de contraparte que não utiliza a Didit pré-visualize a troca pendente a partir da ligação de recolha enviada por e-mail. O próprio token é a autenticação.", "operationId": "getTravelRulePickup", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_pickup", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact", "in": "query", "required": false, "schema": { "type": "string" }, "description": "O valor `?contact=` da ligação, o contacto para o qual a ligação foi enviada. Devolvido como `contact` sem alterações; não é validado." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/pickup/{token}/" } ], "responses": { "200": { "description": "Pré-visualização da recolha.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRulePickupInfo" }, "example": { "reference": "33333333-4444-5555-6666-777777777777", "requested_at": "2026-07-05T10:00:00Z", "originator_vasp_name": "Origin CASP SL", "originator_vasp_lei": "529900EXAMPLEORIG001", "recipient_vasp_name": "Example Counterparty VASP", "language": "es", "amount": "0.250000000000000000", "currency": "ETH", "fiat_amount": "", "fiat_currency": "", "chain": "ETH", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "status": "AWAITING_COUNTERPARTY", "ivms_version": "ivms101.2023", "deadline_at": "2026-07-07T10:00:00Z", "reminders_sent": 0, "contact": "", "decline_reasons": [ "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ], "join_invitation": { "eligible": false, "url": "" }, "originator_data": { "name": "Jane Doe", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" }, "beneficiary_data": { "name": "Ana Diaz", "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb" }, "ivms_request": { "originator": { "originatorPersons": [ { "naturalPerson": { "name": { "nameIdentifier": [ { "primaryIdentifier": "Doe", "secondaryIdentifier": "Jane", "nameIdentifierType": "LEGL" } ] } } } ], "accountNumber": [ "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" ] }, "beneficiary": { "beneficiaryPersons": [ { "naturalPerson": { "name": { "nameIdentifier": [ { "primaryIdentifier": "Diaz", "secondaryIdentifier": "Ana", "nameIdentifierType": "LEGL" } ] } } } ], "accountNumber": [ "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb" ] } }, "data_masked": false } } } }, "404": { "description": "Token desconhecido." }, "410": { "description": "A janela foi encerrada: a contraparte já respondeu, a transferência saiu de AWAITING_COUNTERPARTY ou o prazo expirou." } } } }, "/v3/travel-rule/pickup/{token}/respond/": { "post": { "summary": "Responder a uma recolha por via de e-mail", "description": "Público, não autenticado. Aceita ou recusa a troca a partir da ligação de recolha enviada por e-mail. Ao aceitar, beneficiary_name é verificado contra a política name_matching_strictness do ordenante.", "operationId": "respondTravelRulePickup", "x-didit-sdk": { "resource": "travel_rule", "method": "respond_pickup", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact", "in": "query", "required": false, "schema": { "type": "string" }, "description": "O valor `?contact=` da ligação. Utilizado quando o corpo não envia nenhum `contact`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRulePickupRespondRequest" }, "example": { "decision": "accept", "beneficiary_name": "Carlos Ruiz" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/respond/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"accept\", \"beneficiary_name\": \"Carlos Ruiz\"}'" } ], "responses": { "200": { "description": "O estado da troca resultante: COMPLETED ou COUNTERPARTY_MISMATCHED_DATA após uma aceitação, COUNTERPARTY_VASP_GENERAL_DECLINE após uma recusa, que também devolve `decline_reason`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "decline_reason": { "type": "string", "description": "Presente após uma recusa." } } }, "examples": { "accepted": { "value": { "status": "COMPLETED" } }, "declined": { "value": { "status": "COUNTERPARTY_VASP_GENERAL_DECLINE", "decline_reason": "not_our_customer" } } } } } }, "400": { "description": "Um campo é inválido: por exemplo, `decision` em falta ou diferente de `accept` ou `decline`, `decline_detail` em falta numa recusa com `decline_reason: other`, uma `ivms_response` que não seja um objeto IVMS 101 ou tenha mais de 16384 carateres, ou um `contact` no corpo que não seja um UUID (`{\"contact\": [\"Must be a valid UUID.\"]}`).", "content": { "application/json": { "example": { "decline_detail": [ "Say what the reason is when you choose another reason." ] } } } }, "404": { "description": "Token desconhecido." }, "410": { "description": "A janela foi encerrada: a contraparte já respondeu, a transferência saiu de AWAITING_COUNTERPARTY ou o prazo expirou." } } } }, "/v3/travel-rule/pickup/{token}/messages/": { "get": { "summary": "Listar mensagens de recolha", "description": "Público, não autenticado. As mensagens de uma transferência através da via EMAIL tal como o VASP de contraparte as lê: o que o cliente enviou é `INBOUND` e é assinado com o nome do VASP do cliente. O token é a autenticação.", "operationId": "listTravelRulePickupMessages", "x-didit-sdk": { "resource": "travel_rule", "method": "list_pickup_messages", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/pickup/{token}/messages/" } ], "responses": { "200": { "description": "As mensagens, da mais antiga para a mais recente, do lado da contraparte.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleMessage" } } } } }, "404": { "description": "Token desconhecido." }, "410": { "description": "A ligação de recolha expirou ou a transferência está fechada." } } }, "post": { "summary": "Responder no portal de recolha", "description": "Público, não autenticado. O VASP de contraparte responde numa transferência através da via EMAIL. Tem o mesmo corpo que as mensagens da transação; os anexos têm de ser PDF, PNG, JPEG ou WebP. O token é a autenticação.", "operationId": "createTravelRulePickupMessage", "x-didit-sdk": { "resource": "travel_rule", "method": "create_pickup_message", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" }, "example": { "kind": "MESSAGE", "body": "Attached is the proof of address of the wallet holder." } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/messages/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"kind\": \"MESSAGE\", \"body\": \"Attached is the proof of address of the wallet holder.\"}'" } ], "responses": { "201": { "description": "A mensagem armazenada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessage" } } } }, "400": { "description": "Corpo inválido, um tipo ou tamanho de ficheiro não aceite, mais de 100 mensagens na transferência ou um `reply_to` que não seja uma mensagem desta transferência.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "requested_documents": [ "Name at least one document the counterparty should send." ] } } } }, "404": { "description": "Token desconhecido." }, "410": { "description": "A ligação de recolha expirou ou a transferência está fechada." } } } }, "/v3/travel-rule/inbound/": { "post": { "summary": "Registar uma transferência de entrada pós-depósito (sunrise)", "description": "Registar dados da Travel Rule para um depósito de cripto que já foi liquidado on-chain antes de ocorrer qualquer troca. Cria uma transação de entrada da Travel Rule (ou reutiliza um depósito não reclamado) e resolve a transferência em relação ao seu livro de endereços de carteiras. Para uma transação recém-criada, o Didit envia primeiro transaction.created e depois os webhooks travel_rule.status.updated.", "operationId": "registerTravelRuleInbound", "x-didit-sdk": { "resource": "travel_rule", "method": "register_inbound", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundRequest" }, "example": { "chain": "ETH", "txid": "0xdeposit-hash", "wallet_address": "0xYourDepositWallet", "amount": "500.00", "currency": "USDC", "originator_data": { "name": "Origin CASP SL" }, "beneficiary_data": { "name": "Ana Diaz" }, "originating_vasp": { "name": "Origin CASP SL", "lei": "", "travel_address": "ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/inbound/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"chain\":\"ETH\",\"txid\":\"0xdeposit-hash\",\"wallet_address\":\"0xYourDepositWallet\",\"amount\":\"500.00\",\"currency\":\"USDC\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.register_inbound(\n chain=\"ETH\",\n txid=\"0xdeposit-hash\",\n wallet_address=\"0xYourDepositWallet\",\n amount=\"500.00\",\n currency=\"USDC\",\n originator_data={\"name\": \"Origin CASP SL\"},\n beneficiary_data={\"name\": \"Ana Diaz\"},\n originating_vasp={\n \"name\": \"Origin CASP SL\",\n \"lei\": \"\",\n \"travel_address\": \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.registerInbound({\n chain: \"ETH\",\n txid: \"0xdeposit-hash\",\n wallet_address: \"0xYourDepositWallet\",\n amount: \"500.00\",\n currency: \"USDC\",\n originator_data: { name: \"Origin CASP SL\" },\n beneficiary_data: { name: \"Ana Diaz\" },\n originating_vasp: {\n name: \"Origin CASP SL\",\n lei: \"\",\n travel_address: \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RegisterInbound(ctx, didit.TravelRuleInboundRequest{\n\tChain: \"ETH\",\n\tTxid: \"0xdeposit-hash\",\n\tWalletAddress: \"0xYourDepositWallet\",\n\tAmount: \"500.00\",\n\tCurrency: \"USDC\",\n\tOriginatorData: didit.Some(map[string]any{\"name\": \"Origin CASP SL\"}),\n\tBeneficiaryData: didit.Some(map[string]any{\"name\": \"Ana Diaz\"}),\n\tOriginatingVASP: didit.Some(didit.TravelRuleInboundRequestOriginatingVASP{\n\t\tName: didit.String(\"Origin CASP SL\"),\n\t\tLei: didit.String(\"\"),\n\t\tTravelAddress: didit.String(\"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleInboundRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().registerInbound(TravelRuleInboundRequest.builder()\n .chain(\"ETH\")\n .txid(\"0xdeposit-hash\")\n .walletAddress(\"0xYourDepositWallet\")\n .amount(\"500.00\")\n .currency(\"USDC\")\n .originatorData(Map.of(\"name\", \"Origin CASP SL\"))\n .beneficiaryData(Map.of(\"name\", \"Ana Diaz\"))\n .originatingVasp(TravelRuleInboundRequest.OriginatingVasp.builder()\n .name(\"Origin CASP SL\")\n .lei(\"\")\n .travelAddress(\"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->registerInbound([\n 'chain' => 'ETH',\n 'txid' => '0xdeposit-hash',\n 'wallet_address' => '0xYourDepositWallet',\n 'amount' => '500.00',\n 'currency' => 'USDC',\n 'originator_data' => ['name' => 'Origin CASP SL'],\n 'beneficiary_data' => ['name' => 'Ana Diaz'],\n 'originating_vasp' => [\n 'name' => 'Origin CASP SL',\n 'lei' => '',\n 'travel_address' => 'ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.register_inbound(\n chain: \"ETH\",\n txid: \"0xdeposit-hash\",\n wallet_address: \"0xYourDepositWallet\",\n amount: \"500.00\",\n currency: \"USDC\",\n originator_data: { name: \"Origin CASP SL\" },\n beneficiary_data: { name: \"Ana Diaz\" },\n originating_vasp: {\n name: \"Origin CASP SL\",\n lei: \"\",\n travel_address: \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RegisterInboundAsync(new TravelRuleInboundRequest\n{\n Chain = \"ETH\",\n Txid = \"0xdeposit-hash\",\n WalletAddress = \"0xYourDepositWallet\",\n Amount = \"500.00\",\n Currency = \"USDC\",\n OriginatorData = new Dictionary { [\"name\"] = \"Origin CASP SL\" },\n BeneficiaryData = new Dictionary { [\"name\"] = \"Ana Diaz\" },\n OriginatingVasp = new TravelRuleInboundRequestOriginatingVasp\n {\n Name = \"Origin CASP SL\",\n Lei = \"\",\n TravelAddress = \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Já foi registada uma transferência para este txid e wallet_address; a existente é devolvida sem alterações (created é false).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundResponse" } } } }, "201": { "description": "Foi registada uma nova transferência Travel Rule, numa nova transação de entrada ou num depósito não reclamado existente (created é true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundResponse" } } } }, "400": { "description": "Falta um campo obrigatório (`chain`, `txid`, `wallet_address`, `amount`, `currency`), `originating_vasp.lei` não é um LEI válido, `originating_vasp.travel_address` não é um Travel Address válido, um memo, X-address ou `utxo` que a blockchain não suporta, ou `originator_data` / `beneficiary_data` que não é um objeto.", "content": { "application/json": { "examples": { "Missing field": { "value": { "txid": [ "This field is required." ] } }, "Invalid LEI": { "value": { "originating_vasp": { "lei": [ "Invalid LEI: expected 20 alphanumeric characters (ISO 17442)." ] } } } } } } } } } }, "/v3/travel-rule/test-vasp/inbound/": { "post": { "summary": "Acionar uma transferência de entrada a partir do VASP de teste da Didit (sandbox)", "description": "Apenas aplicações em sandbox. O VASP de Teste do Didit envia à sua aplicação uma transferência Travel Rule de entrada, permitindo-lhe testar o lado recetor de uma plataforma de câmbio de criptomoedas de ponta a ponta antes de avançar para produção. A transferência é registada e decidida pela mesma lógica que uma transferência de entrada real a partir de uma rede executa contra o seu livro de endereços de carteiras, pelo que a caixa de entrada, a decisão e o fluxo de propriedade da carteira funcionam exatamente como em produção. Nada sai do Didit. Uma aplicação em produção recebe 400. Envie novamente a mesma `reference` para obter a transferência registada pela primeira chamada em vez de uma segunda transferência.", "operationId": "triggerTravelRuleTestVaspInbound", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "trigger_test_vasp_inbound", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTestVaspInboundRequest" }, "example": { "beneficiary_wallet_address": "0xYourSandboxWallet", "scenario": "accept", "amount": "1", "reference": "demo-001" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/test-vasp/inbound/ \\\n -H 'x-api-key: YOUR_SANDBOX_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"beneficiary_wallet_address\":\"0xYourSandboxWallet\",\"scenario\":\"accept\",\"reference\":\"demo-001\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.trigger_test_vasp_inbound(\n beneficiary_wallet_address=\"0xYourSandboxWallet\",\n scenario=\"accept\",\n amount=\"1\",\n reference=\"demo-001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.triggerTestVaspInbound({\n beneficiary_wallet_address: \"0xYourSandboxWallet\",\n scenario: \"accept\",\n amount: \"1\",\n reference: \"demo-001\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.TriggerTestVASPInbound(ctx, didit.TravelRuleTestVASPInboundRequest{\n\tBeneficiaryWalletAddress: \"0xYourSandboxWallet\",\n\tScenario: didit.Some(didit.TravelRuleTestVASPInboundRequestScenario(\"accept\")),\n\tAmount: didit.String(\"1\"),\n\tReference: didit.String(\"demo-001\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleTestVaspInboundRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().triggerTestVaspInbound(TravelRuleTestVaspInboundRequest.builder()\n .beneficiaryWalletAddress(\"0xYourSandboxWallet\")\n .scenario(TravelRuleTestVaspInboundRequest.Scenario.of(\"accept\"))\n .amount(\"1\")\n .reference(\"demo-001\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->triggerTestVaspInbound([\n 'beneficiary_wallet_address' => '0xYourSandboxWallet',\n 'scenario' => 'accept',\n 'amount' => '1',\n 'reference' => 'demo-001',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.trigger_test_vasp_inbound(\n beneficiary_wallet_address: \"0xYourSandboxWallet\",\n scenario: \"accept\",\n amount: \"1\",\n reference: \"demo-001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.TriggerTestVaspInboundAsync(new TravelRuleTestVaspInboundRequest\n{\n BeneficiaryWalletAddress = \"0xYourSandboxWallet\",\n Scenario = new TravelRuleTestVaspInboundRequestScenario(\"accept\"),\n Amount = \"1\",\n Reference = \"demo-001\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A transferência de entrada foi registada e decidida. Uma repetição com a mesma `reference` devolve o mesmo corpo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTestVaspInboundResponse" } } } }, "400": { "description": "Corpo inválido, um `scenario` desconhecido ou não suportado, ou a aplicação é uma aplicação de produção.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Não foi possível registar a transferência, por exemplo, porque o Travel Rule não está ativado para a aplicação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/travel-rule/widget-session/": { "post": { "summary": "Emitir uma sessão do widget de propriedade de uma carteira", "description": "Gerar um URL/token para o widget alojado para comprovar a propriedade da carteira. Envie o cliente para o URL devolvido para comprovar o controlo de uma carteira (assinatura de mensagem, teste Satoshi, captura de ecrã ou autodeclaração). Nesta versão, o widget funciona apenas na web - abra o URL no navegador do sistema ou num separador personalizado, nunca dentro de uma webview de SDK móvel.", "operationId": "createTravelRuleWidgetSession", "x-didit-sdk": { "resource": "travel_rule", "method": "create_widget_session", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetSessionCreate" }, "example": { "wallet_address": "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9", "chain": "ETH", "holder_name": "Jane Doe", "vendor_data": "user-042", "transaction_id": "99999999-aaaa-bbbb-cccc-dddddddddddd", "expires_in_minutes": 60 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget-session/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"wallet_address\":\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\"chain\":\"ETH\",\"holder_name\":\"Jane Doe\",\"transaction_id\":\"99999999-aaaa-bbbb-cccc-dddddddddddd\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.create_widget_session(\n wallet_address=\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain=\"ETH\",\n holder_name=\"Jane Doe\",\n vendor_data=\"user-042\",\n transaction_id=\"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes=60,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.createWidgetSession({\n wallet_address: \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain: \"ETH\",\n holder_name: \"Jane Doe\",\n vendor_data: \"user-042\",\n transaction_id: \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes: 60,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.CreateWidgetSession(ctx, didit.TravelRuleWidgetSessionCreate{\n\tWalletAddress: didit.String(\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\"),\n\tChain: didit.String(\"ETH\"),\n\tHolderName: didit.String(\"Jane Doe\"),\n\tVendorData: didit.String(\"user-042\"),\n\tTransactionID: didit.String(\"99999999-aaaa-bbbb-cccc-dddddddddddd\"),\n\tExpiresInMinutes: didit.Int(60),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWidgetSessionCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().createWidgetSession(TravelRuleWidgetSessionCreate.builder()\n .walletAddress(\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\")\n .chain(\"ETH\")\n .holderName(\"Jane Doe\")\n .vendorData(\"user-042\")\n .transactionId(\"99999999-aaaa-bbbb-cccc-dddddddddddd\")\n .expiresInMinutes(60L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->createWidgetSession([\n 'wallet_address' => '0xd3b62acb76fb27a7f8961ec40fa11746b113aca9',\n 'chain' => 'ETH',\n 'holder_name' => 'Jane Doe',\n 'vendor_data' => 'user-042',\n 'transaction_id' => '99999999-aaaa-bbbb-cccc-dddddddddddd',\n 'expires_in_minutes' => 60,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.create_widget_session(\n wallet_address: \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain: \"ETH\",\n holder_name: \"Jane Doe\",\n vendor_data: \"user-042\",\n transaction_id: \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes: 60\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.CreateWidgetSessionAsync(new TravelRuleWidgetSessionCreate\n{\n WalletAddress = \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n Chain = \"ETH\",\n HolderName = \"Jane Doe\",\n VendorData = \"user-042\",\n TransactionId = \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n ExpiresInMinutes = 60,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A sessão de widget gerada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetSessionResponse" } } } }, "400": { "description": "Corpo inválido: o `callback_url` não é um URL http(s) absoluto, o `expires_in_minutes` está fora do intervalo de 5 a 10080, o `transaction_id` não é um UUID ou um campo excede o respetivo limite.", "content": { "application/json": { "examples": { "Invalid callback_url": { "value": { "callback_url": [ "callback_url must be an absolute http(s) URL." ] } } } } } }, "404": { "description": "`transaction_id` não identifica uma transferência Travel Rule nesta aplicação." } } } }, "/v3/travel-rule/widget/{token}/": { "get": { "summary": "Obter contexto do widget de propriedade da carteira", "description": "Endpoint de leitura público associado ao token de sessão do widget - sem necessidade de chave de API. Devolve o contexto do widget e o estado de cada prova, para que possa consultá-lo periodicamente para detetar a conclusão; completed_at deixa de ser nulo assim que uma prova é verificada. Uma prova SATOSHI_TEST pode permanecer no estado PENDING enquanto o seu depósito for visto on-chain mas não confirmado - uma tarefa em segundo plano verifica-a automaticamente de novo e conclui-a assim que o depósito confirmar, pelo que nenhuma ação do cliente é necessária enquanto aguarda. Cada prova inclui os campos de que o seu método precisa: deposit_address, expected_amount e o seu próprio expires_at para SATOSHI_TEST; challenge para MESSAGE_SIGNING. Prefira o webhook travel_rule.status.updated à consulta periódica (polling) quando a sessão estiver associada a uma transferência.", "operationId": "getTravelRuleWidgetContext", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_widget_context", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token de sessão opaco devolvido quando a sessão do widget foi gerada.", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/widget/{token}/" } ], "responses": { "200": { "description": "O contexto do widget e os estados dos comprovativos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetContext" } } } }, "404": { "description": "Token desconhecido." }, "410": { "description": "A sessão expirou sem ser concluída." } } } }, "/v3/travel-rule/widget/{token}/vasps/": { "get": { "summary": "Pesquisar VASPs a partir do widget de carteira", "description": "Endpoint de leitura público associado ao token de sessão do widget, sem necessidade de chave de API: o seletor de VASP do widget do utilizador final. A mesma pesquisa e filtros que GET /v3/travel-rule/vasps/ para a aplicação do widget, respondendo apenas sobre a identidade de cada VASP e se pode ser contactada.", "operationId": "listTravelRuleWidgetVasps", "x-didit-sdk": { "resource": "travel_rule", "method": "list_widget_vasps", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token de sessão opaco devolvido quando a sessão do widget foi gerada.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "Um fragmento de nome ou pseudónimo (sem distinção entre maiúsculas e minúsculas), um LEI exato ou um domínio (exemplo.com ou um URL no mesmo). Os membros da rede Didit correspondem pelo seu nome legal, LEI ou domínio do seu e-mail de conformidade." }, { "name": "network", "in": "query", "schema": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "description": "Apenas entradas de diretório atualmente listadas pelo diretório de membros de uma rede." }, { "name": "jurisdiction", "in": "query", "schema": { "type": "string" }, "description": "Código de país ISO 3166 alpha-2 ou alpha-3. 400 para qualquer outro valor." }, { "name": "reachable", "in": "query", "schema": { "type": "boolean" }, "description": "true: apenas VASPs para os quais a sua aplicação dispõe de uma rota disponível (incluindo membros da rede Didit). false: apenas entradas do diretório que não consegue alcançar atualmente." }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "directory", "didit" ] }, "description": "Apenas entradas de diretório ou apenas membros da rede Didit." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/travel-rule/widget/{token}/vasps/?search=counterparty'" } ], "responses": { "200": { "description": "Resultados paginados, ordenados por nome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VaspDirectoryWidgetEntry" } } } } } } }, "400": { "description": "Um filtro não é válido: o corpo indica cada campo, por exemplo, uma rede ou código de país desconhecido.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "jurisdiction": [ "Use an ISO 3166 alpha-2 or alpha-3 country code." ], "network": [ "\"SWIFT\" is not a valid choice." ] } } } }, "404": { "description": "Token desconhecido." }, "410": { "description": "A sessão expirou." } } }, "post": { "summary": "Selecionar o VASP de contraparte no widget da carteira", "description": "Endpoint de escrita público associado ao token de sessão do widget, sem necessidade de chave de API: o utilizador final escolheu a VASP de destino que a descoberta automática não conseguiu identificar. Apenas uma transferência de saída em COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA a aceita. A transferência é encaminhada para essa VASP e enviada novamente; a descoberta automática nunca substitui a escolha.", "operationId": "selectTravelRuleWidgetVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "select_widget_vasp", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token de sessão opaco devolvido quando a sessão do widget foi gerada.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vasp" ], "properties": { "vasp": { "type": "string", "format": "uuid", "description": "O `id` de um VASP a partir de `GET /v3/travel-rule/widget/{token}/vasps/`." } } }, "example": { "vasp": "9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/vasps/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"vasp\": \"9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607\"}'" } ], "responses": { "200": { "description": "A escolha foi registada e a transferência está a ser enviada novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "transfer_status": { "type": "string", "description": "O estado da transferência após a seleção." }, "counterparty_vasp": { "type": "string", "description": "O nome do VASP que o utilizador final selecionou." } } }, "example": { "detail": "Counterparty VASP selected; the transfer is being resent.", "transfer_status": "AWAITING_COUNTERPARTY", "counterparty_vasp": "Northwind Exchange" } } } }, "400": { "description": "`vasp` está em falta ou nenhuma entrada do diretório ativo tem esse id.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "vasp": [ "No directory entry has this id." ] } } } }, "404": { "description": "Token desconhecido." }, "409": { "description": "A sessão do widget não está associada a uma transferência Travel Rule ou a transferência não é de saída num estado que aceite uma contraparte." }, "410": { "description": "A sessão expirou." } } } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/": { "patch": { "summary": "Ativar/desativar monitorização contínua AML para utilizadores", "description": "Ativa ou desativa a monitorização AML contínua ao nível do utilizador. É mantida exatamente uma triagem AML monitorizada por utilizador; para utilizadores sem qualquer triagem AML (por exemplo, utilizadores importados), é primeiro criada e realizada uma, faturada como uma triagem AML normal. Defina estimate_only para pré-visualizar contagens e custos sem gravar. Lotes de 20 ou menos são resolvidos em linha (200, COMPLETED); lotes maiores devolvem 202 e são executados de forma assíncrona.", "operationId": "toggle_vendor_users_ongoing_monitoring", "x-didit-sdk": { "resource": "users", "method": "set_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleRequest" }, "example": { "is_enabled": true, "didit_internal_id_list": [ "5b9a0000-0000-4000-8000-00000000f00d" ] } } } }, "responses": { "200": { "description": "Estimativa (quando estimate_only) ou a tarefa concluída para pequenos lotes processados inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "Lotes maiores são processados de forma assíncrona; consulte periodicamente o endpoint de tarefas com o job_id devolvido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "Privilégio write:sessions em falta, ou saldo insuficiente para ativar (a estimativa está incluída no corpo do erro)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.set_ongoing_monitoring(\n is_enabled=True,\n didit_internal_id_list=[\"5b9a0000-0000-4000-8000-00000000f00d\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.setOngoingMonitoring({\n is_enabled: true,\n didit_internal_id_list: [\"5b9a0000-0000-4000-8000-00000000f00d\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.SetOngoingMonitoring(ctx, didit.OngoingMonitoringToggleRequest{\n\tIsEnabled: true,\n\tDiditInternalIDList: didit.Some([]string{\"5b9a0000-0000-4000-8000-00000000f00d\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.OngoingMonitoringToggleRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().setOngoingMonitoring(OngoingMonitoringToggleRequest.builder()\n .isEnabled(true)\n .diditInternalIdList(List.of(\"5b9a0000-0000-4000-8000-00000000f00d\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->setOngoingMonitoring([\n 'is_enabled' => true,\n 'didit_internal_id_list' => ['5b9a0000-0000-4000-8000-00000000f00d'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.set_ongoing_monitoring(\n is_enabled: true,\n didit_internal_id_list: [\"5b9a0000-0000-4000-8000-00000000f00d\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.SetOngoingMonitoringAsync(new OngoingMonitoringToggleRequest\n{\n IsEnabled = true,\n DiditInternalIdList = new string[] { \"5b9a0000-0000-4000-8000-00000000f00d\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "Obter tarefa de monitorização AML contínua", "description": "Progresso e contadores por resultado de uma tarefa de alternância de monitorização. Efetue sondagens a cada dois segundos enquanto o estado for PENDING ou PROCESSING.", "operationId": "get_vendor_users_ongoing_monitoring_job", "x-didit-sdk": { "resource": "users", "method": "retrieve_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da tarefa de monitorização devolvido pelo endpoint de alternância." } ], "responses": { "200": { "description": "A tarefa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "Tarefa desconhecida para esta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.retrieve_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.RetrieveOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->retrieveOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.retrieve_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.RetrieveOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/": { "patch": { "summary": "Ativar/desativar monitorização contínua AML para empresas", "description": "Equivalente ao nível da empresa da alternância do utilizador: uma triagem AML monitorizada por empresa, sendo que as empresas sem qualquer triagem AML são triadas primeiro (entidade empresarial). O mesmo contrato de estimate_only, via rápida inline e tarefa assíncrona.", "operationId": "toggle_vendor_businesses_ongoing_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleRequest" }, "example": { "is_enabled": true, "didit_internal_id_list": [ "b0000000-0000-4000-8000-0000000000b1" ] } } } }, "responses": { "200": { "description": "Estimativa (quando estimate_only) ou a tarefa concluída para pequenos lotes processados inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "Lotes maiores são processados de forma assíncrona; consulte periodicamente o endpoint de tarefas com o job_id devolvido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "Privilégio write:sessions em falta, ou saldo insuficiente para ativar (a estimativa está incluída no corpo do erro)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.set_ongoing_monitoring(\n is_enabled=True,\n didit_internal_id_list=[\"b0000000-0000-4000-8000-0000000000b1\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setOngoingMonitoring({\n is_enabled: true,\n didit_internal_id_list: [\"b0000000-0000-4000-8000-0000000000b1\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetOngoingMonitoring(ctx, didit.OngoingMonitoringToggleRequest{\n\tIsEnabled: true,\n\tDiditInternalIDList: didit.Some([]string{\"b0000000-0000-4000-8000-0000000000b1\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.OngoingMonitoringToggleRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().setOngoingMonitoring(OngoingMonitoringToggleRequest.builder()\n .isEnabled(true)\n .diditInternalIdList(List.of(\"b0000000-0000-4000-8000-0000000000b1\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setOngoingMonitoring([\n 'is_enabled' => true,\n 'didit_internal_id_list' => ['b0000000-0000-4000-8000-0000000000b1'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_ongoing_monitoring(\n is_enabled: true,\n didit_internal_id_list: [\"b0000000-0000-4000-8000-0000000000b1\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetOngoingMonitoringAsync(new OngoingMonitoringToggleRequest\n{\n IsEnabled = true,\n DiditInternalIdList = new string[] { \"b0000000-0000-4000-8000-0000000000b1\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "Obter tarefa de monitorização AML contínua", "description": "Progresso e contadores por resultado de uma tarefa de alternância de monitorização. Efetue sondagens a cada dois segundos enquanto o estado for PENDING ou PROCESSING.", "operationId": "get_vendor_businesses_ongoing_monitoring_job", "x-didit-sdk": { "resource": "businesses", "method": "retrieve_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da tarefa de monitorização devolvido pelo endpoint de alternância." } ], "responses": { "200": { "description": "A tarefa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "Tarefa desconhecida para esta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.retrieve_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.RetrieveOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieveOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/": { "patch": { "summary": "Ativar/desativar monitorização contínua AML para sessões de empresas", "description": "Comutador ao nível da sessão para verificações KYB, endereçado pelo número de sessão. Nas sessões sem uma triagem AML, é criada uma e associada à própria sessão. O mesmo contrato de estimate_only, caminho rápido inline e tarefa assíncrona que os endpoints ao nível do utilizador. Substitui o comportamento síncrono legado que ignorava sessões sem uma triagem AML.", "operationId": "toggle_business_sessions_ongoing_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_session_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean", "description": "true para ativar a monitorização, false para a desativar." }, "estimate_only": { "type": "boolean", "default": false, "description": "Quando for true, devolve a estimativa de custos e não realiza gravações." }, "update_all": { "type": "boolean", "default": false, "description": "Aplicar a todas as entidades da aplicação (delimitado pelos parâmetros filter_* quando presentes)." }, "filter_search": { "type": "string" }, "filter_status": { "type": "array", "items": { "type": "string" } }, "filter_country": { "type": "string" }, "filter_date_from": { "type": "string", "format": "date" }, "filter_date_to": { "type": "string", "format": "date" }, "session_numbers": { "type": "array", "items": { "type": "string" }, "description": "Números de sessão de empresa a alternar. Obrigatório a menos que update_all (ou o alias legado toggle_all) seja true." }, "toggle_all": { "type": "boolean", "default": false, "description": "Alias legado de update_all." }, "filter_workflow_id": { "type": "string" } } }, "example": { "is_enabled": true, "session_numbers": [ "1001", "1002" ] } } } }, "responses": { "200": { "description": "Estimativa (quando estimate_only) ou a tarefa concluída para pequenos lotes processados inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "Lotes maiores são processados de forma assíncrona; consulte periodicamente o endpoint de tarefas com o job_id devolvido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "Privilégio write:sessions em falta, ou saldo insuficiente para ativar (a estimativa está incluída no corpo do erro)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.set_session_ongoing_monitoring(\n is_enabled=True,\n session_numbers=[\"1001\", \"1002\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setSessionOngoingMonitoring({\n is_enabled: true,\n session_numbers: [\"1001\", \"1002\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetSessionOngoingMonitoring(ctx, didit.BusinessesSetSessionOngoingMonitoringParams{\n\tIsEnabled: true,\n\tSessionNumbers: didit.Some([]string{\"1001\", \"1002\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesSetSessionOngoingMonitoringParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().setSessionOngoingMonitoring(BusinessesSetSessionOngoingMonitoringParams.builder()\n .isEnabled(true)\n .sessionNumbers(List.of(\"1001\", \"1002\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setSessionOngoingMonitoring([\n 'is_enabled' => true,\n 'session_numbers' => ['1001', '1002'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_session_ongoing_monitoring(\n is_enabled: true,\n session_numbers: [\"1001\", \"1002\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetSessionOngoingMonitoringAsync(new BusinessesSetSessionOngoingMonitoringParams\n{\n IsEnabled = true,\n SessionNumbers = new string[] { \"1001\", \"1002\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "Obter tarefa de monitorização AML contínua", "description": "Progresso e contadores por resultado de uma tarefa de alternância de monitorização. Efetue sondagens a cada dois segundos enquanto o estado for PENDING ou PROCESSING.", "operationId": "get_business_sessions_ongoing_monitoring_job", "x-didit-sdk": { "resource": "businesses", "method": "retrieve_session_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da tarefa de monitorização devolvido pelo endpoint de alternância." } ], "responses": { "200": { "description": "A tarefa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "Tarefa desconhecida para esta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.retrieve_session_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieveSessionOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.RetrieveSessionOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieveSessionOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieveSessionOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve_session_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveSessionOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/": { "get": { "summary": "Listar casos", "description": "Listar casos para a aplicação, dos mais recentes para os mais antigos. Suporta filtros, pesquisa e ordenação; consulte os parâmetros de consulta. Paginado com `limit`/`offset`.", "operationId": "list_cases", "x-didit-sdk": { "resource": "cases", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Tamanho da página. A predefinição é 50." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset de base zero do primeiro registo." }, { "name": "status__in", "in": "query", "schema": { "type": "string" }, "description": "Estados a incluir separados por vírgulas, por exemplo, OPEN,AWAITING_USER." }, { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "Prioridades a incluir separadas por vírgulas." }, { "name": "source__in", "in": "query", "schema": { "type": "string" }, "description": "Origens a incluir separadas por vírgulas." }, { "name": "blueprint", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filtrar para casos neste blueprint." }, { "name": "assigned_to", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filtrar para casos atribuídos a este utilizador." }, { "name": "unassigned", "in": "query", "schema": { "type": "boolean" }, "description": "true para casos não atribuídos, false para casos atribuídos." }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "Filtrar para casos que tenham exatamente esta etiqueta." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Corresponde ao título, número do caso, etiqueta, nome/UUID/ID externo do sujeito, UUID da sessão associada ou UUID da transação associada." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limite inferior da data de criação (inclusivo)." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limite superior da data de criação (inclusivo)." }, { "name": "due_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Limite superior de due_at." }, { "name": "overdue", "in": "query", "schema": { "type": "boolean" }, "description": "true para devolver apenas casos em atraso que estejam abertos ou a aguardar utilizador." }, { "name": "ordering", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "due_at", "-due_at" ], "default": "-created_at" }, "description": "Ordem de ordenação. due_at ordena os nulos no final." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/?status__in=OPEN,AWAITING_USER&ordering=-due_at' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.ListAutoPaging(ctx, didit.CasesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Lista paginada de casos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número de linhas correspondentes. Exato até 100, limitado a 100 acima desse valor por motivos de desempenho. Confie que `next` é null para detetar a última página." }, "next": { "type": "string", "nullable": true, "description": "URL absoluto da página seguinte, ou null." }, "previous": { "type": "string", "nullable": true, "description": "URL absoluto da página anterior, ou null." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseListItem" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar caso", "description": "Crie um caso associado a exatamente um sujeito (um utilizador ou uma empresa), diretamente ou derivando o sujeito a partir de uma ligação de sessão/transação anexada. A origem é sempre `MANUAL` para casos criados via API.", "operationId": "create_case", "x-didit-sdk": { "resource": "cases", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID de CaseBlueprint. Omitir para não usar blueprint." }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "MEDIUM" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "object", "description": "Obrigatório exceto se links for fornecido; o sujeito estritamente único do caso.", "properties": { "type": { "type": "string", "enum": [ "user", "business" ] }, "uuid": { "type": "string", "format": "uuid" } } }, "links": { "type": "array", "description": "Sessões/sessões de empresa/transações a anexar na criação, por exemplo, [{\"entity_type\": \"transaction\", \"entity_uuid\": \"...\"}]. Quando o assunto for omitido, o assunto é derivado do proprietário da primeira associação.", "items": { "type": "object" } }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID do utilizador a atribuir imediatamente." }, "review_duplicates": { "type": "boolean", "default": false, "description": "Volte a verificar investigações existentes antes de criar o caso. Quando for true, um sujeito com casos existentes exige um separate_incident_reason não vazio. A consola ativa sempre esta proteção. Omiti-la mantém o comportamento existente da API." }, "separate_incident_reason": { "type": "string", "maxLength": 1000 }, "source_context": { "$ref": "#/components/schemas/CaseDuplicateCaseFraudSourceContextRequest" } } }, "example": { "title": "Manual - Jane Doe", "blueprint": "b1de0000-0000-4000-8000-000000000002", "priority": "HIGH", "subject": { "type": "user", "uuid": "5b9a0000-0000-4000-8000-00000000f00d" }, "tags": [ "review" ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Manual - Jane Doe\", \"blueprint\": \"b1de0000-0000-4000-8000-000000000002\", \"priority\": \"HIGH\", \"subject\": {\"type\": \"user\", \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\"}, \"tags\": [\"review\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.create(\n title=\"Manual - Jane Doe\",\n blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n priority=\"HIGH\",\n tags=[\"review\"],\n subject={\n \"type\": \"user\",\n \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.create({\n title: \"Manual - Jane Doe\",\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n priority: \"HIGH\",\n tags: [\"review\"],\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Create(ctx, didit.CasesCreateParams{\n\tTitle: \"Manual - Jane Doe\",\n\tBlueprint: didit.String(\"b1de0000-0000-4000-8000-000000000002\"),\n\tPriority: didit.Some(didit.CasesCreateParamsPriority(\"HIGH\")),\n\tTags: didit.Some([]string{\"review\"}),\n\tSubject: didit.Some(didit.CasesCreateParamsSubject{\n\t\tType: didit.Some(didit.CasesCreateParamsSubjectType(\"user\")),\n\t\tUUID: didit.String(\"5b9a0000-0000-4000-8000-00000000f00d\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().create(CasesCreateParams.builder()\n .title(\"Manual - Jane Doe\")\n .blueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .priority(CasesCreateParams.Priority.of(\"HIGH\"))\n .tags(List.of(\"review\"))\n .subject(CasesCreateParams.Subject.builder()\n .type(CasesCreateParams.Subject.Type.of(\"user\"))\n .uuid(\"5b9a0000-0000-4000-8000-00000000f00d\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->create([\n 'title' => 'Manual - Jane Doe',\n 'blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n 'priority' => 'HIGH',\n 'tags' => ['review'],\n 'subject' => [\n 'type' => 'user',\n 'uuid' => '5b9a0000-0000-4000-8000-00000000f00d',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.create(\n title: \"Manual - Jane Doe\",\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n priority: \"HIGH\",\n tags: [\"review\"],\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.CreateAsync(new CasesCreateParams\n{\n Title = \"Manual - Jane Doe\",\n Blueprint = \"b1de0000-0000-4000-8000-000000000002\",\n Priority = new CasesCreateParamsPriority(\"HIGH\"),\n Tags = new string[] { \"review\" },\n Subject = new CasesCreateParamsSubject\n {\n Type = new CasesCreateParamsSubjectType(\"user\"),\n Uuid = \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Caso criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "Nem subject nem links fornecidos, ou o sujeito/blueprint/responsável não foi encontrado.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "A revisão de duplicados está ativada e foi encontrado um caso existente sem um motivo de incidente separado. Nenhum caso foi criado." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/": { "get": { "summary": "Obter caso", "description": "Obter um caso com o seu sujeito, blueprint, notas, eventos, ligações e lista de verificação.", "operationId": "get_case", "x-didit-sdk": { "resource": "cases", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retrieve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retrieve(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Retrieve(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retrieve(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retrieve('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retrieve(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetrieveAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhe do caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "404": { "description": "Caso (ou recurso aninhado) não encontrado nesta aplicação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar caso", "description": "Atualizar o título, a prioridade, a data limite, as etiquetas ou a equipa de revisão responsável pelo caso. Envie apenas os campos que pretende alterar; os campos omitidos mantêm o seu valor. `tags` substitui toda a lista de etiquetas. `team` recebe o uuid de uma equipa de revisão ativa desta aplicação (liste-as com `GET .../cases/teams/`), ou null para remover a equipa. Requer uma chave de API de acesso total, ou `write:cases` para um membro da consola: uma chave com acesso restrito recebe 403. Regista os eventos PRIORITY_CHANGED, DUE_DATE_CHANGED, TAG_ADDED, TAG_REMOVED e TEAM_CHANGED conforme aplicável; uma alteração de título é guardada sem um evento na linha temporal. Devolve o caso atualizado.", "operationId": "update_case", "x-didit-sdk": { "resource": "cases", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Novo título do caso." }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Novo prazo. Envie null para o limpar." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "A lista completa de etiquetas. Substitui as etiquetas atuais." }, "team": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID da equipa de revisão responsável pelo caso. Deve ser uma equipa ativa desta aplicação. Envie null para desassociar a equipa." } } }, "examples": { "Change priority and deadline": { "value": { "priority": "HIGH", "due_at": "2026-11-01T00:00:00Z" } }, "Move the case to a team": { "value": { "team": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "Clear the team": { "value": { "team": null } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"priority\": \"HIGH\", \"due_at\": \"2026-08-01T00:00:00Z\"}'" }, { "lang": "curl", "label": "curl (change team)", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"team\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.update(\n \"c1a5e000-0000-4000-8000-000000000001\",\n priority=\"HIGH\",\n due_at=\"2026-11-01T00:00:00Z\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.update(\"c1a5e000-0000-4000-8000-000000000001\", {\n priority: \"HIGH\",\n due_at: \"2026-11-01T00:00:00Z\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Update(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesUpdateParams{\n\tPriority: didit.Some(didit.CasesUpdateParamsPriority(\"HIGH\")),\n\tDueAt: didit.Time(time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport me.didit.Didit;\nimport me.didit.types.CasesUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().update(\"c1a5e000-0000-4000-8000-000000000001\", CasesUpdateParams.builder()\n .priority(CasesUpdateParams.Priority.of(\"HIGH\"))\n .dueAt(OffsetDateTime.parse(\"2026-11-01T00:00:00Z\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->update('c1a5e000-0000-4000-8000-000000000001', [\n 'priority' => 'HIGH',\n 'due_at' => '2026-11-01T00:00:00Z',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.update(\n \"c1a5e000-0000-4000-8000-000000000001\",\n priority: \"HIGH\",\n due_at: \"2026-11-01T00:00:00Z\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.UpdateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesUpdateParams\n{\n Priority = new CasesUpdateParamsPriority(\"HIGH\"),\n DueAt = DateTimeOffset.Parse(\"2026-11-01T00:00:00Z\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Caso atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "Um campo falhou a validação. O corpo é indexado pelo nome do campo. `team` é rejeitado quando não for uma equipa de revisão ativa desta aplicação.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Team not active in this application": { "value": { "team": [ "Choose an active team of this application." ] } }, "Invalid priority": { "value": { "priority": [ "\"URGENT\" is not a valid choice." ] } } } } } }, "403": { "description": "A chave de API pertence a outra aplicação ou é uma chave com acesso restrito: os endpoints de Cases necessitam de uma chave de acesso total. Um token de membro da consola necessita de `write:cases`.", "content": { "application/json": { "examples": { "Restricted API Key": { "summary": "Chave de API com acesso restrito", "value": { "detail": "This API key has no access to this endpoint." } }, "Missing Privilege": { "summary": "Membro da consola sem write:cases, ou uma chave de outra aplicação", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Caso não encontrado nesta aplicação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No Case matches the given query." } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Eliminar caso", "description": "Eliminar um caso permanentemente. Os seus rascunhos de relatórios regulamentares são eliminados juntamente com ele. As verificações, pessoas, empresas e transações associadas não são eliminadas. Não existe nenhum endpoint para anular a eliminação.\n\nSe o caso tiver um relatório regulamentar finalizado, todo o pedido é recusado com `409` e nada é eliminado. O corpo utiliza `code: in_filed_report` e identifica cada relatório com `uuid`, `report_number`, `report_type` e `case_uuid`. Elimine os relatórios e, em seguida, repita o pedido.", "operationId": "delete_case", "x-didit-sdk": { "resource": "cases", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.delete(\"c1a5e000-0000-4000-8000-000000000001\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Delete(ctx, \"c1a5e000-0000-4000-8000-000000000001\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().delete(\"c1a5e000-0000-4000-8000-000000000001\");" }, { "lang": "php", "label": "PHP", "source": "cases->delete('c1a5e000-0000-4000-8000-000000000001');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.delete(\"c1a5e000-0000-4000-8000-000000000001\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.DeleteAsync(\"c1a5e000-0000-4000-8000-000000000001\");" } ], "responses": { "204": { "description": "Caso eliminado." }, "403": { "description": "A chave não pode eliminar casos. Requer uma chave de acesso total com `write:cases`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "404": { "description": "O caso não existe nesta aplicação ou já foi eliminado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "O caso tem um relatório regulatório finalizado. Nada é eliminado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/assign/": { "post": { "summary": "Atribuir ou remover atribuição de caso", "description": "Atribua o caso a um utilizador ou remova a atribuição enviando assignee_user_id: null. assignee_email/assignee_name criam automaticamente um registo de Utilizador quando o responsável ainda não existe.", "operationId": "assign_case", "x-didit-sdk": { "resource": "cases", "method": "assign", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assignee_user_id" ], "properties": { "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "null para desatribuir." }, "assignee_email": { "type": "string", "format": "email", "nullable": true }, "assignee_name": { "type": "string", "nullable": true } } }, "example": { "assignee_user_id": "9a000000-0000-4000-8000-0000000000aa" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/assign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"assignee_user_id\": \"9a000000-0000-4000-8000-0000000000aa\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.assign(\n \"c1a5e000-0000-4000-8000-000000000001\",\n assignee_user_id=\"9a000000-0000-4000-8000-0000000000aa\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.assign(\"c1a5e000-0000-4000-8000-000000000001\", {\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Assign(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesAssignParams{\n\tAssigneeUserID: didit.String(\"9a000000-0000-4000-8000-0000000000aa\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesAssignParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().assign(\"c1a5e000-0000-4000-8000-000000000001\", CasesAssignParams.builder()\n .assigneeUserId(\"9a000000-0000-4000-8000-0000000000aa\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->assign('c1a5e000-0000-4000-8000-000000000001', [\n 'assignee_user_id' => '9a000000-0000-4000-8000-0000000000aa',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.assign(\n \"c1a5e000-0000-4000-8000-000000000001\",\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.AssignAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesAssignParams\n{\n AssigneeUserId = \"9a000000-0000-4000-8000-0000000000aa\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Caso atribuído/não atribuído.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/resolve/": { "post": { "summary": "Resolver caso", "description": "Resolva o caso com uma de cinco resoluções: FALSE_POSITIVE (nenhuma preocupação encontrada), VALID_THREAT (preocupação confirmada), INCONCLUSIVE, REQUIREMENTS_NOT_MET ou REQUIREMENTS_SATISFIED. Bloqueado com 400 se a lista de verificação do blueprint não for opcional e restarem itens incompletos, ou se o blueprint exigir uma nota de resolução e nenhuma for fornecida. Quando o blueprint do caso tem um passo de verificação a quatro olhos (four_eyes_checker_blueprint), a resolução fica pendente (case.pending_resolution) e o caso avança para o blueprint do verificador em vez de ser resolvido de imediato; um responsável diferente deve chamar approve ou reject-approval. Envie uma resolução a quatro olhos como membro da consola: uma resolução enviada por uma chave de API não tem um autor registado, pelo que approve e reject-approval devolvem 403 a qualquer chamador. Num blueprint a quatro olhos pode indicar o membro que deve aprovar através de `checker`: apenas esse membro poderá aprovar ou rejeitar a resolução, e o campo `checker` da resposta identifica-o. Sem `checker`, a resolução aguarda na fila do blueprint do verificador. Enviar `checker` para um blueprint sem passo de verificação devolve 400.", "operationId": "resolve_case", "x-didit-sdk": { "resource": "cases", "method": "resolve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resolution" ], "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "note": { "type": "string", "nullable": true, "description": "Obrigatório quando o blueprint define require_resolution_note." }, "checker": { "type": "string", "format": "uuid", "nullable": true, "description": "Apenas modelos de quatro olhos. O UUID de utilizador do membro que tem de aprovar esta resolução (o mesmo ID de `assigned_to.uuid` num caso, ou `members[].user_id` numa equipa de revisão). O membro tem de ter acesso a casos nesta aplicação e não pode ser o responsável que submete a resolução. Omita-o ou envie null para deixar a resolução para a fila de verificadores." } } }, "examples": { "Resolve": { "value": { "resolution": "FALSE_POSITIVE", "note": "Confirmed legitimate activity after reviewing documents." } }, "Four-eyes blueprint with a named checker": { "value": { "resolution": "VALID_THREAT", "note": "Document tampering confirmed.", "checker": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/resolve/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"resolution\": \"FALSE_POSITIVE\", \"note\": \"Confirmed legitimate activity after reviewing documents.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.resolve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n resolution=\"FALSE_POSITIVE\",\n note=\"Confirmed legitimate activity after reviewing documents.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.resolve(\"c1a5e000-0000-4000-8000-000000000001\", {\n resolution: \"FALSE_POSITIVE\",\n note: \"Confirmed legitimate activity after reviewing documents.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Resolve(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesResolveParams{\n\tResolution: \"FALSE_POSITIVE\",\n\tNote: didit.String(\"Confirmed legitimate activity after reviewing documents.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesResolveParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().resolve(\"c1a5e000-0000-4000-8000-000000000001\", CasesResolveParams.builder()\n .resolution(CasesResolveParams.Resolution.of(\"FALSE_POSITIVE\"))\n .note(\"Confirmed legitimate activity after reviewing documents.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->resolve('c1a5e000-0000-4000-8000-000000000001', [\n 'resolution' => 'FALSE_POSITIVE',\n 'note' => 'Confirmed legitimate activity after reviewing documents.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.resolve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n resolution: \"FALSE_POSITIVE\",\n note: \"Confirmed legitimate activity after reviewing documents.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ResolveAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesResolveParams\n{\n Resolution = \"FALSE_POSITIVE\",\n Note = \"Confirmed legitimate activity after reviewing documents.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Resolvido, ou colocado em espera para aprovação a quatro olhos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "A resolução foi recusada. Os erros não associados a campos são apresentados como uma lista de cadeias de carateres: uma checklist incompleta, uma nota obrigatória em falta ou um `checker` que não pôde ser verificado ou não é um revisor ativo com acesso a casos nesta aplicação. Os erros de `checker` surgem indexados pelo campo: o membro indicado é o responsável a submeter a resolução ou o modelo do caso não tem nenhum passo de verificação.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } ] }, "examples": { "Incomplete checklist": { "value": [ "Case has incomplete checklist items: Verify source of funds" ] }, "Resolution note required": { "value": [ "A resolution note is required to resolve this case." ] }, "Reviewer access could not be verified": { "value": [ "Reviewer access could not be verified. Try again." ] }, "Checker is not an active reviewer": { "value": [ "Choose an active reviewer with case access to this application." ] }, "Checker is the submitting officer": { "value": { "checker": [ "The officer who submitted the resolution cannot be its checker." ] } }, "Policy has no checker step": { "value": { "checker": [ "This review policy has no checker step, so the case resolves directly." ] } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/reopen/": { "post": { "summary": "Reabrir caso", "description": "Mova um caso que aguarda utilizador ou resolvido de volta para aberto, eliminando resolution, resolution_notes, resolved_at e resolved_by_email.", "operationId": "reopen_case", "x-didit-sdk": { "resource": "cases", "method": "reopen", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/reopen/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.reopen(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.reopen(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Reopen(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().reopen(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->reopen('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.reopen(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ReopenAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Reabrir caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/request-info/": { "post": { "summary": "Pedir informações (a aguardar o utilizador)", "description": "Mova um caso aberto para awaiting_user enquanto são recolhidas mais informações do utilizador verificado. Falha com 400 se uma resolução estiver atualmente pendente de aprovação a quatro olhos.", "operationId": "request_case_info", "x-didit-sdk": { "resource": "cases", "method": "request_info", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/request-info/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.request_info(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requestInfo(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RequestInfo(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requestInfo(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requestInfo('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.request_info(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RequestInfoAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Pedir informações (a aguardar o utilizador).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/escalate/": { "post": { "summary": "Escalar caso", "description": "Move o caso para o escalation_blueprint configurado no respetivo modelo. Requer que o modelo atual tenha escalation_enabled e um escalation_blueprint definido, caso contrário devolve 400.", "operationId": "escalate_case", "x-didit-sdk": { "resource": "cases", "method": "escalate", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/escalate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.escalate(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.escalate(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Escalate(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().escalate(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->escalate('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.escalate(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.EscalateAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Escalar caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/transfer/": { "post": { "summary": "Transferir caso", "description": "Mova o caso para um modelo ativo diferente da mesma aplicação. Requer que o modelo atual tenha transfer_enabled, caso contrário devolve 400.", "operationId": "transfer_case", "x-didit-sdk": { "resource": "cases", "method": "transfer", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_blueprint" ], "properties": { "target_blueprint": { "type": "string", "format": "uuid" } } }, "example": { "target_blueprint": "b1de0000-0000-4000-8000-000000000002" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/transfer/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"target_blueprint\": \"b1de0000-0000-4000-8000-000000000002\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.transfer(\n \"c1a5e000-0000-4000-8000-000000000001\",\n target_blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.transfer(\"c1a5e000-0000-4000-8000-000000000001\", {\n target_blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Transfer(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesTransferParams{\n\tTargetBlueprint: \"b1de0000-0000-4000-8000-000000000002\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesTransferParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().transfer(\"c1a5e000-0000-4000-8000-000000000001\", CasesTransferParams.builder()\n .targetBlueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->transfer('c1a5e000-0000-4000-8000-000000000001', [\n 'target_blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.transfer(\n \"c1a5e000-0000-4000-8000-000000000001\",\n target_blueprint: \"b1de0000-0000-4000-8000-000000000002\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.TransferAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesTransferParams\n{\n TargetBlueprint = \"b1de0000-0000-4000-8000-000000000002\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Caso transferido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/approve/": { "post": { "summary": "Aprovar resolução faseada (princípio dos 4 olhos)", "description": "Aplica uma resolução preparada através de resolve num modelo de quatro olhos. O autor da chamada tem de ser um responsável diferente daquele que a submeteu, caso contrário recebe 403. Quando a resolução indica um revisor (o `checker` do caso), apenas esse membro a pode aprovar: qualquer outro autor da chamada, incluindo uma chave de API, recebe 403.", "operationId": "approve_case_resolution", "x-didit-sdk": { "resource": "cases", "method": "approve_resolution", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/approve/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.approve_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.approveResolution(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ApproveResolution(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().approveResolution(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->approveResolution('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.approve_resolution(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ApproveResolutionAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Resolução aplicada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "409": { "description": "O caso não tem nenhuma resolução pendente de aprovação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "403": { "description": "O chamador não pode aprovar esta resolução: foi quem a submeteu, o caso não tem nenhum autor registado ou a resolução indica um verificador diferente. Uma chave de API recebe sempre este 403 quando um verificador é indicado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Caller submitted the resolution": { "value": { "detail": "The officer who submitted the resolution cannot approve it." } }, "No recorded maker": { "value": { "detail": "Case has no recorded maker for this pending resolution; approve is not permitted." } }, "Caller is not the named checker": { "value": { "detail": "Only the named checker can approve this resolution." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/reject-approval/": { "post": { "summary": "Rejeitar resolução preparada (princípio dos 4 olhos)", "description": "Rejeitar uma resolução colocada em espera por resolve e devolver o caso ao modelo do respetivo criador. O chamador tem de ser um responsável diferente daquele que a submeteu, caso contrário recebe 403. Quando a resolução indica um revisor (o `checker` do caso), apenas esse membro pode rejeitá-la: qualquer outro chamador, incluindo uma chave de API, recebe 403.", "operationId": "reject_case_resolution", "x-didit-sdk": { "resource": "cases", "method": "reject_resolution", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "nullable": true } } }, "example": { "notes": "Needs a clearer rationale before this can be approved." } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/reject-approval/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"notes\": \"Needs a clearer rationale before this can be approved.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.reject_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n notes=\"Needs a clearer rationale before this can be approved.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.rejectResolution(\"c1a5e000-0000-4000-8000-000000000001\", {\n notes: \"Needs a clearer rationale before this can be approved.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RejectResolution(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRejectResolutionParams{\n\tNotes: didit.String(\"Needs a clearer rationale before this can be approved.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesRejectResolutionParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().rejectResolution(\"c1a5e000-0000-4000-8000-000000000001\", CasesRejectResolutionParams.builder()\n .notes(\"Needs a clearer rationale before this can be approved.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->rejectResolution('c1a5e000-0000-4000-8000-000000000001', [\n 'notes' => 'Needs a clearer rationale before this can be approved.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.reject_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n notes: \"Needs a clearer rationale before this can be approved.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RejectResolutionAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesRejectResolutionParams\n{\n Notes = \"Needs a clearer rationale before this can be approved.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Resolução rejeitada, caso devolvido ao modelo do criador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "409": { "description": "O caso não tem nenhuma resolução pendente de aprovação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "403": { "description": "O chamador não pode rejeitar esta resolução: foi quem a submeteu, o caso não tem nenhum autor registado ou a resolução indica um verificador diferente. Uma chave de API recebe sempre este 403 quando um verificador é indicado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Caller submitted the resolution": { "value": { "detail": "The officer who submitted the resolution cannot reject it." } }, "No recorded maker": { "value": { "detail": "Case has no recorded maker for this pending resolution; reject is not permitted." } }, "Caller is not the named checker": { "value": { "detail": "Only the named checker can reject this resolution." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/entity-actions/": { "post": { "operationId": "apply_case_entity_action", "x-didit-sdk": { "resource": "cases", "method": "apply_entity_action", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" }, "example": { "client_reference": "e1a00000-0000-4000-8000-000000000001", "action": "add_tags", "tags": [ "source-of-funds-reviewed" ] } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionResult" } } }, "description": "" }, "409": { "description": "A referência pertence a um payload de ação diferente." } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Aplica uma ação explícita ao sujeito do caso. Indique uma client_reference única para obter um recibo de ação e tornar as repetições idempotentes. A reutilização dessa referência com um payload diferente devolve 409. Com uma referência, inspecione receipt.status mesmo quando o código de estado HTTP for 200: FAILED significa que nenhuma ação foi aplicada. A repetição de um pedido com falha não o volta a executar a menos que retry seja true. A omissão de client_reference mantém a resposta legada.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.apply_entity_action(\n \"11111111-2222-3333-4444-555555555555\",\n client_reference=\"e1a00000-0000-4000-8000-000000000001\",\n action=\"add_tags\",\n tags=[\"source-of-funds-reviewed\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.applyEntityAction(\"11111111-2222-3333-4444-555555555555\", {\n client_reference: \"e1a00000-0000-4000-8000-000000000001\",\n action: \"add_tags\",\n tags: [\"source-of-funds-reviewed\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ApplyEntityAction(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseActionCaseEntityActionRequest{\n\tClientReference: didit.String(\"e1a00000-0000-4000-8000-000000000001\"),\n\tAction: didit.CaseActionActionEnum(\"add_tags\"),\n\tTags: didit.Some([]string{\"source-of-funds-reviewed\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseActionActionEnum;\nimport me.didit.types.CaseActionCaseEntityActionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().applyEntityAction(\"11111111-2222-3333-4444-555555555555\", CaseActionCaseEntityActionRequest.builder()\n .clientReference(\"e1a00000-0000-4000-8000-000000000001\")\n .action(CaseActionActionEnum.of(\"add_tags\"))\n .tags(List.of(\"source-of-funds-reviewed\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->applyEntityAction('11111111-2222-3333-4444-555555555555', [\n 'client_reference' => 'e1a00000-0000-4000-8000-000000000001',\n 'action' => 'add_tags',\n 'tags' => ['source-of-funds-reviewed'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.apply_entity_action(\n \"11111111-2222-3333-4444-555555555555\",\n client_reference: \"e1a00000-0000-4000-8000-000000000001\",\n action: \"add_tags\",\n tags: [\"source-of-funds-reviewed\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ApplyEntityActionAsync(\"11111111-2222-3333-4444-555555555555\", new CaseActionCaseEntityActionRequest\n{\n ClientReference = \"e1a00000-0000-4000-8000-000000000001\",\n Action = \"add_tags\",\n Tags = new string[] { \"source-of-funds-reviewed\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/print/": { "get": { "summary": "Imprimir caso (PDF)", "description": "Gere o caso completo (resumo, assunto, estado da lista de verificação, notas, sessões/transações anexadas, eventos, lista de relatórios da UIF) como PDF e devolva um URL de transferência pré-assinado.", "operationId": "print_case", "x-didit-sdk": { "resource": "cases", "method": "print", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/print/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.print(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.print(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Print(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().print(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->print('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.print(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.PrintAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "URL pré-assinado do PDF.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/": { "get": { "operationId": "list_case_notes", "x-didit-sdk": { "resource": "cases.notes", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "Qual o campo a utilizar para ordenar os resultados.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Número de resultados a devolver por página.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "O índice inicial a partir do qual devolver os resultados.", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPaginatedCaseNoteList" } } }, "description": "" }, "403": { "description": "O chamador não possui a permissão de casos necessária." }, "404": { "description": "O caso ou nota não está disponível para este chamador." } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.notes.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Notes.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesNotesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().notes().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->notes->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.notes.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Notes.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "create_case_note", "x-didit-sdk": { "resource": "cases.notes", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" }, "example": { "comment": "Proof of address matches the ID document." } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "403": { "description": "O chamador não possui a permissão de casos necessária." }, "404": { "description": "O caso ou nota não está disponível para este chamador." }, "409": { "description": "Esta referência de cliente já foi utilizada para outra nota ou para uma nota que foi eliminada." } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "description": "Adicione uma nota no âmbito do caso. Um client_reference opcional faz com que uma nova tentativa inalterada devolva a mesma nota sem atividade ou notificações duplicadas. reply_to tem de identificar uma nota ativa neste caso. A resposta inclui um excerto delimitado da nota principal sem copiar esse excerto para a resposta guardada.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment=\"Proof of address matches the ID document.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.create(\"11111111-2222-3333-4444-555555555555\", {\n comment: \"Proof of address matches the ID document.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseCollaborationCaseNoteCreateRequest{\n\tComment: \"Proof of address matches the ID document.\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseCollaborationCaseNoteCreateRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().create(\"11111111-2222-3333-4444-555555555555\", CaseCollaborationCaseNoteCreateRequest.builder()\n .comment(\"Proof of address matches the ID document.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->create('11111111-2222-3333-4444-555555555555', [\n 'comment' => 'Proof of address matches the ID document.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment: \"Proof of address matches the ID document.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseCollaborationCaseNoteCreateRequest\n{\n Comment = \"Proof of address matches the ID document.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/{note_uuid}/": { "patch": { "operationId": "root_partial_update", "x-didit-sdk": { "resource": "cases.notes", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "note_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" }, "example": { "is_pinned": true } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "403": { "description": "O chamador não possui a permissão de casos necessária." }, "404": { "description": "O caso ou nota não está disponível para este chamador." } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "description": "Fixar ou desafixar uma nota existente. As notas fixadas aparecem primeiro. As alterações de fixação são registadas na atividade do caso e não alteram evidências nem decisões de origem.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n is_pinned=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n {\n is_pinned: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.Update(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", didit.CaseCollaborationPatchedCaseNoteUpdateRequest{\n\tIsPinned: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseCollaborationPatchedCaseNoteUpdateRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().update(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", CaseCollaborationPatchedCaseNoteUpdateRequest.builder()\n .isPinned(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->update('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555', [\n 'is_pinned' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n is_pinned: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", new CaseCollaborationPatchedCaseNoteUpdateRequest\n{\n IsPinned = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "delete_case_note", "x-didit-sdk": { "resource": "cases.notes", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "note_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "204": { "description": "A nota é eliminada permanentemente. As respostas permanecem, sem o excerto da nota-pai eliminada. Os anexos são eliminados, a menos que outra nota ainda os utilize." }, "403": { "description": "O chamador não possui a permissão de casos necessária." }, "404": { "description": "O caso ou nota não está disponível para este chamador." } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Notes.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().notes().delete(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "cases->notes->delete('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Notes.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/presign/": { "post": { "summary": "Carregar anexo de nota", "description": "Carregar um ficheiro (JPEG, PNG, WebP, PDF, texto simples ou CSV; máx. 5 MB) para anexar a uma nota. Devolve o s3_key para passar no array attachments da nota.", "operationId": "upload_case_note_attachment", "x-didit-sdk": { "resource": "cases.notes", "method": "create_attachment_upload", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/notes/presign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@evidence.pdf'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.create_attachment_upload(\n \"c1a5e000-0000-4000-8000-000000000001\",\n file=open(\"document.pdf\", \"rb\"),\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.createAttachmentUpload(\"c1a5e000-0000-4000-8000-000000000001\", {\n file: await fileFromPath(\"document.pdf\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.CreateAttachmentUpload(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesNotesCreateAttachmentUploadParams{\n\tFile: didit.FileFromPath(\"document.pdf\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.CasesNotesCreateAttachmentUploadParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().createAttachmentUpload(\"c1a5e000-0000-4000-8000-000000000001\", CasesNotesCreateAttachmentUploadParams.builder()\n .file(Path.of(\"document.pdf\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->createAttachmentUpload('c1a5e000-0000-4000-8000-000000000001', [\n 'file' => File::fromPath('document.pdf'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.create_attachment_upload(\n \"c1a5e000-0000-4000-8000-000000000001\",\n file: Pathname(\"document.pdf\")\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.CreateAttachmentUploadAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesNotesCreateAttachmentUploadParams\n{\n File = FileUpload.FromPath(\"document.pdf\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Ficheiro carregado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "s3_key": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "file_size": { "type": "integer" } } } } } }, "400": { "description": "Nenhum ficheiro, tipo de conteúdo não suportado ou o ficheiro excede 5 MB.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Obter URL do anexo da nota", "description": "Gerar um novo URL de transferência pré-assinado para um anexo já armazenado numa das notas do caso.", "operationId": "get_case_note_attachment_url", "x-didit-sdk": { "resource": "cases.notes", "method": "retrieve_attachment_url", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." }, { "name": "s3_key", "in": "query", "schema": { "type": "string" }, "description": "O s3_key do anexo, conforme devolvido pelo carregamento ou listado na nota.", "required": true } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/notes/presign/?s3_key=case-notes/c1a5e000-0000-4000-8000-000000000001/evidence.pdf' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.retrieve_attachment_url(\n \"c1a5e000-0000-4000-8000-000000000001\",\n s3_key=\"your-s3-key\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.retrieveAttachmentUrl(\"c1a5e000-0000-4000-8000-000000000001\", {\n s3_key: \"your-s3-key\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.RetrieveAttachmentURL(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesNotesRetrieveAttachmentURLParams{\n\tS3Key: \"your-s3-key\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesNotesRetrieveAttachmentUrlParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().retrieveAttachmentUrl(\"c1a5e000-0000-4000-8000-000000000001\", CasesNotesRetrieveAttachmentUrlParams.builder()\n .s3Key(\"your-s3-key\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->retrieveAttachmentUrl('c1a5e000-0000-4000-8000-000000000001', [\n 's3_key' => 'your-s3-key',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.retrieve_attachment_url(\n \"c1a5e000-0000-4000-8000-000000000001\",\n s3_key: \"your-s3-key\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.RetrieveAttachmentUrlAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesNotesRetrieveAttachmentUrlParams\n{\n S3Key = \"your-s3-key\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "URL pré-assinado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "s3_key": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" } } } } } }, "404": { "description": "s3_key em falta ou não pertence a este caso.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/links/": { "get": { "summary": "Listar ligações do caso", "description": "Listar sessões, sessões de empresa e transações associadas ao caso.", "operationId": "list_case_links", "x-didit-sdk": { "resource": "cases.links", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.links.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.links.list(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Links.List(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().links().list(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->links->list('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.links.list(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Links.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Ligações do caso.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CaseLink" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Adicionar ligação ao caso", "description": "Anexar uma sessão, sessão de empresa ou transação ao caso. Rejeitado com 400 se a entidade pertencer a um sujeito diferente do caso.", "operationId": "create_case_link", "x-didit-sdk": { "resource": "cases.links", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "entity_uuid" ], "properties": { "entity_type": { "type": "string", "enum": [ "session", "business_session", "transaction" ] }, "entity_uuid": { "type": "string", "format": "uuid" } } }, "example": { "entity_type": "transaction", "entity_uuid": "77000000-0000-4000-8000-000000000077" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"entity_type\": \"transaction\", \"entity_uuid\": \"77000000-0000-4000-8000-000000000077\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.links.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n entity_type=\"transaction\",\n entity_uuid=\"77000000-0000-4000-8000-000000000077\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.links.create(\"c1a5e000-0000-4000-8000-000000000001\", {\n entity_type: \"transaction\",\n entity_uuid: \"77000000-0000-4000-8000-000000000077\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Links.Create(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesLinksCreateParams{\n\tEntityType: \"transaction\",\n\tEntityUUID: \"77000000-0000-4000-8000-000000000077\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesLinksCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().links().create(\"c1a5e000-0000-4000-8000-000000000001\", CasesLinksCreateParams.builder()\n .entityType(CasesLinksCreateParams.EntityType.of(\"transaction\"))\n .entityUuid(\"77000000-0000-4000-8000-000000000077\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->links->create('c1a5e000-0000-4000-8000-000000000001', [\n 'entity_type' => 'transaction',\n 'entity_uuid' => '77000000-0000-4000-8000-000000000077',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.links.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n entity_type: \"transaction\",\n entity_uuid: \"77000000-0000-4000-8000-000000000077\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Links.CreateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesLinksCreateParams\n{\n EntityType = \"transaction\",\n EntityUuid = \"77000000-0000-4000-8000-000000000077\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Ligação criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseLink" } } } }, "400": { "description": "A entidade pertence a um perfil diferente do sujeito do caso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/links/{link_uuid}/": { "delete": { "summary": "Remover ligação ao caso", "description": "Desassociar do caso uma sessão vinculada, sessão de empresa ou transação.", "operationId": "delete_case_link", "x-didit-sdk": { "resource": "cases.links", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." }, { "name": "link_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11000000-0000-4000-8000-000000000004" }, "description": "UUID da ligação." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/11000000-0000-4000-8000-000000000004/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Links.Delete(ctx, \"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().links().delete(\"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\");" }, { "lang": "php", "label": "PHP", "source": "cases->links->delete('c1a5e000-0000-4000-8000-000000000001', '11000000-0000-4000-8000-000000000004');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Links.DeleteAsync(\"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\");" } ], "responses": { "204": { "description": "Ligação removida." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/events/": { "get": { "summary": "Listar eventos do caso", "description": "Cronologia de auditoria apenas de leitura do caso (criação, alterações de estado, atribuição, resolução, escalamento, transferências, alterações de etiquetas/prioridade/data-limite, ações de entidades e muito mais).", "operationId": "list_case_events", "x-didit-sdk": { "resource": "cases", "method": "list_events", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Tamanho da página." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset de base zero." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/events/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.list_events(\n \"c1a5e000-0000-4000-8000-000000000001\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.listEvents(\"c1a5e000-0000-4000-8000-000000000001\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.ListEventsAutoPaging(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesListEventsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().listEvents(\"c1a5e000-0000-4000-8000-000000000001\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->listEvents('c1a5e000-0000-4000-8000-000000000001') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list_events(\"c1a5e000-0000-4000-8000-000000000001\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.ListEventsAsync(\"c1a5e000-0000-4000-8000-000000000001\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Eventos paginados, os mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número de linhas correspondentes. Exato até 100, limitado a 100 acima desse valor por motivos de desempenho. Confie que `next` é null para detetar a última página." }, "next": { "type": "string", "nullable": true, "description": "URL absoluto da página seguinte, ou null." }, "previous": { "type": "string", "nullable": true, "description": "URL absoluto da página anterior, ou null." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseEvent" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/checklist/": { "get": { "summary": "Listar lista de verificação do caso", "description": "Listar os itens da lista de verificação do caso, copiados de content_config.checklist.items do blueprint aquando da criação, ordenados.", "operationId": "list_case_checklist", "x-didit-sdk": { "resource": "cases.checklist", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/checklist/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.checklist.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.checklist.list(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Checklist.List(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().checklist().list(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->checklist->list('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.checklist.list(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Checklist.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Itens da lista de verificação.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CaseChecklistItem" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/checklist/{item_uuid}/": { "patch": { "summary": "Alternar estado do item da lista de verificação", "description": "Marque um item da lista de verificação como concluído ou incompleto. A resolução fica bloqueada enquanto qualquer item estiver incompleto, a menos que o modelo marque a lista de verificação como opcional.", "operationId": "toggle_case_checklist_item", "x-didit-sdk": { "resource": "cases.checklist", "method": "toggle_item", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." }, { "name": "item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c4ec0000-0000-4000-8000-000000000005" }, "description": "UUID do item da lista de verificação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_completed" ], "properties": { "is_completed": { "type": "boolean" } } }, "example": { "is_completed": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/checklist/c4ec0000-0000-4000-8000-000000000005/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_completed\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.checklist.toggle_item(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n is_completed=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.checklist.toggleItem(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n {\n is_completed: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Checklist.ToggleItem(ctx, \"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", didit.CasesChecklistToggleItemParams{\n\tIsCompleted: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesChecklistToggleItemParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().checklist().toggleItem(\"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", CasesChecklistToggleItemParams.builder()\n .isCompleted(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->checklist->toggleItem('c1a5e000-0000-4000-8000-000000000001', 'c4ec0000-0000-4000-8000-000000000005', [\n 'is_completed' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.checklist.toggle_item(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n is_completed: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Checklist.ToggleItemAsync(\"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", new CasesChecklistToggleItemParams\n{\n IsCompleted = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Item da lista de verificação atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseChecklistItem" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/aml/": { "get": { "summary": "Listar alertas AML do caso", "description": "Listar ocorrências de triagem AML para o sujeito do caso. O mesmo formato das ocorrências devolvidas por POST /v3/aml/.", "operationId": "list_case_aml_hits", "x-didit-sdk": { "resource": "cases", "method": "list_aml_hits", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/aml/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_aml_hits(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listAmlHits(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListAMLHits(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listAmlHits(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listAmlHits('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list_aml_hits(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListAmlHitsAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Ocorrências AML.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AMLScreening" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/statistics/": { "get": { "summary": "Análises do caso", "description": "Métricas agregadas de casos para o intervalo de datas (por predefinição, os últimos 30 dias; máximo de 731 dias). Gráficos, tabelas, totais, eventos de atribuição e contagens atuais da fila usam os mesmos filtros com âmbito da aplicação. Os filtros usam valores atuais dos casos. As datas aplicam-se a cada evento de métrica, pelo que casos mais antigos atribuídos ou resolvidos durante o período permanecem incluídos. A profundidade da fila é independente do intervalo de datas. Filtros inválidos devolvem 400; um modelo ou responsável atribuído desconhecido devolve um resultado vazio.", "operationId": "get_case_analytics", "x-didit-sdk": { "resource": "cases", "method": "retrieve_statistics", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo (inclusive). O valor predefinido corresponde à data de há 30 dias." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo (inclusive). O valor predefinido é o dia de hoje." }, { "name": "blueprint", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filtrar pelo UUID do blueprint atual." }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filtrar pelo UUID do utilizador revisor atualmente atribuído." }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "description": "Filtrar pela prioridade atual do caso." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "description": "Filtrar pela origem da criação do caso." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "description": "Filtrar pelo estado atual do caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/statistics/?date_from=2026-06-01&date_to=2026-06-30' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retrieve_statistics()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retrieveStatistics();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RetrieveStatistics(ctx, didit.CasesRetrieveStatisticsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retrieveStatistics();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retrieveStatistics();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retrieve_statistics\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetrieveStatisticsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Payload de análise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "created": { "type": "integer" }, "reviewed": { "type": "integer" } } } }, "tables": { "type": "object", "properties": { "officer": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Valor da dimensão: e-mail do responsável, \"blueprint_name:uuid\", origem ou estado. \"unassigned\"/\"none\" para dimensões em falta." }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "blueprint": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Valor da dimensão: e-mail do responsável, \"blueprint_name:uuid\", origem ou estado. \"unassigned\"/\"none\" para dimensões em falta." }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "source": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Valor da dimensão: e-mail do responsável, \"blueprint_name:uuid\", origem ou estado. \"unassigned\"/\"none\" para dimensões em falta." }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "status": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Valor da dimensão: e-mail do responsável, \"blueprint_name:uuid\", origem ou estado. \"unassigned\"/\"none\" para dimensões em falta." }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } } } }, "totals": { "type": "object", "properties": { "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } }, "queue": { "type": "object", "description": "Instantâneo em tempo real, não limitado ao intervalo de datas.", "properties": { "open": { "type": "integer" }, "overdue": { "type": "integer" } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/bulk/status/": { "post": { "summary": "Atualizar em massa o estado de casos", "description": "Aplica a mesma transição de estado a vários casos numa única chamada: OPEN reabre, AWAITING_USER solicita informações, RESOLVED resolve (resolução obrigatória). Cada caso é avaliado de forma independente; falhas de controlo (checklist incompleta, nota obrigatória em falta) são comunicadas por caso sem abortar o lote.", "operationId": "bulk_update_case_status", "x-didit-sdk": { "resource": "cases", "method": "bulk_update_status", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case_uuids", "status" ], "properties": { "case_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "description": "Obrigatório quando o estado for RESOLVED." }, "note": { "type": "string", "nullable": true } } }, "example": { "case_uuids": [ "c1a5e000-0000-4000-8000-000000000001" ], "status": "RESOLVED", "resolution": "FALSE_POSITIVE" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/bulk/status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case_uuids\": [\"c1a5e000-0000-4000-8000-000000000001\"], \"status\": \"RESOLVED\", \"resolution\": \"FALSE_POSITIVE\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.bulk_update_status(\n case_uuids=[\"c1a5e000-0000-4000-8000-000000000001\"],\n status=\"RESOLVED\",\n resolution=\"FALSE_POSITIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.bulkUpdateStatus({\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n status: \"RESOLVED\",\n resolution: \"FALSE_POSITIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.BulkUpdateStatus(ctx, didit.CasesBulkUpdateStatusParams{\n\tCaseUUIDs: []string{\"c1a5e000-0000-4000-8000-000000000001\"},\n\tStatus: \"RESOLVED\",\n\tResolution: didit.Some(didit.CasesBulkUpdateStatusParamsResolution(\"FALSE_POSITIVE\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBulkUpdateStatusParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().bulkUpdateStatus(CasesBulkUpdateStatusParams.builder()\n .caseUuids(List.of(\"c1a5e000-0000-4000-8000-000000000001\"))\n .status(CasesBulkUpdateStatusParams.Status.of(\"RESOLVED\"))\n .resolution(CasesBulkUpdateStatusParams.Resolution.of(\"FALSE_POSITIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->bulkUpdateStatus([\n 'case_uuids' => ['c1a5e000-0000-4000-8000-000000000001'],\n 'status' => 'RESOLVED',\n 'resolution' => 'FALSE_POSITIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.bulk_update_status(\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n status: \"RESOLVED\",\n resolution: \"FALSE_POSITIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.BulkUpdateStatusAsync(new CasesBulkUpdateStatusParams\n{\n CaseUuids = new string[] { \"c1a5e000-0000-4000-8000-000000000001\" },\n Status = \"RESOLVED\",\n Resolution = new CasesBulkUpdateStatusParamsResolution(\"FALSE_POSITIVE\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Resultados por caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBulkUpdateResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/bulk/assign/": { "post": { "summary": "Atribuir casos em massa", "description": "Atribuir (ou retirar a atribuição, com assignee_user_id: null) vários casos em simultâneo. Todos os casos devem partilhar o mesmo modelo; as discrepâncias são comunicadas por caso sem abortar o lote.", "operationId": "bulk_assign_cases", "x-didit-sdk": { "resource": "cases", "method": "bulk_assign", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case_uuids", "assignee_user_id" ], "properties": { "case_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true }, "assignee_email": { "type": "string", "format": "email", "nullable": true }, "assignee_name": { "type": "string", "nullable": true } } }, "example": { "case_uuids": [ "c1a5e000-0000-4000-8000-000000000001" ], "assignee_user_id": "9a000000-0000-4000-8000-0000000000aa" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/bulk/assign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case_uuids\": [\"c1a5e000-0000-4000-8000-000000000001\"], \"assignee_user_id\": \"9a000000-0000-4000-8000-0000000000aa\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.bulk_assign(\n case_uuids=[\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id=\"9a000000-0000-4000-8000-0000000000aa\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.bulkAssign({\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.BulkAssign(ctx, didit.CasesBulkAssignParams{\n\tCaseUUIDs: []string{\"c1a5e000-0000-4000-8000-000000000001\"},\n\tAssigneeUserID: didit.String(\"9a000000-0000-4000-8000-0000000000aa\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBulkAssignParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().bulkAssign(CasesBulkAssignParams.builder()\n .caseUuids(List.of(\"c1a5e000-0000-4000-8000-000000000001\"))\n .assigneeUserId(\"9a000000-0000-4000-8000-0000000000aa\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->bulkAssign([\n 'case_uuids' => ['c1a5e000-0000-4000-8000-000000000001'],\n 'assignee_user_id' => '9a000000-0000-4000-8000-0000000000aa',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.bulk_assign(\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.BulkAssignAsync(new CasesBulkAssignParams\n{\n CaseUuids = new string[] { \"c1a5e000-0000-4000-8000-000000000001\" },\n AssigneeUserId = \"9a000000-0000-4000-8000-0000000000aa\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Resultados por caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBulkUpdateResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/": { "get": { "summary": "Listar blueprints", "description": "Listar blueprints de casos para a aplicação.", "operationId": "list_case_blueprints", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Tamanho da página." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset de base zero." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.blueprints.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.blueprints.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Blueprints.ListAutoPaging(ctx, didit.CasesBlueprintsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().blueprints().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Blueprints.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Lista paginada de esquemas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número de linhas correspondentes, limitado a 100 por motivos de desempenho." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseBlueprintListItem" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar modelo", "description": "Crie um modelo de caso: definições gerais (atribuição, escalamento, transferência, associação segundo o princípio dos quatro olhos) mais content_config, as seis secções que estruturam a página do caso. Defina publish=false para criar um rascunho não publicado; publicar cria a sua primeira versão de produção. Descartar um rascunho nunca publicado elimina-o.", "operationId": "create_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "assignee_pool" ], "properties": { "name": { "type": "string", "maxLength": 24, "description": "Máximo de 24 caracteres, por ex., \"investigação AML\"." }, "description": { "type": "string", "nullable": true }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Lista de UUIDs de utilizadores. As matrizes vazias são rejeitadas com \"Pick at least one assignee\"." }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ], "default": "MANUAL" }, "max_active_cases": { "type": "integer", "nullable": true, "minimum": 1, "description": "Limiar do modo automático: \"menos de N casos deste blueprint atribuídos\"." }, "escalation_enabled": { "type": "boolean", "default": false }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID do esquema orientador de destino. Não é imposto no momento de guardar, mas a ação de escalamento falha com 400 até que ambos escalation_enabled e escalation_blueprint estejam definidos." }, "transfer_enabled": { "type": "boolean", "default": false }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "Definir isto ativa a revisão a 4 olhos: as resoluções neste modelo são colocadas na fila do modelo do verificador." }, "require_resolution_note": { "type": "boolean", "default": false }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "is_active": { "type": "boolean", "default": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760, "description": "Prazo predefinido para casos recém-abertos. Os prazos dos casos existentes permanecem inalterados." }, "publish": { "type": "boolean", "writeOnly": true, "default": true, "description": "Defina como false para guardar um rascunho nunca publicado. O registo permanece inativo na versão 0 até que o rascunho seja explicitamente publicado. Omitir este campo preserva a criação imediata para integrações existentes." } } }, "example": { "name": "AML investigation", "assignee_pool": [ "9a000000-0000-4000-8000-0000000000aa" ], "assignment_method": "AUTOMATIC", "max_active_cases": 15, "require_resolution_note": true, "content_config": { "aml_control": { "enabled": true, "financial": true, "identity": false } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"AML investigation\", \"assignee_pool\": [\"9a000000-0000-4000-8000-0000000000aa\"], \"assignment_method\": \"AUTOMATIC\", \"max_active_cases\": 15, \"require_resolution_note\": true, \"content_config\": {\"aml_control\": {\"enabled\": true, \"financial\": true, \"identity\": false}}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.create(\n name=\"AML investigation\",\n assignee_pool=[\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method=\"AUTOMATIC\",\n max_active_cases=15,\n require_resolution_note=True,\n content_config={\n \"aml_control\": {\n \"enabled\": True,\n \"financial\": True,\n \"identity\": False,\n },\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.create({\n name: \"AML investigation\",\n assignee_pool: [\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method: \"AUTOMATIC\",\n max_active_cases: 15,\n require_resolution_note: true,\n content_config: {\n aml_control: {\n enabled: true,\n financial: true,\n identity: false,\n },\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Create(ctx, didit.CasesBlueprintsCreateParams{\n\tName: \"AML investigation\",\n\tAssigneePool: []string{\"9a000000-0000-4000-8000-0000000000aa\"},\n\tAssignmentMethod: didit.Some(didit.CasesBlueprintsCreateParamsAssignmentMethod(\"AUTOMATIC\")),\n\tMaxActiveCases: didit.Int(15),\n\tRequireResolutionNote: didit.Bool(true),\n\tContentConfig: didit.Some(didit.CaseContentConfigParam{\n\t\tAMLControl: didit.Some(didit.CaseContentConfigParamAMLControl{\n\t\t\tEnabled: didit.Bool(true),\n\t\t\tFinancial: didit.Bool(true),\n\t\t\tIdentity: didit.Bool(false),\n\t\t}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseContentConfig;\nimport me.didit.types.CasesBlueprintsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().create(CasesBlueprintsCreateParams.builder()\n .name(\"AML investigation\")\n .assigneePool(List.of(\"9a000000-0000-4000-8000-0000000000aa\"))\n .assignmentMethod(CasesBlueprintsCreateParams.AssignmentMethod.of(\"AUTOMATIC\"))\n .maxActiveCases(15L)\n .requireResolutionNote(true)\n .contentConfig(CaseContentConfig.builder()\n .amlControl(CaseContentConfig.AmlControl.builder()\n .enabled(true)\n .financial(true)\n .identity(false)\n .build())\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->create([\n 'name' => 'AML investigation',\n 'assignee_pool' => ['9a000000-0000-4000-8000-0000000000aa'],\n 'assignment_method' => 'AUTOMATIC',\n 'max_active_cases' => 15,\n 'require_resolution_note' => true,\n 'content_config' => [\n 'aml_control' => [\n 'enabled' => true,\n 'financial' => true,\n 'identity' => false,\n ],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.create(\n name: \"AML investigation\",\n assignee_pool: [\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method: \"AUTOMATIC\",\n max_active_cases: 15,\n require_resolution_note: true,\n content_config: {\n aml_control: {\n enabled: true,\n financial: true,\n identity: false,\n },\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.CreateAsync(new CasesBlueprintsCreateParams\n{\n Name = \"AML investigation\",\n AssigneePool = new string[] { \"9a000000-0000-4000-8000-0000000000aa\" },\n AssignmentMethod = new CasesBlueprintsCreateParamsAssignmentMethod(\"AUTOMATIC\"),\n MaxActiveCases = 15,\n RequireResolutionNote = true,\n ContentConfig = new CaseContentConfig\n {\n AmlControl = new CaseContentConfigAmlControl\n {\n Enabled = true,\n Financial = true,\n Identity = false,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Blueprint criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } }, "400": { "description": "Nome com mais de 24 carateres, assignee_pool vazio ou um modelo referenciado (escalation/checker) não encontrado.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/": { "get": { "summary": "Obter modelo", "description": "Obter um blueprint, incluindo as respetivas origens de criação associadas (configuração AML, regras de transação, nós do fluxo) e quais os blueprints que escalam para o mesmo.", "operationId": "get_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "UUID do blueprint." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.retrieve(\n \"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.retrieve(\"b1de0000-0000-4000-8000-000000000002\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Retrieve(ctx, \"b1de0000-0000-4000-8000-000000000002\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().retrieve(\"b1de0000-0000-4000-8000-000000000002\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->retrieve('b1de0000-0000-4000-8000-000000000002');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.retrieve(\"b1de0000-0000-4000-8000-000000000002\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.RetrieveAsync(\"b1de0000-0000-4000-8000-000000000002\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhe do blueprint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar plano", "description": "Atualizar parcialmente as definições gerais ou content_config de um blueprint.", "operationId": "update_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "UUID do blueprint." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 24, "description": "Máximo de 24 caracteres, por ex., \"investigação AML\"." }, "description": { "type": "string", "nullable": true }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Lista de UUIDs de utilizadores. As matrizes vazias são rejeitadas com \"Pick at least one assignee\"." }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "max_active_cases": { "type": "integer", "nullable": true, "minimum": 1, "description": "Limiar do modo automático: \"menos de N casos deste blueprint atribuídos\"." }, "escalation_enabled": { "type": "boolean" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID do esquema orientador de destino. Não é imposto no momento de guardar, mas a ação de escalamento falha com 400 até que ambos escalation_enabled e escalation_blueprint estejam definidos." }, "transfer_enabled": { "type": "boolean" }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "Definir isto ativa a revisão a 4 olhos: as resoluções neste modelo são colocadas na fila do modelo do verificador." }, "require_resolution_note": { "type": "boolean" }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "is_active": { "type": "boolean" }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760, "description": "Prazo predefinido para casos recém-abertos. Os prazos dos casos existentes permanecem inalterados." }, "expected_version": { "type": "integer", "minimum": 1, "description": "A versão aberta pelo editor. Uma versão desatualizada devolve 409 sem alterar a política de revisão." } } }, "example": { "transfer_enabled": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"transfer_enabled\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.update(\n \"b1de0000-0000-4000-8000-000000000002\",\n transfer_enabled=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.update(\"b1de0000-0000-4000-8000-000000000002\", {\n transfer_enabled: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Update(ctx, \"b1de0000-0000-4000-8000-000000000002\", didit.CasesBlueprintsUpdateParams{\n\tTransferEnabled: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesBlueprintsUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().update(\"b1de0000-0000-4000-8000-000000000002\", CasesBlueprintsUpdateParams.builder()\n .transferEnabled(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->update('b1de0000-0000-4000-8000-000000000002', [\n 'transfer_enabled' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.update(\n \"b1de0000-0000-4000-8000-000000000002\",\n transfer_enabled: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.UpdateAsync(\"b1de0000-0000-4000-8000-000000000002\", new CasesBlueprintsUpdateParams\n{\n TransferEnabled = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Esquema atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } }, "409": { "description": "A política de revisão foi alterada desde expected_version. Reveja a versão mais recente antes de tentar novamente." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Eliminar esquema", "description": "Eliminar um modelo. A eliminação é sempre bem-sucedida e não afeta os casos do modelo: os casos existentes mantêm a sua referência ao modelo e as respetivas definições continuam a aplicar-se a eles. Um modelo eliminado deixa de aparecer nas listas de modelos e já não pode ser escolhido como destino de transferência; se um modelo de criador (maker) for eliminado enquanto uma resolução aguarda aprovação de 4 olhos, uma resolução rejeitada mantém o caso no modelo de verificador (checker).", "operationId": "delete_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "UUID do blueprint." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.blueprints.delete(\n \"b1de0000-0000-4000-8000-000000000002\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.blueprints.delete(\"b1de0000-0000-4000-8000-000000000002\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Blueprints.Delete(ctx, \"b1de0000-0000-4000-8000-000000000002\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().blueprints().delete(\"b1de0000-0000-4000-8000-000000000002\");" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->delete('b1de0000-0000-4000-8000-000000000002');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.delete(\"b1de0000-0000-4000-8000-000000000002\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Blueprints.DeleteAsync(\"b1de0000-0000-4000-8000-000000000002\");" } ], "responses": { "204": { "description": "Blueprint eliminado." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/presets/": { "get": { "summary": "Listar predefinições de blueprints", "description": "Listar as quatro predefinições integradas (Screening hit, AML investigation, Suspicious activity, KYC review) com o respetivo content_config e se cada uma já está instalada nesta aplicação.", "operationId": "list_case_blueprint_presets", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list_presets", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/presets/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.list_presets()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.listPresets();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.ListPresets(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().listPresets();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->listPresets();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.list_presets\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.ListPresetsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Catálogo de predefinições.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "preset_key": { "type": "string", "enum": [ "screening_hit", "aml_investigation", "suspicious_activity", "kyc" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "installed": { "type": "boolean" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/presets/install/": { "post": { "summary": "Instalar predefinições de modelo", "description": "Copiar um ou mais modelos predefinidos para a aplicação como esquemas editáveis. Idempotente por preset_key; omita preset_keys para instalar todos os modelos predefinidos ainda não instalados.", "operationId": "install_case_blueprint_presets", "x-didit-sdk": { "resource": "cases.blueprints", "method": "install_presets", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "preset_keys": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Subconjunto de screening_hit, aml_investigation, suspicious_activity, kyc. Omita para instalar todos." } } }, "example": { "preset_keys": [ "aml_investigation", "kyc" ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/presets/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"preset_keys\": [\"aml_investigation\", \"kyc\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.install_presets(\n preset_keys=[\"aml_investigation\", \"kyc\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.installPresets({\n preset_keys: [\"aml_investigation\", \"kyc\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.InstallPresets(ctx, didit.CasesBlueprintsInstallPresetsParams{\n\tPresetKeys: didit.Some([]string{\"aml_investigation\", \"kyc\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBlueprintsInstallPresetsParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().installPresets(CasesBlueprintsInstallPresetsParams.builder()\n .presetKeys(List.of(\"aml_investigation\", \"kyc\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->installPresets([\n 'preset_keys' => ['aml_investigation', 'kyc'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.install_presets(preset_keys: [\"aml_investigation\", \"kyc\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.InstallPresetsAsync(new CasesBlueprintsInstallPresetsParams\n{\n PresetKeys = new string[] { \"aml_investigation\", \"kyc\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Uma ou mais predefinições instaladas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintPresetInstallResult" } } } }, "200": { "description": "Nenhuma nova predefinição para instalar (todas as predefinições solicitadas já existem).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintPresetInstallResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/report-templates/": { "get": { "summary": "Listar modelos de relatório", "description": "Listar modelos de relatórios da UIF para a aplicação.", "operationId": "list_report_templates", "x-didit-sdk": { "resource": "report_templates", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Tamanho da página." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset de base zero." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.report_templates.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.reportTemplates.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.ReportTemplates.ListAutoPaging(ctx, didit.ReportTemplatesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.reportTemplates().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.report_templates.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.ReportTemplates.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Modelos paginados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número de linhas correspondentes, limitado a 100 por motivos de desempenho." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar modelo de relatório", "description": "Crie um modelo reutilizável de cabeçalho goAML por jurisdição e por tipo de relatório. Rejeitado com 400 se algum dos campos obrigatórios ao nível do modelo (rentity_id, submission_code, currency_code_local) estiver em falta no field_config; um modelo inválido não pode ser guardado nem utilizado para criar um relatório. Os campos de cabeçalho específicos da submissão (action, submission_date, transactions) são validados apenas no momento de validar/finalizar o relatório.", "operationId": "create_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "jurisdiction", "report_type" ], "properties": { "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Código de país ISO 3166-1 alpha-2, convertido para maiúsculas ao guardar." }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "field_config": { "type": "object", "description": "Predefinições de cabeçalho goAML reutilizáveis. Campos obrigatórios ao nível do modelo: rentity_id, submission_code e currency_code_local (3 letras). Opcional: enabled_fields (que blocos de relatório opcionais incluir) mais predefinições de reporting_person, location, reason e action. Os campos de cabeçalho por submissão (action, submission_date, transactions, jurisdiction) são obrigatórios quando o relatório é validado ou finalizado, não no modelo." } } }, "example": { "name": "US SAR default", "jurisdiction": "US", "report_type": "SAR", "field_config": { "rentity_id": "FIU-US-00123", "submission_code": "E", "currency_code_local": "USD" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"US SAR default\", \"jurisdiction\": \"US\", \"report_type\": \"SAR\", \"field_config\": {\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.create(\n name=\"US SAR default\",\n jurisdiction=\"US\",\n report_type=\"SAR\",\n field_config={\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.create({\n name: \"US SAR default\",\n jurisdiction: \"US\",\n report_type: \"SAR\",\n field_config: { rentity_id: \"FIU-US-00123\", submission_code: \"E\", currency_code_local: \"USD\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Create(ctx, didit.ReportTemplatesCreateParams{\n\tName: \"US SAR default\",\n\tJurisdiction: \"US\",\n\tReportType: \"SAR\",\n\tFieldConfig: didit.Some(map[string]any{\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.ReportTemplatesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().create(ReportTemplatesCreateParams.builder()\n .name(\"US SAR default\")\n .jurisdiction(\"US\")\n .reportType(ReportTemplatesCreateParams.ReportType.of(\"SAR\"))\n .fieldConfig(Map.of(\"rentity_id\", \"FIU-US-00123\", \"submission_code\", \"E\", \"currency_code_local\", \"USD\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->create([\n 'name' => 'US SAR default',\n 'jurisdiction' => 'US',\n 'report_type' => 'SAR',\n 'field_config' => ['rentity_id' => 'FIU-US-00123', 'submission_code' => 'E', 'currency_code_local' => 'USD'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.create(\n name: \"US SAR default\",\n jurisdiction: \"US\",\n report_type: \"SAR\",\n field_config: { rentity_id: \"FIU-US-00123\", submission_code: \"E\", currency_code_local: \"USD\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.CreateAsync(new ReportTemplatesCreateParams\n{\n Name = \"US SAR default\",\n Jurisdiction = \"US\",\n ReportType = \"SAR\",\n FieldConfig = new Dictionary { [\"rentity_id\"] = \"FIU-US-00123\", [\"submission_code\"] = \"E\", [\"currency_code_local\"] = \"USD\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Modelo criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } }, "400": { "description": "Jurisdição não reconhecida, ou field_config falha na validação de campos obrigatórios.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/report-templates/{template_uuid}/": { "get": { "summary": "Obter modelo de relatório", "description": "Obter um modelo de relatório.", "operationId": "get_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "UUID do modelo de relatório." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.retrieve(\n \"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.retrieve(\"7ec00000-0000-4000-8000-000000000006\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Retrieve(ctx, \"7ec00000-0000-4000-8000-000000000006\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().retrieve(\"7ec00000-0000-4000-8000-000000000006\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->retrieve('7ec00000-0000-4000-8000-000000000006');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.retrieve(\"7ec00000-0000-4000-8000-000000000006\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.RetrieveAsync(\"7ec00000-0000-4000-8000-000000000006\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhes do modelo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar modelo de relatório", "description": "Atualizar parcialmente um modelo de relatório. Valida novamente os campos obrigatórios do goAML ao guardar.", "operationId": "update_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "UUID do modelo de relatório." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Código de país ISO 3166-1 alpha-2, convertido para maiúsculas ao guardar." }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "field_config": { "type": "object", "description": "Predefinições de cabeçalho goAML reutilizáveis. Campos obrigatórios ao nível do modelo: rentity_id, submission_code e currency_code_local (3 letras). Opcional: enabled_fields (que blocos de relatório opcionais incluir) mais predefinições de reporting_person, location, reason e action. Os campos de cabeçalho por submissão (action, submission_date, transactions, jurisdiction) são obrigatórios quando o relatório é validado ou finalizado, não no modelo." } } }, "example": { "field_config": { "rentity_id": "FIU-US-00124" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"field_config\": {\"rentity_id\": \"FIU-US-00124\"}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.update(\n \"7ec00000-0000-4000-8000-000000000006\",\n field_config={\"rentity_id\": \"FIU-US-00124\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.update(\"7ec00000-0000-4000-8000-000000000006\", {\n field_config: { rentity_id: \"FIU-US-00124\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Update(ctx, \"7ec00000-0000-4000-8000-000000000006\", didit.ReportTemplatesUpdateParams{\n\tFieldConfig: didit.Some(map[string]any{\"rentity_id\": \"FIU-US-00124\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.ReportTemplatesUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().update(\"7ec00000-0000-4000-8000-000000000006\", ReportTemplatesUpdateParams.builder()\n .fieldConfig(Map.of(\"rentity_id\", \"FIU-US-00124\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->update('7ec00000-0000-4000-8000-000000000006', [\n 'field_config' => ['rentity_id' => 'FIU-US-00124'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.update(\n \"7ec00000-0000-4000-8000-000000000006\",\n field_config: { rentity_id: \"FIU-US-00124\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.UpdateAsync(\"7ec00000-0000-4000-8000-000000000006\", new ReportTemplatesUpdateParams\n{\n FieldConfig = new Dictionary { [\"rentity_id\"] = \"FIU-US-00124\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Modelo atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Eliminar modelo de relatório", "description": "Eliminar um modelo de relatório. Os relatórios já criados a partir dele não são afetados.", "operationId": "delete_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "UUID do modelo de relatório." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.report_templates.delete(\n \"7ec00000-0000-4000-8000-000000000006\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.reportTemplates.delete(\"7ec00000-0000-4000-8000-000000000006\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.ReportTemplates.Delete(ctx, \"7ec00000-0000-4000-8000-000000000006\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.reportTemplates().delete(\"7ec00000-0000-4000-8000-000000000006\");" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->delete('7ec00000-0000-4000-8000-000000000006');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.report_templates.delete(\"7ec00000-0000-4000-8000-000000000006\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.ReportTemplates.DeleteAsync(\"7ec00000-0000-4000-8000-000000000006\");" } ], "responses": { "204": { "description": "Modelo eliminado." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/regulatory-reports/": { "get": { "summary": "Listar relatórios do caso", "description": "Listar relatórios da UIF gerados para o caso.", "operationId": "list_case_regulatory_reports", "x-didit-sdk": { "resource": "cases.regulatory_reports", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Tamanho da página." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset de base zero." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.regulatory_reports.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.regulatoryReports.list(\"c1a5e000-0000-4000-8000-000000000001\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RegulatoryReports.ListAutoPaging(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRegulatoryReportsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().regulatoryReports().list(\"c1a5e000-0000-4000-8000-000000000001\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->regulatoryReports->list('c1a5e000-0000-4000-8000-000000000001') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.regulatory_reports.list(\"c1a5e000-0000-4000-8000-000000000001\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RegulatoryReports.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Relatórios paginados para o caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportList" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar relatório a partir do caso", "description": "Crie um rascunho de relatório da UIF para o caso: estado DRAFT, preenchido automaticamente a partir do modelo opcional, do sujeito do caso, das transações associadas e da narrativa. Valide e depois finalize para produzir o XML e PDF goAML.", "operationId": "create_case_regulatory_report", "x-didit-sdk": { "resource": "cases.regulatory_reports", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID do caso." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "Obrigatório exceto se for fornecido um modelo; caso contrário, é utilizado o report_type do modelo." }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Obrigatório exceto se for fornecido um modelo." }, "template": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID do modelo de relatório; a respetiva field_config preenche o rascunho antes da intercalação dos dados derivados do caso." }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "description": "Transações a anexar; por predefinição, as transações associadas ao caso." }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "template": "7ec00000-0000-4000-8000-000000000006" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"template\": \"7ec00000-0000-4000-8000-000000000006\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.regulatory_reports.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n template=\"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.regulatoryReports.create(\"c1a5e000-0000-4000-8000-000000000001\", {\n template: \"7ec00000-0000-4000-8000-000000000006\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RegulatoryReports.Create(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRegulatoryReportsCreateParams{\n\tTemplate: didit.String(\"7ec00000-0000-4000-8000-000000000006\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesRegulatoryReportsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().regulatoryReports().create(\"c1a5e000-0000-4000-8000-000000000001\", CasesRegulatoryReportsCreateParams.builder()\n .template(\"7ec00000-0000-4000-8000-000000000006\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->regulatoryReports->create('c1a5e000-0000-4000-8000-000000000001', [\n 'template' => '7ec00000-0000-4000-8000-000000000006',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.regulatory_reports.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RegulatoryReports.CreateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesRegulatoryReportsCreateParams\n{\n Template = \"7ec00000-0000-4000-8000-000000000006\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Rascunho de relatório criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "O modelo referenciado não foi encontrado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/": { "get": { "summary": "Listar relatórios", "description": "Lista de relatórios da UIF ao nível da aplicação, opcionalmente filtrada por status, report_type ou case.", "operationId": "list_regulatory_reports", "x-didit-sdk": { "resource": "regulatory_reports", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Tamanho da página." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset de base zero." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "description": "Filtrar por estado." }, { "name": "report_type", "in": "query", "schema": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "description": "Filtrar por tipo de relatório." }, { "name": "case", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filtrar para relatórios neste caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.regulatory_reports.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.regulatoryReports.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.RegulatoryReports.ListAutoPaging(ctx, didit.RegulatoryReportsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.regulatoryReports().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.regulatory_reports.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.RegulatoryReports.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Relatórios paginados de toda a aplicação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportList" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar relatório autónomo", "description": "Crie um rascunho de relatório da UIF a partir da página autónoma Relatórios: tanto o caso como o modelo são obrigatórios (ao contrário da criação no âmbito do caso, que pode omitir o modelo).", "operationId": "create_standalone_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case", "template" ], "properties": { "case": { "type": "string", "format": "uuid" }, "template": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "Obrigatório exceto se for fornecido um modelo; caso contrário, é utilizado o report_type do modelo." }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Obrigatório exceto se for fornecido um modelo." }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "description": "Transações a anexar; por predefinição, as transações associadas ao caso." }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "case": "c1a5e000-0000-4000-8000-000000000001", "template": "7ec00000-0000-4000-8000-000000000006" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case\": \"c1a5e000-0000-4000-8000-000000000001\", \"template\": \"7ec00000-0000-4000-8000-000000000006\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.create(\n case=\"c1a5e000-0000-4000-8000-000000000001\",\n template=\"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.create({\n case: \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Create(ctx, didit.RegulatoryReportsCreateParams{\n\tCase: \"c1a5e000-0000-4000-8000-000000000001\",\n\tTemplate: \"7ec00000-0000-4000-8000-000000000006\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().create(RegulatoryReportsCreateParams.builder()\n .case_(\"c1a5e000-0000-4000-8000-000000000001\")\n .template(\"7ec00000-0000-4000-8000-000000000006\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->create([\n 'case' => 'c1a5e000-0000-4000-8000-000000000001',\n 'template' => '7ec00000-0000-4000-8000-000000000006',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.create(\n case: \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.CreateAsync(new RegulatoryReportsCreateParams\n{\n Case = \"c1a5e000-0000-4000-8000-000000000001\",\n Template = \"7ec00000-0000-4000-8000-000000000006\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Rascunho de relatório criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "O modelo referenciado não foi encontrado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/": { "get": { "summary": "Obter relatório", "description": "Obter um relatório regulamentar.", "operationId": "get_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID do relatório." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.retrieve(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.retrieve(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Retrieve(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().retrieve(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->retrieve('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.retrieve(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.RetrieveAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhe do relatório.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar relatório", "description": "Edita os campos de um relatório em rascunho ou validado. Relatórios finalizados não podem ser editados (409).", "operationId": "update_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID do relatório." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2 }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "rentity_id": "FIU-US-00123", "currency_code_local": "USD" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"rentity_id\": \"FIU-US-00123\", \"currency_code_local\": \"USD\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.update(\n \"5ec00000-0000-4000-8000-000000000007\",\n rentity_id=\"FIU-US-00123\",\n currency_code_local=\"USD\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.update(\"5ec00000-0000-4000-8000-000000000007\", {\n rentity_id: \"FIU-US-00123\",\n currency_code_local: \"USD\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Update(ctx, \"5ec00000-0000-4000-8000-000000000007\", didit.RegulatoryReportsUpdateParams{\n\tRentityID: didit.String(\"FIU-US-00123\"),\n\tCurrencyCodeLocal: didit.String(\"USD\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().update(\"5ec00000-0000-4000-8000-000000000007\", RegulatoryReportsUpdateParams.builder()\n .rentityId(\"FIU-US-00123\")\n .currencyCodeLocal(\"USD\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->update('5ec00000-0000-4000-8000-000000000007', [\n 'rentity_id' => 'FIU-US-00123',\n 'currency_code_local' => 'USD',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.update(\n \"5ec00000-0000-4000-8000-000000000007\",\n rentity_id: \"FIU-US-00123\",\n currency_code_local: \"USD\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.UpdateAsync(\"5ec00000-0000-4000-8000-000000000007\", new RegulatoryReportsUpdateParams\n{\n RentityId = \"FIU-US-00123\",\n CurrencyCodeLocal = \"USD\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Relatório atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "409": { "description": "O relatório já está finalizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Eliminar relatório", "description": "Eliminar um relatório regulamentar permanentemente. O relatório, a respetiva narrativa e os motivos copiados, as suas ligações a transações e o XML e PDF goAML gerados são apagados, incluindo todas as versões armazenadas desses ficheiros. O relatório desaparece das listas e os URLs de transferência deixam de funcionar. Outros registos, incluindo o caso, transações, pessoas e empresas, não são eliminados. Não é possível anular a operação.\n\nUm relatório em rascunho ou validado pode ser eliminado sem corpo de pedido. Eliminar um relatório finalizado requer `confirm_delete: true` no corpo do pedido. Se o relatório não existir, o pedido devolve `404`; se for enviado um relatório finalizado sem confirmação, devolve `400` e nada é eliminado.", "operationId": "delete_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID do relatório." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl (draft report)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (finalized report)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"confirm_delete\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.regulatory_reports.delete(\n \"5ec00000-0000-4000-8000-000000000007\",\n confirm_delete=True,\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.regulatoryReports.delete(\"5ec00000-0000-4000-8000-000000000007\", {\n confirm_delete: true,\n});" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsDeleteParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.regulatoryReports().delete(\"5ec00000-0000-4000-8000-000000000007\", RegulatoryReportsDeleteParams.builder()\n .confirmDelete(true)\n .build());" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->delete('5ec00000-0000-4000-8000-000000000007', [\n 'confirm_delete' => true,\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.regulatory_reports.delete(\n \"5ec00000-0000-4000-8000-000000000007\",\n confirm_delete: true\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.RegulatoryReports.DeleteAsync(\"5ec00000-0000-4000-8000-000000000007\", new RegulatoryReportsDeleteParams\n{\n ConfirmDelete = true,\n});" } ], "responses": { "204": { "description": "Relatório eliminado, incluindo os seus ficheiros gerados." }, "400": { "description": "Um relatório finalizado foi enviado sem `confirm_delete: true`. Nada é eliminado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_delete": { "type": "array", "items": { "type": "string" } } } }, "example": { "confirm_delete": [ "This field is required to delete a finalized report." ] } } } }, "403": { "description": "A chave de API não pode eliminar relatórios. O endpoint requer `write:cases`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "404": { "description": "Relatório não encontrado nesta aplicação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "O relatório já está a ser eliminado. Repita o pedido para concluir a eliminação dos respetivos ficheiros.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "This report is being deleted. Retry deleting it to finish erasing its files.", "code": "report_deletion_pending" } } } }, "503": { "description": "Não foi possível apagar os ficheiros do relatório neste momento. O relatório permanece intacto. Repita o pedido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "The report files could not be erased. Please retry deleting the report.", "code": "report_storage_unavailable" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "description": "Obrigatório apenas para um relatório finalizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_delete": { "type": "boolean", "description": "Defina como true para confirmar que um relatório finalizado e os respetivos ficheiros gerados são eliminados permanentemente." } }, "example": { "confirm_delete": true } }, "example": { "confirm_delete": true } } } } } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/validate/": { "post": { "summary": "Validar relatório", "description": "Verifica o relatório em relação aos campos obrigatórios do cabeçalho goAML (ID da entidade declarante, código de submissão, moeda local, ação tomada, data de submissão), além de pelo menos uma transação anexada e uma jurisdição de 2 letras, sem gerar quaisquer ficheiros. Também armazena o resultado no relatório: validation_errors e validated_at são atualizados, e o estado de um relatório não finalizado muda para VALIDATED (sem erros) ou volta para DRAFT (com erros).", "operationId": "validate_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "validate", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID do relatório." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/validate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.validate(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.validate(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Validate(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().validate(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->validate('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.validate(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.ValidateAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Resultado da validação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "is_valid": { "type": "boolean" }, "errors": { "type": "array", "description": "Vazio quando válido.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/finalize/": { "post": { "summary": "Finalizar relatório", "description": "Volte a validar, depois componha o XML e o PDF do goAML e envie ambos para o S3. Em relatórios SAR/STR/TFR, isto também move os alertas de transação do caso de Pending SAR para SAR filed.", "operationId": "finalize_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "finalize", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID do relatório." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/finalize/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.finalize(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.finalize(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Finalize(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().finalize_(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->finalize('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.finalize(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.FinalizeAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Relatório finalizado; xml_s3_key e pdf_s3_key estão definidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "O relatório falhou a validação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "409": { "description": "O relatório não se encontra num estado finalizável.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/download-url/": { "get": { "summary": "Obter URL de transferência do relatório", "description": "Gerar um URL pré-assinado para o ficheiro XML do goAML ou PDF de um relatório finalizado.", "operationId": "get_regulatory_report_download_url", "x-didit-sdk": { "resource": "regulatory_reports", "method": "retrieve_download_url", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID do relatório." }, { "name": "file", "in": "query", "schema": { "type": "string", "enum": [ "pdf", "xml" ], "default": "pdf" }, "description": "Qual o ficheiro a descarregar." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/download-url/?file=xml' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.retrieve_download_url(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.retrieveDownloadUrl(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.RetrieveDownloadURL(ctx, \"5ec00000-0000-4000-8000-000000000007\", didit.RegulatoryReportsRetrieveDownloadURLParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().retrieveDownloadUrl(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->retrieveDownloadUrl('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.retrieve_download_url(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.RetrieveDownloadUrlAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "URL de transferência pré-assinado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" }, "file": { "type": "string", "enum": [ "pdf", "xml" ] } } } } } }, "409": { "description": "O relatório ainda não está finalizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "status": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/rules/": { "get": { "summary": "Listar regras", "description": "Listar as regras de monitorização de transações da aplicação: as suas regras personalizadas e quaisquer predefinições da biblioteca que tenha instalado. Filtre por origem, categoria, modo, pacote ou pesquisa de texto livre; ordene com `ordering` (run_count, approved_pct, reviewed_pct, declined_pct, latest_triggered_at, title, created_at, source, cada um com um prefixo `-` opcional).", "operationId": "listTransactionRules", "x-didit-sdk": { "resource": "transactions.rules", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PRESET", "CUSTOM" ] }, "description": "PRESET ou CUSTOM" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtrar por categoria de regra" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ] }, "description": "ACTIVE, DISABLED ou TEST" }, { "name": "bundle", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtrar predefinições por pacote" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Correspondência insensível a maiúsculas/minúsculas no título e descrição" }, { "name": "ordering", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Campos de ordenação separados por vírgulas, por predefinição source,-run_count" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tamanho da página" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Offset de página" } ], "responses": { "200": { "description": "Regras paginadas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/?source=CUSTOM&ordering=-run_count' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.rules.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.rules.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Rules.ListAutoPaging(ctx, didit.TransactionsRulesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().rules().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Rules.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Criar regra", "description": "Crie uma regra CUSTOM de monitorização de transações. Os títulos são únicos por aplicação (duplicado -> 400). Uma ação `change_status` direcionada a `AWAITING_USER` tem de incluir `workflow_id`. As regras criadas no modo ACTIVE aplicam-se a novas transações imediatamente - o fluxo de trabalho recomendado é criar no modo TEST, fazer backtesting e, em seguida, mudar o modo para ACTIVE. Para alterar uma regra da biblioteca, crie-a como uma cópia: envie a definição da regra da biblioteca com `metadata.based_on` (a sua chave de biblioteca) e `metadata.based_on_rule_uuid`.", "operationId": "createTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleCreateRequest" }, "example": { "title": "Structuring - inbound (custom)", "description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days", "category": "finance", "mode": "TEST", "evaluation_mode": "ALL", "scope": { "transaction_types": [ "finance" ], "directions": [ "INBOUND" ] }, "conditions": [ { "field": "currency", "operator": "eq", "value": "EUR" }, { "field": "amount", "operator": "lt", "value": 10000 } ], "aggregation": [ { "metric": "count", "operator": "gte", "value": 20, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } }, { "metric": "max", "field": "amount", "operator": "lt", "value": 10000, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } } ], "actions": [ { "type": "add_score", "value": 35 } ] } } } }, "responses": { "201": { "description": "A regra criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "400": { "description": "Erro de validação - título duplicado, operador/métrica desconhecidos, janela malformada, direção de âmbito inválida ou AWAITING_USER sem workflow_id.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "title": [ "A rule with this name already exists." ] } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Structuring - inbound (custom)\", \"description\": \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\", \"category\": \"finance\", \"mode\": \"TEST\", \"evaluation_mode\": \"ALL\", \"scope\": {\"transaction_types\": [\"finance\"], \"directions\": [\"INBOUND\"]}, \"conditions\": [{\"field\": \"currency\", \"operator\": \"eq\", \"value\": \"EUR\"}, {\"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000}], \"aggregation\": [{\"metric\": \"count\", \"operator\": \"gte\", \"value\": 20, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}, {\"metric\": \"max\", \"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}], \"actions\": [{\"type\": \"add_score\", \"value\": 35}]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.create(\n title=\"Structuring - inbound (custom)\",\n description=\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category=\"finance\",\n mode=\"TEST\",\n evaluation_mode=\"ALL\",\n scope={\n \"transaction_types\": [\"finance\"],\n \"directions\": [\"INBOUND\"],\n },\n conditions=[{\n \"field\": \"currency\",\n \"operator\": \"eq\",\n \"value\": \"EUR\",\n }, {\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000,\n }],\n aggregation=[{\n \"metric\": \"count\",\n \"operator\": \"gte\",\n \"value\": 20.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }, {\n \"metric\": \"max\",\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }],\n actions=[{\n \"type\": \"add_score\",\n \"value\": 35,\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.create({\n title: \"Structuring - inbound (custom)\",\n description: \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category: \"finance\",\n mode: \"TEST\",\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n actions: [{\n type: \"add_score\",\n value: 35,\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Create(ctx, didit.TransactionRuleCreateRequest{\n\tTitle: \"Structuring - inbound (custom)\",\n\tDescription: didit.String(\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\"),\n\tCategory: \"finance\",\n\tMode: \"TEST\",\n\tEvaluationMode: didit.Some(didit.TransactionRuleCreateRequestEvaluationMode(\"ALL\")),\n\tScope: didit.Some(didit.TransactionRuleScopeParam{\n\t\tTransactionTypes: didit.Some([]string{\"finance\"}),\n\t\tDirections: didit.Some([]didit.TransactionRuleScopeDirections{\"INBOUND\"}),\n\t}),\n\tConditions: didit.Some([]didit.TransactionRuleConditionParam{{\n\t\tField: \"currency\",\n\t\tOperator: \"eq\",\n\t\tValue: didit.Some[any](\"EUR\"),\n\t}, {\n\t\tField: \"amount\",\n\t\tOperator: \"lt\",\n\t\tValue: didit.Some[any](10000),\n\t}}),\n\tAggregation: didit.Some([]didit.TransactionRuleAggregationParam{{\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"count\")),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"gte\")),\n\t\tValue: 20.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}, {\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"max\")),\n\t\tField: didit.String(\"amount\"),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"lt\")),\n\t\tValue: 10000.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}}),\n\tActions: didit.Some([]didit.TransactionRuleActionParam{{\n\t\tType: \"add_score\",\n\t\tValue: didit.Some[any](35),\n\t}}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleAction;\nimport me.didit.types.TransactionRuleActionAddScore;\nimport me.didit.types.TransactionRuleAggregation;\nimport me.didit.types.TransactionRuleCondition;\nimport me.didit.types.TransactionRuleCreateRequest;\nimport me.didit.types.TransactionRuleScope;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().create(TransactionRuleCreateRequest.builder()\n .title(\"Structuring - inbound (custom)\")\n .description(\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\")\n .category(\"finance\")\n .mode(TransactionRuleCreateRequest.Mode.of(\"TEST\"))\n .evaluationMode(TransactionRuleCreateRequest.EvaluationMode.of(\"ALL\"))\n .scope(TransactionRuleScope.builder()\n .transactionTypes(List.of(\"finance\"))\n .directions(List.of(TransactionRuleScope.Directions.of(\"INBOUND\")))\n .build())\n .conditions(List.of(\n TransactionRuleCondition.builder()\n .field(\"currency\")\n .operator(TransactionRuleCondition.Operator.of(\"eq\"))\n .value(\"EUR\")\n .build(),\n TransactionRuleCondition.builder()\n .field(\"amount\")\n .operator(TransactionRuleCondition.Operator.of(\"lt\"))\n .value(10000)\n .build()))\n .aggregation(List.of(\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"count\"))\n .operator(TransactionRuleAggregation.Operator.of(\"gte\"))\n .value(20.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build(),\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"max\"))\n .field(\"amount\")\n .operator(TransactionRuleAggregation.Operator.of(\"lt\"))\n .value(10000.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build()))\n .actions(List.of(TransactionRuleAction.ofAddScore(TransactionRuleActionAddScore.builder()\n .type(TransactionRuleActionAddScore.Type.of(\"add_score\"))\n .value(35L)\n .build())))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->create([\n 'title' => 'Structuring - inbound (custom)',\n 'description' => '20+ inbound EUR transfers, all under 10,000 EUR, 30 days',\n 'category' => 'finance',\n 'mode' => 'TEST',\n 'evaluation_mode' => 'ALL',\n 'scope' => [\n 'transaction_types' => ['finance'],\n 'directions' => ['INBOUND'],\n ],\n 'conditions' => [[\n 'field' => 'currency',\n 'operator' => 'eq',\n 'value' => 'EUR',\n ], [\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000,\n ]],\n 'aggregation' => [[\n 'metric' => 'count',\n 'operator' => 'gte',\n 'value' => 20.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ], [\n 'metric' => 'max',\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ]],\n 'actions' => [[\n 'type' => 'add_score',\n 'value' => 35,\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.create(\n title: \"Structuring - inbound (custom)\",\n description: \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category: \"finance\",\n mode: \"TEST\",\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n actions: [{\n type: \"add_score\",\n value: 35,\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.CreateAsync(new TransactionRuleCreateRequest\n{\n Title = \"Structuring - inbound (custom)\",\n Description = \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n Category = \"finance\",\n Mode = \"TEST\",\n EvaluationMode = new TransactionRuleCreateRequestEvaluationMode(\"ALL\"),\n Scope = new TransactionRuleScope\n {\n TransactionTypes = new string[] { \"finance\" },\n Directions = new TransactionRuleScopeDirections[] { \"INBOUND\" },\n },\n Conditions = new TransactionRuleCondition[]\n {\n new()\n {\n Field = \"currency\",\n Operator = \"eq\",\n Value = \"EUR\",\n },\n new()\n {\n Field = \"amount\",\n Operator = \"lt\",\n Value = 10000,\n },\n },\n Aggregation = new TransactionRuleAggregation[]\n {\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"count\"),\n Operator = new TransactionRuleAggregationOperator(\"gte\"),\n Value = 20.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"max\"),\n Field = \"amount\",\n Operator = new TransactionRuleAggregationOperator(\"lt\"),\n Value = 10000.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n },\n Actions = new TransactionRuleAction[]\n {\n new()\n {\n Type = new TransactionRuleActionType(\"add_score\"),\n Value = 35,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/transactions/rules/{rule_uuid}/": { "parameters": [ { "name": "rule_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "O uuid da regra a partir de list ou create." } ], "get": { "summary": "Obter regra", "description": "Obtenha uma regra com a sua configuração completa e contadores de execução.", "operationId": "getTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "A regra.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "404": { "description": "Não existe essa regra nesta aplicação.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Atualizar regra", "description": "Atualize parcialmente uma regra. As regras personalizadas aceitam todos os campos de configuração. As regras da biblioteca (PRESET) aceitam apenas `mode` - utilize-o para ativar, desativar ou mudar uma predefinição para TEST; qualquer outro campo devolve 400, pois a Didit mantém as regras da biblioteca e aplica as respetivas atualizações automaticamente. Para alterar as condições de uma regra da biblioteca, crie uma cópia personalizada com `POST /v3/transactions/rules/` utilizando a definição da regra da biblioteca, `metadata.based_on` (a chave da biblioteca) e `metadata.based_on_rule_uuid`; em seguida, desative a regra da biblioteca com `mode: DISABLED` para que uma transação não gere alertas duplicados. Uma cópia instalada de uma regra da biblioteca retida está desativada: definir o seu `mode` para qualquer valor diferente de `DISABLED` devolve 400 (\"This library rule cannot run yet: its conditions read data the rules engine cannot evaluate.\").", "operationId": "updateTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleUpdateRequest" }, "example": { "mode": "ACTIVE" } } } }, "responses": { "200": { "description": "A regra atualizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "400": { "description": "Erro de validação, um campo que não seja de modo numa regra da biblioteca ou um modo diferente de DISABLED numa regra da biblioteca retida.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"mode\": \"ACTIVE\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n mode=\"ACTIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.update(\"11111111-2222-3333-4444-555555555555\", {\n mode: \"ACTIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TransactionRuleUpdateRequest{\n\tMode: didit.Some(didit.TransactionRuleUpdateRequestMode(\"ACTIVE\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionRuleUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().update(\"11111111-2222-3333-4444-555555555555\", TransactionRuleUpdateRequest.builder()\n .mode(TransactionRuleUpdateRequest.Mode.of(\"ACTIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->update('11111111-2222-3333-4444-555555555555', [\n 'mode' => 'ACTIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n mode: \"ACTIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new TransactionRuleUpdateRequest\n{\n Mode = new TransactionRuleUpdateRequestMode(\"ACTIVE\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Eliminar regra", "description": "Eliminar uma regra CUSTOM. A eliminação é imediata e permanente: a regra deixa de ser avaliada para novas transações e desaparece das listagens, enquanto as execuções anteriores da regra em transações já avaliadas mantêm os seus resultados registados. As regras de biblioteca não podem ser eliminadas - desinstale-as através do endpoint de instalação (podem sempre ser reinstaladas a partir da biblioteca).", "operationId": "deleteTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Eliminado." }, "400": { "description": "A regra é uma predefinição da biblioteca - desinstale-a em alternativa.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "detail": "Library rules cannot be deleted. Uninstall them via the rules install endpoint instead." } } } }, "404": { "description": "Não existe essa regra nesta aplicação.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.transactions.rules.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.transactions.rules.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Transactions.Rules.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.transactions().rules().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Transactions.Rules.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/transactions/rules/backtest/": { "post": { "summary": "Configuração da regra de backtest", "description": "Avalie uma configuração de regra hipotética em relação às suas transações recentes (as mais recentes primeiro, até ao limite do backtest) sem criar uma regra nem modificar qualquer transação. Utilize-a antes de ativar uma regra para ver com que frequência teria correspondido e quantos sujeitos teria afetado.", "operationId": "backtestTransactionRules", "x-didit-sdk": { "resource": "transactions.rules", "method": "backtest", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleBacktestRequest" }, "example": { "conditions": [ { "field": "currency", "operator": "eq", "value": "EUR" }, { "field": "amount", "operator": "lt", "value": 10000 } ], "aggregation": [ { "metric": "count", "operator": "gte", "value": 20, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } }, { "metric": "max", "field": "amount", "operator": "lt", "value": 10000, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } } ], "evaluation_mode": "ALL", "scope": { "transaction_types": [ "finance" ], "directions": [ "INBOUND" ] }, "period_days": 90 } } } }, "responses": { "200": { "description": "Estatísticas de backtest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleBacktestResult" }, "example": { "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"conditions\": [{\"field\": \"currency\", \"operator\": \"eq\", \"value\": \"EUR\"}, {\"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000}], \"aggregation\": [{\"metric\": \"count\", \"operator\": \"gte\", \"value\": 20, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}, {\"metric\": \"max\", \"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}], \"evaluation_mode\": \"ALL\", \"scope\": {\"transaction_types\": [\"finance\"], \"directions\": [\"INBOUND\"]}, \"period_days\": 90}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.backtest(\n conditions=[{\n \"field\": \"currency\",\n \"operator\": \"eq\",\n \"value\": \"EUR\",\n }, {\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000,\n }],\n aggregation=[{\n \"metric\": \"count\",\n \"operator\": \"gte\",\n \"value\": 20.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }, {\n \"metric\": \"max\",\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }],\n evaluation_mode=\"ALL\",\n scope={\n \"transaction_types\": [\"finance\"],\n \"directions\": [\"INBOUND\"],\n },\n period_days=90,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.backtest({\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n period_days: 90,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Backtest(ctx, didit.TransactionRuleBacktestRequest{\n\tConditions: didit.Some([]didit.TransactionRuleConditionParam{{\n\t\tField: \"currency\",\n\t\tOperator: \"eq\",\n\t\tValue: didit.Some[any](\"EUR\"),\n\t}, {\n\t\tField: \"amount\",\n\t\tOperator: \"lt\",\n\t\tValue: didit.Some[any](10000),\n\t}}),\n\tAggregation: didit.Some([]didit.TransactionRuleAggregationParam{{\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"count\")),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"gte\")),\n\t\tValue: 20.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}, {\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"max\")),\n\t\tField: didit.String(\"amount\"),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"lt\")),\n\t\tValue: 10000.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}}),\n\tEvaluationMode: didit.Some(didit.TransactionRuleBacktestRequestEvaluationMode(\"ALL\")),\n\tScope: didit.Some(didit.TransactionRuleScopeParam{\n\t\tTransactionTypes: didit.Some([]string{\"finance\"}),\n\t\tDirections: didit.Some([]didit.TransactionRuleScopeDirections{\"INBOUND\"}),\n\t}),\n\tPeriodDays: didit.Int(90),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleAggregation;\nimport me.didit.types.TransactionRuleBacktestRequest;\nimport me.didit.types.TransactionRuleCondition;\nimport me.didit.types.TransactionRuleScope;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().backtest(TransactionRuleBacktestRequest.builder()\n .conditions(List.of(\n TransactionRuleCondition.builder()\n .field(\"currency\")\n .operator(TransactionRuleCondition.Operator.of(\"eq\"))\n .value(\"EUR\")\n .build(),\n TransactionRuleCondition.builder()\n .field(\"amount\")\n .operator(TransactionRuleCondition.Operator.of(\"lt\"))\n .value(10000)\n .build()))\n .aggregation(List.of(\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"count\"))\n .operator(TransactionRuleAggregation.Operator.of(\"gte\"))\n .value(20.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build(),\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"max\"))\n .field(\"amount\")\n .operator(TransactionRuleAggregation.Operator.of(\"lt\"))\n .value(10000.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build()))\n .evaluationMode(TransactionRuleBacktestRequest.EvaluationMode.of(\"ALL\"))\n .scope(TransactionRuleScope.builder()\n .transactionTypes(List.of(\"finance\"))\n .directions(List.of(TransactionRuleScope.Directions.of(\"INBOUND\")))\n .build())\n .periodDays(90L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->backtest([\n 'conditions' => [[\n 'field' => 'currency',\n 'operator' => 'eq',\n 'value' => 'EUR',\n ], [\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000,\n ]],\n 'aggregation' => [[\n 'metric' => 'count',\n 'operator' => 'gte',\n 'value' => 20.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ], [\n 'metric' => 'max',\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ]],\n 'evaluation_mode' => 'ALL',\n 'scope' => [\n 'transaction_types' => ['finance'],\n 'directions' => ['INBOUND'],\n ],\n 'period_days' => 90,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.backtest(\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n period_days: 90\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.BacktestAsync(new TransactionRuleBacktestRequest\n{\n Conditions = new TransactionRuleCondition[]\n {\n new()\n {\n Field = \"currency\",\n Operator = \"eq\",\n Value = \"EUR\",\n },\n new()\n {\n Field = \"amount\",\n Operator = \"lt\",\n Value = 10000,\n },\n },\n Aggregation = new TransactionRuleAggregation[]\n {\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"count\"),\n Operator = new TransactionRuleAggregationOperator(\"gte\"),\n Value = 20.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"max\"),\n Field = \"amount\",\n Operator = new TransactionRuleAggregationOperator(\"lt\"),\n Value = 10000.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n },\n EvaluationMode = new TransactionRuleBacktestRequestEvaluationMode(\"ALL\"),\n Scope = new TransactionRuleScope\n {\n TransactionTypes = new string[] { \"finance\" },\n Directions = new TransactionRuleScopeDirections[] { \"INBOUND\" },\n },\n PeriodDays = 90,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/transactions/rules/library/": { "get": { "summary": "Listar biblioteca de regras", "description": "Consulte a biblioteca completa de regras predefinidas (150+ regras) com a configuração completa de cada entrada e um sinalizador `is_installed` para esta aplicação. Filtre por pacote, categoria ou pesquisa de texto livre. Uma regra da biblioteca cujas condições leiam dados que o motor de regras ainda não consegue avaliar é retida até que possa ser executada. Regras retidas não são listadas.", "operationId": "listTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "list_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "bundle", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtrar por pacote, por exemplo, finance, aml_ctf, crypto_monitoring, travel_rule" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtrar por categoria" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Correspondência insensível a maiúsculas/minúsculas no título e descrição" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tamanho da página" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Offset de página" } ], "responses": { "200": { "description": "Entradas paginadas da biblioteca.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleLibraryEntry" } } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/library/?bundle=finance' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.rules.list_library():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.rules.listLibrary()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Rules.ListLibraryAutoPaging(ctx, didit.TransactionsRulesListLibraryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().rules().listLibrary()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->listLibrary() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.list_library.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Rules.ListLibraryAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/transactions/rules/install/": { "post": { "summary": "Instalar regras da biblioteca", "description": "Instale uma ou mais predefinições na aplicação, por `library_keys` ou um `bundle` completo. Uma predefinição instalada fica ativa de imediato enquanto a monitorização de transações estiver ligada, e desativada caso contrário; as chaves já instaladas são ignoradas. Uma regra de biblioteca cujas condições leiam dados que o motor de regras ainda não consegue avaliar fica retida até que possa ser executada. Um pedido que mencione uma em `library_keys` responde 400 e não instala nada (\"Estas regras da biblioteca ainda não podem ser executadas: as respetivas condições leem dados que o motor de regras não consegue avaliar.\" seguido das chaves), e uma instalação por `bundle` ignora-a. Uma regra retida volta a ser ativada por si só assim que as suas condições puderem ser avaliadas. Uma entrada em `library_keys` que não esteja na biblioteca é ignorada, não recusada.", "operationId": "installTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "install_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallRequest" }, "example": { "library_keys": [ "structuring-inbound", "structuring-outbound" ] } } } }, "responses": { "200": { "description": "O que foi instalado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallResult" }, "example": { "installed_library_keys": [ "structuring-inbound", "structuring-outbound" ], "installed_count": 2 } } } }, "400": { "description": "Nem library_keys nem bundle fornecidos, `library_keys` não é uma lista, ou uma entrada de `library_keys` está retida. Uma entrada desconhecida é ignorada e responde com 200 sem ela.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"library_keys\": [\"structuring-inbound\", \"structuring-outbound\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.install_library(\n library_keys=[\"structuring-inbound\", \"structuring-outbound\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.installLibrary({\n library_keys: [\"structuring-inbound\", \"structuring-outbound\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.InstallLibrary(ctx, didit.TransactionRuleInstallRequest{\n\tLibraryKeys: didit.Some([]string{\"structuring-inbound\", \"structuring-outbound\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleInstallRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().installLibrary(TransactionRuleInstallRequest.builder()\n .libraryKeys(List.of(\"structuring-inbound\", \"structuring-outbound\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->installLibrary([\n 'library_keys' => ['structuring-inbound', 'structuring-outbound'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.install_library(library_keys: [\"structuring-inbound\", \"structuring-outbound\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.InstallLibraryAsync(new TransactionRuleInstallRequest\n{\n LibraryKeys = new string[] { \"structuring-inbound\", \"structuring-outbound\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Desinstalar regras da biblioteca", "description": "Remove predefinições instaladas da aplicação, através de `library_keys` ou de um `bundle` completo. As predefinições desinstaladas deixam de ser avaliadas imediatamente e podem ser reinstaladas a partir da biblioteca a qualquer momento.", "operationId": "uninstallTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "uninstall_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallRequest" }, "example": { "bundle": "responsible_gaming" } } } }, "responses": { "200": { "description": "Quantas predefinições foram removidas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallResult" }, "example": { "uninstalled_count": 5 } } } }, "400": { "description": "Nem library_keys nem bundle fornecidos.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/transactions/rules/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"bundle\": \"responsible_gaming\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.uninstall_library(\n bundle=\"responsible_gaming\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.uninstallLibrary({\n bundle: \"responsible_gaming\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.UninstallLibrary(ctx, didit.TransactionRuleInstallRequest{\n\tBundle: didit.String(\"responsible_gaming\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionRuleInstallRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().uninstallLibrary(TransactionRuleInstallRequest.builder()\n .bundle(\"responsible_gaming\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->uninstallLibrary([\n 'bundle' => 'responsible_gaming',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.uninstall_library(bundle: \"responsible_gaming\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.UninstallLibraryAsync(new TransactionRuleInstallRequest\n{\n Bundle = \"responsible_gaming\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/": { "get": { "summary": "Listar redes", "description": "Listar redes de fraude detetadas na organização desta aplicação, por predefinição da de maior risco para a de menor risco. Por predefinição, as redes descartadas são excluídas; passe status para as incluir. As aplicações de sandbox nunca têm redes: o agrupamento exclui totalmente os dados de sandbox. Cada resposta inclui o `sharing_mode` da organização e se os sinais interorganizações se aplicam à mesma (`cross_org_available`, `cross_org_unavailable_reason`). Os `kpis` agregam as redes que correspondem aos seus filtros e os `counts` agregam todas as redes que a aplicação pode ver; passe `summary=false` para ignorar ambos quando apenas precisar da página. Requer uma chave de API de acesso total, ou `list:networks` para um membro da consola.", "operationId": "list_networks", "x-didit-sdk": { "resource": "networks", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Estados a incluir separados por vírgulas: active,in_review,resolved,dismissed. Omita para excluir dismissed." }, { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "identity", "transactions" ] }, "description": "`transactions` mantém as redes cujos membros são todos partes da transação; `identity` mantém todas as outras redes. Omita para incluir ambas. Também restringe `counts.views` e `counts.facets`. Qualquer outro valor devolve 400." }, { "name": "signal_type", "in": "query", "schema": { "type": "string" }, "description": "Tipos de sinal separados por vírgulas: ip_address,device,face,document_number,phone,email,address." }, { "name": "pattern_type", "in": "query", "schema": { "type": "string" }, "description": "Tipos de padrão separados por vírgulas, por exemplo, exact_same_device,same_email." }, { "name": "risk_band", "in": "query", "schema": { "type": "string" }, "description": "Intervalos separados por vírgulas: low,medium,high." }, { "name": "min_size", "in": "query", "schema": { "type": "integer" }, "description": "Número mínimo de membros." }, { "name": "max_size", "in": "query", "schema": { "type": "integer" }, "description": "Número máximo de membros." }, { "name": "assignee", "in": "query", "schema": { "type": "string" }, "description": "Responsáveis atribuídos separados por vírgulas: `unassigned`, e-mails dos membros (correspondência sem distinção de maiúsculas e minúsculas) ou `me` para o membro da consola que efetua a chamada. Uma rede corresponde a qualquer valor. `me` necessita de um token de membro da consola: uma chave de API recebe 400 `{\"assignee\": [\"\\\"me\\\" needs a user token; an API key has no assignee identity.\"]}`." }, { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "Prioridades separadas por vírgulas: `low`, `medium`, `high`, ou `none` para redes sem prioridade. Qualquer outro valor devolve 400 `{\"priority\": \"Unknown priority: .\"}`." }, { "name": "risk_min", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "Pontuação de risco mínima, um número inteiro de 0 a 100. Um valor que não seja um número inteiro devolve 400 `{\"risk_min\": \"Use a whole number from 0 to 100.\"}`." }, { "name": "has_case", "in": "query", "schema": { "type": "boolean" }, "description": "`true` mantém as redes para as quais a sua aplicação abriu um caso, `false` as outras. Qualquer outro valor é ignorado." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limite inferior para last_activity_at (data ou datetime ISO 8601)." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limite superior de first_activity_at (data ou data e hora ISO 8601)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Pesquisa em texto livre pelo nome da rede, nomes dos membros, o network_id (N-0001) e tokens exatos de pattern_type." }, { "name": "ordering", "in": "query", "schema": { "type": "string" }, "description": "Um de risk_score, -risk_score, last_activity_at, -last_activity_at, first_activity_at, -first_activity_at, network_number, -network_number. O valor predefinido é -risk_score,-last_activity_at." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Tamanho da página, 1-500. A predefinição é 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset de base zero do primeiro registo." }, { "name": "summary", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "`false` devolve apenas a página e a respetiva `count`, sem `kpis` e `counts`. O valor predefinido é `true`. Qualquer valor diferente de `true` ou `false` devolve 400." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/?status=active,in_review&ordering=-risk_score' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.networks.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.networks.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Networks.ListAutoPaging(ctx, didit.NetworksListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.networks().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "networks->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.networks.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Networks.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Lista paginada de redes, com o modo de partilha da organização e a disponibilidade interorganizações, além de `kpis` e `counts`, a menos que `summary=false`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "integer", "nullable": true, "description": "Offset da página seguinte, ou null na última página." }, "previous": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkListItem" } }, "kpis": { "type": "object", "description": "Cada chave é {value, delta} sobre os resultados correspondentes aos filtros atuais. Omitido quando `summary=false`.", "properties": { "active": { "type": "object" }, "in_review": { "type": "object" }, "applicants_involved": { "type": "object" }, "detected_this_period": { "type": "object" }, "false_positive_rate": { "type": "object" } } }, "counts": { "$ref": "#/components/schemas/NetworkListCounts" }, "sharing_mode": { "type": "string", "enum": [ "off", "private", "global" ], "description": "O modo de partilha entre organizações da organização. Apenas `global` compara redes entre organizações; `private` e `off` restringem-nas ao próprio histórico da organização.", "example": "global" }, "cross_org_available": { "type": "boolean", "description": "Se os sinais entre organizações se aplicam a esta organização. Exigem tanto o plano Enterprise como o modo de partilha `global`.", "example": true }, "cross_org_unavailable_reason": { "type": "string", "enum": [ "plan", "sharing_mode" ], "nullable": true, "description": "O motivo pelo qual os sinais interorganizacionais não se aplicam, verificados por esta ordem. `plan`: o plano da organização não inclui a rede de fraude interorganizacional (requer o plano Enterprise), independentemente do modo de partilha. `sharing_mode`: o plano inclui-a, mas o modo de partilha é `private` ou `off`. Nulo quando `cross_org_available` é `true`.", "example": null } }, "required": [ "count", "next", "previous", "results", "sharing_mode", "cross_org_available", "cross_org_unavailable_reason" ] } } } }, "400": { "description": "Um valor inválido de filtro, ordenação, paginação ou `summary`.", "content": { "application/json": { "examples": { "Invalid summary": { "summary": "Resumo inválido", "value": { "summary": [ "Must be \"true\" or \"false\"." ] } }, "Invalid scope": { "summary": "Âmbito inválido", "value": { "scope": [ "Use identity or transactions." ] } }, "Unsupported ordering": { "summary": "Ordenação não suportada", "value": [ "Unsupported ordering." ] } } } } }, "401": { "description": "Credenciais em falta ou inválidas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenciais em falta ou inválidas", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "A chave de API pertence a outra aplicação ou é uma chave com acesso restrito: os endpoints de Networks necessitam de uma chave de acesso total. Um token de membro da consola necessita de `list:networks`. Também é devolvido com `code: networks_not_entitled` quando o Networks não está ativado para a organização.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Redes não ativadas", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chave de API restrita", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Sem permissão", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/": { "get": { "summary": "Obter rede", "description": "Obtenha os detalhes completos de uma única rede: estatísticas, etiquetas de fraude e sinais de risco, além do `sharing_mode` da organização e da disponibilidade entre organizações, das `tags` da sua aplicação na rede, dos `outcomes` dos membros e das pontuações de padrões (`patterns`). Requer uma chave de API com acesso total ou `read:networks` para um membro da consola.", "operationId": "get_network", "x-didit-sdk": { "resource": "networks", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID da rede." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieve(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.Retrieve(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieve(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieve('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Detalhe da rede.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "404": { "description": "Rede não encontrada (ou não visível para esta aplicação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "401": { "description": "Credenciais em falta ou inválidas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenciais em falta ou inválidas", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "A chave de API pertence a outra aplicação ou é uma chave com acesso restrito: os endpoints de Networks necessitam de uma chave de acesso total. Um token de membro da consola necessita de `read:networks`. Também é devolvido com `code: networks_not_entitled` quando o Networks não está ativado para a organização.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Redes não ativadas", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chave de API restrita", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Sem permissão", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/graph/": { "get": { "summary": "Obter grafo de rede", "description": "Obter a rede como um grafo de nós de sujeitos (utilizadores do fornecedor, empresas do fornecedor, partes da transação) e nós de sinais (os valores partilhados de dispositivo/IP/face/documento/telefone/e-mail/morada que os ligam), com arestas que representam associações.", "operationId": "get_network_graph", "x-didit-sdk": { "resource": "networks", "method": "retrieve_graph", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID da rede." }, { "name": "depth", "in": "query", "schema": { "type": "string", "enum": [ "1", "2", "3", "all" ] }, "description": "Saltos a partir do sujeito em foco a incluir. Por predefinição, todos (sem limite)." }, { "name": "focus_kind", "in": "query", "schema": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party" ] }, "description": "Tipo de sujeito no qual centrar o grafo. Tem de ser fornecido juntamente com focus_id; assume um membro arbitrário por predefinição quando a profundidade é delimitada e nenhum dos dois é fornecido." }, { "name": "focus_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "UUID do sujeito no qual centrar o grafo." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/graph/?depth=2' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_graph(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveGraph(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveGraph(ctx, \"n3a5e000-0000-4000-8000-000000000001\", didit.NetworksRetrieveGraphParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveGraph(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveGraph('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_graph(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveGraphAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Grafo da rede.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkGraph" } } } }, "404": { "description": "Rede não encontrada (ou não visível para esta aplicação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/members/": { "get": { "summary": "Listar membros da rede", "description": "Liste os sujeitos (utilizadores do fornecedor, empresas do fornecedor ou partes da transação) que pertencem a esta rede.", "operationId": "list_network_members", "x-didit-sdk": { "resource": "networks", "method": "list_members", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID da rede." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/members/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.list_members(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.listMembers(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.ListMembers(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().listMembers(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->listMembers('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.list_members(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.ListMembersAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Membros da rede. Não paginado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkMember" } } } } } } }, "404": { "description": "Rede não encontrada (ou não visível para esta aplicação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/signals/": { "get": { "summary": "Listar sinais da rede", "description": "Liste os sinais (dispositivo partilhado, IP, rosto, número do documento, telefone, e-mail ou valores de morada) que associam os membros desta rede.", "operationId": "list_network_signals", "x-didit-sdk": { "resource": "networks", "method": "list_signals", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID da rede." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/signals/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.list_signals(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.listSignals(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.ListSignals(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().listSignals(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->listSignals('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.list_signals(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.ListSignalsAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Sinais da rede. Não paginado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkSignal" } } } } } } }, "404": { "description": "Rede não encontrada (ou não visível para esta aplicação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/timeline/": { "get": { "summary": "Obter linha cronológica da rede", "description": "Sem `contract`: os eventos próprios da rede (deteção, observação mais recente de cada sinal e a respetiva revisão), do mais antigo para o mais recente e sem paginação. `limit`, `cursor` e `event_type` são ignorados. Com `contract=2`: a cronologia tipificada, do mais recente para o mais antigo e paginada por cursor. Acrescenta as ações das contas-membro (tentativas de verificação, transações, inícios de sessão enviados através da API de eventos e as regras ativas acionadas) e os casos abertos para a rede. Os eventos `note_added` são devolvidos apenas a membros da consola, nunca a uma chave de API. Requer uma chave de API com acesso total ou `read:networks` para um membro da consola.", "operationId": "get_network_timeline", "x-didit-sdk": { "resource": "networks", "method": "retrieve_timeline", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID da rede." }, { "name": "contract", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "2" ] }, "description": "`2` devolve a cronologia tipada. Omita-o para a cronologia predefinida. Qualquer outro valor devolve 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Apenas cronologia tipificada. Eventos por página, entre 1 e 500. O valor predefinido é 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Apenas cronologia tipificada. O `next_cursor` da página anterior. Um cursor inválido ou vazio devolve 400." }, { "name": "event_type", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "network_detected", "signal_observed", "network_active", "network_in_review", "network_resolved", "network_dismissed", "verification_attempt", "transaction", "login", "rule_hit", "case_linked", "note_added" ] } }, "description": "Apenas cronologia tipificada. Tipos de eventos a manter, repetidos ou separados por vírgulas, no máximo 20 valores. O valor predefinido inclui todos os tipos." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/timeline/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (typed timeline)", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/timeline/?contract=2&limit=50&event_type=verification_attempt,login' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_timeline(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveTimeline(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveTimeline(ctx, \"n3a5e000-0000-4000-8000-000000000001\", didit.NetworksRetrieveTimelineParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveTimeline(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveTimeline('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_timeline(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveTimelineAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Sem `contract`: `{results}`, os mais antigos primeiro, sem paginação. Com `contract=2`: `{results, next_cursor}`, os mais recentes primeiro.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NetworkTimeline" }, { "$ref": "#/components/schemas/NetworkTimelinePage" } ] }, "examples": { "Default timeline": { "summary": "Sem contrato", "value": { "results": [ { "event_type": "network_detected", "occurred_at": "2026-10-01T09:12:44Z", "label": "Network detected", "metadata": { "network_id": "N-0042" } }, { "event_type": "signal_observed", "occurred_at": "2026-10-12T16:03:10Z", "label": "device observed", "metadata": { "signal_type": "device", "subject_count": 3, "is_hub": false } }, { "event_type": "network_in_review", "occurred_at": "2026-10-12T16:30:00Z", "label": "Network in_review", "metadata": { "reason": "Shared device across three new accounts." } } ] } }, "Typed timeline": { "summary": "Com contract=2", "value": { "results": [ { "id": "monitoring_event:9b2f1c3e-4d5a-4b6c-8d7e-0f1a2b3c4d5e", "event_type": "login", "occurred_at": "2026-10-12T18:41:02Z", "ingested_at": "2026-10-12T18:41:03Z", "label": "Login", "metadata": {}, "account": { "node_id": "vendor_user:5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "node_type": "account", "uuid": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "vendor_data": "user-1042", "display_name": "Alex Example", "ownership": "owned", "route": { "kind": "user", "id": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "source_ref": { "kind": "monitoring_event", "id": "9b2f1c3e-4d5a-4b6c-8d7e-0f1a2b3c4d5e", "ownership": "owned" }, "verification_attempt": null, "transaction": null, "login": { "action": "auth.login", "succeeded": true, "status": "APPROVED", "ip": { "address": "203.0.113.24", "country_code": "ES", "city": "Madrid", "connection_type": null, "is_vpn_or_tor": false, "is_data_center": false }, "device": { "fingerprint": "fp_0a1b2c3d", "label": "Chrome · Android" }, "is_first_login": false, "is_new_device": true }, "rule_hit": null, "case_linked": null, "note_added": null }, { "id": "session:1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "event_type": "verification_attempt", "occurred_at": "2026-10-12T16:03:10Z", "ingested_at": "2026-10-12T16:03:10Z", "label": "Verification attempt 2 of 2", "metadata": {}, "account": { "node_id": "vendor_user:5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "node_type": "account", "uuid": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "vendor_data": "user-1042", "display_name": "Alex Example", "ownership": "owned", "route": { "kind": "user", "id": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "source_ref": { "kind": "session", "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "ownership": "owned", "route": { "kind": "session", "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "verification_attempt": { "session_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "session_number": 1287, "attempt": 2, "attempt_count": 2, "status": "Approved", "status_changed_at": "2026-10-12T16:05:41Z", "decline_reasons": [] }, "transaction": null, "login": null, "rule_hit": null, "case_linked": null, "note_added": null }, { "id": "signal_observed:8d7c6b5a-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "event_type": "signal_observed", "occurred_at": "2026-10-12T16:03:10Z", "ingested_at": "2026-10-01T09:12:44Z", "label": "device observed", "metadata": { "signal_type": "device", "subject_count": 3, "is_hub": false }, "account": null, "source_ref": null, "verification_attempt": null, "transaction": null, "login": null, "rule_hit": null, "case_linked": null, "note_added": null } ], "next_cursor": "eyJ0IjoiMjAyNi0xMC0xMlQxNjowMzoxMCswMDowMCIsImMiOiIyMDI2LTEwLTAxVDA5OjEyOjQ0KzAwOjAwIiwiciI6MSwidSI6IjhkN2M2YjVhLTRlM2YtNGEyYi05YzFkLTBlOWY4YTdiNmM1ZCJ9" } } } } } }, "400": { "description": "Com `contract` presente: um valor inválido de `contract`, `limit`, `cursor` ou `event_type`.", "content": { "application/json": { "examples": { "Unsupported contract": { "summary": "Contrato não suportado", "value": { "contract": [ "\"3\" is not a valid choice." ] } }, "Invalid cursor": { "summary": "Cursor inválido", "value": { "cursor": [ "This cursor is not valid. Reload the feed." ] } }, "Limit too large": { "summary": "Limite demasiado grande", "value": { "limit": [ "Ensure this value is less than or equal to 500." ] } }, "Unknown event type": { "summary": "Tipo de evento desconhecido", "value": { "event_type": { "0": [ "\"logout\" is not a valid choice." ] } } } } } } }, "401": { "description": "Credenciais em falta ou inválidas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenciais em falta ou inválidas", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "A chave de API pertence a outra aplicação ou é uma chave com acesso restrito: os endpoints de Networks necessitam de uma chave de acesso total. Um token de membro da consola necessita de `read:networks`. Também é devolvido com `code: networks_not_entitled` quando o Networks não está ativado para a organização.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Redes não ativadas", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chave de API restrita", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Sem permissão", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Rede não encontrada (ou não visível para esta aplicação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/map/": { "get": { "summary": "Obter mapa de rede", "description": "Pontos geográficos onde os endereços/localizações dos membros desta rede convergem, obtidos a partir das sessões, sessões de empresa e transações que sustentam as suas adesões.", "operationId": "get_network_map", "x-didit-sdk": { "resource": "networks", "method": "retrieve_map", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID da rede." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/map/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_map(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveMap(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveMap(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveMap(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveMap('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_map(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveMapAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Mapa da rede.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkMap" } } } }, "404": { "description": "Rede não encontrada (ou não visível para esta aplicação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/sessions/{session_id}/networks/": { "get": { "summary": "Listar redes de uma sessão", "description": "Listar as redes a que o utilizador do fornecedor da sessão pertence. É resolvido através do utilizador associado a vendor_data da sessão.", "operationId": "list_session_network_memberships", "x-didit-sdk": { "resource": "sessions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da sessão." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/sessions/aaaaaaaa-0000-4000-8000-000000000001/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.sessions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.sessions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Redes a que esta entidade pertence. Não paginado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entidade não encontrada nesta aplicação, ou não tem nenhum sujeito associado para consultar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/business-sessions/{business_session_id}/networks/": { "get": { "summary": "Listar redes de uma sessão de empresa", "description": "Listar as redes a que a empresa do fornecedor da sessão de empresa pertence.", "operationId": "list_business_session_network_memberships", "x-didit-sdk": { "resource": "business_sessions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "business_session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da sessão da empresa." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/business-sessions/aaaaaaaa-0000-4000-8000-000000000002/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.business_sessions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businessSessions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.BusinessSessions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businessSessions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businessSessions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.business_sessions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.BusinessSessions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Redes a que esta entidade pertence. Não paginado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entidade não encontrada nesta aplicação, ou não tem nenhum sujeito associado para consultar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/users/{vendor_user_uuid}/networks/": { "get": { "summary": "Listar redes de um utilizador", "description": "Listar as redes a que um utilizador do fornecedor pertence.", "operationId": "list_user_network_memberships", "x-didit-sdk": { "resource": "users", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "vendor_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID do utilizador do fornecedor." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/users/aaaaaaaa-0000-4000-8000-000000000003/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Redes a que esta entidade pertence. Não paginado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entidade não encontrada nesta aplicação, ou não tem nenhum sujeito associado para consultar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/{vendor_business_uuid}/networks/": { "get": { "summary": "Listar redes de uma empresa", "description": "Listar as redes a que uma empresa do fornecedor pertence.", "operationId": "list_business_network_memberships", "x-didit-sdk": { "resource": "businesses", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "vendor_business_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da empresa do fornecedor." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/businesses/aaaaaaaa-0000-4000-8000-000000000004/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Redes a que esta entidade pertence. Não paginado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entidade não encontrada nesta aplicação, ou não tem nenhum sujeito associado para consultar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/networks/": { "get": { "summary": "Listar redes de uma transação", "description": "Listar as redes a que o sujeito de KYC/KYB subjacente à transação pertence (resolvidas através da sessão ou sessão de empresa da transação).", "operationId": "list_transaction_network_memberships", "x-didit-sdk": { "resource": "transactions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "transaction_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da transação." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/aaaaaaaa-0000-4000-8000-000000000005/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.transactions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.transactions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.transactions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.transactions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Redes a que esta entidade pertence. Não paginado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entidade não encontrada nesta aplicação, ou não tem nenhum sujeito associado para consultar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/parties/{transaction_party_uuid}/networks/": { "get": { "summary": "Listar redes de uma parte da transação", "description": "Listar as redes a que uma parte da transação (ordenante, beneficiário ou contraparte) pertence, resolvidas através da própria parte e não através da sessão subjacente à transação.", "operationId": "list_transaction_party_network_memberships", "x-didit-sdk": { "resource": "transactions", "method": "list_party_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "transaction_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da transação." }, { "name": "transaction_party_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da parte da transação." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/aaaaaaaa-0000-4000-8000-000000000005/parties/bbbbbbbb-0000-4000-8000-000000000006/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.transactions.list_party_networks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.transactions.listPartyNetworks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.ListPartyNetworks(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.transactions().listPartyNetworks(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->listPartyNetworks('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.transactions.list_party_networks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.ListPartyNetworksAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Redes a que esta entidade pertence. Não paginado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entidade não encontrada nesta aplicação, ou não tem nenhum sujeito associado para consultar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/biometric-templates/": { "get": { "summary": "Listar templates biométricos retidos", "description": "Uma aplicação que tenha ativado a funcionalidade mantém um template biométrico facial sem imagens, gerido separadamente e associado ao Utilizador quando uma sessão é eliminada (consulte `DELETE /v3/session/{sessionId}/delete/`). Os templates são dados biométricos com um `expires_at` finito; nunca contêm imagens, dados da sessão ou campos de identidade, e são eliminados permanentemente após a eliminação do Utilizador, eliminação por privacidade, expiração ou uma eliminação permanente explícita. Estes endpoints aceitam apenas chaves de API da aplicação (`x-api-key`); os tokens de utilizador da Business Console são rejeitados com `403`.\n\nDevolve uma lista paginada dos templates que a aplicação detém atualmente. Os templates purgados não são listados.", "operationId": "list_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "vendor_data", "required": false, "description": "Correspondência de subcadeia insensível a maiúsculas/minúsculas no `vendor_data` atual do utilizador titular.", "schema": { "type": "string" } }, { "in": "query", "name": "vendor_user_uuid", "required": false, "description": "Correspondência exata no Utilizador proprietário.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "required": false, "description": "Estado do ciclo de vida. Modelos eliminados nunca são listados.", "schema": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ] } }, { "in": "query", "name": "source_type", "required": false, "description": "Como o modelo foi criado.", "schema": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ] } }, { "in": "query", "name": "retained_from", "required": false, "description": "Modelos conservados nesta data/hora ou após a mesma.", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "retained_to", "required": false, "description": "Modelos conservados nesta data/hora ou antes da mesma. Não pode ser anterior a `retained_from` (`400`).", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "ordering", "required": false, "description": "Ordem de ordenação.", "schema": { "type": "string", "enum": [ "retained_at", "-retained_at", "expires_at", "-expires_at" ], "default": "-retained_at" } }, { "in": "query", "name": "limit", "required": false, "description": "Tamanho da página.", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "description": "Offset de paginação.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Modelos paginados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID do modelo. Gerado aleatoriamente; não derivado da sessão eliminada nem do respetivo rosto." }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "O utilizador titular." }, "vendor_data": { "type": "string", "nullable": true, "description": "Os `vendor_data` atuais do utilizador, resolvidos quando lê o modelo (nunca copiados)." }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "Como o modelo foi criado: uma eliminação de sessão (API ou Console), a janela automática de conservação de dados da aplicação ou um preenchimento retroativo operado pela Didit que tenha solicitado." }, "provenance_reference": { "type": "string", "format": "uuid", "description": "Referência opaca que associa o modelo ao seu registo de auditoria. Não é o id da sessão eliminada e não pode ser resolvido para o mesmo." }, "retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "A política da aplicação no momento da conservação." }, "retention_override": { "type": "boolean", "nullable": true, "description": "O valor de `retain_face_embeddings` enviado na eliminação, ou `null` quando a política foi aplicada." }, "retained_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando o modelo expira e é eliminado automaticamente. Sempre definido." }, "retained_by": { "type": "string", "nullable": true, "description": "Identidade principal que deu a instrução: o id da aplicação para chaves de API, o id do membro da consola para ações na consola ou um identificador `service:` para retenção automática. Nunca um endereço de e-mail." }, "retained_by_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ] }, "instruction_class": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ] }, "instruction_source": { "type": "string", "enum": [ "api", "console", "automatic_retention", "backfill", "privacy_erasure", "explicit_template_purge", "vendor_user_delete", "expiry", "reconciliation", "migration", "system" ] }, "instruction_id": { "type": "string", "description": "O `instruction_id` enviado na eliminação, ou um id gerado pela Didit." }, "held_out_of_use": { "type": "boolean", "description": "`true` apenas enquanto for aplicável uma retenção legal. Um modelo retido é excluído de todas as correspondências." }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed", "purged" ], "description": "Apenas os modelos `active` que não estejam retidos, que não tenham ultrapassado `expires_at` e cujo Utilizador ainda exista participam na correspondência." }, "purged_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "examples": { "One active template": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "vendor_data": "user-42", "source_type": "session_delete", "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f", "retention_policy": "retain_until_user_deleted", "retention_override": null, "retained_at": "2026-08-28T10:15:42.318402Z", "expires_at": "2027-08-28T10:15:42.318402Z", "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e", "retained_by_type": "API_KEY", "instruction_class": "operational_session_delete", "instruction_source": "api", "instruction_id": "post-approval-cleanup-2026-08", "held_out_of_use": false, "status": "active", "purged_at": null } ] } } } } } }, "400": { "description": "Valor de filtro inválido ou `retained_to` anterior a `retained_from`. Erros de validação organizados por campo.", "content": { "application/json": { "examples": { "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Token de utilizador da consola, ou a chave de API não é permitida. Estes endpoints aceitam apenas chaves de API de aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/biometric-templates/?vendor_data=user-42&status=active' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.biometric_templates.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.biometricTemplates.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.BiometricTemplates.ListAutoPaging(ctx, didit.BiometricTemplatesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.biometricTemplates().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.biometric_templates.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.BiometricTemplates.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/biometric-templates/count/": { "get": { "summary": "Contar templates biométricos retidos", "description": "Uma aplicação que tenha ativado a funcionalidade mantém um template biométrico facial sem imagens, gerido separadamente e associado ao Utilizador quando uma sessão é eliminada (consulte `DELETE /v3/session/{sessionId}/delete/`). Os templates são dados biométricos com um `expires_at` finito; nunca contêm imagens, dados da sessão ou campos de identidade, e são eliminados permanentemente após a eliminação do Utilizador, eliminação por privacidade, expiração ou uma eliminação permanente explícita. Estes endpoints aceitam apenas chaves de API da aplicação (`x-api-key`); os tokens de utilizador da Business Console são rejeitados com `403`.\n\nDevolve o número de templates que correspondem aos mesmos filtros do endpoint de listagem. Utilize-o para verificar o que uma eliminação permanente em massa filtrada com `delete_all: true` iria afetar.", "operationId": "count_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "count", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "vendor_data", "required": false, "description": "Correspondência de subcadeia insensível a maiúsculas/minúsculas no `vendor_data` atual do utilizador titular.", "schema": { "type": "string" } }, { "in": "query", "name": "vendor_user_uuid", "required": false, "description": "Correspondência exata no Utilizador proprietário.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "required": false, "description": "Estado do ciclo de vida. Modelos eliminados nunca são listados.", "schema": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ] } }, { "in": "query", "name": "source_type", "required": false, "description": "Como o modelo foi criado.", "schema": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ] } }, { "in": "query", "name": "retained_from", "required": false, "description": "Modelos conservados nesta data/hora ou após a mesma.", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "retained_to", "required": false, "description": "Modelos conservados nesta data/hora ou antes da mesma. Não pode ser anterior a `retained_from` (`400`).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Contagem.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } } }, "examples": { "Count": { "value": { "count": 128 } } } } } }, "400": { "description": "Valor de filtro inválido ou `retained_to` anterior a `retained_from`. Erros de validação organizados por campo.", "content": { "application/json": { "examples": { "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Token de utilizador da consola, ou a chave de API não é permitida. Estes endpoints aceitam apenas chaves de API de aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/biometric-templates/count/?status=active' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.count()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.count();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Count(ctx, didit.BiometricTemplatesCountParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().count();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->count();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.count\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.CountAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/biometric-templates/{template_uuid}/": { "get": { "summary": "Obter template biométrico retido", "description": "Uma aplicação que tenha ativado a funcionalidade mantém um template biométrico facial sem imagens, gerido separadamente e associado ao Utilizador quando uma sessão é eliminada (consulte `DELETE /v3/session/{sessionId}/delete/`). Os templates são dados biométricos com um `expires_at` finito; nunca contêm imagens, dados da sessão ou campos de identidade, e são eliminados permanentemente após a eliminação do Utilizador, eliminação por privacidade, expiração ou uma eliminação permanente explícita. Estes endpoints aceitam apenas chaves de API da aplicação (`x-api-key`); os tokens de utilizador da Business Console são rejeitados com `403`.\n\nDevolve um template. A resposta nunca inclui uma imagem, um vetor, o ID da sessão eliminada ou dados de identidade.", "operationId": "get_biometric_template", "x-didit-sdk": { "resource": "biometric_templates", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "template_uuid", "required": true, "description": "ID do modelo, tal como devolvido em `biometric_template_uuid` pelos endpoints de eliminação de sessão, `biometric_template_id` numa correspondência da Pesquisa facial, ou pelo endpoint de listagem.", "schema": { "type": "string", "format": "uuid", "example": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b" } } ], "responses": { "200": { "description": "O modelo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID do modelo. Gerado aleatoriamente; não derivado da sessão eliminada nem do respetivo rosto." }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "O utilizador titular." }, "vendor_data": { "type": "string", "nullable": true, "description": "Os `vendor_data` atuais do utilizador, resolvidos quando lê o modelo (nunca copiados)." }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "Como o modelo foi criado: uma eliminação de sessão (API ou Console), a janela automática de conservação de dados da aplicação ou um preenchimento retroativo operado pela Didit que tenha solicitado." }, "provenance_reference": { "type": "string", "format": "uuid", "description": "Referência opaca que associa o modelo ao seu registo de auditoria. Não é o id da sessão eliminada e não pode ser resolvido para o mesmo." }, "retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "A política da aplicação no momento da conservação." }, "retention_override": { "type": "boolean", "nullable": true, "description": "O valor de `retain_face_embeddings` enviado na eliminação, ou `null` quando a política foi aplicada." }, "retained_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando o modelo expira e é eliminado automaticamente. Sempre definido." }, "retained_by": { "type": "string", "nullable": true, "description": "Identidade principal que deu a instrução: o id da aplicação para chaves de API, o id do membro da consola para ações na consola ou um identificador `service:` para retenção automática. Nunca um endereço de e-mail." }, "retained_by_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ] }, "instruction_class": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ] }, "instruction_source": { "type": "string", "enum": [ "api", "console", "automatic_retention", "backfill", "privacy_erasure", "explicit_template_purge", "vendor_user_delete", "expiry", "reconciliation", "migration", "system" ] }, "instruction_id": { "type": "string", "description": "O `instruction_id` enviado na eliminação, ou um id gerado pela Didit." }, "held_out_of_use": { "type": "boolean", "description": "`true` apenas enquanto for aplicável uma retenção legal. Um modelo retido é excluído de todas as correspondências." }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed", "purged" ], "description": "Apenas os modelos `active` que não estejam retidos, que não tenham ultrapassado `expires_at` e cujo Utilizador ainda exista participam na correspondência." }, "purged_at": { "type": "string", "format": "date-time", "nullable": true } } }, "examples": { "Active template": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "vendor_data": "user-42", "source_type": "session_delete", "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f", "retention_policy": "retain_until_user_deleted", "retention_override": null, "retained_at": "2026-08-28T10:15:42.318402Z", "expires_at": "2027-08-28T10:15:42.318402Z", "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e", "retained_by_type": "API_KEY", "instruction_class": "operational_session_delete", "instruction_source": "api", "instruction_id": "post-approval-cleanup-2026-08", "held_out_of_use": false, "status": "active", "purged_at": null } } } } } }, "403": { "description": "Token de utilizador da consola, ou a chave de API não é permitida. Estes endpoints aceitam apenas chaves de API de aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Modelo desconhecido, um modelo de outra aplicação ou (no `GET`) um modelo eliminado.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Biometric template not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/biometric-templates/9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.retrieve(\n \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Retrieve(ctx, \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->retrieve('9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.RetrieveAsync(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Purgar um template biométrico conservado", "description": "Uma aplicação que tenha ativado a funcionalidade mantém um template biométrico facial sem imagens, gerido separadamente e associado ao Utilizador quando uma sessão é eliminada (consulte `DELETE /v3/session/{sessionId}/delete/`). Os templates são dados biométricos com um `expires_at` finito; nunca contêm imagens, dados da sessão ou campos de identidade, e são eliminados permanentemente após a eliminação do Utilizador, eliminação por privacidade, expiração ou uma eliminação permanente explícita. Estes endpoints aceitam apenas chaves de API da aplicação (`x-api-key`); os tokens de utilizador da Business Console são rejeitados com `403`.\n\nElimina permanentemente um template: é removido de todos os tipos de correspondência e o template armazenado é eliminado. Irreversível e registado no registo de auditoria com a entidade responsável.\n\n**Semântica de nova tentativa:** A Didit elimina primeiro o template armazenado e só depois marca o template como purgado. Se um armazenamento biométrico estiver indisponível, a chamada devolve `503`, o template passa para `status: purge_failed` e já fica excluído da correspondência; repita a mesma chamada para concluir. Repetir uma eliminação permanente de um template já purgado devolve `already_purged`.\n\nOs templates também são eliminados permanentemente através de `POST /v3/users/delete/` para o Utilizador proprietário, por qualquer eliminação das sessões desse Utilizador com `deletion_instruction: privacy_erasure`, e automaticamente em `expires_at`.", "operationId": "purge_biometric_template", "x-didit-sdk": { "resource": "biometric_templates", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "template_uuid", "required": true, "description": "ID do modelo, tal como devolvido em `biometric_template_uuid` pelos endpoints de eliminação de sessão, `biometric_template_id` numa correspondência da Pesquisa facial, ou pelo endpoint de listagem.", "schema": { "type": "string", "format": "uuid", "example": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b" } } ], "responses": { "200": { "description": "Resultado da purga.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "purged", "already_purged" ] } } }, "examples": { "Purged": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "purged" } }, "Already purged": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "already_purged" } } } } } }, "403": { "description": "Token de utilizador da consola, ou a chave de API não é permitida. Estes endpoints aceitam apenas chaves de API de aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Modelo desconhecido, um modelo de outra aplicação ou (no `GET`) um modelo eliminado.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Biometric template not found." } } } } } }, "503": { "description": "Um armazenamento biométrico estava indisponível durante a retenção ou eliminação de um template biométrico. Nada é eliminado; repita o mesmo pedido. As novas tentativas são idempotentes e convergem para um único modelo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/biometric-templates/9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.delete(\n \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Delete(ctx, \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->delete('9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.DeleteAsync(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/biometric-templates/delete/": { "post": { "summary": "Eliminar em massa templates biométricos retidos", "description": "Uma aplicação que tenha aderido mantém um template biométrico facial sem imagem, gerido separadamente e associado ao Utilizador quando uma sessão é eliminada (consulte `DELETE /v3/session/{sessionId}/delete/`). Os templates biométricos são dados biométricos com um `expires_at` finito; nunca contêm imagens, dados da sessão ou campos de identidade, e são purgados aquando da eliminação do Utilizador, apagamento por motivos de privacidade, expiração ou uma purga explícita. Estes endpoints aceitam apenas chaves de API da aplicação (`x-api-key`); os tokens de utilizador da Business Console são rejeitados com `403`.\n\nPurga vários templates numa única chamada, por lista explícita de id ou com `delete_all: true` opcionalmente restringido pelos mesmos filtros que o endpoint de listagem. Os templates são purgados um a um e cada resultado reporta `purged` ou `already_purged`. Se um armazenamento biométrico estiver indisponível, a chamada devolve `503` no primeiro template com falha: os templates purgados anteriormente no pedido permanecem purgados, o que falhou passa para `purge_failed` (já excluído da correspondência) e repetir o pedido conclui a operação.\n\n**`delete_all: true` sem filtros purga todos os templates biométricos na aplicação e não pode ser anulado.** Execute primeiro o endpoint de contagem com os mesmos filtros.", "operationId": "bulk_purge_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Modelos a eliminar definitivamente. Obrigatório, exceto se `delete_all` for `true`. Os IDs já eliminados são reportados como `already_purged`." }, "delete_all": { "type": "boolean", "default": false, "description": "Quando `true`, purga todos os modelos correspondentes aos filtros abaixo (todos os modelos da aplicação quando nenhum filtro é fornecido). `template_uuids` é ignorado. Irreversível." }, "vendor_data": { "type": "string", "description": "Apenas com `delete_all`: correspondência de substring sem distinção entre maiúsculas e minúsculas no `vendor_data` do utilizador proprietário." }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "Apenas com `delete_all`: correspondência exata no utilizador proprietário." }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ], "description": "Apenas com `delete_all`." }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "Apenas com `delete_all`." }, "retained_from": { "type": "string", "format": "date-time", "description": "Apenas com `delete_all`." }, "retained_to": { "type": "string", "format": "date-time", "description": "Apenas com `delete_all`. Não pode ser anterior a `retained_from`." } } }, "examples": { "By id": { "value": { "template_uuids": [ "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" ] } }, "Every template of one User": { "value": { "delete_all": true, "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f" } }, "Every template in the application": { "value": { "delete_all": true } } } } } }, "responses": { "200": { "description": "Resultados de eliminação por modelo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "purged", "already_purged" ] } } } } } }, "examples": { "Mixed": { "value": { "results": [ { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "purged" }, { "uuid": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "outcome": "already_purged" } ] } } } } } }, "400": { "description": "Erro de validação — nada é purgado.", "content": { "application/json": { "examples": { "Missing selector": { "value": { "template_uuids": [ "This field is required unless delete_all is true." ] } }, "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Token de utilizador da consola, ou a chave de API não é permitida. Estes endpoints aceitam apenas chaves de API de aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "503": { "description": "Um armazenamento biométrico estava indisponível durante a retenção ou eliminação de um template biométrico. Nada é eliminado; repita o mesmo pedido. As novas tentativas são idempotentes e convergem para um único modelo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/biometric-templates/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"delete_all\": true, \"vendor_user_uuid\": \"2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.batch_delete(\n template_uuids=[\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.batchDelete({\n template_uuids: [\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.BatchDelete(ctx, didit.BiometricTemplatesBatchDeleteParams{\n\tTemplateUUIDs: didit.Some([]string{\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BiometricTemplatesBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().batchDelete(BiometricTemplatesBatchDeleteParams.builder()\n .templateUuids(List.of(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->batchDelete([\n 'template_uuids' => ['9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b', '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.batch_delete(template_uuids: [\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.BatchDeleteAsync(new BiometricTemplatesBatchDeleteParams\n{\n TemplateUuids = new string[] { \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/kyb/shareholders/": { "post": { "summary": "Empresa no registo KYB com acionistas (autónoma)", "operationId": "post_v3_kyb_shareholders", "x-didit-sdk": { "resource": "kyb", "method": "list_shareholders", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Obtenha o perfil Lite **mais os acionistas diretos** (pessoas singulares e entidades coletivas, com os seus escalões de propriedade) de um candidato devolvido por `POST /v3/kyb/search/`.\n\n**Emparelhamento com a pesquisa.** Transmita o `kyb_response_id` do candidato exatamente como devolvido por uma pesquisa da mesma aplicação. Pesquise no nível que pretende comprar (`tier` em `POST /v3/kyb/search/`), pois a pesquisa é executada na cadeia de registos que serve esse nível e uma pesquisa Lite vazia não constitui prova de que o registo não tem a empresa registada. Quando os dados de propriedade do país residem noutro registo, a Didit volta a localizar a empresa nesse registo através do número de registo, sem custos adicionais.\n\n**Faturação.** É faturado ao preço de Acionistas aplicável no país - consulte os [preços do registo KYB](/pt/getting-started/kyb-registry-pricing). Quando o registo não contiver nenhum registo de acionistas para a empresa (ou o país não disponibilizar de todo dados de propriedade), o perfil Lite é entregue e faturado em alternativa: leia `registry_tier_delivered` e `registry_ownership_status`. O saldo é verificado em relação ao preço de Acionistas antes de qualquer chamada ao registo (`403` em caso de saldo insuficiente).\n\n**Disponibilidade.** Apenas v3. Cada chamada cria uma sessão de empresa (o seu id é o `request_id`).\n\n**Relatórios pendentes.** Quando um relatório ainda está a ser preparado, ou a secção de propriedade ainda não foi obtida do registo, o endpoint devolve 202 Accepted, kyb_registry.fetch_status=pending, kyb_registry.registry_ownership_status=pending e registry_tier_delivered=null. Guarde o request_id e consulte GET /v3/session/{request_id}/decision/ até que registry_checks[0].company.fetch_status esteja resolvido. A Didit conclui o relatório automaticamente e debita o nível entregue assim que estiver pronto. Não repita a compra enquanto estiver pendente; cada novo POST cria um pedido em separado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/shareholders/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.list_shareholders(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.listShareholders({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListShareholders(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().listShareholders(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->listShareholders([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.list_shareholders(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.ListShareholdersAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Relatório da empresa devolvido e faturado no nível entregue. Relatórios de propriedade ainda em preparação podem devolver 202; guarde o request_id para obter a decisão guardada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão de empresa criada para esta consulta. O registo guardado (visível na consola) continua a ser atualizado se a consulta ao registo for concluída após a resposta." }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "O nível que este endpoint comercializa: `basic` (Lite) para select, `shareholders`, `ubo`." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "O nível efetivamente entregue e faturado. Inferior ao solicitado quando os registos do país não contêm dados de propriedade ou quando o registo não tem qualquer registo de propriedade para esta empresa.", "nullable": true }, "kyb_registry": { "type": "object", "description": "Perfil completo da empresa no registo de empresas.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID da Didit para este registo de empresa." }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Avaliação da Didit sobre a verificação do registo (por exemplo, `In Review` quando a empresa não está ativa no registo ou não foi possível obter os dados de propriedade)." }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off", null ], "description": "Estado normalizado da empresa conforme reportado pelo registo de empresas." }, "data_resolved": { "type": "boolean", "description": "`true` assim que o registo tiver devolvido o perfil completo. `false` quando o registo ainda estava a processar após o polling — o registo guardado é concluído automaticamente assim que o registo ficar resolvido." }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alfa-2.", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "Código de subdivisão quando o registo é regional (p. ex., `CA` para `US-CA`); vazio caso contrário." }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "Nível de risco reportado pelo registo de empresas, quando disponível." }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "Estado de verificação entre jurisdições: `verified` quando o estado do registo estabelece a regularidade da situação (`active`), `failed` quando indica que a empresa já não está em atividade (por exemplo `dissolved`), caso contrário `unknown`. `null` para uma empresa que não provenha de um registo e enquanto uma seleção estiver ainda `pending`." }, "is_from_registry": { "type": "boolean", "description": "Sempre `true` para este endpoint — o perfil foi obtido a partir de um registo oficial." }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "Ciclo de vida de obtenção do registo de empresas. Espelhado por `data_resolved`." }, "alternative_names": { "type": "string", "nullable": true, "description": "Nomes alternativos, comerciais, anteriores ou no idioma original da empresa em texto, quando comunicados." }, "nature_of_business": { "type": "string", "nullable": true, "description": "Descrição da atividade ou código de classificação, quando comunicado." }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "Montante decimal como string, quando reportado." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Código ISO 4217, quando comunicado." }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI, quando comunicado." }, "location_of_registration": { "type": "string", "nullable": true, "description": "Registo de empresas/jurisdição onde a empresa está registada, quando reportado." }, "vat_number": { "type": "string", "nullable": true, "description": "Número de IVA da UE, quando recolhido durante o passo de registo alojado ou editado posteriormente. No momento da seleção, normalmente ainda não está definido — a validação de IVA e do número de identificação fiscal é executada quando o utilizador final envia o passo de registo no fluxo alojado." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Resultado da validação do número de IVA ou, quando inexistente, do `tax_number`, no envio do registo. `valid` / `invalid`: decidido pelo registo oficial do país (VIES da UE, Noruega, Suíça, Brasil, Colômbia, Costa Rica, Equador, Paraguai; Polónia também pelo seu registo doméstico de IVA). `format_valid` / `invalid_format`: decidido pelas regras de formato e de dígito de controlo do país quando nenhum registo pode ser consultado. `could_not_validate`: o registo estava indisponível. `not_applicable`: sem número, um país sem registo ou regras, ou uma sessão de sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "O número que foi verificado, tal como a fonte o conhece (por exemplo, o número de IVA derivado de um SIREN francês ou de um RSIN neerlandês). `null` quando nenhuma verificação foi executada." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "A origem que determinou o `vat_validation_status`: um registo oficial ou `format_rules`. `null` quando nenhuma verificação foi executada." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registado na fonte que validou o número, quando esta o divulga. Apenas definido quando o estado for `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Morada registada junto da fonte que validou o número, quando esta a divulga. Apenas definida quando o estado é `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da verificação. `null` quando nenhuma verificação foi executada." }, "financial_summary": { "type": "object", "nullable": true, "description": "Detalhes das ações/capital reportados pelo registo de empresas (moeda, total de ações, classes de ações), quando disponíveis." }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "Designação no registo em bruto (por ex., `Director`, `Secretary`)." }, "role": { "type": "string", "description": "Função normalizada derivada da designação. Conjunto completo de 17 valores do modelo; a análise do registo de empresas neste endpoint emite tipicamente director, non_executive_director, secretary, chairman ou company_officer.", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "`false` quando o registo marca a nomeação como tendo cessado." }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ], "description": "Estado de uma sessão KYC associada, caso tenha sido iniciada uma para este administrador. Caso contrário, `null`." }, "kyc_session_url": { "type": "string", "nullable": true, "description": "URL de verificação da sessão de KYC associada, quando existir." }, "first_name": { "type": "string", "nullable": true, "description": "Nome próprio quando explicitamente indicado pelo registo; não deduzido a partir do nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Apelido quando explicitamente comunicado pelo registo." }, "address": { "type": "string", "nullable": true, "description": "Morada do administrador indicada pelo registo." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data em que o administrador foi nomeado.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data em que a nomeação terminou, quando reportada.", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa comunicada pelo registo de empresas. Nulo quando apenas o ano ou mês de nascimento é conhecido.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Ano de nascimento reportado pelo registo de empresas, incluindo quando a data completa não está disponível." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mês de nascimento reportado pelo registo de empresas. Nulo quando apenas o ano é conhecido." } } }, "description": "Administradores, secretários e outros responsáveis extraídos do registo." }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se o proprietário é uma pessoa singular ou uma entidade coletiva." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Funções normalizadas (por exemplo, `ubo`, `shareholder`)." }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferior da faixa de propriedade reportada pelo registo (por exemplo, `25%`)." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superior do intervalo de propriedade reportado pelo registo." }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem de propriedade analisada (limite máximo, recorrendo ao limite mínimo como alternativa)." }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa quando comunicada.", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "Data de nomeação quando comunicada.", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "Beneficiários efetivos / pessoas com controlo significativo extraídos do registo. Pode estar vazio quando o registo não divulga a propriedade." }, "addresses": { "type": "array", "nullable": true, "description": "Todas as moradas indicadas pelo registo, num formato canónico. Nulo quando este não indicar nenhuma.", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "As atividades sob as quais o registo classifica a empresa, num formato canónico. Null quando não indica nenhuma.", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Datas de submissão no registo de empresas, quando disponíveis. As declarações anuais e assembleias gerais utilizam last_annual_return_date e last_agm_date; são distintas das contas financeiras." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "Sempre `null` neste endpoint (utilizado pelo fluxo alojado de KYB quando os utilizadores finais editam dados do registo)." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Sempre `null` neste endpoint." }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Definido quando um revisor da consola edita o registo posteriormente." }, "is_editable": { "type": "boolean", "description": "Se os dados provenientes do registo ainda podem ser editados no fluxo alojado/consola." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "Igual ao `registry_tier_delivered` de nível superior.", "nullable": true }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable", "pending", null ], "description": "`delivered` quando os dados de propriedade foram devolvidos, `not_held` quando o registo de propriedade respondeu e não lista esta empresa (consulte `registry_data.ownership_error`), `unavailable` quando um nível de propriedade foi solicitado mas o registo não tinha nenhum para esta empresa ou não pôde ser consultado (consulte `registry_data.ownership_error`), `pending` quando a secção de propriedade ainda não foi obtida do registo e a Didit ainda a está a preencher, `not_requested` no nível Lite." }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "O nível de registo encomendado pelo fluxo: `basic`, `shareholders` ou `ubo`. Também em `ownership.tier_requested`." }, "registry_monitoring": { "type": "object", "nullable": true, "description": "A monitorização mais recente do registo para a empresa, ou `null` quando não existir nenhuma.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "Os campos da empresa que o monitor acompanha." } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou." }, "metadata": { "type": "object", "nullable": true, "description": "Eco do objeto `metadata` que enviou." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "Perfil completo do registo de empresas (lista de administradores truncada para brevidade)", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "Erro de validação. Problemas ao nível do campo utilizam o envelope padrão do DRF.", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` é obrigatório", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "As seleções são sempre persistidas", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer triagem ou chamada ao fornecedor ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "202": { "description": "Relatório aceite e ainda em processamento. Quando um relatório ainda está a ser preparado, o endpoint devolve 202 Accepted, kyb_registry.fetch_status=pending e registry_tier_delivered=null. Guarde o request_id e consulte GET /v3/session/{request_id}/decision/ até que registry_checks[0].company.fetch_status seja resolvido. A Didit conclui o relatório automaticamente e debita o nível entregue assim que estiver pronto. Não repita a compra enquanto estiver pendente; cada novo POST cria um pedido separado.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1kyb~1shareholders~1/post/responses/200/content/application~1json/schema" }, "examples": { "Pending (registry still resolving)": { "summary": "O relatório de propriedade ainda está a ser processado; obter a decisão guardada", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Example Holdings Limited", "registration_number": "12345678", "country_code": "HK", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true, "registry_tier_delivered": null, "registry_ownership_status": "pending" }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00", "registry_tier_delivered": null, "registry_tier_requested": "shareholders" } } } } } } } } }, "/v3/kyb/ubo/": { "post": { "summary": "Empresa no registo KYB com beneficiários efetivos (autónoma)", "operationId": "post_v3_kyb_ubo", "x-didit-sdk": { "resource": "kyb", "method": "list_ubos", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Obtenha o perfil Lite, os acionistas diretos **e os beneficiários efetivos** resolvidos através da cadeia de propriedade (`registry_data.ubo_resolution` contém a cadeia de empresas-mãe) de um candidato devolvido por `POST /v3/kyb/search/`.\n\n**Emparelhamento com a pesquisa.** Transmita o `kyb_response_id` do candidato exatamente como devolvido por uma pesquisa da mesma aplicação. Pesquise no nível que pretende comprar (`tier` em `POST /v3/kyb/search/`), pois a pesquisa é executada na cadeia de registos que serve esse nível e uma pesquisa Lite vazia não constitui prova de que o registo não possui a empresa. Quando os dados de propriedade do país residem noutro registo, a Didit volta a localizar a empresa nesse registo através do número de registo, sem custos adicionais.\n\n**Faturação.** É faturado ao preço de UBO do país - consulte os [preços do registo KYB](/pt/getting-started/kyb-registry-pricing). O nível entregue é o mais elevado que o país e o registo conseguem disponibilizar: Acionistas quando o relatório resolvido não indicar nenhuma pessoa singular como beneficiário efetivo, Lite quando não existir qualquer registo de propriedade; `registry_tier_delivered` indica o que foi faturado. O saldo é verificado em relação ao preço de UBO antes de qualquer chamada ao registo (`403` em caso de saldo insuficiente).\n\n**Disponibilidade.** Apenas v3. Cada chamada cria uma sessão de empresa (o seu id é o `request_id`).\n\n**Relatórios pendentes.** Quando um relatório ainda está a ser preparado, ou a secção de propriedade ainda não foi obtida do registo, o endpoint devolve 202 Accepted, kyb_registry.fetch_status=pending, kyb_registry.registry_ownership_status=pending e registry_tier_delivered=null. Guarde o request_id e consulte GET /v3/session/{request_id}/decision/ até que registry_checks[0].company.fetch_status esteja resolvido. A Didit conclui o relatório automaticamente e debita o nível entregue assim que estiver pronto. Não repita a compra enquanto estiver pendente; cada novo POST cria um pedido em separado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/ubo/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.list_ubos(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.listUbos({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListUBOs(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().listUbos(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->listUbos([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.list_ubos(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.ListUbosAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Relatório da empresa devolvido e faturado no nível entregue. Relatórios de propriedade ainda em preparação podem devolver 202; guarde o request_id para obter a decisão guardada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão de empresa criada para esta consulta. O registo guardado (visível na consola) continua a ser atualizado se a consulta ao registo for concluída após a resposta." }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "O nível que este endpoint comercializa: `basic` (Lite) para select, `shareholders`, `ubo`." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "O nível efetivamente entregue e faturado. Inferior ao solicitado quando os registos do país não contêm dados de propriedade, quando o registo não tem qualquer registo de propriedade para esta empresa ou quando o relatório resolvido de um pedido de `ubo` não identifica nenhuma pessoa singular como beneficiário efetivo.", "nullable": true }, "kyb_registry": { "type": "object", "description": "Perfil completo da empresa no registo de empresas.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID da Didit para este registo de empresa." }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Avaliação da Didit sobre a verificação do registo (por exemplo, `In Review` quando a empresa não está ativa no registo ou não foi possível obter os dados de propriedade)." }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off", null ], "description": "Estado normalizado da empresa conforme reportado pelo registo de empresas." }, "data_resolved": { "type": "boolean", "description": "`true` assim que o registo tiver devolvido o perfil completo. `false` quando o registo ainda estava a processar após o polling — o registo guardado é concluído automaticamente assim que o registo ficar resolvido." }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alfa-2.", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "Código de subdivisão quando o registo é regional (p. ex., `CA` para `US-CA`); vazio caso contrário." }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "Nível de risco reportado pelo registo de empresas, quando disponível." }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "Estado de verificação entre jurisdições: `verified` quando o estado do registo estabelece a regularidade da situação (`active`), `failed` quando indica que a empresa já não está em atividade (por exemplo `dissolved`), caso contrário `unknown`. `null` para uma empresa que não provenha de um registo e enquanto uma seleção estiver ainda `pending`." }, "is_from_registry": { "type": "boolean", "description": "Sempre `true` para este endpoint — o perfil foi obtido a partir de um registo oficial." }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "Ciclo de vida de obtenção do registo de empresas. Espelhado por `data_resolved`." }, "alternative_names": { "type": "string", "nullable": true, "description": "Nomes alternativos, comerciais, anteriores ou no idioma original da empresa em texto, quando comunicados." }, "nature_of_business": { "type": "string", "nullable": true, "description": "Descrição da atividade ou código de classificação, quando comunicado." }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "Montante decimal como string, quando reportado." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Código ISO 4217, quando comunicado." }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI, quando comunicado." }, "location_of_registration": { "type": "string", "nullable": true, "description": "Registo de empresas/jurisdição onde a empresa está registada, quando reportado." }, "vat_number": { "type": "string", "nullable": true, "description": "Número de IVA da UE, quando recolhido durante o passo de registo alojado ou editado posteriormente. No momento da seleção, normalmente ainda não está definido — a validação de IVA e do número de identificação fiscal é executada quando o utilizador final envia o passo de registo no fluxo alojado." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Resultado da validação do número de IVA ou, quando inexistente, do `tax_number`, no envio do registo. `valid` / `invalid`: decidido pelo registo oficial do país (VIES da UE, Noruega, Suíça, Brasil, Colômbia, Costa Rica, Equador, Paraguai; Polónia também pelo seu registo doméstico de IVA). `format_valid` / `invalid_format`: decidido pelas regras de formato e de dígito de controlo do país quando nenhum registo pode ser consultado. `could_not_validate`: o registo estava indisponível. `not_applicable`: sem número, um país sem registo ou regras, ou uma sessão de sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "O número que foi verificado, tal como a fonte o conhece (por exemplo, o número de IVA derivado de um SIREN francês ou de um RSIN neerlandês). `null` quando nenhuma verificação foi executada." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "A origem que determinou o `vat_validation_status`: um registo oficial ou `format_rules`. `null` quando nenhuma verificação foi executada." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registado na fonte que validou o número, quando esta o divulga. Apenas definido quando o estado for `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Morada registada junto da fonte que validou o número, quando esta a divulga. Apenas definida quando o estado é `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da verificação. `null` quando nenhuma verificação foi executada." }, "financial_summary": { "type": "object", "nullable": true, "description": "Detalhes das ações/capital reportados pelo registo de empresas (moeda, total de ações, classes de ações), quando disponíveis." }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "Designação no registo em bruto (por ex., `Director`, `Secretary`)." }, "role": { "type": "string", "description": "Função normalizada derivada da designação. Conjunto completo de 17 valores do modelo; a análise do registo de empresas neste endpoint emite tipicamente director, non_executive_director, secretary, chairman ou company_officer.", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "`false` quando o registo marca a nomeação como tendo cessado." }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ], "description": "Estado de uma sessão KYC associada, caso tenha sido iniciada uma para este administrador. Caso contrário, `null`." }, "kyc_session_url": { "type": "string", "nullable": true, "description": "URL de verificação da sessão de KYC associada, quando existir." }, "first_name": { "type": "string", "nullable": true, "description": "Nome próprio quando explicitamente indicado pelo registo; não deduzido a partir do nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Apelido quando explicitamente comunicado pelo registo." }, "address": { "type": "string", "nullable": true, "description": "Morada do administrador indicada pelo registo." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data em que o administrador foi nomeado.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data em que a nomeação terminou, quando reportada.", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa comunicada pelo registo de empresas. Nulo quando apenas o ano ou mês de nascimento é conhecido.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Ano de nascimento reportado pelo registo de empresas, incluindo quando a data completa não está disponível." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mês de nascimento reportado pelo registo de empresas. Nulo quando apenas o ano é conhecido." } } }, "description": "Administradores, secretários e outros responsáveis extraídos do registo." }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se o proprietário é uma pessoa singular ou uma entidade coletiva." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Funções normalizadas (por exemplo, `ubo`, `shareholder`)." }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferior da faixa de propriedade reportada pelo registo (por exemplo, `25%`)." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superior do intervalo de propriedade reportado pelo registo." }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem de propriedade analisada (limite máximo, recorrendo ao limite mínimo como alternativa)." }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa quando comunicada.", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "Data de nomeação quando comunicada.", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "Beneficiários efetivos / pessoas com controlo significativo extraídos do registo. Pode estar vazio quando o registo não divulga a propriedade." }, "addresses": { "type": "array", "nullable": true, "description": "Todas as moradas indicadas pelo registo, num formato canónico. Nulo quando este não indicar nenhuma.", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "As atividades sob as quais o registo classifica a empresa, num formato canónico. Null quando não indica nenhuma.", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Datas de submissão no registo de empresas, quando disponíveis. As declarações anuais e assembleias gerais utilizam last_annual_return_date e last_agm_date; são distintas das contas financeiras." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "Sempre `null` neste endpoint (utilizado pelo fluxo alojado de KYB quando os utilizadores finais editam dados do registo)." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Sempre `null` neste endpoint." }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Definido quando um revisor da consola edita o registo posteriormente." }, "is_editable": { "type": "boolean", "description": "Se os dados provenientes do registo ainda podem ser editados no fluxo alojado/consola." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "Igual ao `registry_tier_delivered` de nível superior.", "nullable": true }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable", "pending", null ], "description": "`delivered` quando os dados de propriedade foram devolvidos, `not_held` quando o registo de propriedade respondeu e não lista esta empresa (consulte `registry_data.ownership_error`), `unavailable` quando um nível de propriedade foi solicitado mas o registo não tinha nenhum para esta empresa ou não pôde ser consultado (consulte `registry_data.ownership_error`), `pending` quando a secção de propriedade ainda não foi obtida do registo e a Didit ainda a está a preencher, `not_requested` no nível Lite." }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "O nível de registo encomendado pelo fluxo: `basic`, `shareholders` ou `ubo`. Também em `ownership.tier_requested`." }, "registry_monitoring": { "type": "object", "nullable": true, "description": "A monitorização mais recente do registo para a empresa, ou `null` quando não existir nenhuma.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "Os campos da empresa que o monitor acompanha." } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou." }, "metadata": { "type": "object", "nullable": true, "description": "Eco do objeto `metadata` que enviou." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "Perfil completo do registo de empresas (lista de administradores truncada para brevidade)", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": { "ubo_resolution": { "parent_chain": [], "subsidiaries": [], "unresolved": [] } }, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "Erro de validação. Problemas ao nível do campo utilizam o envelope padrão do DRF.", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` é obrigatório", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "As seleções são sempre persistidas", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } } } } } }, "403": { "description": "Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{\"detail\": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{\"error\": ...}` antes de qualquer triagem ou chamada ao fornecedor ocorrer.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre a chamada", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Mais de 300 pedidos de escrita no minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "202": { "description": "Relatório aceite e ainda em processamento. Quando um relatório ainda está a ser preparado, o endpoint devolve 202 Accepted, kyb_registry.fetch_status=pending e registry_tier_delivered=null. Guarde o request_id e consulte GET /v3/session/{request_id}/decision/ até que registry_checks[0].company.fetch_status seja resolvido. A Didit conclui o relatório automaticamente e debita o nível entregue assim que estiver pronto. Não repita a compra enquanto estiver pendente; cada novo POST cria um pedido separado.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1kyb~1ubo~1/post/responses/200/content/application~1json/schema" }, "examples": { "Pending (registry still resolving)": { "summary": "O relatório de propriedade ainda está a ser processado; obter a decisão guardada", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Example Holdings Limited", "registration_number": "12345678", "country_code": "HK", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true, "registry_tier_delivered": null, "registry_ownership_status": "pending" }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00", "registry_tier_delivered": null, "registry_tier_requested": "ubo" } } } } } } } } }, "/v3/id-verification/wallets/": { "get": { "operationId": "list_wallets", "x-didit-sdk": { "resource": "id_wallets", "method": "list", "auth": "api_key", "server": true }, "description": "Cada carteira Digital ID com o respetivo endpoint inicial, países, campos obrigatórios e se esta aplicação pode iniciá-la neste ambiente agora. Estar listada não significa que esteja ativa.", "summary": "Listar carteiras de Digital ID", "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletCatalogResponse" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenciais em falta (x-api-key ou Authorization: Bearer)." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request GET \\\n --url https://verification.didit.me/v3/id-verification/wallets/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.list()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.list();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.List(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().list();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->list();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.list\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.ListAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/": { "get": { "operationId": "get_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "retrieve_verification", "auth": "api_key", "server": true }, "description": "Estado e resultado de uma verificação de carteira: a identidade normalizada e os atributos próprios da carteira quando verificada, o código de erro quando recusada, a próxima ação enquanto pendente. Uma verificação após expires_at é concluída com o resultado timeout.", "summary": "Obter verificação de carteira", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "O request_id devolvido pelo endpoint de início.", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenciais em falta (x-api-key ou Authorization: Bearer)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro not_found: nenhuma verificação de carteira desta aplicação tem este request_id." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request GET \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.retrieve_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.retrieveVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.RetrieveVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().retrieveVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->retrieveVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.retrieve_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.RetrieveVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/poll/": { "post": { "operationId": "poll_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "poll_verification", "auth": "api_key", "server": true }, "description": "Smart-ID e Mobile-ID: pergunte ao fornecedor se o utilizador confirmou, recusou ou deixou o pedido expirar, e verifique a identidade assinada quando este confirmou. Carteiras de redirecionamento concluem o processo através do navegador do utilizador, pelo que para elas isto apenas lê a verificação. Devolve a verificação no seu estado posterior.", "summary": "Fazer polling de uma verificação de carteira", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "O request_id devolvido pelo endpoint de início.", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "smart_id", "name": "Smart-ID", "issuing_authority": "SK ID Solutions" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenciais em falta (x-api-key ou Authorization: Bearer)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro not_found: nenhuma verificação de carteira desta aplicação tem este request_id." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/poll/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.poll_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.pollVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.PollVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().pollVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->pollVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.poll_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.PollVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/cancel/": { "post": { "operationId": "cancel_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "cancel_verification", "auth": "api_key", "server": true }, "description": "Retirar uma verificação pendente: é recusada como cancelada e nunca faturada. Uma verificação já decidida é devolvida inalterada. Smart-ID e Mobile-ID: um cancelamento que chegue enquanto uma sondagem está a verificar o início de sessão aguarda alguns segundos por essa sondagem e, em seguida, recusa-a, ou devolve-a como verificada se o utilizador já tiver confirmado. Uma verificação que o utilizador esteja a concluir neste momento não pode ser cancelada (409 verification_in_progress com Retry-After): tente novamente após esse número de segundos para ler o respetivo resultado.", "summary": "Cancelar uma verificação de carteira", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "O request_id devolvido pelo endpoint de início.", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Declined", "outcome": "cancelled", "error": "cancelled_by_customer", "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": null, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenciais em falta (x-api-key ou Authorization: Bearer)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro not_found: nenhuma verificação de carteira desta aplicação tem este request_id." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro verification_in_progress: o utilizador está a concluir este início de sessão neste momento. O cabeçalho Retry-After indica quando tentar novamente; a nova tentativa devolve a verificação decidida." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/cancel/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.cancel_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.cancelVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.CancelVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().cancelVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->cancelVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.cancel_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.CancelVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/mitid/": { "post": { "operationId": "start_mitid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mitid", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com MitID (Danish Agency for Digital Government; DNK) sem qualquer fluxo. É faturado uma única vez, apenas quando a identidade for verificada. A resposta contém next_action.type=redirect com o URL para onde deve enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação MitID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" }, "example": { "country": "DNK", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mitid", "name": "MitID", "issuing_authority": "Danish Agency for Digital Government" }, "country": "DNK", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mitid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"DNK\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mitid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"DNK\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMitid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DNK\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMitid(ctx, didit.IDWalletsStartMitidParams{\n\tBody: didit.DigitalIDWalletAPIMitidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIMitidWalletVerificationStartCountryEnum(\"DNK\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiMitidWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiMitidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMitid(DigitalIdWalletApiMitidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiMitidWalletVerificationStartCountryEnum.of(\"DNK\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMitid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'DNK',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mitid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DNK\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMitidAsync(new DigitalIdWalletApiMitidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiMitidWalletVerificationStartCountryEnum(\"DNK\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mitid" } }, "/v3/id-verification/wallets/bankid-se/": { "post": { "operationId": "start_bankid_se_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_se", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com BankID (SWE) (Finansiell ID-Teknik / consórcio bancário; SWE) sem qualquer fluxo. Faturado uma vez, apenas quando a identidade é verificada. A resposta inclui next_action.type=redirect com o URL para onde enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação BankID (SWE)", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" }, "example": { "country": "SWE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_se", "name": "BankID", "issuing_authority": "Finansiell ID-Teknik / bank consortium" }, "country": "SWE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-se/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"SWE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_se(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"SWE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidSe({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidSe(ctx, didit.IDWalletsStartBankidSeParams{\n\tBody: didit.DigitalIDWalletAPIBankidSeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryEe9enum(\"SWE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidSeWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryEe9Enum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidSe(DigitalIdWalletApiBankidSeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryEe9Enum.of(\"SWE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidSe([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'SWE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_se(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidSeAsync(new DigitalIdWalletApiBankidSeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryEe9Enum(\"SWE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_se" } }, "/v3/id-verification/wallets/bankid-no/": { "post": { "operationId": "start_bankid_no_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_no", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com BankID (NOR) (BankID BankAxept AS; NOR) sem qualquer fluxo. É cobrado uma vez, apenas quando a identidade é verificada. A resposta inclui next_action.type=redirect com o URL para onde enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação BankID (NOR)", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_no", "name": "BankID", "issuing_authority": "BankID BankAxept AS" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-no/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_no(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidNo({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidNo(ctx, didit.IDWalletsStartBankidNoParams{\n\tBody: didit.DigitalIDWalletAPIBankidNoWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidNoWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidNo(DigitalIdWalletApiBankidNoWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidNo([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_no(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidNoAsync(new DigitalIdWalletApiBankidNoWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_no" } }, "/v3/id-verification/wallets/vipps/": { "post": { "operationId": "start_vipps_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_vipps", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o Vipps (Vipps MobilePay / BankID NO; NOR) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa ao return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Vipps", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "vipps", "name": "Vipps", "issuing_authority": "Vipps MobilePay / BankID NO" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/vipps/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_vipps(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startVipps({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartVipps(ctx, didit.IDWalletsStartVippsParams{\n\tBody: didit.DigitalIDWalletAPIVippsWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\nimport me.didit.types.DigitalIdWalletApiVippsWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startVipps(DigitalIdWalletApiVippsWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startVipps([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_vipps(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartVippsAsync(new DigitalIdWalletApiVippsWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "vipps" } }, "/v3/id-verification/wallets/buypass/": { "post": { "operationId": "start_buypass_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_buypass", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com Buypass ID (Buypass AS; NOR) sem qualquer fluxo. É cobrado uma vez, apenas quando a identidade é verificada. A resposta inclui next_action.type=redirect com o URL para onde enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Buypass ID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "buypass", "name": "Buypass ID", "issuing_authority": "Buypass AS" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/buypass/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_buypass(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBuypass({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBuypass(ctx, didit.IDWalletsStartBuypassParams{\n\tBody: didit.DigitalIDWalletAPIBuypassWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBuypassWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBuypass(DigitalIdWalletApiBuypassWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBuypass([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_buypass(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBuypassAsync(new DigitalIdWalletApiBuypassWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "buypass" } }, "/v3/id-verification/wallets/itsme/": { "post": { "operationId": "start_itsme_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_itsme", "auth": "api_key", "server": true }, "description": "Iniciar um início de sessão itsme (Belgian Mobile ID; BEL, LUX, NLD) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde direcionar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar a verificação itsme", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" }, "example": { "country": "BEL", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "itsme", "name": "itsme", "issuing_authority": "Belgian Mobile ID" }, "country": "BEL", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/itsme/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"BEL\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_itsme(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"BEL\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startItsme({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BEL\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartItsme(ctx, didit.IDWalletsStartItsmeParams{\n\tBody: didit.DigitalIDWalletAPIItsmeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIItsmeWalletVerificationStartCountryEnum(\"BEL\"),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiItsmeWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startItsme(DigitalIdWalletApiItsmeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum.of(\"BEL\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startItsme([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'BEL',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_itsme(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BEL\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartItsmeAsync(new DigitalIdWalletApiItsmeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"BEL\",\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "itsme" } }, "/v3/id-verification/wallets/idin/": { "post": { "operationId": "start_idin_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_idin", "auth": "api_key", "server": true }, "description": "Iniciar um início de sessão iDIN (bancos neerlandeses (Currence iDIN); NLD) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde direcionar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar a verificação iDIN", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" }, "example": { "country": "NLD", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "idin", "name": "iDIN", "issuing_authority": "Dutch banks (Currence iDIN)" }, "country": "NLD", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/idin/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NLD\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_idin(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NLD\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startIdin({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NLD\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartIdin(ctx, didit.IDWalletsStartIdinParams{\n\tBody: didit.DigitalIDWalletAPIIdinWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIIdinWalletVerificationStartCountryEnum(\"NLD\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiIdinWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiIdinWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startIdin(DigitalIdWalletApiIdinWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiIdinWalletVerificationStartCountryEnum.of(\"NLD\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startIdin([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NLD',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_idin(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NLD\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartIdinAsync(new DigitalIdWalletApiIdinWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiIdinWalletVerificationStartCountryEnum(\"NLD\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "idin" } }, "/v3/id-verification/wallets/ftn/": { "post": { "operationId": "start_ftn_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_ftn", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com Finnish Trust Network (bancos e operadoras móveis finlandesas (FTN); FIN) sem qualquer fluxo. É faturado uma única vez, apenas quando a identidade for verificada. A resposta contém next_action.type=redirect com o URL para onde deve enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Finnish Trust Network", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" }, "example": { "country": "FIN", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"FIN\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_ftn(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"FIN\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFtn({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FIN\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFtn(ctx, didit.IDWalletsStartFtnParams{\n\tBody: didit.DigitalIDWalletAPIFtnWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIFtnWalletVerificationStartCountryEnum(\"FIN\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiFtnWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiFtnWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFtn(DigitalIdWalletApiFtnWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiFtnWalletVerificationStartCountryEnum.of(\"FIN\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFtn([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'FIN',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_ftn(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FIN\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFtnAsync(new DigitalIdWalletApiFtnWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiFtnWalletVerificationStartCountryEnum(\"FIN\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "ftn" } }, "/v3/id-verification/wallets/personalausweis/": { "post": { "operationId": "start_personalausweis_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_personalausweis", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o Personalausweis (Bundesministerium des Innern (eID); DEU) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa ao return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Personalausweis", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" }, "example": { "country": "DEU", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "personalausweis", "name": "Personalausweis", "issuing_authority": "Bundesministerium des Innern (eID)" }, "country": "DEU", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/personalausweis/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"DEU\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_personalausweis(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"DEU\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startPersonalausweis({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DEU\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartPersonalausweis(ctx, didit.IDWalletsStartPersonalausweisParams{\n\tBody: didit.DigitalIDWalletAPIPersonalausweisWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIPersonalausweisWalletVerificationStartCountryEnum(\"DEU\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startPersonalausweis(DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum.of(\"DEU\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startPersonalausweis([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'DEU',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_personalausweis(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DEU\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartPersonalausweisAsync(new DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum(\"DEU\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "personalausweis" } }, "/v3/id-verification/wallets/frejaid/": { "post": { "operationId": "start_frejaid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_frejaid", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com Freja eID (Freja eID Group; SWE) sem qualquer fluxo. É faturado uma única vez, apenas quando a identidade for verificada. A resposta contém next_action.type=redirect com o URL para onde deve enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Freja eID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" }, "example": { "country": "SWE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "frejaid", "name": "Freja eID", "issuing_authority": "Freja eID Group" }, "country": "SWE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/frejaid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"SWE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_frejaid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"SWE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFrejaid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFrejaid(ctx, didit.IDWalletsStartFrejaidParams{\n\tBody: didit.DigitalIDWalletAPIFrejaidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryEe9enum(\"SWE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryEe9Enum;\nimport me.didit.types.DigitalIdWalletApiFrejaidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFrejaid(DigitalIdWalletApiFrejaidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryEe9Enum.of(\"SWE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFrejaid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'SWE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_frejaid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFrejaidAsync(new DigitalIdWalletApiFrejaidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryEe9Enum(\"SWE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "frejaid" } }, "/v3/id-verification/wallets/uae-pass/": { "post": { "operationId": "start_uae_pass_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_uae_pass", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o UAE PASS (UAE Digital Government Authority; ARE) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa ao return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação UAE PASS", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" }, "example": { "country": "ARE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "uae_pass", "name": "UAE PASS", "issuing_authority": "UAE Digital Government Authority" }, "country": "ARE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/uae-pass/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"ARE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_uae_pass(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"ARE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startUaePass({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ARE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartUaePass(ctx, didit.IDWalletsStartUaePassParams{\n\tBody: didit.DigitalIDWalletAPIUaePassWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIUaePassWalletVerificationStartCountryEnum(\"ARE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiUaePassWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startUaePass(DigitalIdWalletApiUaePassWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum.of(\"ARE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startUaePass([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'ARE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_uae_pass(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ARE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartUaePassAsync(new DigitalIdWalletApiUaePassWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum(\"ARE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "uae_pass" } }, "/v3/id-verification/wallets/govbr/": { "post": { "operationId": "start_govbr_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_govbr", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o gov.br (Governo Federal do Brasil; BRA) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa ao return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar a verificação gov.br", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" }, "example": { "country": "BRA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "govbr", "name": "gov.br", "issuing_authority": "Governo Federal do Brasil" }, "country": "BRA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/govbr/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"BRA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_govbr(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"BRA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startGovbr({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BRA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartGovbr(ctx, didit.IDWalletsStartGovbrParams{\n\tBody: didit.DigitalIDWalletAPIGovbrWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIGovbrWalletVerificationStartCountryEnum(\"BRA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiGovbrWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startGovbr(DigitalIdWalletApiGovbrWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum.of(\"BRA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startGovbr([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'BRA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_govbr(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BRA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartGovbrAsync(new DigitalIdWalletApiGovbrWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum(\"BRA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "govbr" } }, "/v3/id-verification/wallets/oneid/": { "post": { "operationId": "start_oneid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_oneid", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o OneID (OneID (UK bank-verified identity); GBR) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa ao return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação OneID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" }, "example": { "country": "GBR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "oneid", "name": "OneID", "issuing_authority": "OneID (UK bank-verified identity)" }, "country": "GBR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/oneid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"GBR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_oneid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"GBR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startOneid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartOneid(ctx, didit.IDWalletsStartOneidParams{\n\tBody: didit.DigitalIDWalletAPIOneidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountry520enum(\"GBR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountry520Enum;\nimport me.didit.types.DigitalIdWalletApiOneidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startOneid(DigitalIdWalletApiOneidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountry520Enum.of(\"GBR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startOneid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'GBR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_oneid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartOneidAsync(new DigitalIdWalletApiOneidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountry520Enum(\"GBR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "oneid" } }, "/v3/id-verification/wallets/govuk-wallet/": { "post": { "operationId": "start_govuk_wallet_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_govuk_wallet", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com a GOV.UK Wallet (UK Government Digital Service; GBR) sem qualquer fluxo. É faturado uma única vez, apenas quando a identidade for verificada. A resposta contém next_action.type=redirect com o URL para onde deve enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação GOV.UK Wallet", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" }, "example": { "country": "GBR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "govuk_wallet", "name": "GOV.UK Wallet", "issuing_authority": "UK Government Digital Service" }, "country": "GBR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/govuk-wallet/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"GBR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_govuk_wallet(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"GBR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startGovukWallet({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartGovukWallet(ctx, didit.IDWalletsStartGovukWalletParams{\n\tBody: didit.DigitalIDWalletAPIGovukWalletWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountry520enum(\"GBR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountry520Enum;\nimport me.didit.types.DigitalIdWalletApiGovukWalletWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startGovukWallet(DigitalIdWalletApiGovukWalletWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountry520Enum.of(\"GBR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startGovukWallet([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'GBR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_govuk_wallet(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartGovukWalletAsync(new DigitalIdWalletApiGovukWalletWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountry520Enum(\"GBR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "govuk_wallet" } }, "/v3/id-verification/wallets/smart-id/": { "post": { "operationId": "start_smart_id_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_smart_id", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o Smart-ID (SK ID Solutions; EST, LVA, LTU, BEL) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=confirm_in_app com o código de comparação a apresentar ao utilizador; o utilizador confirma-o e introduz o respetivo PIN na aplicação (nunca recolha o PIN). Faça polling do endpoint POST /v3/id-verification/wallets/verifications/{request_id}/poll/ a cada poll_interval_seconds, ou confie no webhook: a Didit também realiza polling em segundo plano. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Smart-ID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "personal_code": "00000000000" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "smart_id", "name": "Smart-ID", "issuing_authority": "SK ID Solutions" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/smart-id/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"personal_code\": \"00000000000\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_smart_id(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n personal_code=\"00000000000\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startSmartId({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartSmartID(ctx, didit.IDWalletsStartSmartIDParams{\n\tBody: didit.DigitalIDWalletAPISmartIDWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPISmartIDWalletVerificationStartCountryEnum(\"EST\"),\n\t\tPersonalCode: \"00000000000\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiSmartIdWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startSmartId(DigitalIdWalletApiSmartIdWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum.of(\"EST\"))\n .personalCode(\"00000000000\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startSmartId([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'personal_code' => '00000000000',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_smart_id(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartSmartIdAsync(new DigitalIdWalletApiSmartIdWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"EST\",\n PersonalCode = \"00000000000\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "smart_id" } }, "/v3/id-verification/wallets/mobile-id/": { "post": { "operationId": "start_mobile_id_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mobile_id", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com Mobile-ID (SK ID Solutions com as operadoras móveis nacionais; EST, LTU) sem qualquer fluxo. É faturado uma única vez, apenas quando a identidade for verificada. A resposta contém next_action.type=confirm_in_app com o código de comparação para mostrar ao utilizador; o utilizador confirma-o e introduz o seu PIN na aplicação (nunca recolha o PIN). Faça polling com POST /v3/id-verification/wallets/verifications/{request_id}/poll/ a cada poll_interval_seconds ou confie no webhook: a Didit também faz polling em segundo plano. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Mobile-ID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "personal_code": "00000000000", "phone_number": "+37200000000" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mobile_id", "name": "Mobile-ID", "issuing_authority": "SK ID Solutions with the national mobile operators" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mobile-id/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"personal_code\": \"00000000000\",\n \"phone_number\": \"+37200000000\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mobile_id(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n personal_code=\"00000000000\",\n phone_number=\"+37200000000\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMobileId({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n phone_number: \"+37200000000\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMobileID(ctx, didit.IDWalletsStartMobileIDParams{\n\tBody: didit.DigitalIDWalletAPIMobileIDWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIMobileIDWalletVerificationStartCountryEnum(\"EST\"),\n\t\tPersonalCode: \"00000000000\",\n\t\tPhoneNumber: \"+37200000000\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiMobileIdWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMobileId(DigitalIdWalletApiMobileIdWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum.of(\"EST\"))\n .personalCode(\"00000000000\")\n .phoneNumber(\"+37200000000\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMobileId([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'personal_code' => '00000000000',\n 'phone_number' => '+37200000000',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mobile_id(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n phone_number: \"+37200000000\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMobileIdAsync(new DigitalIdWalletApiMobileIdWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"EST\",\n PersonalCode = \"00000000000\",\n PhoneNumber = \"+37200000000\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mobile_id" } }, "/v3/id-verification/wallets/idcard-ee/": { "post": { "operationId": "start_idcard_ee_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_idcard_ee", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o cartão de identidade estónio (Police and Border Guard Board (Estonia); EST) sem qualquer fluxo. É cobrado uma vez, apenas quando a identidade é verificada. A resposta inclui next_action.type=redirect com o URL para onde enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação de cartão de cidadão estoniano", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "idcard_ee", "name": "Estonian ID-card", "issuing_authority": "Police and Border Guard Board (Estonia)" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/idcard-ee/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_idcard_ee(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startIdcardEe({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartIdcardEe(ctx, didit.IDWalletsStartIdcardEeParams{\n\tBody: didit.DigitalIDWalletAPIIdcardEeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIIdcardEeWalletVerificationStartCountryEnum(\"EST\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiIdcardEeWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startIdcardEe(DigitalIdWalletApiIdcardEeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum.of(\"EST\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startIdcardEe([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_idcard_ee(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartIdcardEeAsync(new DigitalIdWalletApiIdcardEeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum(\"EST\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "idcard_ee" } }, "/v3/id-verification/wallets/eparaksts-mobile/": { "post": { "operationId": "start_eparaksts_mobile_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_eparaksts_mobile", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o eParaksts mobile (LVRTC (Latvian State Radio and Television Centre); LVA) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa ao return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar a verificação móvel eParaksts", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" }, "example": { "country": "LVA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "eparaksts_mobile", "name": "eParaksts mobile", "issuing_authority": "LVRTC (Latvian State Radio and Television Centre)" }, "country": "LVA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/eparaksts-mobile/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"LVA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_eparaksts_mobile(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"LVA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startEparakstsMobile({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"LVA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartEparakstsMobile(ctx, didit.IDWalletsStartEparakstsMobileParams{\n\tBody: didit.DigitalIDWalletAPIEparakstsMobileWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIEparakstsMobileWalletVerificationStartCountryEnum(\"LVA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startEparakstsMobile(DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum.of(\"LVA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startEparakstsMobile([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'LVA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_eparaksts_mobile(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"LVA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartEparakstsMobileAsync(new DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum(\"LVA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "eparaksts_mobile" } }, "/v3/id-verification/wallets/bankid-cz/": { "post": { "operationId": "start_bankid_cz_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_cz", "auth": "api_key", "server": true }, "description": "Inicie sessão com Bank iD (Bankovní identita, a.s.; CZE) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado através de GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Bank iD", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" }, "example": { "country": "CZE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_cz", "name": "Bank iD", "issuing_authority": "Bankovní identita, a.s." }, "country": "CZE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-cz/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"CZE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_cz(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"CZE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidCz({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidCz(ctx, didit.IDWalletsStartBankidCzParams{\n\tBody: didit.DigitalIDWalletAPIBankidCzWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryE2dEnum(\"CZE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidCzWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryE2dEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidCz(DigitalIdWalletApiBankidCzWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryE2dEnum.of(\"CZE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidCz([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'CZE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_cz(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidCzAsync(new DigitalIdWalletApiBankidCzWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryE2dEnum(\"CZE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_cz" } }, "/v3/id-verification/wallets/mojeid/": { "post": { "operationId": "start_mojeid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mojeid", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com o MojeID (CZ.NIC; CZE) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa ao return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação MojeID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" }, "example": { "country": "CZE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mojeid", "name": "MojeID", "issuing_authority": "CZ.NIC" }, "country": "CZE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mojeid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"CZE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mojeid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"CZE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMojeid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMojeid(ctx, didit.IDWalletsStartMojeidParams{\n\tBody: didit.DigitalIDWalletAPIMojeidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryE2dEnum(\"CZE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryE2dEnum;\nimport me.didit.types.DigitalIdWalletApiMojeidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMojeid(DigitalIdWalletApiMojeidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryE2dEnum.of(\"CZE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMojeid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'CZE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mojeid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMojeidAsync(new DigitalIdWalletApiMojeidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryE2dEnum(\"CZE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mojeid" } }, "/v3/id-verification/wallets/diia/": { "post": { "operationId": "start_diia_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_diia", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com Diia (Ministry of Digital Transformation of Ukraine; UKR) sem qualquer fluxo. É cobrado uma vez, apenas quando a identidade é verificada. A resposta inclui next_action.type=redirect com o URL para onde enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Diia", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" }, "example": { "country": "UKR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "diia", "name": "Diia", "issuing_authority": "Ministry of Digital Transformation of Ukraine" }, "country": "UKR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/diia/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"UKR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_diia(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"UKR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startDiia({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"UKR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartDiia(ctx, didit.IDWalletsStartDiiaParams{\n\tBody: didit.DigitalIDWalletAPIDiiaWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIDiiaWalletVerificationStartCountryEnum(\"UKR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiDiiaWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startDiia(DigitalIdWalletApiDiiaWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum.of(\"UKR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startDiia([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'UKR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_diia(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"UKR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartDiiaAsync(new DigitalIdWalletApiDiiaWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum(\"UKR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "diia" } }, "/v3/id-verification/wallets/franceconnect/": { "post": { "operationId": "start_franceconnect_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_franceconnect", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com FranceConnect (DINUM (Estado francês); FRA) sem qualquer fluxo. É faturado uma única vez, apenas quando a identidade for verificada. A resposta contém next_action.type=redirect com o URL para onde deve enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação FranceConnect", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" }, "example": { "country": "FRA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "franceconnect", "name": "FranceConnect", "issuing_authority": "DINUM (French state)" }, "country": "FRA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/franceconnect/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"FRA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_franceconnect(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"FRA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFranceconnect({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FRA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFranceconnect(ctx, didit.IDWalletsStartFranceconnectParams{\n\tBody: didit.DigitalIDWalletAPIFranceconnectWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIFranceconnectWalletVerificationStartCountryEnum(\"FRA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiFranceconnectWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFranceconnect(DigitalIdWalletApiFranceconnectWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum.of(\"FRA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFranceconnect([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'FRA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_franceconnect(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FRA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFranceconnectAsync(new DigitalIdWalletApiFranceconnectWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum(\"FRA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "franceconnect" } }, "/v3/id-verification/wallets/audkenni/": { "post": { "operationId": "start_audkenni_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_audkenni", "auth": "api_key", "server": true }, "description": "Inicie sessão com Auðkenni (Auðkenni (ID eletrónico islandês); ISL) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta inclui next_action.type=redirect com o URL para onde deve encaminhar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado através de GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox recebem uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Auðkenni", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" }, "example": { "country": "ISL", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "audkenni", "name": "Auðkenni", "issuing_authority": "Auðkenni (Icelandic electronic ID)" }, "country": "ISL", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/audkenni/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"ISL\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_audkenni(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"ISL\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startAudkenni({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ISL\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartAudkenni(ctx, didit.IDWalletsStartAudkenniParams{\n\tBody: didit.DigitalIDWalletAPIAudkenniWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIAudkenniWalletVerificationStartCountryEnum(\"ISL\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiAudkenniWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startAudkenni(DigitalIdWalletApiAudkenniWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum.of(\"ISL\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startAudkenni([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'ISL',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_audkenni(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ISL\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartAudkenniAsync(new DigitalIdWalletApiAudkenniWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum(\"ISL\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "audkenni" } }, "/v3/id-verification/wallets/connectid/": { "post": { "operationId": "start_connectid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_connectid", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com ConnectID (Australian Payments Plus; AUS) sem qualquer fluxo. É cobrado uma vez, apenas quando a identidade é verificada. A resposta inclui next_action.type=redirect com o URL para onde enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação ConnectID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" }, "example": { "country": "AUS", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "connectid", "name": "ConnectID", "issuing_authority": "Australian Payments Plus" }, "country": "AUS", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/connectid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"AUS\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_connectid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"AUS\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startConnectid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUS\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartConnectid(ctx, didit.IDWalletsStartConnectidParams{\n\tBody: didit.DigitalIDWalletAPIConnectidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIConnectidWalletVerificationStartCountryEnum(\"AUS\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiConnectidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startConnectid(DigitalIdWalletApiConnectidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum.of(\"AUS\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startConnectid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'AUS',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_connectid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUS\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartConnectidAsync(new DigitalIdWalletApiConnectidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum(\"AUS\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "connectid" } }, "/v3/id-verification/wallets/eudi/": { "post": { "operationId": "start_eudi_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_eudi", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com EUDI Wallet (o próprio Estado-Membro do utilizador; o emissor varia consoante o país; AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE, ISL, LIE, NOR) sem qualquer fluxo. É faturado uma vez, apenas quando a identidade é verificada. A resposta inclui next_action.type=redirect com o URL para onde enviar o navegador do utilizador; o utilizador regressa a return_url com request_id e result anexados. Leia o resultado com GET /v3/id-verification/wallets/verifications/{request_id}/ ou a partir do webhook, nunca a partir do URL. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação EUDI Wallet", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" }, "example": { "country": "AUT", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "eudi", "name": "EUDI Wallet", "issuing_authority": "The user's own member state; the issuer differs per country" }, "country": "AUT", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/eudi/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"AUT\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_eudi(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"AUT\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startEudi({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUT\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartEudi(ctx, didit.IDWalletsStartEudiParams{\n\tBody: didit.DigitalIDWalletAPIEudiWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIEudiWalletVerificationStartCountryEnum(\"AUT\"),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiEudiWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiEudiWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startEudi(DigitalIdWalletApiEudiWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiEudiWalletVerificationStartCountryEnum.of(\"AUT\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startEudi([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'AUT',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_eudi(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUT\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartEudiAsync(new DigitalIdWalletApiEudiWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"AUT\",\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "eudi" } }, "/v3/organization/{organization_id}/application/{application_id}/cases/teams/": { "get": { "summary": "Listar equipas de revisão", "description": "Requer `list:cases` para a aplicação solicitada.", "operationId": "list_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeam" } }, "count": { "type": "integer", "description": "Contagem de correspondências, limitada a 100. Siga next para continuar além do limite." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.teams.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.teams.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Teams.ListAutoPaging(ctx, didit.CasesTeamsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().teams().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->teams->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.teams.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Teams.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Criar equipa de revisão", "description": "Requer `write:cases` para a aplicação solicitada.", "operationId": "create_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeamCreate" }, "example": { "name": "AML analysts", "members": [ { "user_id": "9a000000-0000-4000-8000-0000000000aa", "capacity": 10 } ] } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.create(\n name=\"AML analysts\",\n members=[{\n \"user_id\": \"9a000000-0000-4000-8000-0000000000aa\",\n \"capacity\": 10,\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.create({\n name: \"AML analysts\",\n members: [{\n user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n capacity: 10,\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Create(ctx, didit.CaseReviewTeamCreate{\n\tName: \"AML analysts\",\n\tMembers: []didit.CaseReviewTeamMemberParam{{\n\t\tUserID: \"9a000000-0000-4000-8000-0000000000aa\",\n\t\tCapacity: didit.Int(10),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseReviewTeamCreate;\nimport me.didit.types.CaseReviewTeamMember;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().create(CaseReviewTeamCreate.builder()\n .name(\"AML analysts\")\n .members(List.of(CaseReviewTeamMember.builder()\n .userId(\"9a000000-0000-4000-8000-0000000000aa\")\n .capacity(10L)\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->create([\n 'name' => 'AML analysts',\n 'members' => [[\n 'user_id' => '9a000000-0000-4000-8000-0000000000aa',\n 'capacity' => 10,\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.create(\n name: \"AML analysts\",\n members: [{\n user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n capacity: 10,\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.CreateAsync(new CaseReviewTeamCreate\n{\n Name = \"AML analysts\",\n Members = new CaseReviewTeamMember[]\n {\n new()\n {\n UserId = \"9a000000-0000-4000-8000-0000000000aa\",\n Capacity = 10,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/fraud/checks/{check_id}/": { "get": { "operationId": "root_retrieve", "x-didit-sdk": { "resource": "fraud_checks", "method": "retrieve", "auth": "api_key", "server": true }, "description": "Obter uma verificação criada anteriormente através do seu `check_id`.", "summary": "Obter uma Verificação de Fraude", "parameters": [ { "in": "path", "name": "check_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckResponse" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsErrorMessage" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsForbiddenErrorMessage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ "Fraud Check" ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/": { "get": { "operationId": "organization_application_cases_requests_list", "x-didit-sdk": { "resource": "cases.requests", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "Qual o campo a utilizar para ordenar os resultados.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Número de resultados a devolver por página.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "O índice inicial a partir do qual devolver os resultados.", "schema": { "type": "integer" } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingPaginatedCaseRequestList" } } }, "description": "" }, "404": { "description": "O pedido ou caso não está disponível para este chamador." }, "403": { "description": "O chamador não possui a permissão de casos necessária." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.requests.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.requests.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Requests.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesRequestsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().requests().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->requests->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.requests.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Requests.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "organization_application_cases_requests_create", "x-didit-sdk": { "resource": "cases.requests", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } } }, "required": true }, "responses": { "404": { "description": "O pedido ou caso não está disponível para este chamador." }, "403": { "description": "O chamador não possui a permissão de casos necessária." }, "400": { "description": "Entradas inválidas, finalidade não suportada, contacto verificado indisponível ou uma resposta imutável já existente." }, "409": { "description": "A pré-visualização mudou ou expirou. Pré-visualize novamente antes de confirmar." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Confirme a pré-visualização assinada exata dentro de 15 minutos. Apenas modelos fixos e um contacto verificado por OTP pertencente ao titular do caso são aceites. O ID do pedido torna as repetições idempotentes. A entrega é colocada em fila; SENT, SIMULATED e UNKNOWN são resultados distintos. Um pedido que exija ação coloca o caso em Awaiting user. Uma atualização de revisão mantém o seu estado inalterado.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.create(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id=\"11111111-2222-3333-4444-555555555555\",\n purpose=\"identity_document\",\n request_id=\"11111111-2222-3333-4444-555555555555\",\n expires_at=\"2026-01-15T10:00:00Z\",\n preview_token=\"your-preview-token\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.create(\"11111111-2222-3333-4444-555555555555\", {\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n request_id: \"11111111-2222-3333-4444-555555555555\",\n expires_at: \"2026-01-15T10:00:00Z\",\n preview_token: \"your-preview-token\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CustomerMessagingCaseRequestConfirmRequest{\n\tContactID: \"11111111-2222-3333-4444-555555555555\",\n\tPurpose: didit.CustomerMessagingPurposeEnum(\"identity_document\"),\n\tRequestID: \"11111111-2222-3333-4444-555555555555\",\n\tExpiresAt: time.Date(2026, 1, 15, 10, 0, 0, 0, time.UTC),\n\tPreviewToken: \"your-preview-token\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport me.didit.Didit;\nimport me.didit.types.CustomerMessagingCaseRequestConfirmRequest;\nimport me.didit.types.CustomerMessagingPurposeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().create(\"11111111-2222-3333-4444-555555555555\", CustomerMessagingCaseRequestConfirmRequest.builder()\n .contactId(\"11111111-2222-3333-4444-555555555555\")\n .purpose(CustomerMessagingPurposeEnum.of(\"identity_document\"))\n .requestId(\"11111111-2222-3333-4444-555555555555\")\n .expiresAt(OffsetDateTime.parse(\"2026-01-15T10:00:00Z\"))\n .previewToken(\"your-preview-token\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->create('11111111-2222-3333-4444-555555555555', [\n 'contact_id' => '11111111-2222-3333-4444-555555555555',\n 'purpose' => 'identity_document',\n 'request_id' => '11111111-2222-3333-4444-555555555555',\n 'expires_at' => '2026-01-15T10:00:00Z',\n 'preview_token' => 'your-preview-token',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.create(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n request_id: \"11111111-2222-3333-4444-555555555555\",\n expires_at: \"2026-01-15T10:00:00Z\",\n preview_token: \"your-preview-token\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new CustomerMessagingCaseRequestConfirmRequest\n{\n ContactId = \"11111111-2222-3333-4444-555555555555\",\n Purpose = \"identity_document\",\n RequestId = \"11111111-2222-3333-4444-555555555555\",\n ExpiresAt = DateTimeOffset.Parse(\"2026-01-15T10:00:00Z\"),\n PreviewToken = \"your-preview-token\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/fraud/checks/": { "post": { "operationId": "create_fraud_check", "x-didit-sdk": { "resource": "fraud_checks", "method": "create", "auth": "api_key", "server": true }, "description": "Submeta um ou mais identificadores tipificados e receba normalização, enriquecimento atualizado, validação fidedigna onde o país e o tipo de identificador tenham cobertura, dimensões de risco independentes e uma recomendação numa única resposta.\n\nEstes perfis suportam verificações de identificadores. A vinculação de identidade baseada em selfie (`biometric_identity`) requer a versão de perfil `2026-09-14.2` e um CPF brasileiro; é executada apenas com o consentimento do utilizador e quando a sua organização tiver direito a ela. Versões anteriores reportam-na como `not_available_in_profile_version`. Os módulos que não possam ser executados são reportados como ignorados com um motivo determinístico; uma fonte que não tenha conseguido responder nunca é reportada como uma não correspondência de identidade.", "summary": "Executar uma verificação de fraude", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" }, "example": { "client_reference": "review-attempt-001", "subject": { "identifiers": [ { "type": "email", "value": "applicant@example.com" } ], "attributes": { "first_name": "Alex", "last_name": "Example" } }, "checks": { "include": [ "networks_same_org", "networks_cross_org", "email_risk" ] } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckResponse" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsErrorMessage" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsForbiddenErrorMessage" } } }, "description": "" }, "409": { "description": "Conflito, devolvido sem cobrança: o `client_reference` já foi utilizado com um corpo de pedido diferente; uma verificação com o mesmo `client_reference` ainda está em execução (tente novamente após `Retry-After` segundos com a mesma referência); ou a verificação na qual este controlo é registado foi eliminada antes de o controlo ser concluído.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "examples": { "different_body": { "summary": "Referência reutilizada com um corpo diferente", "value": { "error": "client_reference has already been used with a different request body." } }, "still_running": { "summary": "Uma verificação com esta referência ainda está em execução", "value": { "error": "A check with this client_reference is already running. Retry with the same reference later." } }, "verification_deleted": { "summary": "A verificação foi eliminada antes da conclusão da verificação", "value": { "error": "This verification was deleted before the check completed." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente, enviados quando uma verificação com a mesma `client_reference` ainda estiver em execução.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ "Fraud Check" ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.create(\n client_reference=\"review-attempt-001\",\n subject={\n \"identifiers\": [{\n \"type\": \"email\",\n \"value\": \"applicant@example.com\",\n }],\n \"attributes\": {\n \"first_name\": \"Alex\",\n \"last_name\": \"Example\",\n },\n },\n checks={\n \"include\": [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.create({\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Create(ctx, didit.FraudCheckRequestRequest{\n\tClientReference: didit.String(\"review-attempt-001\"),\n\tSubject: didit.FraudCheckSubjectRequest{\n\t\tIdentifiers: []didit.FraudCheckIdentifierRequest{{\n\t\t\tType: didit.FraudTypeEnum(\"email\"),\n\t\t\tValue: \"applicant@example.com\",\n\t\t}},\n\t\tAttributes: didit.Some(didit.FraudCheckAttributesRequest{\n\t\t\tFirstName: didit.String(\"Alex\"),\n\t\t\tLastName: didit.String(\"Example\"),\n\t\t}),\n\t},\n\tChecks: didit.Some(didit.FraudCheckModuleSelectionRequest{\n\t\tInclude: didit.Some([]didit.FraudExcludeEnum{didit.FraudExcludeEnum(\"networks_same_org\"), didit.FraudExcludeEnum(\"networks_cross_org\"), didit.FraudExcludeEnum(\"email_risk\")}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.FraudCheckAttributesRequest;\nimport me.didit.types.FraudCheckIdentifierRequest;\nimport me.didit.types.FraudCheckModuleSelectionRequest;\nimport me.didit.types.FraudCheckRequestRequest;\nimport me.didit.types.FraudCheckSubjectRequest;\nimport me.didit.types.FraudExcludeEnum;\nimport me.didit.types.FraudTypeEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().create(FraudCheckRequestRequest.builder()\n .clientReference(\"review-attempt-001\")\n .subject(FraudCheckSubjectRequest.builder()\n .identifiers(List.of(FraudCheckIdentifierRequest.builder()\n .type(FraudTypeEnum.of(\"email\"))\n .value(\"applicant@example.com\")\n .build()))\n .attributes(FraudCheckAttributesRequest.builder()\n .firstName(\"Alex\")\n .lastName(\"Example\")\n .build())\n .build())\n .checks(FraudCheckModuleSelectionRequest.builder()\n .include(List.of(FraudExcludeEnum.of(\"networks_same_org\"), FraudExcludeEnum.of(\"networks_cross_org\"), FraudExcludeEnum.of(\"email_risk\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->create([\n 'client_reference' => 'review-attempt-001',\n 'subject' => [\n 'identifiers' => [[\n 'type' => 'email',\n 'value' => 'applicant@example.com',\n ]],\n 'attributes' => [\n 'first_name' => 'Alex',\n 'last_name' => 'Example',\n ],\n ],\n 'checks' => [\n 'include' => ['networks_same_org', 'networks_cross_org', 'email_risk'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.create(\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.CreateAsync(new FraudCheckRequestRequest\n{\n ClientReference = \"review-attempt-001\",\n Subject = new()\n {\n Identifiers = new FraudCheckIdentifierRequest[]\n {\n new()\n {\n Type = \"email\",\n Value = \"applicant@example.com\",\n },\n },\n Attributes = new FraudCheckAttributesRequest\n {\n FirstName = \"Alex\",\n LastName = \"Example\",\n },\n },\n Checks = new FraudCheckModuleSelectionRequest\n {\n Include = new FraudExcludeEnum[] { \"networks_same_org\", \"networks_cross_org\", \"email_risk\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/cancel/": { "post": { "operationId": "organization_application_cases_requests_cancel_create", "x-didit-sdk": { "resource": "cases.requests", "method": "cancel", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } }, "description": "" }, "404": { "description": "O pedido ou caso não está disponível para este chamador." }, "403": { "description": "O chamador não possui a permissão de casos necessária." }, "400": { "description": "Entradas inválidas, finalidade não suportada, contacto verificado indisponível ou uma resposta imutável já existente." }, "409": { "description": "A pré-visualização mudou ou expirou. Pré-visualize novamente antes de confirmar." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Cancel(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().cancel(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->cancel('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.CancelAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/options/": { "get": { "operationId": "organization_application_cases_requests_options_retrieve", "x-didit-sdk": { "resource": "cases.requests", "method": "retrieve_options", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestOptions" } } }, "description": "" }, "404": { "description": "O pedido ou caso não está disponível para este chamador." }, "403": { "description": "O chamador não possui a permissão de casos necessária." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.retrieve_options(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.retrieveOptions(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.RetrieveOptions(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().retrieveOptions(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->retrieveOptions('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.retrieve_options(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.RetrieveOptionsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/attachment/": { "get": { "operationId": "organization_application_cases_requests_attachment_retrieve", "x-didit-sdk": { "resource": "cases.requests", "method": "retrieve_attachment", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } }, "description": "" }, "404": { "description": "O pedido ou caso não está disponível para este chamador." }, "403": { "description": "O chamador não possui a permissão de casos necessária." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.cases.requests.retrieve_attachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.png\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.cases.requests.retrieveAttachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.png\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Cases.Requests.RetrieveAttachment(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.png\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().requests().retrieveAttachment(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.png\"));" }, { "lang": "php", "label": "PHP", "source": "cases->requests->retrieveAttachment('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.png');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.cases.requests.retrieve_attachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.png\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Cases.Requests.RetrieveAttachmentAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.png\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/history/": { "get": { "operationId": "list_case_routing_rule_history", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "list_history", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "Qual o campo a utilizar para ordenar os resultados.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Número de resultados a devolver por página.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "O índice inicial a partir do qual devolver os resultados.", "schema": { "type": "integer" } } ], "tags": [ "Case Assignment" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPaginatedPolicyRevisionList" } } }, "description": "" }, "403": { "description": "É necessário acesso ao caso." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.routing_rules.list_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.routingRules.listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RoutingRules.ListHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesRoutingRulesListHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().routingRules().listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->listHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.list_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RoutingRules.ListHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/resubmission-preview/": { "post": { "summary": "Pré-visualizar um e-mail de ressubmissão", "description": "Gere o e-mail que acompanharia um reenvio de KYC ou KYB sem alterar a sessão, redefinir verificações, prolongar a respetiva validade, executar verificações ou enviar e-mails. Requer o privilégio `write:sessions` (uma chave de API com âmbito restrito necessita de acesso de escrita a decisões) e uma sessão no estado `Approved`, `Declined`, `In Review`, `Kyc Expired` ou `Abandoned`. O servidor valida os passos do fluxo selecionados e gera o respetivo modelo traduzido fixo com o remetente de marca branca verificado e a imagem de marca aplicáveis. O pedido não pode definir um assunto, corpo da mensagem ou URL de ação.\n\n`email_address` é opcional. Sem este, o e-mail segue para o próprio endereço da pessoa: aquele que foi verificado num passo de verificação de e-mail do fluxo ou, caso contrário, o indicado em `contact_details` quando a sessão foi criada. Um endereço que forneça prevalece (`recipient_source: request`). Quando nenhum endereço é conhecido e não fornecer nenhum, `recipient` e `preview_token` são strings vazias e nenhum e-mail pode ser enviado.\n\nA resposta inclui o destinatário e a respetiva origem, o remetente, o assunto, o HTML, o idioma, os passos resolvidos, se a confirmação enviará o e-mail (`will_be_sent`, `not_sent_reason`) e um `preview_token` assinado. `requires_user_action` é `false` quando todos os passos selecionados são executados sem a pessoa: o reenvio termina então por si próprio e nenhum e-mail é enviado (`not_sent_reason: no_user_action`).\n\nEsta pré-visualização não reserva o estado da sessão nem autoriza a entrega. Após a sua revisão, chame [Update Session Status](/pt/sessions-api/update-status) com `new_status: Resubmitted`, os mesmos `nodes_to_resubmit` e `email_language` que pré-visualizou, `send_email: true`, `email_address` definido como `recipient` e `email_preview_token` definido como `preview_token`. O recibo expira após 15 minutos. Quando um recibo é fornecido, alterações nos dados de entrada, no conteúdo da mensagem, no remetente ou no estado da sessão devolvem `409` antes de qualquer mutação ou envio. As integrações existentes podem omitir o recibo. Gere novamente a pré-visualização após um conflito. Trate a resposta como conteúdo de verificação sensível; as respostas utilizam `Cache-Control: no-store`. Renderize o HTML numa frame em sandbox, nunca diretamente no DOM da sua aplicação.", "operationId": "post_v3_session_resubmission_preview", "x-didit-sdk": { "resource": "sessions", "method": "preview_resubmission", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação a atualizar. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB) — o serviço resolve o ID em ambos os tipos de sessão.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes_to_resubmit": { "type": "array", "description": "Passos a pré-visualizar, utilizando a mesma validação, seleção e ordenação do fluxo de um reenvio. Omita para selecionar automaticamente tentativas registadas que necessitem de reenvio.", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "Identificador do nó tal como aparece na definição do fluxo da sessão (por exemplo `feature_ocr`, `feature_liveness`).", "example": "feature_ocr" }, "feature": { "type": "string", "description": "Tipo de funcionalidade do nó. Os aliases `ID_VERIFICATION`, `POA`, `PHONE` e `EMAIL` são normalizados do lado do servidor para `OCR`, `PROOF_OF_ADDRESS`, `PHONE_VERIFICATION` e `EMAIL_VERIFICATION`. `KYB_REGISTRY`, `KYB_KEY_PEOPLE` e `KYB` passam na validação do esquema, mas são sempre rejeitados com a regra de negócio `400` mostrada nos exemplos.", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "email_address": { "type": "string", "format": "email", "description": "Opcional. Envie o e-mail para este endereço em vez do da própria pessoa. Sem este campo, o destinatário é o endereço que a pessoa verificou no fluxo ou, na sua ausência, o fornecido em `contact_details`. Nenhum e-mail é enviado por esta chamada.", "example": "user@example.com" }, "email_language": { "type": "string", "description": "Idioma do e-mail de notificação. Aceita qualquer cadeia de caracteres ao nível do esquema; códigos não suportados revertem silenciosamente para inglês (`en`).", "default": "en", "example": "en" } } }, "examples": { "Person's Own Address": { "summary": "Pré-visualizar uma ressubmissão de comprovativo de morada para a própria morada da pessoa", "value": { "nodes_to_resubmit": [ { "node_id": "feature_poa_1", "feature": "POA" } ], "email_language": "en" } }, "Named Recipient": { "summary": "Pré-visualizar o e-mail para um endereço indicado", "value": { "nodes_to_resubmit": [ { "node_id": "feature_ocr", "feature": "OCR" } ], "email_address": "person@example.com", "email_language": "en" } } } } } }, "responses": { "200": { "description": "Apenas pré-visualização. A sessão permanece inalterada e nenhum e-mail é enviado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "recipient_source", "sender", "sender_name", "sender_email", "sender_kind", "subject", "html", "text", "language", "will_be_sent", "not_sent_reason", "preview_token", "nodes_to_resubmit", "requires_user_action" ], "properties": { "recipient": { "type": "string", "description": "O endereço para o qual o e-mail é enviado. Uma string vazia quando não se conhece qualquer endereço para a pessoa: nesse caso, nenhum e-mail pode ser enviado e `preview_token` fica também vazio. Passe-o como `email_address` quando confirmar.", "example": "person@example.com" }, "recipient_source": { "type": "string", "enum": [ "email_verification", "contact_details", "request", "" ], "description": "De onde provém `recipient`. `request`: o `email_address` que passou. `email_verification`: o endereço que a pessoa verificou num passo de verificação de e-mail do fluxo. `contact_details`: o endereço fornecido em `contact_details` aquando da criação da sessão. Uma string vazia quando não existir endereço.", "example": "email_verification" }, "sender": { "type": "string", "description": "O cabeçalho `From` com o qual o e-mail é enviado.", "example": "Example App " }, "sender_name": { "type": "string", "description": "A parte do nome de apresentação de `sender`.", "example": "Example App" }, "sender_email": { "type": "string", "format": "email", "description": "A parte da morada de `sender`.", "example": "no-reply@mail.example.com" }, "sender_kind": { "type": "string", "enum": [ "customer", "didit" ], "description": "`customer`: o e-mail sai a partir do domínio de remetente verificado da sua aplicação (marca branca). `didit`: sai a partir do remetente próprio da Didit.", "example": "customer" }, "subject": { "type": "string", "description": "A linha de assunto exatamente como é enviada.", "example": "Action Required: Complete your verification in Example App" }, "html": { "type": "string", "description": "O HTML do e-mail exatamente como é enviado, com o respetivo logótipo incorporado como data URL. Renderize-o numa frame isolada (sandbox), nunca diretamente no DOM da sua aplicação.", "example": "..." }, "text": { "type": "string", "description": "O texto simples do e-mail, tal como o histórico de Mensagens da pessoa o guarda, para uma pré-visualização compacta (o HTML continua a ser o e-mail que a pessoa recebe).", "example": "Almost there\n\nSome steps need to be completed again.\nHere’s what to fix:\n\nhttps://verify.didit.me/session/abc123" }, "language": { "type": "string", "description": "O idioma em que o e-mail está escrito. Inglês (`en`) quando o `email_language` solicitado não estiver disponível.", "example": "en" }, "will_be_sent": { "type": "boolean", "description": "Se confirmar a alteração com `send_email: true` envia este e-mail. `false` quando `not_sent_reason` estiver definido.", "example": true }, "not_sent_reason": { "type": "string", "nullable": true, "enum": [ "no_user_action", "no_recipient", "sandbox", null ], "description": "O motivo pelo qual a confirmação não enviaria nenhum e-mail, ou `null` quando será enviado. `no_user_action`: todos os passos selecionados são executados sem a pessoa, pelo que o novo envio é concluído de forma autónoma e nenhum e-mail é enviado. `no_recipient`: nenhum endereço é conhecido para a pessoa e você não transmitiu nenhum. `sandbox`: uma sessão de sandbox cujo destinatário não aceitou a entrega de e-mails em sandbox, pelo que o envio é apenas simulado.", "example": null }, "nodes_to_resubmit": { "type": "array", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "Identificador do nó tal como aparece na definição do fluxo da sessão (por exemplo `feature_ocr`, `feature_liveness`).", "example": "feature_ocr" }, "feature": { "type": "string", "description": "Tipo de funcionalidade do nó. Os aliases `ID_VERIFICATION`, `POA`, `PHONE` e `EMAIL` são normalizados do lado do servidor para `OCR`, `PROOF_OF_ADDRESS`, `PHONE_VERIFICATION` e `EMAIL_VERIFICATION`. `KYB_REGISTRY`, `KYB_KEY_PEOPLE` e `KYB` passam na validação do esquema, mas são sempre rejeitados com a regra de negócio `400` mostrada nos exemplos.", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "requires_user_action": { "type": "boolean", "description": "Se pelo menos uma das verificações selecionadas requer a interação do utilizador. Isto não prevê o resultado final do fluxo." }, "preview_token": { "type": "string", "description": "Recibo assinado para este e-mail exato, válido por 15 minutos. Passe-o como `email_preview_token` para [Atualizar estado da sessão](/pt/sessions-api/update-status). Uma string vazia quando não há destinatário.", "example": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } }, "examples": { "Will Be Sent": { "summary": "Destinatário predefinido: o endereço verificado no fluxo", "value": { "recipient": "person@example.com", "recipient_source": "email_verification", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Action Required: Complete your verification in Example App", "html": "...", "language": "en", "will_be_sent": true, "not_sent_reason": null, "nodes_to_resubmit": [ { "node_id": "feature_poa_1", "feature": "PROOF_OF_ADDRESS" } ], "requires_user_action": true, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } }, "No User Action": { "summary": "Apenas foram selecionados passos do back-end, pelo que nenhum e-mail é enviado", "value": { "recipient": "person@example.com", "recipient_source": "contact_details", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Action Required: Complete your verification in Example App", "html": "...", "language": "en", "will_be_sent": false, "not_sent_reason": "no_user_action", "nodes_to_resubmit": [ { "node_id": "feature_aml", "feature": "AML" } ], "requires_user_action": false, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } } } }, "headers": { "Cache-Control": { "description": "Sempre `no-store`: a pré-visualização contém conteúdo de verificação e não deve ser guardada em cache.", "schema": { "type": "string", "example": "no-store" } } } }, "400": { "description": "A sessão não está num estado aceite por este endpoint, já se encontra no estado `Resubmitted`, os passos selecionados não podem ser submetidos novamente ou um campo é inválido.", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "A sessão não está num estado aceite por este endpoint", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Already Resubmitted": { "summary": "A sessão já se encontra no estado Resubmitted", "value": [ "The new status is the same as the current status." ] }, "Nothing To Resubmit": { "summary": "A seleção automática não encontrou nenhum passo que necessite de novo envio", "value": { "nodes_to_resubmit": "No features found that need resubmission. All features are already approved." } }, "Invalid Email": { "summary": "email_address não é um endereço de e-mail", "value": { "email_address": [ "Enter a valid email address." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chave de API com âmbito cuja data de validade já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenciais em falta, um chamador sem o privilégio `write:sessions`, uma chave de API com âmbito sem o acesso de que este endpoint necessita, ou um `session_id` que pertence a outra aplicação.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "O autor da chamada não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chave de API com âmbito sem este acesso", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "Não existe nenhuma sessão de KYC ou KYB com este `session_id`.", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id desconhecido", "value": { "detail": "Not found." } } } } } }, "429": { "description": "Os passos a submeter novamente são todos exclusivamente de backend (AML, DATABASE_VALIDATION, IP_ANALYSIS), e a sessão já foi submetida novamente para passos exclusivamente de backend nos últimos 30 segundos, pelo que o Update Session Status recusaria a nova submissão. Tente novamente após o intervalo indicado em `Retry-After`.", "content": { "application/json": { "examples": { "Backend-only resubmit throttled": { "value": { "detail": "This session was already resubmitted for backend-only features within the last 30 seconds; repeating it cannot change the outcome. Wait before resubmitting again." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.preview_resubmission(\n \"11111111-2222-3333-4444-555555555555\",\n nodes_to_resubmit=[{\n \"node_id\": \"feature_poa_1\",\n \"feature\": \"POA\",\n }],\n email_language=\"en\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.previewResubmission(\"11111111-2222-3333-4444-555555555555\", {\n nodes_to_resubmit: [{\n node_id: \"feature_poa_1\",\n feature: \"POA\",\n }],\n email_language: \"en\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.PreviewResubmission(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsPreviewResubmissionParams{\n\tNodesToResubmit: didit.Some([]didit.SessionsPreviewResubmissionParamsNodesToResubmit{{\n\t\tNodeID: \"feature_poa_1\",\n\t\tFeature: \"POA\",\n\t}}),\n\tEmailLanguage: didit.String(\"en\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsPreviewResubmissionParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().previewResubmission(\"11111111-2222-3333-4444-555555555555\", SessionsPreviewResubmissionParams.builder()\n .nodesToResubmit(List.of(SessionsPreviewResubmissionParams.NodesToResubmit.builder()\n .nodeId(\"feature_poa_1\")\n .feature(SessionsPreviewResubmissionParams.NodesToResubmit.Feature.of(\"POA\"))\n .build()))\n .emailLanguage(\"en\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->previewResubmission('11111111-2222-3333-4444-555555555555', [\n 'nodes_to_resubmit' => [[\n 'node_id' => 'feature_poa_1',\n 'feature' => 'POA',\n ]],\n 'email_language' => 'en',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.preview_resubmission(\n \"11111111-2222-3333-4444-555555555555\",\n nodes_to_resubmit: [{\n node_id: \"feature_poa_1\",\n feature: \"POA\",\n }],\n email_language: \"en\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.PreviewResubmissionAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsPreviewResubmissionParams\n{\n NodesToResubmit = new SessionsPreviewResubmissionParamsNodesToResubmit[]\n {\n new()\n {\n NodeId = \"feature_poa_1\",\n Feature = \"POA\",\n },\n },\n EmailLanguage = \"en\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/": { "get": { "summary": "Obter regra de encaminhamento", "description": "Requer `read:cases` para a aplicação solicitada.", "operationId": "retrieve_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." }, "404": { "description": "Registo não encontrado nesta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Atualizar regra de encaminhamento", "description": "Requer `write:cases` para a aplicação solicitada.", "operationId": "update_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." }, "404": { "description": "Registo não encontrado nesta aplicação." }, "409": { "description": "A regra de encaminhamento foi alterada desde expected_version. Reveja a regra mais recente antes de tentar novamente." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRuleUpdate" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"your-name\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"your-name\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseRoutingRuleUpdate{\n\tName: didit.String(\"your-name\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseRoutingRuleUpdate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().update(\"11111111-2222-3333-4444-555555555555\", CaseRoutingRuleUpdate.builder()\n .name(\"your-name\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'your-name',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"your-name\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseRoutingRuleUpdate\n{\n Name = \"your-name\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/case-requests/{request_uuid}/": { "get": { "operationId": "case_requests_retrieve", "x-didit-sdk": { "resource": "case_requests", "method": "retrieve", "auth": "device_token", "server": false }, "parameters": [ { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPublic" } } }, "description": "" }, "404": { "description": "O pedido ou caso não está disponível para este chamador." } }, "security": [ { "CaseRequestToken": [] } ], "description": "Aceda a um pedido de cliente utilizando o seu token específico do pedido. Não são devolvidos conclusões privadas do caso, dados de identidade originais nem o endereço do destinatário. Pedidos acionáveis expiram após sete dias. O cancelamento ou a resolução do caso invalida a ligação. As respostas são imutáveis e permanecem como prova para avaliação do revisor; nunca aprovam nem atualizam uma verificação de origem." }, "post": { "operationId": "case_requests_create", "x-didit-sdk": { "resource": "case_requests", "method": "respond", "auth": "device_token", "server": false }, "parameters": [ { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseResult" } } }, "description": "" }, "404": { "description": "O pedido ou caso não está disponível para este chamador." }, "400": { "description": "Entradas inválidas, finalidade não suportada, contacto verificado indisponível ou uma resposta imutável já existente." }, "409": { "description": "A pré-visualização mudou ou expirou. Pré-visualize novamente antes de confirmar." } }, "security": [ { "CaseRequestToken": [] } ], "description": "Aceda a um pedido de cliente utilizando o seu token específico do pedido. Não são devolvidos conclusões privadas do caso, dados de identidade originais nem o endereço do destinatário. Pedidos acionáveis expiram após sete dias. O cancelamento ou a resolução do caso invalida a ligação. As respostas são imutáveis e permanecem como prova para avaliação do revisor; nunca aprovam nem atualizam uma verificação de origem." } }, "/v3/fraud/checks/plan/": { "post": { "operationId": "plan_create", "x-didit-sdk": { "resource": "fraud_checks", "method": "plan", "auth": "api_key", "server": true }, "description": "Validar as verificações selecionadas e estimar o seu preço sem executar, criar uma sessão ou faturar.", "summary": "Planear uma verificação de fraude", "tags": [ "Fraud Check" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" }, "example": { "client_reference": "review-attempt-001", "subject": { "identifiers": [ { "type": "email", "value": "applicant@example.com" } ], "attributes": { "first_name": "Alex", "last_name": "Example" } }, "checks": { "include": [ "networks_same_org", "networks_cross_org", "email_risk" ] } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckPlan" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudBadRequestErrorMessage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.plan(\n client_reference=\"review-attempt-001\",\n subject={\n \"identifiers\": [{\n \"type\": \"email\",\n \"value\": \"applicant@example.com\",\n }],\n \"attributes\": {\n \"first_name\": \"Alex\",\n \"last_name\": \"Example\",\n },\n },\n checks={\n \"include\": [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.plan({\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Plan(ctx, didit.FraudCheckRequestRequest{\n\tClientReference: didit.String(\"review-attempt-001\"),\n\tSubject: didit.FraudCheckSubjectRequest{\n\t\tIdentifiers: []didit.FraudCheckIdentifierRequest{{\n\t\t\tType: didit.FraudTypeEnum(\"email\"),\n\t\t\tValue: \"applicant@example.com\",\n\t\t}},\n\t\tAttributes: didit.Some(didit.FraudCheckAttributesRequest{\n\t\t\tFirstName: didit.String(\"Alex\"),\n\t\t\tLastName: didit.String(\"Example\"),\n\t\t}),\n\t},\n\tChecks: didit.Some(didit.FraudCheckModuleSelectionRequest{\n\t\tInclude: didit.Some([]didit.FraudExcludeEnum{didit.FraudExcludeEnum(\"networks_same_org\"), didit.FraudExcludeEnum(\"networks_cross_org\"), didit.FraudExcludeEnum(\"email_risk\")}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.FraudCheckAttributesRequest;\nimport me.didit.types.FraudCheckIdentifierRequest;\nimport me.didit.types.FraudCheckModuleSelectionRequest;\nimport me.didit.types.FraudCheckRequestRequest;\nimport me.didit.types.FraudCheckSubjectRequest;\nimport me.didit.types.FraudExcludeEnum;\nimport me.didit.types.FraudTypeEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().plan(FraudCheckRequestRequest.builder()\n .clientReference(\"review-attempt-001\")\n .subject(FraudCheckSubjectRequest.builder()\n .identifiers(List.of(FraudCheckIdentifierRequest.builder()\n .type(FraudTypeEnum.of(\"email\"))\n .value(\"applicant@example.com\")\n .build()))\n .attributes(FraudCheckAttributesRequest.builder()\n .firstName(\"Alex\")\n .lastName(\"Example\")\n .build())\n .build())\n .checks(FraudCheckModuleSelectionRequest.builder()\n .include(List.of(FraudExcludeEnum.of(\"networks_same_org\"), FraudExcludeEnum.of(\"networks_cross_org\"), FraudExcludeEnum.of(\"email_risk\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->plan([\n 'client_reference' => 'review-attempt-001',\n 'subject' => [\n 'identifiers' => [[\n 'type' => 'email',\n 'value' => 'applicant@example.com',\n ]],\n 'attributes' => [\n 'first_name' => 'Alex',\n 'last_name' => 'Example',\n ],\n ],\n 'checks' => [\n 'include' => ['networks_same_org', 'networks_cross_org', 'email_risk'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.plan(\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.PlanAsync(new FraudCheckRequestRequest\n{\n ClientReference = \"review-attempt-001\",\n Subject = new()\n {\n Identifiers = new FraudCheckIdentifierRequest[]\n {\n new()\n {\n Type = \"email\",\n Value = \"applicant@example.com\",\n },\n },\n Attributes = new FraudCheckAttributesRequest\n {\n FirstName = \"Alex\",\n LastName = \"Example\",\n },\n },\n Checks = new FraudCheckModuleSelectionRequest\n {\n Include = new FraudExcludeEnum[] { \"networks_same_org\", \"networks_cross_org\", \"email_risk\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/": { "get": { "summary": "Listar regras de encaminhamento", "description": "Requer `list:cases` para a aplicação solicitada.", "operationId": "list_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingRule" } }, "count": { "type": "integer", "description": "Contagem de correspondências, limitada a 100. Siga next para continuar além do limite." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.routing_rules.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.routingRules.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RoutingRules.ListAutoPaging(ctx, didit.CasesRoutingRulesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().routingRules().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RoutingRules.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Criar regra de encaminhamento", "description": "Requer `write:cases` para a aplicação solicitada. Defina publish=false para criar um rascunho não publicado; Publicar cria a sua primeira versão ativa. Descartar um rascunho que nunca foi publicado elimina-o.", "operationId": "create_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRuleCreate" }, "example": { "name": "AML screening alerts", "conditions": [ { "field": "source", "operator": "equals", "value": "AML_SCREENING" } ], "blueprint": "b1de0000-0000-4000-8000-000000000002" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.create(\n name=\"AML screening alerts\",\n conditions=[{\n \"field\": \"source\",\n \"operator\": \"equals\",\n \"value\": \"AML_SCREENING\",\n }],\n blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.create({\n name: \"AML screening alerts\",\n conditions: [{\n field: \"source\",\n operator: \"equals\",\n value: \"AML_SCREENING\",\n }],\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Create(ctx, didit.CaseRoutingRuleCreate{\n\tName: \"AML screening alerts\",\n\tConditions: []didit.CaseRoutingConditionParam{{\n\t\tField: \"source\",\n\t\tOperator: \"equals\",\n\t\tValue: \"AML_SCREENING\",\n\t}},\n\tBlueprint: \"b1de0000-0000-4000-8000-000000000002\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseRoutingCondition;\nimport me.didit.types.CaseRoutingRuleCreate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().create(CaseRoutingRuleCreate.builder()\n .name(\"AML screening alerts\")\n .conditions(List.of(CaseRoutingCondition.builder()\n .field(CaseRoutingCondition.Field.of(\"source\"))\n .operator(CaseRoutingCondition.Operator.of(\"equals\"))\n .value(CaseRoutingCondition.Value.ofString(\"AML_SCREENING\"))\n .build()))\n .blueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->create([\n 'name' => 'AML screening alerts',\n 'conditions' => [[\n 'field' => 'source',\n 'operator' => 'equals',\n 'value' => 'AML_SCREENING',\n ]],\n 'blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.create(\n name: \"AML screening alerts\",\n conditions: [{\n field: \"source\",\n operator: \"equals\",\n value: \"AML_SCREENING\",\n }],\n blueprint: \"b1de0000-0000-4000-8000-000000000002\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.CreateAsync(new CaseRoutingRuleCreate\n{\n Name = \"AML screening alerts\",\n Conditions = new CaseRoutingCondition[]\n {\n new()\n {\n Field = \"source\",\n Operator = \"equals\",\n Value = \"AML_SCREENING\",\n },\n },\n Blueprint = \"b1de0000-0000-4000-8000-000000000002\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/publish/": { "post": { "operationId": "publish_case_routing_rule", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "publish", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationCaseRoutingRule" } } }, "description": "" }, "403": { "description": "É necessário acesso ao caso." }, "409": { "description": "A versão publicada ou revisão do rascunho mudou. Recarregue antes de tentar novamente." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.publish(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Publish(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().publish(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->publish('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.PublishAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/publish/": { "post": { "operationId": "publish_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "publish", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationCaseBlueprint" } } }, "description": "" }, "409": { "description": "A versão publicada ou a revisão de rascunho guardada foi alterada. Recarregue antes de tentar novamente." }, "403": { "description": "Falta a permissão de caso obrigatória." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.publish(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Publish(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().publish(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->publish('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.PublishAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/preview/": { "post": { "operationId": "organization_application_cases_requests_preview_create", "x-didit-sdk": { "resource": "cases.requests", "method": "preview", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewResponse" } } }, "description": "" }, "404": { "description": "O pedido ou caso não está disponível para este chamador." }, "403": { "description": "O chamador não possui a permissão de casos necessária." }, "400": { "description": "Entradas inválidas, finalidade não suportada, contacto verificado indisponível ou uma resposta imutável já existente." }, "409": { "description": "A pré-visualização mudou ou expirou. Pré-visualize novamente antes de confirmar." } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Gere o e-mail de produção sem enviar nem alterar o caso. Devolve o destinatário, o remetente, o assunto e o corpo exatos, bem como um preview_token assinado. Envie os mesmos contact_id, purpose, language, request_id, expires_at e preview_token para confirmar no prazo de 15 minutos.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.preview(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id=\"11111111-2222-3333-4444-555555555555\",\n purpose=\"identity_document\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.preview(\"11111111-2222-3333-4444-555555555555\", {\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Preview(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CustomerMessagingCaseRequestPreviewRequest{\n\tContactID: \"11111111-2222-3333-4444-555555555555\",\n\tPurpose: didit.CustomerMessagingPurposeEnum(\"identity_document\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CustomerMessagingCaseRequestPreviewRequest;\nimport me.didit.types.CustomerMessagingPurposeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().preview(\"11111111-2222-3333-4444-555555555555\", CustomerMessagingCaseRequestPreviewRequest.builder()\n .contactId(\"11111111-2222-3333-4444-555555555555\")\n .purpose(CustomerMessagingPurposeEnum.of(\"identity_document\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->preview('11111111-2222-3333-4444-555555555555', [\n 'contact_id' => '11111111-2222-3333-4444-555555555555',\n 'purpose' => 'identity_document',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.preview(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.PreviewAsync(\"11111111-2222-3333-4444-555555555555\", new CustomerMessagingCaseRequestPreviewRequest\n{\n ContactId = \"11111111-2222-3333-4444-555555555555\",\n Purpose = \"identity_document\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/action-receipts/": { "get": { "operationId": "action_receipts_retrieve", "x-didit-sdk": { "resource": "cases", "method": "list_action_receipts", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "query", "name": "offset", "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0 } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseActionReceiptPage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Listar recibos de ação do sujeito, dos mais recentes para os mais antigos, com no máximo 20 resultados por página. Utilize next_offset para a página seguinte. O texto da nota de entrada não é exposto no histórico.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_action_receipts(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listActionReceipts(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListActionReceipts(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesListActionReceiptsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listActionReceipts(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listActionReceipts('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.list_action_receipts(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListActionReceiptsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/{note_uuid}/": { "delete": { "operationId": "delete_network_note", "x-didit-sdk": { "resource": "networks.notes", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "Eliminar a sua nota de rede", "description": "Requer write:networks e o autor autenticado da nota. A eliminação é irreversível. Os dados da conta conectada e de verificação não são afetados.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da rede." }, { "name": "note_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token de acesso do utilizador da consola no formato Bearer ." } ], "responses": { "204": { "description": "Nota eliminada." }, "401": { "description": "A autenticação é obrigatória." }, "403": { "description": "Permissão ou acesso a Networks em falta." }, "404": { "description": "A rede ou nota não está visível para esta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nclient.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nawait didit.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nif err := client.Networks.Notes.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesDeleteParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nclient.networks().notes().delete(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "networks->notes->delete('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ndidit.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nawait client.Networks.Notes.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/action-receipts/{receipt_uuid}/retry/": { "post": { "operationId": "action_receipts_retry_create", "x-didit-sdk": { "resource": "cases", "method": "retry_action_receipt", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "receipt_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Tentar novamente apenas esta ação de sujeito com falha utilizando as respetivas entradas guardadas. A permissão de escrita atual é verificada. As ações aplicadas devolvem o respetivo recibo sem executar novamente. O encerramento do caso é independente.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retry_action_receipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retryActionReceipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RetryActionReceipt(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retryActionReceipt(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retryActionReceipt('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retry_action_receipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetryActionReceiptAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/draft/": { "get": { "operationId": "get_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "retrieve_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftResponse" } } }, "description": "" }, "403": { "description": "Falta a permissão de caso obrigatória." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.retrieve_draft(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.RetrieveDraft(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->retrieveDraft('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.retrieve_draft(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.RetrieveDraftAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "put": { "operationId": "save_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "save_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" }, "example": { "expected_version": 1, "expected_revision": "4e5f0000-0000-4000-8000-000000000003", "changes": { "max_active_cases": 20 } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraft" } } }, "description": "" }, "409": { "description": "A versão publicada ou a revisão de rascunho guardada foi alterada. Recarregue antes de tentar novamente." }, "403": { "description": "Falta a permissão de caso obrigatória." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=1,\n expected_revision=\"4e5f0000-0000-4000-8000-000000000003\",\n changes={\"max_active_cases\": 20},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.saveDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { max_active_cases: 20 },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.SaveDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftWriteRequest{\n\tExpectedVersion: 1,\n\tExpectedRevision: didit.String(\"4e5f0000-0000-4000-8000-000000000003\"),\n\tChanges: map[string]any{\"max_active_cases\": 20},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftWriteRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().saveDraft(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftWriteRequest.builder()\n .expectedVersion(1L)\n .expectedRevision(\"4e5f0000-0000-4000-8000-000000000003\")\n .changes(Map.of(\"max_active_cases\", 20))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->saveDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 1,\n 'expected_revision' => '4e5f0000-0000-4000-8000-000000000003',\n 'changes' => ['max_active_cases' => 20],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { max_active_cases: 20 }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.SaveDraftAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftWriteRequest\n{\n ExpectedVersion = 1,\n ExpectedRevision = \"4e5f0000-0000-4000-8000-000000000003\",\n Changes = new Dictionary { [\"max_active_cases\"] = 20 },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "discard_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "discard_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "204": { "description": "Sem corpo de resposta" }, "409": { "description": "A versão publicada ou a revisão de rascunho guardada foi alterada. Recarregue antes de tentar novamente." }, "403": { "description": "Falta a permissão de caso obrigatória." } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.blueprints.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.blueprints.discardDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Blueprints.DiscardDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().blueprints().discardDraft(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->discardDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Blueprints.DiscardDraftAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/teams/{record_uuid}/": { "get": { "summary": "Obter equipa de revisão", "description": "Requer `read:cases` para a aplicação solicitada.", "operationId": "retrieve_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." }, "404": { "description": "Registo não encontrado nesta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Atualizar equipa de revisão", "description": "Requer `write:cases` para a aplicação solicitada.", "operationId": "update_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." }, "404": { "description": "Registo não encontrado nesta aplicação." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeamUpdate" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"your-name\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"your-name\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseReviewTeamUpdate{\n\tName: didit.String(\"your-name\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseReviewTeamUpdate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().update(\"11111111-2222-3333-4444-555555555555\", CaseReviewTeamUpdate.builder()\n .name(\"your-name\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'your-name',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"your-name\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseReviewTeamUpdate\n{\n Name = \"your-name\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/report/": { "get": { "operationId": "download_network_report", "x-didit-sdk": { "resource": "networks", "method": "download_report", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "Descarregar um relatório de prova de rede", "description": "Descarregue um PDF da rede da organização atual, das respetivas ligações de conta observadas, referências de sinais e estado de revisão. Requer read:networks. As informações de inteligência global e as notas privadas de analistas não estão incluídas. Cada lista de contas e sinais está limitada a 500 entradas e o relatório indica quando está incompleto. O pedido não altera o estado da rede. Os erros são devolvidos em formato JSON.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da rede." }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token de acesso do utilizador da consola no formato Bearer ." } ], "responses": { "200": { "description": "Relatório de evidências da rede. Cache-Control: no-store.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "A autenticação é obrigatória." }, "403": { "description": "Permissão ou acesso a Networks em falta." }, "404": { "description": "A rede ou nota não está visível para esta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\ncontent = client.networks.download_report(\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nconst content = await didit.networks.downloadReport(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nresp, err := client.Networks.DownloadReport(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksDownloadReportParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nclient.networks().downloadReport(\"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build())\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "networks->downloadReport('11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ncontent = didit.networks.download_report(\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nvar content = await client.Networks.DownloadReportAsync(\"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/": { "get": { "operationId": "list_network_notes", "x-didit-sdk": { "resource": "networks.notes", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "Listar notas privadas da rede", "description": "Utilizadores da consola com read:networks podem ler notas numa rede visível para a aplicação. As notas permanecem dentro da organização e não são contribuídas para a inteligência partilhada. As notas mais recentes aparecem primeiro.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da rede." }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token de acesso do utilizador da consola no formato Bearer ." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Uma página de notas. A contagem está limitada a 100; use next para continuar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNote" } } } } } } }, "401": { "description": "A autenticação é obrigatória." }, "403": { "description": "Permissão ou acesso a Networks em falta." }, "404": { "description": "A rede ou nota não está visível para esta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nfor item in client.networks.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nfor await (const item of didit.networks.notes.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\niter := client.Networks.Notes.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesListParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nfor (var item : client.networks().notes().list(\"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build())) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "networks->notes->list('11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]) as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ndidit.networks.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n).auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Networks.Notes.ListAsync(\"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n}))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "create_network_note", "x-didit-sdk": { "resource": "networks.notes", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "Adicionar uma nota privada de rede", "description": "Requer um utilizador da consola com write:networks. O autor é atribuído a partir do utilizador autenticado. Forneça um novo client_reference UUID aleatório para cada nota; tente novamente com o mesmo corpo e referência após uma resposta incerta para evitar duplicados. A reutilização de uma referência para outro corpo, autor ou rede devolve 409. As notas acompanham a investigação que prevalece quando as redes são fundidas.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da rede." }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token de acesso do utilizador da consola no formato Bearer ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comment", "client_reference" ], "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "client_reference": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Nota privada guardada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkNote" } } } }, "200": { "description": "Nota privada guardada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkNote" } } } }, "400": { "description": "Nota inválida ou em branco." }, "409": { "description": "A referência já foi utilizada para outra nota." }, "401": { "description": "A autenticação é obrigatória." }, "403": { "description": "Permissão ou acesso a Networks em falta." }, "404": { "description": "A rede ou nota não está visível para esta aplicação." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nresult = client.networks.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment=\"your-comment\",\n client_reference=\"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nconst result = await didit.networks.notes.create(\"11111111-2222-3333-4444-555555555555\", {\n comment: \"your-comment\",\n client_reference: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nresult, err := client.Networks.Notes.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesCreateParams{\n\tComment: \"your-comment\",\n\tClientReference: \"11111111-2222-3333-4444-555555555555\",\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\nimport me.didit.types.NetworksNotesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nvar result = client.networks().notes().create(\"11111111-2222-3333-4444-555555555555\", NetworksNotesCreateParams.builder()\n .comment(\"your-comment\")\n .clientReference(\"11111111-2222-3333-4444-555555555555\")\n .build(), RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->notes->create('11111111-2222-3333-4444-555555555555', [\n 'comment' => 'your-comment',\n 'client_reference' => '11111111-2222-3333-4444-555555555555',\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\nresult = didit.networks.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment: \"your-comment\",\n client_reference: \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.Notes.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new NetworksNotesCreateParams\n{\n Comment = \"your-comment\",\n ClientReference = \"11111111-2222-3333-4444-555555555555\",\n}, requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/draft/": { "get": { "operationId": "get_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "retrieve_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftResponse" } } }, "description": "" }, "403": { "description": "É necessário acesso ao caso." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.retrieve_draft(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.RetrieveDraft(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->retrieveDraft('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.retrieve_draft(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.RetrieveDraftAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "put": { "operationId": "save_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "save_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" }, "example": { "expected_version": 1, "expected_revision": "4e5f0000-0000-4000-8000-000000000003", "changes": { "priority": 10 } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraft" } } }, "description": "" }, "403": { "description": "É necessário acesso ao caso." }, "409": { "description": "A versão publicada ou revisão do rascunho mudou. Recarregue antes de tentar novamente." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=1,\n expected_revision=\"4e5f0000-0000-4000-8000-000000000003\",\n changes={\"priority\": 10},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.saveDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { priority: 10 },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.SaveDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftWriteRequest{\n\tExpectedVersion: 1,\n\tExpectedRevision: didit.String(\"4e5f0000-0000-4000-8000-000000000003\"),\n\tChanges: map[string]any{\"priority\": 10},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftWriteRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().saveDraft(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftWriteRequest.builder()\n .expectedVersion(1L)\n .expectedRevision(\"4e5f0000-0000-4000-8000-000000000003\")\n .changes(Map.of(\"priority\", 10))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->saveDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 1,\n 'expected_revision' => '4e5f0000-0000-4000-8000-000000000003',\n 'changes' => ['priority' => 10],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { priority: 10 }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.SaveDraftAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftWriteRequest\n{\n ExpectedVersion = 1,\n ExpectedRevision = \"4e5f0000-0000-4000-8000-000000000003\",\n Changes = new Dictionary { [\"priority\"] = 10 },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "discard_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "discard_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "responses": { "204": { "description": "Sem corpo de resposta" }, "403": { "description": "É necessário acesso ao caso." }, "409": { "description": "A versão publicada ou revisão do rascunho mudou. Recarregue antes de tentar novamente." } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.routing_rules.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.routingRules.discardDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.RoutingRules.DiscardDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().routingRules().discardDraft(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->discardDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.RoutingRules.DiscardDraftAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/duplicates/": { "post": { "operationId": "duplicates_create", "x-didit-sdk": { "resource": "cases", "method": "find_duplicates", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" }, "example": { "subject": { "type": "user", "uuid": "5b9a0000-0000-4000-8000-00000000f00d" } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicatePage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Reveja casos existentes para um sujeito ou registo de origem que lhe pertença antes da criação manual de casos. São devolvidas investigações abertas e resolvidas. Cada página contém no máximo 20 casos; utilize next_offset para pedir outra página.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.find_duplicates(\n subject={\n \"type\": \"user\",\n \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.findDuplicates({\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.FindDuplicates(ctx, didit.CaseDuplicateCaseDuplicateQueryRequest{\n\tSubject: didit.Some(didit.CaseDuplicateCaseSubjectInputRequest{\n\t\tType: didit.CaseDuplicateTypeEnum(\"user\"),\n\t\tUUID: \"5b9a0000-0000-4000-8000-00000000f00d\",\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseDuplicateCaseDuplicateQueryRequest;\nimport me.didit.types.CaseDuplicateCaseSubjectInputRequest;\nimport me.didit.types.CaseDuplicateTypeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().findDuplicates(CaseDuplicateCaseDuplicateQueryRequest.builder()\n .subject(CaseDuplicateCaseSubjectInputRequest.builder()\n .type(CaseDuplicateTypeEnum.of(\"user\"))\n .uuid(\"5b9a0000-0000-4000-8000-00000000f00d\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->findDuplicates([\n 'subject' => [\n 'type' => 'user',\n 'uuid' => '5b9a0000-0000-4000-8000-00000000f00d',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.find_duplicates(\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.FindDuplicatesAsync(new CaseDuplicateCaseDuplicateQueryRequest\n{\n Subject = new CaseDuplicateCaseSubjectInputRequest\n {\n Type = \"user\",\n Uuid = \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/preview/": { "post": { "summary": "Encaminhamento de casos de teste", "description": "Requer `read:cases` para a aplicação solicitada. Avalia as regras atuais ou um rascunho fornecido em relação ao acesso, disponibilidade, competências e capacidade atuais do revisor. Não guarda o rascunho nem reserva capacidade do revisor.", "operationId": "preview_case_routing", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "preview", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingPreview" } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingPreviewRequest" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.preview(\n source=\"MANUAL\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.preview({\n source: \"MANUAL\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Preview(ctx, didit.CaseRoutingPreviewRequest{\n\tSource: \"MANUAL\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseRoutingPreviewRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().preview(CaseRoutingPreviewRequest.builder()\n .source(CaseRoutingPreviewRequest.Source.of(\"MANUAL\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->preview([\n 'source' => 'MANUAL',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.preview(source: \"MANUAL\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.PreviewAsync(new CaseRoutingPreviewRequest\n{\n Source = \"MANUAL\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/reviewers/": { "get": { "summary": "Listar revisores de casos elegíveis", "description": "Requer `list:cases` para a aplicação solicitada.", "operationId": "list_case_reviewers", "x-didit-sdk": { "resource": "cases", "method": "list_reviewers", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } } } } } } } }, "400": { "description": "Entrada inválida." }, "403": { "description": "Permissão insuficiente." }, "503": { "description": "Não foi possível verificar o acesso do revisor. Tente novamente mais tarde." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_reviewers()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listReviewers();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListReviewers(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listReviewers();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listReviewers();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.list_reviewers\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListReviewersAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/history/": { "get": { "operationId": "list_case_blueprint_history", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list_history", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "Qual o campo a utilizar para ordenar os resultados.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Número de resultados a devolver por página.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "O índice inicial a partir do qual devolver os resultados.", "schema": { "type": "integer" } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPaginatedPolicyRevisionList" } } }, "description": "" }, "403": { "description": "Falta a permissão de caso obrigatória." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.blueprints.list_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.blueprints.listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Blueprints.ListHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesBlueprintsListHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().blueprints().listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->listHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.list_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Blueprints.ListHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/documents/{documentId}/file/": { "get": { "summary": "Descarregar um documento assinado", "description": "Descarregue o PDF assinado de um documento de um passo de Assinatura eletrónica. Utilize o caminho `signed_file` de `signatures[].documents[]` na decisão. O PDF contém o documento apresentado ao signatário com os respetivos valores de campos inseridos e a página de prova (exceto se `signature_evidence_page` estiver desativado). Um PDF Avançado (AES) inclui também a assinatura PAdES com o respetivo carimbo temporal; um PDF Simples não possui assinatura digital, selo nem carimbo temporal. A Didit compara o ficheiro com `sha256_signed` antes de o devolver.\n\nFunciona para sessões de Verificação de utilizadores (KYC) e Verificação de empresas (KYB). Requer `read:sessions`; a sua chave de API funciona. Consulte o [relatório de Assinatura eletrónica](/pt/core-technology/electronic-signature/report-electronic-signature#descarregar-os-documentos-assinados).", "operationId": "get_v3_session_signature_document_file", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_document", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "A sessão de Verificação de utilizadores (KYC) ou Verificação de empresas (KYB).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "O passo de Assinatura eletrónica: `node_id` do item em `signatures[]`.", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "documentId", "in": "path", "required": true, "description": "`id` do documento em `signatures[].documents[]`.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "O PDF assinado.", "headers": { "Content-Disposition": { "description": "Anexo com o nome do ficheiro.", "schema": { "type": "string", "example": "attachment; filename=\"agreement-signed.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Credenciais em falta, ou uma credencial que não consegue ler esta sessão. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "Nenhum documento assinado corresponde: a sessão, o passo ou o documento não existe, foi eliminado ou ainda não foi assinado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed yet": { "summary": "O signatário não assinou", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } }, "Unknown document": { "summary": "Não existe esse documento neste passo", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "O ficheiro armazenado já não corresponde ao seu SHA-256 registado. Nada é retornado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Changed file": { "summary": "O ficheiro guardado não corresponde ao seu hash", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_document(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadDocument(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadDocument(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadDocument(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadDocument('11111111-2222-3333-4444-555555555555', 'feature_signature', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_document(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadDocumentAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/evidence/": { "get": { "summary": "Descarregar a prova da assinatura", "description": "Descarregue o PDF de prova de um signatário: o nível e formato, o signatário, o endereço IP, cada documento com o respetivo SHA-256 original e valores de campos e o SHA-256 de cada ficheiro assinado, além de, para uma Assinatura Avançada (AES), a sessão de identidade verificada, a confirmação de código, o certificado e o carimbo temporal. Utilize o caminho `evidence_file` do elemento do signatário em `signatures[]`.\n\nPasse sempre `signature_id` quando um passo de Verificação de empresas (KYB) tiver vários signatários: sem ele, a rota escolhe um dos signatários do passo. Requer `read:sessions`; a sua chave de API funciona.", "operationId": "get_v3_session_signature_evidence", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_evidence", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "A sessão de Verificação de utilizadores (KYC) ou Verificação de empresas (KYB).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "O passo de Assinatura eletrónica: `node_id` do item em `signatures[]`.", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "signature_id", "in": "query", "required": false, "description": "`id` do item do signatário em `signatures[]`.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "O PDF de provas.", "headers": { "Content-Disposition": { "description": "Anexo com o nome do ficheiro.", "schema": { "type": "string", "example": "attachment; filename=\"signature-evidence.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Credenciais em falta, ou uma credencial que não consegue ler esta sessão. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "Nenhuma evidência corresponde: a sessão, passo ou signatário não existe, foi eliminado ou ainda não assinou.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed yet": { "summary": "O signatário não assinou", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } }, "Unknown signer": { "summary": "Não existe essa assinatura neste passo", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "O ficheiro armazenado já não corresponde ao seu SHA-256 registado. Nada é retornado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Changed file": { "summary": "O ficheiro guardado não corresponde ao seu hash", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_evidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadEvidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n);\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadEvidence(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", didit.SessionsSignaturesDownloadEvidenceParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadEvidence(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadEvidence('11111111-2222-3333-4444-555555555555', 'feature_signature');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_evidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadEvidenceAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/fields/{fieldId}/image/": { "get": { "summary": "Descarregar uma imagem da assinatura", "description": "Descarregue a assinatura ou rubrica que um signatário aplicou a um campo, em formato PNG. Utilize o `image_url` do campo em `signatures[].documents[].fields[]`. Requer `read:sessions`; a sua chave de API funciona.", "operationId": "get_v3_session_signature_field_image", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_field_image", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "A sessão de Verificação de utilizadores (KYC) ou Verificação de empresas (KYB).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "O passo de Assinatura eletrónica: `node_id` do item em `signatures[]`.", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "fieldId", "in": "path", "required": true, "description": "O campo na cópia deste signatário, como no `image_url` do campo.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "A imagem.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "A imagem armazenada já não corresponde ao seu SHA-256 registado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "example": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } }, "403": { "description": "Credenciais em falta, ou uma credencial que não consegue ler esta sessão. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "Nenhuma imagem corresponde: a sessão, passo ou campo não existe, foi eliminado ou não tem assinatura ou iniciais aplicadas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Unknown field": { "summary": "Não existe esse campo", "value": { "code": "signature_field_not_found", "detail": "signature_field_not_found" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_field_image(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.png\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadFieldImage(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.png\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadFieldImage(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.png\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadFieldImage(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.png\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadFieldImage('11111111-2222-3333-4444-555555555555', 'feature_signature', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.png');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_field_image(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.png\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadFieldImageAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.png\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/validate/": { "post": { "summary": "Validar assinaturas novamente", "description": "Volte a verificar os documentos assinados de um passo de Assinatura eletrónica. O Didit relê cada PDF assinado, verifica o respetivo SHA-256 e, para uma assinatura avançada (AES), valida a assinatura PAdES, o certificado, os dados de revogação e o carimbo de data/hora (uma assinatura simples não possui assinatura digital, pelo que apenas a integridade do ficheiro é verificada), guardando em seguida o resultado na `validation` de cada signatário e devolvendo os itens atualizados. Nada é assinado novamente. Envie `signature_id` para verificar um signatário; sem este parâmetro, todos os signatários do passo são verificados e a chamada falha se algum deles não tiver assinado.\n\nRequer `write:sessions`; a sua chave de API funciona. Na consola, corresponde ao botão **Validate again**.", "operationId": "post_v3_session_signature_validate", "x-didit-sdk": { "resource": "sessions.signatures", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "A sessão de Verificação de utilizadores (KYC) ou Verificação de empresas (KYB).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "O passo de Assinatura eletrónica: `node_id` do item em `signatures[]`.", "schema": { "type": "string", "example": "feature_signature" } } ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature_id": { "type": "string", "format": "uuid", "description": "`id` do item de um signatário em `signatures[]`." } } }, "example": { "signature_id": "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10" } } } }, "responses": { "200": { "description": "Os signatários verificados, com a respetiva `validation` atualizada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureResult" } } } } } } }, "400": { "description": "Um PDF assinado armazenado já não corresponde ao SHA-256 registado quando foi assinado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Document changed": { "summary": "Um ficheiro assinado já não coincide com o respetivo hash", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } }, "403": { "description": "Credenciais em falta, ou uma credencial que não consegue ler esta sessão. Uma chave em falta devolve `403`; uma chave incorreta, revogada ou expirada devolve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "Nenhuma assinatura corresponde: a sessão, o passo ou o signatário não existe ou foi eliminado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Unknown signer": { "summary": "Não existe essa assinatura neste passo", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "Um signatário do passo ainda não assinou, pelo que não há nada para validar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed": { "summary": "Um signatário ainda não assinou", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n signature_id=\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n {\n signature_id: \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Signatures.Validate(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", didit.SessionsSignaturesValidateParams{\n\tSignatureID: didit.String(\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsSignaturesValidateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().signatures().validate(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", SessionsSignaturesValidateParams.builder()\n .signatureId(\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->validate('11111111-2222-3333-4444-555555555555', 'feature_signature', [\n 'signature_id' => '0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n signature_id: \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Signatures.ValidateAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", new SessionsSignaturesValidateParams\n{\n SignatureId = \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/document-ai/{sessionId}/documents/{documentUuid}/": { "patch": { "summary": "Atualizar um documento do Document AI", "description": "Corrija os campos que o Document AI extraiu de um documento carregado, defina o respetivo estado de revisão, ou ambos, numa sessão de KYC ou KYB. `extracted_data` deve ser um objeto JSON e é combinado chave a chave: uma chave que envie substitui o valor guardado (uma chave enviada como `null` é guardada como `null`) e as chaves omitidas mantêm os seus valores. O estado do documento alimenta o resultado de Document AI do respetivo nó de fluxo na decisão da sessão; o estado da sessão em si não é recalculado. Cada chamada bem-sucedida, incluindo uma que não altere nada, envia um [webhook](https://docs.didit.me/pt/integration/webhooks) `data.updated` com o acionador `manual_review`. Uma chave de API com âmbito necessita de `decisions: write`; consulte [Document AI](https://docs.didit.me/pt/core-technology/document-ai/overview).", "operationId": "patch_v3_document_ai_document", "x-didit-sdk": { "resource": "sessions", "method": "update_document_ai_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação (o `session_id` retornado por `POST /v3/session/`). Aceita IDs de sessão de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB): o servidor resolve o ID em ambos os tipos de sessão. Deve ser um UUID bem formatado; um valor mal formatado não corresponde à rota e retorna um `404` em HTML.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "documentUuid", "in": "path", "required": true, "description": "UUID do documento de Document AI (`document_ai_documents[].items[].uuid` em `GET /v3/session/{sessionId}/decision/`). Tem de pertencer à sessão indicada no caminho.", "schema": { "type": "string", "format": "uuid", "example": "44444444-5555-6666-7777-888888888888" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "extracted_data": { "type": "object", "additionalProperties": true, "description": "Chaves dos campos (as chaves que configurou para o documento) e os respetivos valores corrigidos. Tem de ser um objeto JSON; é intercalado chave a chave nos dados armazenados. Omita este campo em vez de enviar `null`, o que devolve `400`.", "example": { "invoice_number": "INV-2026-0042" } }, "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished" ], "description": "Novo estado de revisão do documento.", "example": "Approved" } } }, "example": { "extracted_data": { "invoice_number": "INV-2026-0042" }, "status": "Approved" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/document-ai/11111111-2222-3333-4444-555555555555/documents/44444444-5555-6666-7777-888888888888/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"extracted_data\": {\"invoice_number\": \"INV-2026-0042\"}, \"status\": \"Approved\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_document_ai_data(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n extracted_data={\"invoice_number\": \"INV-2026-0042\"},\n status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateDocumentAiData(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n {\n extracted_data: { invoice_number: \"INV-2026-0042\" },\n status: \"Approved\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateDocumentAiData(ctx, \"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", didit.SessionsUpdateDocumentAiDataParams{\n\tExtractedData: didit.Some(map[string]any{\"invoice_number\": \"INV-2026-0042\"}),\n\tStatus: didit.Some(didit.SessionsUpdateDocumentAiDataParamsStatus(\"Approved\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateDocumentAiDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateDocumentAiData(\"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", SessionsUpdateDocumentAiDataParams.builder()\n .extractedData(Map.of(\"invoice_number\", \"INV-2026-0042\"))\n .status(SessionsUpdateDocumentAiDataParams.Status.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateDocumentAiData('11111111-2222-3333-4444-555555555555', '44444444-5555-6666-7777-888888888888', [\n 'extracted_data' => ['invoice_number' => 'INV-2026-0042'],\n 'status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_document_ai_data(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n extracted_data: { invoice_number: \"INV-2026-0042\" },\n status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateDocumentAiDataAsync(\"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", new SessionsUpdateDocumentAiDataParams\n{\n ExtractedData = new Dictionary { [\"invoice_number\"] = \"INV-2026-0042\" },\n Status = new SessionsUpdateDocumentAiDataParamsStatus(\"Approved\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Documento atualizado. Devolve o documento após a intercalação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "uuid", "document_key", "original_filename", "file_url", "status", "extracted_data" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador do documento." }, "document_key": { "type": "string", "description": "O documento configurado a que este carregamento corresponde." }, "original_filename": { "type": "string", "nullable": true, "description": "Nome do ficheiro com o qual o documento foi carregado." }, "file_url": { "type": "string", "nullable": true, "description": "Caminho de armazenamento do ficheiro carregado. Não é uma ligação de transferência: leia o `file_url` pré-assinado a partir da decisão da sessão para transferir o ficheiro." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado de revisão do documento." }, "extracted_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Todos os campos extraídos após a união, indexados pela chave do campo." } } }, "example": { "uuid": "44444444-5555-6666-7777-888888888888", "document_key": "invoice", "original_filename": "invoice-2026-09.pdf", "file_url": "document_ai/11111111-2222-3333-4444-555555555555-66666666-7777-8888-9999-000000000000.pdf", "status": "Approved", "extracted_data": { "invoice_number": "INV-2026-0042", "total_amount": 1250.0, "issue_date": "2026-09-01" } } } } }, "400": { "description": "Erro de validação, verificado antes da consulta do documento: `status` não é um dos valores permitidos ou `extracted_data` foi enviado como `null`.", "content": { "application/json": { "examples": { "Invalid status": { "summary": "status não consta do enum", "value": { "status": [ "\"Rejected\" is not a valid choice." ] } }, "Null extracted_data": { "summary": "extracted_data é null", "value": { "extracted_data": [ "This field may not be null." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada ou está fora dos limites de uma chave com âmbito restrito, ou nenhum documento atual com este UUID lhe pertence. A pesquisa da sessão é executada antes da verificação de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo sem uma chave válida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "summary": "Não existe nenhuma sessão com este ID ou foi eliminada", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "A sessão está fora dos limites de uma chave com âmbito restrito (também devolvido para uma sessão eliminada há momentos)", "value": { "detail": "Session not found." } }, "Unknown document": { "summary": "documentUuid não pertence à sessão", "value": { "detail": "Document AI document not found." } } } } } }, "429": { "description": "Limite de pedidos excedido: 300 pedidos de escrita (POST, PATCH, DELETE) por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/aml/dataset-freshness/": { "get": { "summary": "Obter a atualidade do conjunto de dados AML", "description": "Indica a atualidade dos conjuntos de dados por detrás da triagem AML, por família de fontes (`sanctions`, `pep`, `warnings`, `adverse_media`), como prova de auditoria para a [monitorização AML contínua](https://docs.didit.me/pt/core-technology/aml-screening/continuous-monitoring-aml-screening#comprovar-a-execução-da-monitorização). A resposta abrange toda a plataforma: nenhuma sessão no caminho, nenhum dado de cliente no corpo, a mesma resposta para todas as aplicações.\n\nSempre `200` para uma chave aceite. Verifique primeiro a `availability`: quando não estiver `available`, `dataset_freshness` será `null`. As datas nunca são estimadas: uma família cujos conjuntos de dados não reportaram qualquer data está ausente de `sources`, e uma família em que apenas alguns conjuntos de dados reportaram uma tem `oldest_updated_at: null`. As leituras são recolhidas enquanto a monitorização contínua é executada, e não em cada chamada; `captured_at` indica quando.\n\nUma chave de API com âmbito precisa de `sessions: read`; uma chave limitada a determinados fluxos ou a sessões aprovadas não pode chamar este endpoint. Nada é faturado.", "operationId": "get_aml_dataset_freshness", "x-didit-sdk": { "resource": "aml", "method": "retrieve_dataset_freshness", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/aml/dataset-freshness/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml.retrieve_dataset_freshness()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.aml.retrieveDatasetFreshness();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AML.RetrieveDatasetFreshness(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.aml().retrieveDatasetFreshness();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "aml->retrieveDatasetFreshness();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml.retrieve_dataset_freshness\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Aml.RetrieveDatasetFreshnessAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A leitura mais recente da atualidade do conjunto de dados, ou `null` com o motivo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset_freshness", "availability" ], "properties": { "dataset_freshness": { "allOf": [ { "$ref": "#/components/schemas/AMLDatasetFreshness" } ], "nullable": true, "description": "A leitura mais recente, ou `null` quando `availability` não for `available`." }, "availability": { "type": "string", "enum": [ "available", "not_configured", "not_yet_collected" ], "description": "`available` quando existe uma leitura; `not_configured` quando as datas do conjunto de dados não são recolhidas neste ambiente; `not_yet_collected` quando a recolha está configurada, mas ainda não existe nenhuma leitura." } } }, "examples": { "Available": { "value": { "dataset_freshness": { "captured_at": "2026-10-17T06:00:12.345678+00:00", "provider": "aml_data_source", "catalog_version": "20261017054500-abc", "sources": { "sanctions": { "last_updated_at": "2026-10-17T04:10:00+00:00", "oldest_updated_at": "2026-10-15T22:30:00+00:00", "dataset_count": 48, "dated_dataset_count": 48 }, "pep": { "last_updated_at": "2026-10-16T23:05:00+00:00", "oldest_updated_at": null, "dataset_count": 12, "dated_dataset_count": 11 } } }, "availability": "available" } }, "Not collected yet": { "value": { "dataset_freshness": null, "availability": "not_yet_collected" } } } } } }, "401": { "description": "A chave de API expirou. Apenas uma chave criada com uma data de validade pode expirar; após essa data, cada pedido com ela responde `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Uma chave em falta recebe a mensagem genérica; uma chave incorreta, revogada ou expirada recebe `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Mais de 600 pedidos GET por minuto com esta chave de API. Aguarde o número de segundos indicado em `Retry-After` e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos até que a janela atual de um minuto seja reposta.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos por minuto neste orçamento.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Hora Unix em que a janela é reposta.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/": { "get": { "summary": "Listar listas", "description": "Devolve as listas da aplicação, ordenadas pela mais recente primeiro: as listas de sistema que a Didit disponibiliza (uma lista de bloqueio por tipo de entrada, a lista personalizada **High Risk Countries** e qualquer lista de permissões do sistema) e as listas de permissões e listas personalizadas que criou. Filtre com `list_type` e `entry_type`; as listas eliminadas nunca são apresentadas. Os resultados são paginados com `limit` e `offset`. Uma chave de API com âmbito restrito necessita de `workflows: read`. Consulte [Listas](https://docs.didit.me/pt/management-api/lists/overview) para saber o que faz cada tipo de lista.", "operationId": "list_lists", "x-didit-sdk": { "resource": "lists", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_type", "in": "query", "required": false, "description": "Apenas listas deste tipo.", "schema": { "type": "string", "enum": [ "blocklist", "allowlist", "custom" ] } }, { "name": "entry_type", "in": "query", "required": false, "description": "Apenas listas deste tipo de entrada.", "schema": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ] } }, { "name": "ordering", "in": "query", "required": false, "description": "Ordem de ordenação: `-created_at` (mais recentes primeiro, a predefinição) ou `created_at` (mais antigos primeiro).", "schema": { "type": "string", "enum": [ "-created_at", "created_at" ], "default": "-created_at" } }, { "name": "limit", "in": "query", "required": false, "description": "Tamanho da página. A predefinição é 50. Um valor superior a 1000000 devolve `400`; zero, um valor negativo ou um valor não numérico reverte para 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "Índice de base zero do primeiro item a devolver. Prefira seguir `next`. Um valor superior a 1000000 devolve `400`; um valor negativo ou não numérico reverte para 0.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/?list_type=blocklist' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.lists.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.lists.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Lists.ListAutoPaging(ctx, didit.ListsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.lists().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "lists->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Lists.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de listas.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Número total de listas correspondentes aos filtros." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceList" } } } }, "examples": { "Lists": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "22222222-3333-4444-5555-666666666666", "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address", "is_system": false, "entry_count": 3, "last_entry_added_at": "2026-10-02T08:15:27.501334Z", "created_at": "2026-09-30T13:20:45.889120Z", "updated_at": "2026-09-30T13:20:45.889120Z" }, { "uuid": "11111111-2222-3333-4444-555555555555", "name": "Face Blocklist", "description": "Blocked biometric faces. When a face matching an entry in this list is detected during liveness verification, the session will be automatically declined.", "list_type": "blocklist", "entry_type": "face", "is_system": true, "entry_count": 12, "last_entry_added_at": "2026-10-09T16:42:03.118204Z", "created_at": "2026-01-14T10:02:11.402917Z", "updated_at": "2026-01-14T10:02:11.402917Z" } ] } } } } } }, "400": { "description": "Um parâmetro de consulta é inválido.", "content": { "application/json": { "examples": { "Unknown list type": { "value": { "list_type": [ "\"denylist\" is not a valid choice." ] } }, "Unsupported ordering": { "value": { "ordering": [ "\"name\" is not a valid choice." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: read` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "429": { "description": "O limite de leitura partilhado de 600 pedidos por minuto por chave de API foi excedido. Respeite o `Retry-After` antes de tentar novamente.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar uma lista", "description": "Cria uma lista de permissões ou uma lista personalizada na aplicação à qual a chave de API pertence. As listas de bloqueio não podem ser criadas: a Didit disponibiliza uma lista de bloqueio do sistema por tipo de entrada, à qual adiciona itens com [Criar uma entrada de lista](https://docs.didit.me/pt/management-api/lists/create-entry). O `entry_type` não pode ser alterado após a criação e determina como os valores de entrada são validados e correspondidos. As entradas da lista de permissões marcam os itens correspondentes como fidedignos (por exemplo, uma lista de permissões de rostos ignora a ação de rosto duplicado) e nunca sobrepõem uma correspondência com a lista de bloqueio; faça referência a qualquer lista a partir de uma condição de regra de fluxo ou de transação com `value_type: \"list\"`. Uma chave de API com âmbito necessita de `workflows: write`.", "operationId": "create_list", "x-didit-sdk": { "resource": "lists", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "list_type", "entry_type" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Nome da lista. Deve ser diferente do nome de todas as outras listas da aplicação, incluindo listas do sistema." }, "description": { "type": "string", "default": "", "description": "Descrição de texto livre opcional." }, "list_type": { "type": "string", "enum": [ "allowlist", "custom" ], "description": "`allowlist` ou `custom`. `blocklist` é recusada com `400`." }, "entry_type": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ], "description": "O que a lista contém: `face`, `document` (número do documento), `phone`, `email`, `ip_address` (endereço IP ou intervalo CIDR), `device_fingerprint`, `wallet_address`, `bank_account`, `country` (ISO 3166-1 alfa-3), `user` ou `business` (o seu `vendor_data`), ou `key` (qualquer cadeia de carateres). Determina como os valores de entrada são validados e correspondidos. Não pode ser alterado posteriormente." } } }, "examples": { "IP allowlist": { "value": { "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address" } }, "Custom country list": { "value": { "name": "Enhanced due diligence countries", "list_type": "custom", "entry_type": "country" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"name\": \"Trusted office IPs\",\n \"description\": \"Office egress ranges\",\n \"list_type\": \"allowlist\",\n \"entry_type\": \"ip_address\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.create(\n name=\"Trusted office IPs\",\n description=\"Office egress ranges\",\n list_type=\"allowlist\",\n entry_type=\"ip_address\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.create({\n name: \"Trusted office IPs\",\n description: \"Office egress ranges\",\n list_type: \"allowlist\",\n entry_type: \"ip_address\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Create(ctx, didit.ListsCreateParams{\n\tName: \"Trusted office IPs\",\n\tDescription: didit.String(\"Office egress ranges\"),\n\tListType: \"allowlist\",\n\tEntryType: \"ip_address\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().create(ListsCreateParams.builder()\n .name(\"Trusted office IPs\")\n .description(\"Office egress ranges\")\n .listType(ListsCreateParams.ListType.of(\"allowlist\"))\n .entryType(ListsCreateParams.EntryType.of(\"ip_address\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->create([\n 'name' => 'Trusted office IPs',\n 'description' => 'Office egress ranges',\n 'list_type' => 'allowlist',\n 'entry_type' => 'ip_address',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.create(\n name: \"Trusted office IPs\",\n description: \"Office egress ranges\",\n list_type: \"allowlist\",\n entry_type: \"ip_address\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.CreateAsync(new ListsCreateParams\n{\n Name = \"Trusted office IPs\",\n Description = \"Office egress ranges\",\n ListType = \"allowlist\",\n EntryType = \"ip_address\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A lista foi criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceList" }, "examples": { "New allowlist": { "value": { "uuid": "22222222-3333-4444-5555-666666666666", "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address", "is_system": false, "entry_count": 0, "last_entry_added_at": null, "created_at": "2026-10-12T09:15:44.031876Z", "updated_at": "2026-10-12T09:15:44.031876Z" } } } } } }, "400": { "description": "O corpo é inválido.", "content": { "application/json": { "examples": { "Blocklist refused": { "value": { "list_type": [ "Cannot create additional blocklist lists. System blocklists are auto-created for each application." ] } }, "Duplicate name": { "value": { "name": [ "A list with this name already exists for this application." ] } }, "Missing fields": { "value": { "name": [ "This field is required." ], "list_type": [ "This field is required." ], "entry_type": [ "This field is required." ] } }, "Unknown entry type": { "value": { "entry_type": [ "\"iban\" is not a valid choice." ] } }, "Name too long": { "value": { "name": [ "Ensure this field has no more than 255 characters." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: write` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/": { "get": { "summary": "Obter lista", "description": "Retorna uma lista da aplicação com a respetiva contagem de entradas e quando a sua entrada mais recente foi adicionada. A lista de outra aplicação, ou uma que tenha sido eliminada, retorna `404`. Isto retorna apenas a lista: leia os seus valores com [Listar entradas da lista](https://docs.didit.me/pt/management-api/lists/list-entries). Uma chave de API com âmbito precisa de `workflows: read`.", "operationId": "get_list", "x-didit-sdk": { "resource": "lists", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID da lista, conforme retornado por Listar listas ou Criar uma lista.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A lista.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceList" }, "examples": { "System face blocklist": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "name": "Face Blocklist", "description": "Blocked biometric faces. When a face matching an entry in this list is detected during liveness verification, the session will be automatically declined.", "list_type": "blocklist", "entry_type": "face", "is_system": true, "entry_count": 12, "last_entry_added_at": "2026-10-09T16:42:03.118204Z", "created_at": "2026-01-14T10:02:11.402917Z", "updated_at": "2026-01-14T10:02:11.402917Z" } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: read` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "404": { "description": "Não existe nenhuma lista com este UUID na aplicação da chave de API, ou foi eliminada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "description": "O limite de leitura partilhado de 600 pedidos por minuto por chave de API foi excedido. Respeite o `Retry-After` antes de tentar novamente.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar uma lista", "description": "Renomeia uma lista ou altera a sua descrição. Apenas `name` e `description` são lidos; qualquer outro campo é ignorado, pelo que `list_type` e `entry_type` mantêm os valores com que foram criados. As listas de sistema não podem ser modificadas e devolvem `400`. A resposta contém apenas `name` e `description`: chame [Obter uma lista](https://docs.didit.me/pt/management-api/lists/get) para obter a lista completa. Uma chave de API com um âmbito definido necessita de `workflows: write`.", "operationId": "update_list", "x-didit-sdk": { "resource": "lists", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID da lista, conforme retornado por Listar listas ou Criar uma lista.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Novo nome. Deve diferir do nome de qualquer outra lista da aplicação." }, "description": { "type": "string", "description": "Nova descrição. Envie uma string vazia para a limpar." } } }, "examples": { "Rename": { "value": { "name": "Trusted office and VPN IPs" } }, "Rename and describe": { "value": { "name": "Trusted office and VPN IPs", "description": "Office egress ranges and the corporate VPN" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"Trusted office and VPN IPs\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"Trusted office and VPN IPs\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"Trusted office and VPN IPs\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsUpdateParams{\n\tName: didit.String(\"Trusted office and VPN IPs\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().update(\"11111111-2222-3333-4444-555555555555\", ListsUpdateParams.builder()\n .name(\"Trusted office and VPN IPs\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'Trusted office and VPN IPs',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"Trusted office and VPN IPs\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new ListsUpdateParams\n{\n Name = \"Trusted office and VPN IPs\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A lista foi atualizada. Apenas os campos editáveis são devolvidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string", "description": "O nome da lista após a atualização." }, "description": { "type": "string", "description": "A descrição da lista após a atualização." } } }, "examples": { "Renamed": { "value": { "name": "Trusted office and VPN IPs", "description": "Office egress ranges" } } } } } }, "400": { "description": "A lista é uma lista do sistema ou o corpo é inválido.", "content": { "application/json": { "examples": { "System list": { "value": { "non_field_errors": [ "System lists cannot be modified." ] } }, "Duplicate name": { "value": { "name": [ "A list with this name already exists for this application." ] } }, "Blank name": { "value": { "name": [ "This field may not be blank." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: write` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Não existe nenhuma lista com este UUID na aplicação da chave de API, ou foi eliminada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Eliminar uma lista", "description": "Elimina uma lista de permissões ou lista personalizada juntamente com as suas entradas. A eliminação é irreversível: a lista e as suas entradas deixam de aparecer em qualquer leitura, e as condições das regras de fluxos e transações que referenciem a lista passam a avaliá-la como uma lista vazia a partir desse momento. As sessões e transações já avaliadas mantêm os seus resultados, e o nome pode ser reutilizado para uma nova lista. As listas de sistema não podem ser eliminadas e devolvem `400`; para esvaziar uma, [elimine as suas entradas](https://docs.didit.me/pt/management-api/lists/delete-entry). Uma chave de API com âmbito necessita de `workflows: write`.", "operationId": "delete_list", "x-didit-sdk": { "resource": "lists", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID da lista, conforme retornado por Listar listas ou Criar uma lista.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.lists.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.lists.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Lists.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.lists().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "lists->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Lists.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "A lista e as respetivas entradas foram eliminadas. Sem corpo de resposta." }, "400": { "description": "A lista é uma lista do sistema.", "content": { "application/json": { "examples": { "System list": { "value": { "detail": "System lists cannot be deleted." } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: write` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Não existe nenhuma lista com este UUID na aplicação da chave de API, ou já foi eliminada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/": { "get": { "summary": "Listar entradas da lista", "description": "Devolve as entradas atuais de uma lista, ordenadas pela mais recente primeiro. `search` faz a correspondência parcial com o `value` ou `display_label` de uma entrada, sem diferenciar maiúsculas de minúsculas, e `reference_session_id` restringe os resultados às entradas obtidas a partir de uma sessão de verificação de pessoa. Os URLs de imagens em `metadata` são URLs assinados de curta duração emitidos novamente a cada chamada; uma chave de API com âmbito restrito sem `media: read` recebe `null` no seu lugar. Uma chave de API com âmbito restrito necessita de `workflows: read`.", "operationId": "list_list_entries", "x-didit-sdk": { "resource": "lists.entries", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID da lista, conforme retornado por Listar listas ou Criar uma lista.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "search", "in": "query", "required": false, "description": "Texto insensível a maiúsculas/minúsculas que o `value` ou `display_label` da entrada deve conter.", "schema": { "type": "string" } }, { "name": "reference_session_id", "in": "query", "required": false, "description": "Apenas as entradas recolhidas a partir desta sessão de verificação de pessoa, por exemplo para consultar quais dos seus rostos já estão listados.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Tamanho da página. A predefinição é 50. Um valor superior a 1000000 devolve `400`; zero, um valor negativo ou um valor não numérico reverte para 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "Índice de base zero do primeiro item a devolver. Prefira seguir `next`. Um valor superior a 1000000 devolve `400`; um valor negativo ou não numérico reverte para 0.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/?search=example.com' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.lists.entries.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.lists.entries.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Lists.Entries.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.lists().entries().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "lists->entries->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.entries.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Lists.Entries.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de entradas, as mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Número total de entradas correspondentes aos filtros." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceListEntry" } } } }, "examples": { "Entries": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "value": "X1234567", "display_label": "Jane Doe - X1234567", "comment": "", "added_by": "api", "reference_session_id": "33333333-4444-5555-6666-777777777777", "reference_session_number": 1042, "reference_session_type": "kyc", "reference_object_uuid": "66666666-7777-8888-9999-000000000000", "metadata": { "full_name": "Jane Doe", "issuing_state": "ESP", "document_type": "ID", "region": "", "document_number": "X1234567" }, "created_at": "2026-10-12T10:06:12.774915Z" }, { "uuid": "eeeeeeee-ffff-0000-1111-222222222222", "value": "y7654321", "display_label": "", "comment": "Reported by a partner", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": null, "metadata": null, "created_at": "2026-10-03T07:48:30.552810Z" } ] } } } } } }, "400": { "description": "Um parâmetro de consulta é inválido.", "content": { "application/json": { "examples": { "Invalid session id": { "value": { "reference_session_id": [ "Must be a valid UUID." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: read` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "404": { "description": "Não existe nenhuma lista com este UUID na aplicação da chave de API, ou foi eliminada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "description": "O limite de leitura partilhado de 600 pedidos por minuto por chave de API foi excedido. Respeite o `Retry-After` antes de tentar novamente.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar uma entrada na lista", "description": "Adiciona uma entrada a uma lista através de uma de três formas: por `value`; a partir de uma sessão de verificação com `reference_session_id`, em que a Didit lê o valor a partir do registo mais recente da sessão do tipo de entrada da lista e associa-lhe a entrada; ou por `value` com um `reference_object_uuid` e `metadata.reference_type` que aponta para uma transação, utilizador ou empresa. Nas listas de bloqueio de rostos, documentos, telefones e e-mails do sistema, o registo lido da sessão é também sinalizado como incluído na lista de bloqueio, pelo que novas sessões correspondentes são recusadas; nas listas de bloqueio de utilizadores e empresas do sistema, os utilizadores ou empresas correspondentes são definidos como `BLOCKED`. As sessões e transações que já terminaram não são alteradas. Uma chave de API com âmbito necessita de `workflows: write`. Consulte [Criar uma entrada de lista](https://docs.didit.me/pt/management-api/lists/create-entry) para cada modo.", "operationId": "create_list_entry", "x-didit-sdk": { "resource": "lists.entries", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID da lista à qual adicionar. Para um rosto do qual só tenha a imagem, utilize Carregar um rosto para uma lista.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Envie `value`, `reference_session_id` ou ambos. Os campos aplicáveis dependem do `entry_type` da lista.", "properties": { "value": { "type": "string", "description": "O valor a listar, validado relativamente ao `entry_type` da lista: `email` um endereço de e-mail válido; `phone` um número internacional válido, guardado em E.164; `ip_address` um endereço IP ou intervalo CIDR (por exemplo `10.0.0.0/8`); `device_fingerprint` pelo menos 8 carateres entre letras, dígitos, `-`, `_`, `:` e `.` (uma lista de bloqueio recusa uma fingerprint que vários dispositivos distintos tenham reportado); `country` um código ISO 3166-1 alfa-2 ou alfa-3, guardado como alfa-3; `user` e `business` o `vendor_data`; qualquer outro tipo uma cadeia não vazia. Guardado em minúsculas, exceto números de telefone e códigos de país, e uma lista contém cada valor apenas uma vez (não sensível a maiúsculas/minúsculas). Obrigatório exceto se `reference_session_id` for enviado; deve ser deixado em branco com um `face_image_source` de captura de documentos." }, "reference_session_id": { "type": "string", "format": "uuid", "description": "Uma sessão de verificação de pessoa ou empresa da sua aplicação da qual obter o valor. A Didit lê o registo mais recente da sessão do tipo de entrada da lista (`face`, `document`, `phone`, `email`, `ip_address` ou `device_fingerprint`), associa a entrada à sessão e a esse registo, e preenche `display_label` e `metadata` para documentos. Para uma lista de bloqueio de `device_fingerprint`, uma sessão que apenas tenha uma impressão digital de classe de dispositivo, ou que tenha sido concluída em mais de um dispositivo, é recusada: envie a impressão digital exata como `value`. Para outros tipos de entrada, ou quando a sessão não tiver tal registo, envie também `value`; o seu `value` é então armazenado e a entrada continua associada à sessão." }, "reference_object_uuid": { "type": "string", "format": "uuid", "description": "UUID do registo que a entrada representa quando não provém de uma sessão: um UUID de transação, ou o `didit_internal_id` de um utilizador ou empresa. Combine-o com `metadata.reference_type`. Substituído pelo registo da sessão quando `reference_session_id` fornece um." }, "face_image_source": { "type": "string", "enum": [ "liveness", "front_image_camera_front", "back_image_camera_front" ], "default": "liveness", "description": "Listas de rostos com `reference_session_id`: de qual das imagens da sessão o rosto é retirado. `liveness` (predefinição) é a selfie de prova de vida. `front_image_camera_front` e `back_image_camera_front` são as selfies que a câmara frontal tirou enquanto o utilizador fotografava a frente ou o verso do seu documento: aceites apenas na lista de bloqueio de rostos do sistema, com `reference_session_id` e um `value` vazio. Cada selfie pode ser adicionada uma vez e deve mostrar um rosto nítido." }, "reference_node_id": { "type": "string", "nullable": true, "maxLength": 100, "description": "Com um `face_image_source` de captura de documento: o nó de verificação de identidade cuja selfie deve ser utilizada, para fluxos com mais de um. O valor padrão é a verificação de identidade mais recente que tenha essa imagem. Recusado com `liveness`." }, "display_label": { "type": "string", "maxLength": 512, "description": "Rótulo legível. Quando vazio, a Didit deriva um a partir da sessão sempre que possível (por exemplo, o nome do titular e o número do documento)." }, "comment": { "type": "string", "description": "Nota em texto livre, como o motivo da inclusão na lista." }, "metadata": { "type": "object", "additionalProperties": true, "description": "JSON de formato livre armazenado com a entrada e devolvido tal como foi guardado. Utilize `reference_type` e `reference_id` para que a consola estabeleça uma ligação para a origem. `reference_image_url` e `front_image_url` são definidos apenas pela Didit e são descartados se os enviar. Para uma entrada lida a partir de uma sessão, as chaves da Didit são combinadas com as suas.", "properties": { "reference_type": { "type": "string", "enum": [ "transaction", "vendor_user", "vendor_business" ], "description": "A que se refere `reference_object_uuid`." }, "reference_id": { "type": "string", "description": "Identificador do registo de origem." } } } } }, "examples": { "By value": { "value": { "value": "+14155552671", "comment": "Reported fraud" } }, "From a session": { "value": { "reference_session_id": "33333333-4444-5555-6666-777777777777" } }, "Face from a document-capture selfie": { "value": { "reference_session_id": "33333333-4444-5555-6666-777777777777", "face_image_source": "front_image_camera_front" } }, "From a transaction": { "value": { "value": "0x52908400098527886E0F7030069857D2E4169EE7", "reference_object_uuid": "55555555-6666-7777-8888-999999999999", "comment": "Linked to a chargeback", "metadata": { "reference_type": "transaction", "reference_id": "55555555-6666-7777-8888-999999999999" } } }, "Country": { "value": { "value": "PRK", "comment": "Sanctioned jurisdiction" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"value\": \"+14155552671\", \"comment\": \"Reported fraud\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.entries.create(\n \"11111111-2222-3333-4444-555555555555\",\n value=\"+14155552671\",\n comment=\"Reported fraud\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.entries.create(\"11111111-2222-3333-4444-555555555555\", {\n value: \"+14155552671\",\n comment: \"Reported fraud\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesCreateParams{\n\tValue: didit.String(\"+14155552671\"),\n\tComment: didit.String(\"Reported fraud\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsEntriesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().entries().create(\"11111111-2222-3333-4444-555555555555\", ListsEntriesCreateParams.builder()\n .value(\"+14155552671\")\n .comment(\"Reported fraud\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->entries->create('11111111-2222-3333-4444-555555555555', [\n 'value' => '+14155552671',\n 'comment' => 'Reported fraud',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.entries.create(\n \"11111111-2222-3333-4444-555555555555\",\n value: \"+14155552671\",\n comment: \"Reported fraud\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.Entries.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new ListsEntriesCreateParams\n{\n Value = \"+14155552671\",\n Comment = \"Reported fraud\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A entrada foi criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceListEntry" }, "examples": { "By value": { "value": { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "value": "+14155552671", "display_label": "", "comment": "Reported fraud", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": null, "metadata": null, "created_at": "2026-10-12T10:04:51.220391Z" } }, "Document from a session": { "value": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "value": "X1234567", "display_label": "Jane Doe - X1234567", "comment": "", "added_by": "api", "reference_session_id": "33333333-4444-5555-6666-777777777777", "reference_session_number": 1042, "reference_session_type": "kyc", "reference_object_uuid": "66666666-7777-8888-9999-000000000000", "metadata": { "full_name": "Jane Doe", "issuing_state": "ESP", "document_type": "ID", "region": "", "document_number": "X1234567" }, "created_at": "2026-10-12T10:06:12.774915Z" } }, "From a transaction": { "value": { "uuid": "dddddddd-eeee-ffff-0000-111111111111", "value": "0x52908400098527886e0f7030069857d2e4169ee7", "display_label": "", "comment": "Linked to a chargeback", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "55555555-6666-7777-8888-999999999999", "metadata": { "reference_type": "transaction", "reference_id": "55555555-6666-7777-8888-999999999999" }, "created_at": "2026-10-12T10:20:40.117062Z" } } } } } }, "400": { "description": "O corpo é inválido, o valor já existe na lista ou a sessão não pode fornecer o valor.", "content": { "application/json": { "examples": { "Nothing to list": { "value": { "value": [ "Either 'value' or 'reference_session_id' must be provided." ] } }, "Duplicate value": { "value": { "value": [ "An entry with this value already exists in this list." ] } }, "Invalid phone": { "value": { "value": [ "Invalid phone number. Provide a valid international number (e.g. +1234567890)." ] } }, "Invalid IP": { "value": { "value": [ "Invalid IP address or CIDR range (e.g. 192.168.1.1 or 10.0.0.0/24)." ] } }, "Invalid country": { "value": { "value": [ "Invalid country code: XX. Provide a valid ISO 3166-1 alpha-2 or alpha-3 country code." ] } }, "Device-class fingerprint": { "value": { "value": [ "This value is a device-class fingerprint: several distinct devices have reported it, so blocklisting it would decline unrelated people. Block the user by document, face, email or phone instead." ] } }, "Unknown session": { "value": { "reference_session_id": [ "Session not found or does not belong to this application." ] } }, "No data in session": { "value": { "value": [ "Either provide a 'value' or ensure the session contains data for this entry type." ] } }, "Selfie on another list": { "value": { "face_image_source": [ "A document-capture selfie can only be added to the face blocklist." ] } }, "No clear face in selfie": { "value": { "face_image_source": [ "No clear face was found in this selfie, so it cannot be blocklisted." ] } }, "Selfie already listed": { "value": { "face_image_source": [ "This selfie is already in the blocklist." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: write` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Não existe nenhuma lista com este UUID na aplicação da chave de API, ou foi eliminada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "A análise facial de uma selfie de captura de documento está temporariamente indisponível. Nada foi adicionado; tente novamente mais tarde.", "content": { "application/json": { "examples": { "Unavailable": { "value": { "detail": "Service temporarily unavailable. Please try again later." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/{entry_uuid}/": { "delete": { "summary": "Eliminar uma entrada de lista", "description": "Elimina uma entrada de uma lista, incluindo listas de sistema. A entrada deixa de corresponder de imediato e a eliminação é irreversível: para voltar a listar o valor, crie uma nova entrada. Numa lista de bloqueio de sistema de rostos, documentos, telefones ou e-mails, o registo que a entrada representa deixa de estar sinalizado como estando na lista de bloqueio; na lista de bloqueio de sistema de utilizadores ou empresas, os utilizadores ou empresas da aplicação cujo `vendor_data` seja igual ao valor da entrada (ou cujo `didit_internal_id` seja igual ao respetivo `reference_object_uuid`) e que estejam com estado `BLOCKED` regressam a `ACTIVE`. As sessões e transações que já tenham terminado mantêm o seu estado. Uma chave de API com âmbito necessita de `workflows: write`.", "operationId": "delete_list_entry", "x-didit-sdk": { "resource": "lists.entries", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID da lista que contém a entrada.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "entry_uuid", "in": "path", "required": true, "description": "UUID da entrada, conforme retornado por Listar entradas da lista ou Criar uma entrada da lista.", "schema": { "type": "string", "format": "uuid" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Lists.Entries.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.lists().entries().delete(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");" }, { "lang": "php", "label": "PHP", "source": "lists->entries->delete('11111111-2222-3333-4444-555555555555', 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Lists.Entries.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");" } ], "responses": { "204": { "description": "A entrada foi eliminada. Sem corpo." }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: write` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Não existe nenhuma entrada com este UUID nesta lista, a lista não pertence à aplicação da chave de API ou foi eliminada, ou a entrada já foi eliminada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No ListEntry matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/face-upload/": { "post": { "summary": "Carregar um rosto para uma lista", "description": "Adiciona um rosto a uma lista de bloqueio de rostos ou a uma lista de permissões de rostos a partir de uma imagem JPEG ou PNG codificada em base64, para quando não tem uma sessão de verificação para referenciar. A Didit deteta os rostos na imagem, utiliza o maior e cria uma entrada cujo `value` e `reference_object_uuid` são o UUID do novo rosto. Um rosto na lista de bloqueio recusa novas sessões cujo rosto coincida; um rosto na lista de permissões ignora a ação de rosto duplicado e nunca sobrepõe uma correspondência na lista de bloqueio. Numa aplicação sandbox, a imagem não é analisada e a entrada não coincide com nada. Uma chave de API com âmbito necessita de `workflows: write`. Para colocar na lista um rosto de uma sessão existente, utilize [Criar uma entrada de lista](https://docs.didit.me/pt/management-api/lists/create-entry) com `reference_session_id` em alternativa.", "operationId": "upload_list_entry_face", "x-didit-sdk": { "resource": "lists.entries", "method": "upload_face", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID de uma lista com `entry_type: face` e `list_type: blocklist` ou `allowlist`.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "byte", "description": "JPEG ou PNG codificado em base64, no máximo 2 MB após descodificado, mostrando um rosto claramente visível. Envie a string base64 simples, sem o prefixo `data:image/...;base64,`." }, "comment": { "type": "string", "default": "", "description": "Nota de texto livre opcional, como o motivo da inclusão na lista." } } }, "examples": { "Face image": { "value": { "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...", "comment": "Known fraud attempt" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/face-upload/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"image\\\": \\\"$(base64 < face.jpg | tr -d '\\n')\\\", \\\"comment\\\": \\\"Known fraud attempt\\\"}\"" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.entries.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image=\"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment=\"Known fraud attempt\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.entries.uploadFace(\"11111111-2222-3333-4444-555555555555\", {\n image: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment: \"Known fraud attempt\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n\tComment: didit.String(\"Known fraud attempt\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsEntriesUploadFaceParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().entries().uploadFace(\"11111111-2222-3333-4444-555555555555\", ListsEntriesUploadFaceParams.builder()\n .image(\"/9j/4AAQSkZJRgABAQAAAQABAAD...\")\n .comment(\"Known fraud attempt\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->entries->uploadFace('11111111-2222-3333-4444-555555555555', [\n 'image' => '/9j/4AAQSkZJRgABAQAAAQABAAD...',\n 'comment' => 'Known fraud attempt',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.entries.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment: \"Known fraud attempt\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.Entries.UploadFaceAsync(\"11111111-2222-3333-4444-555555555555\", new ListsEntriesUploadFaceParams\n{\n Image = \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n Comment = \"Known fraud attempt\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A entrada de rosto foi criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceListEntry" }, "examples": { "Uploaded face": { "value": { "uuid": "cccccccc-dddd-eeee-ffff-000000000000", "value": "44444444-5555-6666-7777-888888888888", "display_label": "Manually uploaded face", "comment": "Known fraud attempt", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "44444444-5555-6666-7777-888888888888", "metadata": { "reference_image_url": "https://media.example.com/faces/reference.jpg?expires=1760263938&signature=3f9a1c" }, "created_at": "2026-10-12T10:12:18.904467Z" } }, "Sandbox application": { "value": { "uuid": "cccccccc-dddd-eeee-ffff-000000000000", "value": "44444444-5555-6666-7777-888888888888", "display_label": "Sandbox face entry", "comment": "Known fraud attempt", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "44444444-5555-6666-7777-888888888888", "metadata": { "sandbox": true }, "created_at": "2026-10-12T10:12:18.904467Z" } } } } } }, "400": { "description": "A lista não aceita carregamentos de imagens faciais, ou a imagem está em falta, é inválida, demasiado grande ou não mostra um rosto utilizável. Nenhuma entrada foi criada.", "content": { "application/json": { "examples": { "Not a face list": { "value": { "detail": "Face upload is only available for face-type lists." } }, "Custom face list": { "value": { "detail": "Face upload is only available for face blocklists and allowlists." } }, "Missing image": { "value": { "image": [ "This field is required." ] } }, "Invalid base64": { "value": { "image": [ "Invalid base64 encoding." ] } }, "Too large": { "value": { "image": [ "Image exceeds maximum size of 2 MB." ] } }, "Unreadable image": { "value": { "image": "Invalid image. Provide a valid base64-encoded JPG or PNG." } }, "No face": { "value": { "image": "No face detected in the image. Please upload a clear photo with a visible face." } }, "No usable face": { "value": { "image": "Could not extract face embedding. Try a different image." } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: write` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Não existe nenhuma lista com este UUID na aplicação da chave de API, ou foi eliminada.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "A análise facial está temporariamente indisponível. Nenhuma entrada foi criada; tente novamente mais tarde.", "content": { "application/json": { "examples": { "Unavailable": { "value": { "detail": "Service temporarily unavailable. Please try again later." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/": { "get": { "summary": "Listar itens na lista de bloqueio", "description": "Devolve um feed paginado dos rostos, documentos de identificação, números de telefone e endereços de e-mail das sessões de verificação da aplicação que estão atualmente na lista de bloqueio, ordenados pelo `blocklisted_at` mais recente primeiro; filtre com `item_type`. Os itens de sessões eliminadas não são incluídos. O feed abrange registos colocados na lista de bloqueio a partir de uma sessão (com [Adicionar itens de sessão à lista de bloqueio](https://docs.didit.me/pt/management-api/blocklist/add), a partir da consola ou através de uma entrada de lista criada a partir de uma sessão); valores adicionados a uma lista manualmente, rostos carregados, rostos de uma selfie de captura de documento e os outros tipos de entrada são consultados com [Listar entradas da lista](https://docs.didit.me/pt/management-api/lists/list-entries). `face_image` e `front_image` são URLs assinados de curta duração, e uma chave de API com âmbito restrito sem `media: read` recebe `null`. Uma chave de API com âmbito restrito necessita de `workflows: read`.", "operationId": "list_blocklist_items", "x-didit-sdk": { "resource": "blocklist", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "parameters": [ { "name": "item_type", "in": "query", "required": false, "description": "Apenas itens deste tipo. Quando omitido, são devolvidos todos os tipos.", "schema": { "type": "string", "enum": [ "face", "document", "phone", "email" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Tamanho da página. A predefinição é 50. Um valor superior a 1000000 devolve `400`; zero, um valor negativo ou um valor não numérico reverte para 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "Índice de base zero do primeiro item a devolver. Prefira seguir `next`. Um valor superior a 1000000 devolve `400`; um valor negativo ou não numérico reverte para 0.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/blocklist/?item_type=document' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.blocklist.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.blocklist.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Blocklist.ListAutoPaging(ctx, didit.BlocklistListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.blocklist().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "blocklist->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.blocklist.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Blocklist.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de itens na lista de bloqueio, os mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Número total de itens na lista de bloqueio correspondentes aos filtros." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BlocklistedItem" } } } }, "examples": { "Mixed feed": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "type": "document", "session_id": "33333333-4444-5555-6666-777777777777", "session_number": 1042, "blocklisted_at": "2026-10-12T10:06:12.701553Z", "face_image": null, "document_type": "ID", "document_number": "X1234567", "front_image": "https://media.example.com/documents/front.jpg?expires=1760263938&signature=8b2e47", "phone_number": null, "country_code": null, "email": null }, { "type": "phone", "session_id": "77777777-8888-9999-0000-111111111111", "session_number": 1017, "blocklisted_at": "2026-10-08T15:31:09.400127Z", "face_image": null, "document_type": null, "document_number": null, "front_image": null, "phone_number": "+14155552671", "country_code": "US", "email": null } ] } } } } } }, "400": { "description": "Um parâmetro de consulta é inválido.", "content": { "application/json": { "examples": { "Unknown item type": { "value": { "item_type": [ "\"wallet\" is not a valid choice." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: read` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "429": { "description": "O limite de leitura partilhado de 600 pedidos por minuto por chave de API foi excedido. Respeite o `Retry-After` antes de tentar novamente.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/add/": { "post": { "summary": "Adicionar itens da sessão à lista de bloqueio", "description": "Adiciona à lista de bloqueio o rosto, documento de identificação, número de telefone ou endereço de e-mail de uma sessão de verificação de pessoa da aplicação. Para cada tipo selecionado, a Didit obtém o registo mais recente da sessão, marca-o como colocado na lista de bloqueio e adiciona uma entrada associada à sessão à lista de bloqueio correspondente do sistema (`added_by: \"api\"`), para que novas sessões com um rosto, número de documento, número de telefone ou endereço de e-mail correspondente sejam recusadas. Todos os itens selecionados são verificados primeiro, pelo que, se faltar algum, nada é adicionado à lista de bloqueio; repetir a chamada para um item já listado mantém a sua entrada única e atualiza `blocklisted_at`. A sessão em si e as sessões já concluídas não são alteradas. Uma chave de API com âmbito necessita de `workflows: write`.", "operationId": "add_to_blocklist", "x-didit-sdk": { "resource": "blocklist", "method": "add", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "description": "Pelo menos um indicador `blocklist_*` tem de ser `true`.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Uma sessão de verificação de pessoa da sua aplicação. As sessões eliminadas são recusadas." }, "blocklist_face": { "type": "boolean", "default": false, "description": "Adicionar à lista de bloqueio o rosto da sessão." }, "blocklist_document": { "type": "boolean", "default": false, "description": "Adicionar à lista de bloqueio o documento de identificação da sessão. O documento necessita do seu estado emissor, tipo de documento, número de documento e nome completo." }, "blocklist_phone": { "type": "boolean", "default": false, "description": "Adicionar à lista de bloqueio o número de telefone da sessão." }, "blocklist_email": { "type": "boolean", "default": false, "description": "Adicionar à lista de bloqueio o endereço de e-mail da sessão." } } }, "examples": { "Face and document": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "blocklist_face": true, "blocklist_document": true } }, "Phone only": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "blocklist_phone": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/blocklist/add/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_id\": \"33333333-4444-5555-6666-777777777777\",\n \"blocklist_face\": true,\n \"blocklist_document\": true\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.blocklist.add(\n session_id=\"33333333-4444-5555-6666-777777777777\",\n blocklist_face=True,\n blocklist_document=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.blocklist.add({\n session_id: \"33333333-4444-5555-6666-777777777777\",\n blocklist_face: true,\n blocklist_document: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Blocklist.Add(ctx, didit.BlocklistAddParams{\n\tSessionID: \"33333333-4444-5555-6666-777777777777\",\n\tBlocklistFace: didit.Bool(true),\n\tBlocklistDocument: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BlocklistAddParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.blocklist().add(BlocklistAddParams.builder()\n .sessionId(\"33333333-4444-5555-6666-777777777777\")\n .blocklistFace(true)\n .blocklistDocument(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "blocklist->add([\n 'session_id' => '33333333-4444-5555-6666-777777777777',\n 'blocklist_face' => true,\n 'blocklist_document' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.blocklist.add(\n session_id: \"33333333-4444-5555-6666-777777777777\",\n blocklist_face: true,\n blocklist_document: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Blocklist.AddAsync(new BlocklistAddParams\n{\n SessionId = \"33333333-4444-5555-6666-777777777777\",\n BlocklistFace = true,\n BlocklistDocument = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Os itens selecionados foram adicionados à lista de bloqueio.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Sempre `Successfully updated blocklist.`" } } }, "examples": { "Blocklisted": { "value": { "message": "Successfully updated blocklist." } } } } } }, "400": { "description": "O corpo é inválido, a sessão não é uma sessão de verificação desta aplicação ou não possui registo do tipo selecionado. Nada foi adicionado à lista de bloqueio.", "content": { "application/json": { "examples": { "Unknown session": { "value": { "non_field_errors": [ "Session not found" ] } }, "No item selected": { "value": { "non_field_errors": [ "Must specify at least one item to blocklist" ] } }, "No face record": { "value": { "non_field_errors": [ "Session does not have a face record" ] } }, "Incomplete document": { "value": { "non_field_errors": [ "To blocklist a document, the document must have an issuing state, document type, document number and full name" ] } }, "Invalid session id": { "value": { "session_id": [ "Must be a valid UUID." ] } }, "Missing session id": { "value": { "session_id": [ "This field is required." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: write` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/remove/": { "post": { "summary": "Remover itens da sessão da lista de bloqueio", "description": "Levanta o bloqueio sobre o rosto, documento de identidade, número de telefone ou endereço de e-mail de uma sessão de verificação de pessoa da aplicação. Para cada tipo selecionado, a Didit obtém o registo mais recente da sessão, limpa o seu sinalizador de lista de bloqueio e elimina as entradas na lista de bloqueio do sistema criadas a partir desse registo, deixando de recusar novas sessões. As entradas adicionadas a uma lista por valor não são alteradas: encontre-as com [Listar entradas da lista](https://docs.didit.me/pt/management-api/lists/list-entries) e elimine-as com [Eliminar uma entrada da lista](https://docs.didit.me/pt/management-api/lists/delete-entry). Desbloquear um registo que não esteja na lista de bloqueio tem êxito e não altera nada, e as sessões já terminadas não são modificadas. Uma chave de API com restrição de âmbito necessita de `workflows: write`.", "operationId": "remove_from_blocklist", "x-didit-sdk": { "resource": "blocklist", "method": "remove", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "description": "Pelo menos um indicador `unblock_*` tem de ser `true`.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Uma sessão de verificação de pessoa da sua aplicação. As sessões eliminadas são recusadas." }, "unblock_face": { "type": "boolean", "default": false, "description": "Levantar o bloqueio sobre o rosto da sessão." }, "unblock_document": { "type": "boolean", "default": false, "description": "Levantar o bloqueio sobre o documento de identidade da sessão." }, "unblock_phone": { "type": "boolean", "default": false, "description": "Levantar o bloqueio sobre o número de telefone da sessão." }, "unblock_email": { "type": "boolean", "default": false, "description": "Levantar o bloqueio sobre o endereço de e-mail da sessão." } } }, "examples": { "Face and document": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "unblock_face": true, "unblock_document": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/blocklist/remove/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_id\": \"33333333-4444-5555-6666-777777777777\",\n \"unblock_face\": true,\n \"unblock_document\": true\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.blocklist.remove(\n session_id=\"33333333-4444-5555-6666-777777777777\",\n unblock_face=True,\n unblock_document=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.blocklist.remove({\n session_id: \"33333333-4444-5555-6666-777777777777\",\n unblock_face: true,\n unblock_document: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Blocklist.Remove(ctx, didit.BlocklistRemoveParams{\n\tSessionID: \"33333333-4444-5555-6666-777777777777\",\n\tUnblockFace: didit.Bool(true),\n\tUnblockDocument: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BlocklistRemoveParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.blocklist().remove(BlocklistRemoveParams.builder()\n .sessionId(\"33333333-4444-5555-6666-777777777777\")\n .unblockFace(true)\n .unblockDocument(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "blocklist->remove([\n 'session_id' => '33333333-4444-5555-6666-777777777777',\n 'unblock_face' => true,\n 'unblock_document' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.blocklist.remove(\n session_id: \"33333333-4444-5555-6666-777777777777\",\n unblock_face: true,\n unblock_document: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Blocklist.RemoveAsync(new BlocklistRemoveParams\n{\n SessionId = \"33333333-4444-5555-6666-777777777777\",\n UnblockFace = true,\n UnblockDocument = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O bloqueio sobre os itens selecionados foi levantado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Sempre `Successfully removed from blocklist.`" } } }, "examples": { "Unblocked": { "value": { "message": "Successfully removed from blocklist." } } } } } }, "400": { "description": "O corpo é inválido, a sessão não é uma sessão de verificação desta aplicação ou não possui registo do tipo selecionado. Nada foi alterado.", "content": { "application/json": { "examples": { "Unknown session": { "value": { "non_field_errors": [ "Session not found" ] } }, "No item selected": { "value": { "non_field_errors": [ "Must specify at least one item to unblock" ] } }, "No email record": { "value": { "non_field_errors": [ "Session does not have an email record" ] } }, "Invalid session id": { "value": { "session_id": [ "Must be a valid UUID." ] } }, "Missing session id": { "value": { "session_id": [ "This field is required." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Outras falhas de autenticação devolvem `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O cabeçalho `x-api-key` está em falta (uma chave errada, revogada ou expirada recebe `401`), ou uma chave de API com âmbito não tem `workflows: write` ou é utilizada a partir de um endereço IP fora da sua lista de permissões.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/": { "get": { "summary": "Obter configuração do webhook", "description": "Devolve as definições de webhook da aplicação numa única chamada: cada [destino do webhook](https://docs.didit.me/pt/management-api/webhook/list-destinations) com o respetivo segredo de assinatura, os tipos de evento a que um destino pode subscrever-se, o URL, versão e segredo de webhook ao nível da aplicação (legados), a política de conservação de dados e de templates biométricos e os hosts de retorno da carteira Digital ID. A Didit entrega webhooks nos destinos, cada um assinado com a sua própria `secret_shared_key`; os campos de nível superior `webhook_url`, `webhook_version` e `secret_shared_key` são utilizados apenas enquanto nenhum destino estiver ativado e, mesmo assim, apenas para `status.updated` e `data.updated`. A resposta contém segredos de assinatura, pelo que deve mantê-la fora de registos e do código do lado do cliente. Uma chave de API com âmbito necessita de `webhooks: read`.", "operationId": "get_webhook_config", "x-didit-sdk": { "resource": "webhooks", "method": "retrieve_config", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.retrieve_config()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.retrieveConfig();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.RetrieveConfig(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().retrieveConfig();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->retrieveConfig();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.retrieve_config\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.RetrieveConfigAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A configuração do webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "examples": { "One destination": { "value": { "webhook_url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy10aGUtYXBwLWxldmVsLXNlY3JldC0wMDA", "capture_method": "MOBILE", "data_retention_months": 24, "face_retention_policy": "delete_with_session", "face_retention_days": null, "biometric_consent_mode": "auto", "available_events": [ { "value": "status.updated", "label": "Session status updated" }, { "value": "data.updated", "label": "Session data updated" }, { "value": "user.status.updated", "label": "User status updated" }, { "value": "user.data.updated", "label": "User data updated" }, { "value": "business.status.updated", "label": "Business status updated" }, { "value": "business.data.updated", "label": "Business data updated" }, { "value": "activity.created", "label": "Activity created" }, { "value": "transaction.created", "label": "Transaction created" }, { "value": "transaction.status.updated", "label": "Transaction status updated" }, { "value": "travel_rule.status.updated", "label": "Travel Rule Status Updated" }, { "value": "workflow.compliance_changed", "label": "Workflow Compliance Changed" } ], "allowed_return_hosts": [ "shop.example.com" ], "endpoints": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC0wMDAwMDA", "subscribed_events": [ "status.updated", "data.updated" ], "created_at": "2026-01-04T08:00:00.000000Z", "updated_at": "2026-04-22T14:09:11.523671Z" } ] } } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Um `x-api-key` em falta, inválido ou revogado recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 600 pedidos GET na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Atualizar configuração do webhook", "description": "Atualize parcialmente as definições ao nível da aplicação: o URL, a versão e o segredo do webhook legado, a política de conservação de dados e de templates biométricos, e os hosts de retorno da carteira Digital ID. Envie apenas os campos a alterar; a resposta é a configuração completa, com a mesma estrutura que `GET /v3/webhook/`. Os destinos não são geridos aqui: crie-os, atualize-os e elimine-os com os endpoints `/v3/webhook/destinations/`, e não envie um campo `endpoints` para este endpoint. Uma alteração em `data_retention_months` também se aplica às sessões existentes, e as sessões que esta eliminar não podem ser restauradas; leia primeiro [Conservação de dados](https://docs.didit.me/pt/console/data-retention). Uma chave de API com âmbito necessita de `webhooks: write`.", "operationId": "update_webhook_config", "x-didit-sdk": { "resource": "webhooks", "method": "update_config", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Envie apenas os campos a alterar. Os destinos não são geridos aqui.", "properties": { "webhook_url": { "type": "string", "format": "uri", "nullable": true, "maxLength": 2000, "description": "URL de webhook legado ao nível da aplicação. O Didit utiliza-o apenas enquanto a aplicação não tiver nenhum destino ativado e, mesmo assim, apenas para `status.updated` e `data.updated`. Não cria um destino, e a próxima criação, atualização ou eliminação de um destino substitui-o. Para receber webhooks, crie antes um destino com `POST /v3/webhook/destinations/`." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versão do payload do `webhook_url` legado." }, "rotate_secret_key": { "type": "boolean", "default": false, "description": "`true` substitui imediatamente a `secret_shared_key` ao nível da aplicação por um novo valor aleatório; o novo valor está na resposta. Os segredos dos destinos não são alterados. Cada chamada com `true` gera um novo segredo, pelo que não é idempotente." }, "capture_method": { "type": "string", "enum": [ "MOBILE", "MOBILE_AND_DESKTOP" ], "description": "Definição legada da aplicação. O fluxo de verificação não a lê." }, "data_retention_months": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 120, "description": "Janela de eliminação automática em meses (um mês conta como 30 dias), ou `null` para nenhuma eliminação automática. Uma alteração aplica-se também a sessões existentes: todas as sessões de verificação de utilizadores com uma antiguidade superior à nova janela são eliminadas automaticamente, e essa eliminação é irreversível." }, "face_retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "O que acontece ao embedding facial de uma sessão quando a sessão é eliminada. `retain_until_user_deleted` requer `face_retention_days` no mesmo pedido ou já definido. Uma alteração aplica-se às eliminações de sessões a partir desse momento; não cria nem elimina definitivamente nenhum template biométrico existente." }, "face_retention_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "Período de conservação, em dias, dos templates biométricos sob `retain_until_user_deleted`." }, "biometric_consent_mode": { "type": "string", "enum": [ "auto", "always", "never" ], "description": "Quando o fluxo alojado e os SDKs nativos solicitam à pessoa consentimento biométrico explícito antes de uma captura de rosto. `auto` (predefinição) solicita apenas quando se aplica um acionador: um estado declarado, o IP da pessoa ou o emissor do documento de identificação situa-se em Illinois, Texas ou Colorado, ou a pessoa aparenta estar nos EUA sem um estado conhecido. `always` solicita a todas as pessoas cujo fluxo capture um rosto. `never` nunca apresenta o passo, e recolhe o consentimento por sua conta antes da selfie. Cada alteração é registada no registo de auditoria. Consulte [Consentimento biométrico](https://docs.didit.me/pt/getting-started/biometric-consent)." }, "allowed_return_hosts": { "type": "array", "maxItems": 20, "description": "Substitui toda a lista de anfitriões de retorno da carteira de Digital ID. Apenas nomes de anfitrião simples, como `shop.example.com`: sem esquema, porta, caminho ou caráter universal. Os valores são convertidos para minúsculas e os duplicados são eliminados. Envie `[]` para limpar a lista.", "items": { "type": "string", "maxLength": 253 } }, "allowed_domains": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 }, "description": "Substitui toda a lista de origens permitidas. Origens (por exemplo `https://app.example.com`; `http` apenas para `localhost`) nas quais o fluxo de verificação alojado pode ser incorporado e para as quais pode redirecionar o utilizador com um callback de sessão. As chamadas servidor a servidor não são afetadas. Uma lista vazia significa sem restrições. A Didit armazena cada origem em minúsculas sem uma porta predefinida. Uma entrada inválida falha com `400` em `allowed_domains`. Envie `[]` para remover a restrição.", "example": [ "https://app.example.com" ] } } }, "examples": { "Enable biometric template retention": { "value": { "face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365, "biometric_consent_mode": "auto" } }, "Rotate the legacy secret": { "value": { "rotate_secret_key": true } }, "Set data retention": { "value": { "data_retention_months": 24 } }, "Register return hosts": { "value": { "allowed_return_hosts": [ "shop.example.com", "app.example.com" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/webhook/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"face_retention_policy\": \"retain_until_user_deleted\", \"face_retention_days\": 365}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.update_config(\n face_retention_policy=\"retain_until_user_deleted\",\n face_retention_days=365,\n biometric_consent_mode=\"auto\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.updateConfig({\n face_retention_policy: \"retain_until_user_deleted\",\n face_retention_days: 365,\n biometric_consent_mode: \"auto\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WebhooksUpdateConfigParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().updateConfig(WebhooksUpdateConfigParams.builder()\n .faceRetentionPolicy(WebhooksUpdateConfigParams.FaceRetentionPolicy.of(\"retain_until_user_deleted\"))\n .faceRetentionDays(365L)\n .biometricConsentMode(WebhooksUpdateConfigParams.BiometricConsentMode.of(\"auto\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->updateConfig([\n 'face_retention_policy' => 'retain_until_user_deleted',\n 'face_retention_days' => 365,\n 'biometric_consent_mode' => 'auto',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.update_config(\n face_retention_policy: \"retain_until_user_deleted\",\n face_retention_days: 365,\n biometric_consent_mode: \"auto\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.UpdateConfigAsync(new WebhooksUpdateConfigParams\n{\n FaceRetentionPolicy = new WebhooksUpdateConfigParamsFaceRetentionPolicy(\"retain_until_user_deleted\"),\n FaceRetentionDays = 365,\n BiometricConsentMode = new WebhooksUpdateConfigParamsBiometricConsentMode(\"auto\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A configuração completa após a atualização, com a mesma estrutura de `GET /v3/webhook/`. Quando rodar o segredo, guarde a nova `secret_shared_key` antes de descartar a resposta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "examples": { "Retention enabled": { "value": { "webhook_url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy10aGUtYXBwLWxldmVsLXNlY3JldC0wMDA", "capture_method": "MOBILE", "data_retention_months": 24, "face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365, "biometric_consent_mode": "auto", "available_events": [ { "value": "status.updated", "label": "Session status updated" }, { "value": "data.updated", "label": "Session data updated" }, { "value": "user.status.updated", "label": "User status updated" }, { "value": "user.data.updated", "label": "User data updated" }, { "value": "business.status.updated", "label": "Business status updated" }, { "value": "business.data.updated", "label": "Business data updated" }, { "value": "activity.created", "label": "Activity created" }, { "value": "transaction.created", "label": "Transaction created" }, { "value": "transaction.status.updated", "label": "Transaction status updated" }, { "value": "travel_rule.status.updated", "label": "Travel Rule Status Updated" }, { "value": "workflow.compliance_changed", "label": "Workflow Compliance Changed" } ], "allowed_return_hosts": [ "shop.example.com" ], "endpoints": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC0wMDAwMDA", "subscribed_events": [ "status.updated", "data.updated" ], "created_at": "2026-01-04T08:00:00.000000Z", "updated_at": "2026-04-22T14:09:11.523671Z" } ] } } } } } }, "400": { "description": "A validação falhou: cada campo inválido é mapeado para uma lista de mensagens e nada é alterado. Um corpo que não seja JSON válido devolve `{\"detail\": \"JSON parse error - ...\"}`.", "content": { "application/json": { "schema": { "type": "object", "description": "Cada campo inválido mapeado para uma lista de mensagens.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Retention days missing": { "value": { "face_retention_days": [ "A finite retention duration is required when face retention is enabled." ], "biometric_consent_mode": "auto" } }, "Retention window out of range": { "value": { "data_retention_months": [ "Ensure this value is less than or equal to 120." ] } }, "Invalid return host": { "value": { "allowed_return_hosts": [ "'https://shop.example.com' is not a hostname. Register the bare host (e.g. shop.example.com): no scheme, port, path or wildcard." ] } }, "Invalid choice": { "value": { "face_retention_policy": [ "\"forever\" is not a valid choice." ] } } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Um `x-api-key` em falta, inválido ou revogado recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 300 pedidos de escrita (POST, PATCH, PUT, DELETE) na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (300).", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/analytics/": { "get": { "summary": "Obter análise do destino do webhook", "description": "Totais de entrega, taxa de falha e tempos de resposta para um destino do webhook, ao longo de todo o intervalo (`summary`) e por dia UTC (`points`). Cada tentativa conta como uma entrega: o primeiro envio de um evento, cada [nova tentativa](https://docs.didit.me/pt/integration/webhooks#política-de-novas-tentativas) automática e cada reenvio. Uma entrega é considerada falhada quando o respetivo estado HTTP registado é 400 ou superior, pelo que tempos limite excedidos (registados como `504`) e falhas de ligação (`503`) contam como falhadas; uma entrega ainda na fila conta apenas em `total_deliveries`. Os registos de entrega estão disponíveis durante cerca de 30 dias. Uma chave de API com âmbito restrito necessita de `webhooks: read`.", "operationId": "get_webhook_destination_analytics", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve_analytics", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID do destino (o `uuid` retornado por `GET /v3/webhook/destinations/`).", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "date_from", "in": "query", "required": false, "description": "Primeiro dia em UTC a incluir, no formato `YYYY-MM-DD` (inclusive). Omitir para começar a partir da entrega mais antiga disponível. `dateFrom` é aceite como alias.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "date_to", "in": "query", "required": false, "description": "Último dia UTC a incluir, no formato `YYYY-MM-DD` (inclusive). Não pode ser anterior a `date_from`. `dateTo` é aceite como alias.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-16" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/analytics/?date_from=2026-10-01&date_to=2026-10-16' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve_analytics(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieveAnalytics(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.RetrieveAnalytics(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsRetrieveAnalyticsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieveAnalytics(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieveAnalytics('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve_analytics(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveAnalyticsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Estatísticas de entrega para o destino.", "content": { "application/json": { "schema": { "type": "object", "required": [ "summary", "points" ], "properties": { "summary": { "type": "object", "description": "Totais ao longo do intervalo solicitado.", "required": [ "total_deliveries", "failed_deliveries", "min_response_time_ms", "avg_response_time_ms", "max_response_time_ms", "error_rate_percentage" ], "properties": { "total_deliveries": { "type": "integer", "minimum": 0, "description": "Tentativas de entrega, incluindo as que estão na fila." }, "failed_deliveries": { "type": "integer", "minimum": 0, "description": "Tentativas cujo estado HTTP registado é igual ou superior a 400." }, "min_response_time_ms": { "type": "integer", "nullable": true, "description": "Tentativa mais rápida em milissegundos, ou `null` quando nenhuma tentativa tem um tempo registado." }, "avg_response_time_ms": { "type": "integer", "nullable": true, "description": "Tempo médio de tentativa em milissegundos, arredondado, ou `null` quando nenhuma tentativa tem um tempo registado." }, "max_response_time_ms": { "type": "integer", "nullable": true, "description": "Tentativa mais demorada em milissegundos, ou `null` quando nenhuma tentativa tiver um tempo registado." }, "error_rate_percentage": { "type": "integer", "minimum": 0, "maximum": 100, "description": "`failed_deliveries` / `total_deliveries` x 100, arredondado a um número inteiro. `0` quando não existem entregas." } } }, "points": { "type": "array", "description": "Uma entrada por dia UTC que teve entregas, da mais antiga para a mais recente. Os dias sem entregas são omitidos, pelo que deve preencher as lacunas com zeros ao criar gráficos.", "items": { "type": "object", "required": [ "date", "total_deliveries", "failed_deliveries", "min_response_time_ms", "avg_response_time_ms", "max_response_time_ms" ], "properties": { "date": { "type": "string", "format": "date", "description": "Dia UTC, `YYYY-MM-DD`." }, "total_deliveries": { "type": "integer", "minimum": 0, "description": "Tentativas de entrega, incluindo as que estão na fila." }, "failed_deliveries": { "type": "integer", "minimum": 0, "description": "Tentativas cujo estado HTTP registado é igual ou superior a 400." }, "min_response_time_ms": { "type": "integer", "nullable": true, "description": "Tentativa mais rápida em milissegundos, ou `null` quando nenhuma tentativa tem um tempo registado." }, "avg_response_time_ms": { "type": "integer", "nullable": true, "description": "Tempo médio de tentativa em milissegundos, arredondado, ou `null` quando nenhuma tentativa tem um tempo registado." }, "max_response_time_ms": { "type": "integer", "nullable": true, "description": "Tentativa mais demorada em milissegundos, ou `null` quando nenhuma tentativa tiver um tempo registado." } } } } } }, "examples": { "Three days of deliveries": { "value": { "summary": { "total_deliveries": 1250, "failed_deliveries": 12, "min_response_time_ms": 38, "avg_response_time_ms": 164, "max_response_time_ms": 5004, "error_rate_percentage": 1 }, "points": [ { "date": "2026-10-14", "total_deliveries": 410, "failed_deliveries": 0, "min_response_time_ms": 38, "avg_response_time_ms": 152, "max_response_time_ms": 911 }, { "date": "2026-10-15", "total_deliveries": 395, "failed_deliveries": 12, "min_response_time_ms": 41, "avg_response_time_ms": 190, "max_response_time_ms": 5004 }, { "date": "2026-10-16", "total_deliveries": 445, "failed_deliveries": 0, "min_response_time_ms": 40, "avg_response_time_ms": 151, "max_response_time_ms": 1220 } ] } }, "No deliveries in range": { "value": { "summary": { "total_deliveries": 0, "failed_deliveries": 0, "min_response_time_ms": null, "avg_response_time_ms": null, "max_response_time_ms": null, "error_rate_percentage": 0 }, "points": [] } } } } } }, "400": { "description": "`date_from` ou `date_to` não é uma data no formato `YYYY-MM-DD`, ou `date_to` é anterior a `date_from`.", "content": { "application/json": { "schema": { "type": "object", "description": "Cada campo inválido mapeado para uma lista de mensagens.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Malformed date": { "value": { "date_from": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reversed range": { "value": { "date_to": [ "date_to must be greater than or equal to date_from." ] } } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Um `x-api-key` em falta, inválido ou revogado recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhum destino com este UUID para a aplicação, ou foi eliminado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 600 pedidos GET na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/": { "get": { "summary": "Listar entregas do destino do webhook", "description": "Pagine todas as tentativas de entrega para um destino de webhook, as mais recentes primeiro. O primeiro envio de cada evento, cada [tentativa](https://docs.didit.me/pt/integration/webhooks#política-de-novas-tentativas) automática e cada reenvio são entradas separadas. As entradas incluem o estado HTTP e o tempo de resposta, mas não o payload: obtenha uma entrega específica para ler os respetivos cabeçalhos e corpo. O valor de `count` é exato até 100 e apresenta 100 acima disso, pelo que deve seguir `next` até que seja `null`. Os registos de entrega ficam disponíveis durante cerca de 30 dias. Uma chave de API com âmbito necessita de `webhooks: read` e `decisions: read`; uma chave limitada a alguns fluxos ou a sessões aprovadas não pode utilizar este endpoint.", "operationId": "list_webhook_destination_deliveries", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "list_deliveries", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID do destino (o `uuid` retornado por `GET /v3/webhook/destinations/`).", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "limit", "in": "query", "required": false, "description": "Número máximo de entregas por página. O valor predefinido é 50. Um valor que não seja um número inteiro positivo reverte para 50; um valor acima de 1000000 devolve `400`.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Número de entregas a ignorar. A predefinição é 0. É preferível seguir os URLs `next` e `previous` da resposta.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "date_from", "in": "query", "required": false, "description": "Primeiro dia em UTC a incluir, no formato `YYYY-MM-DD` (inclusive). Omitir para começar a partir da entrega mais antiga disponível. `dateFrom` é aceite como alias.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "date_to", "in": "query", "required": false, "description": "Último dia UTC a incluir, no formato `YYYY-MM-DD` (inclusive). Não pode ser anterior a `date_from`. `dateTo` é aceite como alias.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-16" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/?limit=50&date_from=2026-10-01' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.webhooks.destinations.list_deliveries(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.webhooks.destinations.listDeliveries(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Webhooks.Destinations.ListDeliveriesAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsListDeliveriesParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.webhooks().destinations().listDeliveries(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->listDeliveries('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.list_deliveries(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Webhooks.Destinations.ListDeliveriesAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de entregas, as mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Entregas correspondentes, exatas até 100 e limitadas a 100 acima desse valor. Utilize `next` para saber se existem mais páginas." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDestinationDelivery" } } } }, "examples": { "Failed delivery, its retry and a queued event": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "66666666-7777-8888-9999-000000000003", "session_id": null, "request_url": "https://yourapp.com/webhooks/didit", "response_status": null, "response_time_ms": null, "status": "APPROVED", "webhook_type": "transaction.created", "created_at": "2026-10-15T09:23:02.871190Z" }, { "uuid": "66666666-7777-8888-9999-000000000002", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "response_time_ms": 143, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:22:19.104233Z" }, { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "response_time_ms": 412, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:21:18.412345Z" } ] } } } } } }, "400": { "description": "`date_from` ou `date_to` não é uma data no formato `YYYY-MM-DD`, `date_to` é anterior a `date_from`, ou `limit` ou `offset` é superior a 1000000 (esse erro é um array de mensagens em JSON).", "content": { "application/json": { "examples": { "Malformed date": { "value": { "date_from": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reversed range": { "value": { "date_to": [ "date_to must be greater than or equal to date_from." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Um `x-api-key` em falta, inválido ou revogado recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.` Uma chave limitada a alguns fluxos ou a sessões aprovadas recebe `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhum destino com este UUID para a aplicação, ou foi eliminado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 600 pedidos GET na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/{delivery_uuid}/": { "get": { "summary": "Obter entrega do destino do webhook", "description": "Obtenha uma tentativa de entrega para um destino do webhook com os cabeçalhos de pedido e o corpo JSON exatos que a Didit enviou, o estado HTTP retornado pelo seu endpoint e o tempo de resposta. `request_header` e `request_body` são texto em JSON: analise-os para ler os cabeçalhos de assinatura e o payload, por exemplo, para verificar a sua [verificação da assinatura](https://docs.didit.me/pt/integration/webhooks#verificação-da-assinatura) em relação ao `secret_shared_key` do destino. Uma entrega nunca contém o segredo de assinatura e a Didit não regista o corpo da resposta do seu endpoint. Uma chave de API com âmbito restrito necessita de `webhooks: read` e `decisions: read`; uma chave limitada a determinados fluxos ou a sessões aprovadas não pode utilizar este endpoint.", "operationId": "get_webhook_destination_delivery", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve_delivery", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID do destino para o qual a entrega foi enviada.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "delivery_uuid", "in": "path", "required": true, "description": "UUID da entrega: o `uuid` de uma entrada retornada por `GET /v3/webhook/destinations/{destination_uuid}/deliveries/`.", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/66666666-7777-8888-9999-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieveDelivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.RetrieveDelivery(ctx, \"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieveDelivery(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieveDelivery('11111111-2222-3333-4444-555555555555', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveDeliveryAsync(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A entrega, com os respetivos cabeçalhos e corpo do pedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationDeliveryDetail" }, "examples": { "Connection failure": { "value": { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "response_time_ms": 412, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:21:18.412345Z", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}" } } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Um `x-api-key` em falta, inválido ou revogado recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.` Uma chave limitada a alguns fluxos ou a sessões aprovadas recebe `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "O destino não existe para a aplicação ou foi eliminado, ou a entrega não existe, pertence a outro destino ou já não está disponível.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } }, "Delivery not found": { "value": { "detail": "Webhook delivery not found." } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 600 pedidos GET na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/{delivery_uuid}/resend/": { "post": { "summary": "Reenviar entrega para o destino do webhook", "description": "Envie novamente uma entrega anterior, por exemplo, após o seu endpoint ter estado indisponível. A Didit utiliza o payload guardado, define um novo `timestamp`, assina-o novamente com o `secret_shared_key` atual do destino (`X-Signature`, `X-Signature-V2`, `X-Signature-Simple` e `X-Timestamp`) e envia-o por POST para o `request_url` da entrega, mesmo que o URL do destino tenha mudado entretanto ou o destino esteja desativado. O `event_id` e o resto do payload permanecem inalterados, pelo que deve eliminar duplicados com base no `event_id`. A chamada aguarda até 5 segundos pelo seu endpoint e devolve a nova entrega com `200`, qualquer que tenha sido a resposta do seu endpoint: leia o `response_status`. Um reenvio não é repetido automaticamente, cada chamada envia novamente e cria uma nova entrega, e o pedido não tem corpo. Uma chave de API com âmbito precisa de `webhooks: write` e `decisions: read`; uma chave limitada a alguns fluxos ou a sessões aprovadas não pode utilizar este endpoint.", "operationId": "resend_webhook_destination_delivery", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "resend_delivery", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID do destino para o qual a entrega foi enviada.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "delivery_uuid", "in": "path", "required": true, "description": "UUID da entrega a reenviar: o `uuid` de uma entrada retornada por `GET /v3/webhook/destinations/{destination_uuid}/deliveries/`.", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/66666666-7777-8888-9999-000000000001/resend/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.resend_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.resendDelivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.ResendDelivery(ctx, \"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().resendDelivery(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->resendDelivery('11111111-2222-3333-4444-555555555555', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.resend_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.ResendDeliveryAsync(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A nova entrega, já tentada. `response_status` é o que o seu endpoint respondeu desta vez (`504` tempo limite excedido, `503` falha de ligação). A entrega original permanece inalterada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationDeliveryDetail" }, "examples": { "Accepted on resend": { "value": { "uuid": "66666666-7777-8888-9999-000000000004", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "response_time_ms": 151, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-16T14:05:42.330981Z", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"b8eb1e376517ee0cad8ba98ff7f8fd35fc72eca231000963a96a335f82328835\", \"X-Signature-V2\": \"9efd2ce9ed1303e1d05273ef9608a59363ed9789a05253db4748b3e8e50cb109\", \"X-Signature-Simple\": \"bf3a9dc04b2c20ab539203b0cd5cca2a10f630bf62d8feb6d68d82af80f64774\", \"X-Timestamp\": \"1792159542\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792159542,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}" } } } } } }, "400": { "description": "A entrega armazenada não pôde ser assinada novamente. Nada é enviado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." }, "code": { "type": "string", "description": "Código de erro legível por máquina estável. Crie ramificações com base neste campo, e não em `detail`." } } }, "examples": { "Unsignable delivery": { "value": { "detail": "Invalid webhook data format", "code": "invalid_webhook_payload" } } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Um `x-api-key` em falta, inválido ou revogado recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.` Uma chave limitada a alguns fluxos ou a sessões aprovadas recebe `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "O destino não existe para a aplicação ou foi eliminado, ou a entrega não existe, pertence a outro destino ou já não está disponível.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } }, "Delivery not found": { "value": { "detail": "Webhook delivery not found." } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 300 pedidos de escrita (POST, PATCH, PUT, DELETE) na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (300).", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/": { "get": { "summary": "Listar eventos de monitorização", "description": "Listar os eventos de monitorização armazenados para a sua aplicação, do `occurred_at` mais recente para o mais antigo, com filtros opcionais que são combinados com AND. Os filtros multivalor (`event_category`, `action_type`, `status`, `retention_class`) repetem o parâmetro e correspondem a qualquer um dos valores; os restantes filtros são correspondências exatas, e valores desconhecidos simplesmente não devolvem eventos. Cada resultado é um resumo: chame `GET /v3/events/{event_uuid}/` para obter o payload, o contexto do dispositivo, o enriquecimento de IP e a evidência da regra, e dê preferência a `GET /v3/events/subjects/{vendor_data}/` para o histórico de um sujeito. As leituras funcionam quer a ingestão de eventos esteja ativada quer não. Uma chave de API com âmbito restrito necessita de `transactions: read`. Consulte [Ingestão de eventos](https://docs.didit.me/pt/transaction-monitoring/events).", "operationId": "list_monitoring_events", "x-didit-sdk": { "resource": "monitoring_events", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Número máximo de eventos por página. O valor predefinido é 50. Valores acima de 1000000 devolvem `400`; um valor não numérico, zero ou negativo reverte para 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Número de eventos a ignorar. A predefinição é 0. É preferível seguir o URL `next` da resposta.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "event_category", "in": "query", "required": false, "description": "Apenas eventos nestas categorias. Repita o parâmetro para vários valores (`?event_category=payment&event_category=dispute`); é devolvido qualquer evento que corresponda a qualquer um deles.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] } }, "example": [ "payment", "dispute" ] }, { "name": "action_type", "in": "query", "required": false, "description": "Apenas eventos com estes tipos de ação (exatos, sensíveis a maiúsculas e minúsculas). Repita para vários valores.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "deposit_completed", "chargeback_opened" ] }, { "name": "status", "in": "query", "required": false, "description": "Apenas eventos com estes estados. Repita para vários valores.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ] } }, "example": [ "IN_REVIEW", "DECLINED" ] }, { "name": "retention_class", "in": "query", "required": false, "description": "Apenas eventos nestas classes de conservação. Repita para vários valores.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ] } }, "example": [ "risk_relevant" ] }, { "name": "subject_vendor_data", "in": "query", "required": false, "description": "Correspondência exata no `vendor_data` do sujeito. O mesmo ID pode nomear um indivíduo e uma empresa; adicione `subject_entity_type` para escolher um, ou utilize `GET /v3/events/subjects/{vendor_data}/`.", "schema": { "type": "string" }, "example": "user-42" }, { "name": "subject_entity_type", "in": "query", "required": false, "description": "`company` devolve apenas eventos de sujeitos do tipo empresa; qualquer outro valor não vazio (por exemplo `individual`) devolve apenas eventos de indivíduos. Omita-o para devolver ambos.", "schema": { "type": "string", "enum": [ "individual", "company" ] }, "example": "individual" }, { "name": "business_vendor_data", "in": "query", "required": false, "description": "Correspondência exata no `business.vendor_data` enviado com o evento.", "schema": { "type": "string" }, "example": "merchant-7" }, { "name": "session_id", "in": "query", "required": false, "description": "Correspondência exata em `session.session_id`.", "schema": { "type": "string" }, "example": "web-session-abc" }, { "name": "device_fingerprint", "in": "query", "required": false, "description": "Correspondência exata em `device_context.fingerprint`.", "schema": { "type": "string" }, "example": "fp-a8c1" }, { "name": "ip_address", "in": "query", "required": false, "description": "Correspondência exata no endereço IP do evento.", "schema": { "type": "string" }, "example": "203.0.113.42" }, { "name": "game_id", "in": "query", "required": false, "description": "Correspondência exata no `game_id` promovido.", "schema": { "type": "string" }, "example": "poker-holdem-01" }, { "name": "round_id", "in": "query", "required": false, "description": "Correspondência exata no `round_id` promovido.", "schema": { "type": "string" }, "example": "round-88231" }, { "name": "affiliate_code", "in": "query", "required": false, "description": "Correspondência exata no `affiliate_code` promovido.", "schema": { "type": "string" }, "example": "aff-summer" }, { "name": "payment_reference_id", "in": "query", "required": false, "description": "Correspondência exata na referência de pagamento (de `transaction_context.payment_reference_id` ou `payload.payment_reference_id`).", "schema": { "type": "string" }, "example": "dep_735" }, { "name": "counterparty_vendor_data", "in": "query", "required": false, "description": "Correspondência exata no `counterparty_vendor_data` promovido.", "schema": { "type": "string" }, "example": "user-77" }, { "name": "matched_only", "in": "query", "required": false, "description": "`true` (também `1` ou `yes`, não sensível a maiúsculas/minúsculas) devolve apenas eventos correspondidos por pelo menos uma regra (`rules_matched_count` superior a 0). Qualquer outro valor é ignorado.", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "occurred_from", "in": "query", "required": false, "description": "Apenas eventos com `occurred_at` neste instante ou após o mesmo (inclusive). Envie um valor ISO 8601: `2026-10-01T00:00:00Z`, um deslocamento explícito com o `+` codificado por percentagem (`2026-10-01T02:00:00%2B02:00`; um `+` não codificado é descodificado como um espaço e o valor deixa de ser analisado), ou apenas uma data (`2026-10-01`), o que significa 00:00:00 UTC desse dia. Um valor sem deslocamento é lido como UTC. Valores em qualquer outro formato não são aceites.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "occurred_to", "in": "query", "required": false, "description": "Apenas eventos com `occurred_at` neste instante ou antes do mesmo (inclusive). Uma data por si só significa o início desse dia, pelo que `occurred_to=2026-10-15` exclui o resto de 15 de outubro; envie `2026-10-15T23:59:59Z` para o incluir. Envie um valor ISO 8601: `2026-10-01T00:00:00Z`, um deslocamento explícito com o `+` codificado por percentagem (`2026-10-01T02:00:00%2B02:00`; um `+` não codificado é descodificado como um espaço e o valor deixa de ser analisado), ou apenas uma data (`2026-10-01`), o que significa 00:00:00 UTC desse dia. Um valor sem deslocamento é lido como UTC. Valores em qualquer outro formato não são aceites.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-17T23:59:59Z" }, { "name": "search", "in": "query", "required": false, "description": "Correspondência de subcadeia sem distinção entre maiúsculas e minúsculas em `event_id`, `action_type`, `subject_vendor_data` ou `counterparty_vendor_data`.", "schema": { "type": "string" }, "example": "chargeback" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true&occurred_from=2026-10-01T00:00:00Z&limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.monitoring_events.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.monitoringEvents.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.MonitoringEvents.ListAutoPaging(ctx, didit.MonitoringEventsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.monitoringEvents().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.MonitoringEvents.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de resumos de eventos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventPage" }, "examples": { "Payment and dispute events": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "received_at": "2026-10-16T14:02:12.418230Z", "status": "IN_REVIEW", "score": 60, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": null, "device_fingerprint": null, "ip_address": null, "ip_country": null, "amount": "250.000000000000000000", "currency": "EUR", "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": "dep_735", "retention_class": "monetary_or_compliance", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": false }, { "event_uuid": "22222222-3333-4444-5555-666666666666", "event_id": "login-2026-10-15-000912", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-15T08:30:00.120000Z", "received_at": "2026-10-15T08:30:00.734512Z", "status": "ACCEPTED", "score": 0, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "standard", "rules_matched_count": 0, "correlation_pending": false, "is_droppable": true } ] } } } } } }, "400": { "description": "`limit` ou `offset` é superior a 1000000. O corpo é um array JSON com uma mensagem. Um `limit` não numérico ou não positivo reverte para o valor padrão de 50 em vez de falhar.", "content": { "application/json": { "examples": { "limit too large": { "summary": "limit superior a 1000000", "value": [ "limit must not exceed 1000000." ] }, "offset too large": { "summary": "offset superior a 1000000", "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "A chave de API com âmbito expirou. Apenas uma chave expirada recebe `401`; uma chave em falta ou inválida recebe `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Um `x-api-key` em falta (uma chave incorreta, revogada ou expirada obtém `401`), uma chave com âmbito restrito sem `transactions: read`, uma chave limitada a alguns fluxos ou a sessões aprovadas (tal chave nunca acede a dados de monitorização de transações), ou um pedido fora da lista de permissões de IP da chave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite de pedidos excedido: os pedidos `GET` partilham um orçamento de 600 pedidos por minuto por chave de API. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar evento de monitorização", "description": "Envie um evento não monetário (início de sessão, sessão, jogabilidade, bónus, afiliado, pagamento, litígio, segurança, jogo responsável ou personalizado) a partir do seu backend. O evento é validado contra o contrato da sua categoria, armazenado, enriquecido com dados de IP uma vez por endereço público exclusivo e avaliado pelas suas regras de eventos em tempo real antes de a resposta ser devolvida; regras entre sujeitos e com janelas temporais alargadas são executadas de forma assíncrona (`correlation_pending: true`), e numa aplicação de sandbox nenhuma regra é executada. `event_id` é a chave de idempotência: o mesmo `event_id` com o mesmo `event_category`, `action_type`, `occurred_at`, `subject.vendor_data` e `payload` devolve `200` com `idempotent_replay: true` e o resultado guardado (outros campos do envelope não são comparados), enquanto valores diferentes devolvem `409`. A ingestão de eventos é opcional por aplicação: até ser ativada, este endpoint devolve `403` com `code: event_monitoring_disabled` e não guarda nada. Uma chave de API com âmbito necessita de `transactions: write`. Consulte [Ingestão de eventos](https://docs.didit.me/pt/transaction-monitoring/events) e [Regras sobre eventos](https://docs.didit.me/pt/transaction-monitoring/event-rules); para enviar eventos a partir de um navegador ou aplicação, utilize [Submissão de eventos do SDK](https://docs.didit.me/pt/transaction-monitoring/sdk-event-submission).", "operationId": "create_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventCreateRequest" }, "examples": { "Login": { "value": { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "time_zone": "Europe/Madrid", "subject": { "vendor_data": "user-42", "entity_type": "individual" }, "session": { "session_id": "web-session-abc", "sequence": 142 }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42" } }, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold" } } }, "Deposit completed": { "value": { "event_id": "deposit-2026-10-17-000002", "event_category": "payment", "action_type": "deposit_completed", "occurred_at": "2026-10-17T09:16:40Z", "subject": { "vendor_data": "user-42" }, "transaction_context": { "amount": "100.00", "currency": "EUR", "direction": "inbound", "payment_reference_id": "dep_736" }, "payload": { "payment_method": "card", "status": "completed" } } }, "Chargeback opened": { "value": { "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "subject": { "vendor_data": "user-42" }, "payload": { "payment_reference_id": "dep_735", "chargeback_id": "cb_5521", "amount": "250.00", "currency": "EUR", "reason_code": "fraud" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"event_id\": \"login-2026-10-17-000001\",\n \"event_category\": \"auth\",\n \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\",\n \"subject\": {\"vendor_data\": \"user-42\", \"entity_type\": \"individual\"},\n \"session\": {\"session_id\": \"web-session-abc\", \"sequence\": 142},\n \"device_context\": {\n \"fingerprint\": \"fp-a8c1\",\n \"network_context\": {\"ip_address\": \"203.0.113.42\"}\n },\n \"payload\": {\"method\": \"password\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create(\n event_id=\"login-2026-10-17-000001\",\n event_category=\"auth\",\n action_type=\"login\",\n occurred_at=\"2026-10-17T09:15:02.481Z\",\n time_zone=\"Europe/Madrid\",\n subject={\n \"vendor_data\": \"user-42\",\n \"entity_type\": \"individual\",\n },\n session={\n \"session_id\": \"web-session-abc\",\n \"sequence\": 142,\n },\n device_context={\n \"fingerprint\": \"fp-a8c1\",\n \"network_context\": {\n \"ip_address\": \"203.0.113.42\",\n },\n },\n payload={\"method\": \"password\"},\n custom_values={\"vip_tier\": \"gold\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.create({\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n time_zone: \"Europe/Madrid\",\n subject: {\n vendor_data: \"user-42\",\n entity_type: \"individual\",\n },\n session: {\n session_id: \"web-session-abc\",\n sequence: 142,\n },\n device_context: {\n fingerprint: \"fp-a8c1\",\n network_context: {\n ip_address: \"203.0.113.42\",\n },\n },\n payload: { method: \"password\" },\n custom_values: { vip_tier: \"gold\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Create(ctx, didit.MonitoringEventCreateRequest{\n\tEventID: \"login-2026-10-17-000001\",\n\tEventCategory: \"auth\",\n\tActionType: \"login\",\n\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\tTimeZone: didit.String(\"Europe/Madrid\"),\n\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\tVendorData: \"user-42\",\n\t\tEntityType: didit.String(\"individual\"),\n\t},\n\tSession: didit.Some(didit.MonitoringEventCreateRequestSession{\n\t\tSessionID: didit.String(\"web-session-abc\"),\n\t\tSequence: didit.Int(142),\n\t}),\n\tDeviceContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContext{\n\t\tFingerprint: didit.String(\"fp-a8c1\"),\n\t\tNetworkContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContextNetworkContext{\n\t\t\tIPAddress: didit.String(\"203.0.113.42\"),\n\t\t}),\n\t}),\n\tPayload: didit.Some(map[string]any{\"method\": \"password\"}),\n\tCustomValues: didit.Some(map[string]any{\"vip_tier\": \"gold\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventCreateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().create(MonitoringEventCreateRequest.builder()\n .eventId(\"login-2026-10-17-000001\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"auth\"))\n .actionType(\"login\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:15:02.481Z\"))\n .timeZone(\"Europe/Madrid\")\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .entityType(\"individual\")\n .build())\n .session(MonitoringEventCreateRequest.Session.builder()\n .sessionId(\"web-session-abc\")\n .sequence(142L)\n .build())\n .deviceContext(MonitoringEventCreateRequest.DeviceContext.builder()\n .fingerprint(\"fp-a8c1\")\n .networkContext(MonitoringEventCreateRequest.DeviceContext.NetworkContext.builder()\n .ipAddress(\"203.0.113.42\")\n .build())\n .build())\n .payload(Map.of(\"method\", \"password\"))\n .customValues(Map.of(\"vip_tier\", MonitoringEventCreateRequest.CustomValuesValue.ofString(\"gold\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->create([\n 'event_id' => 'login-2026-10-17-000001',\n 'event_category' => 'auth',\n 'action_type' => 'login',\n 'occurred_at' => '2026-10-17T09:15:02.481Z',\n 'time_zone' => 'Europe/Madrid',\n 'subject' => [\n 'vendor_data' => 'user-42',\n 'entity_type' => 'individual',\n ],\n 'session' => [\n 'session_id' => 'web-session-abc',\n 'sequence' => 142,\n ],\n 'device_context' => [\n 'fingerprint' => 'fp-a8c1',\n 'network_context' => [\n 'ip_address' => '203.0.113.42',\n ],\n ],\n 'payload' => ['method' => 'password'],\n 'custom_values' => ['vip_tier' => 'gold'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create(\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n time_zone: \"Europe/Madrid\",\n subject: {\n vendor_data: \"user-42\",\n entity_type: \"individual\",\n },\n session: {\n session_id: \"web-session-abc\",\n sequence: 142,\n },\n device_context: {\n fingerprint: \"fp-a8c1\",\n network_context: {\n ip_address: \"203.0.113.42\",\n },\n },\n payload: { method: \"password\" },\n custom_values: { vip_tier: \"gold\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateAsync(new MonitoringEventCreateRequest\n{\n EventId = \"login-2026-10-17-000001\",\n EventCategory = \"auth\",\n ActionType = \"login\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:15:02.481Z\"),\n TimeZone = \"Europe/Madrid\",\n Subject = new()\n {\n VendorData = \"user-42\",\n EntityType = \"individual\",\n },\n Session = new MonitoringEventCreateRequestSession\n {\n SessionId = \"web-session-abc\",\n Sequence = 142,\n },\n DeviceContext = new MonitoringEventCreateRequestDeviceContext\n {\n Fingerprint = \"fp-a8c1\",\n NetworkContext = new MonitoringEventCreateRequestDeviceContextNetworkContext\n {\n IpAddress = \"203.0.113.42\",\n },\n },\n Payload = new Dictionary { [\"method\"] = \"password\" },\n CustomValues = new Dictionary { [\"vip_tier\"] = \"gold\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "O evento foi armazenado e avaliado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventIngestResult" }, "examples": { "Stored, no rule matched": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] } }, "Rule matched, async rule pending": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "IN_REVIEW", "score": 40, "rules_evaluated_count": 6, "rules_matched_count": 1, "correlation_pending": true, "retention_class": "risk_relevant", "expires_at": "2027-01-15T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [ { "rule_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "library_key": null, "mode": "ACTIVE", "is_async": false } ] } } } } } }, "200": { "description": "Reexecução idempotente: já se encontra armazenado um evento com este `event_id` e o mesmo conteúdo. Nada foi armazenado ou avaliado novamente; o corpo descreve o evento armazenado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventIngestResult" }, "examples": { "Replay": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": true, "rule_matches": [] } } } } } }, "400": { "description": "A validação falhou. O corpo é indexado por campo; os campos aninhados são objetos aninhados. Nada é guardado.", "content": { "application/json": { "examples": { "Missing fields": { "value": { "event_id": [ "This field is required." ], "subject": [ "This field is required." ] } }, "Unknown category": { "value": { "event_category": [ "\"login\" is not a valid choice." ] } }, "occurred_at too old": { "value": { "occurred_at": [ "occurred_at is more than 7 days in the past. Use the batch import lane for backfills." ] } }, "occurred_at in the future": { "value": { "occurred_at": [ "occurred_at is more than 5 minutes in the future." ] } }, "Missing subject vendor_data": { "value": { "subject": { "vendor_data": [ "This field is required." ] } } }, "Missing required payload keys": { "value": { "payload": [ "payment.deposit_completed requires: payment_method, status." ] } }, "Missing one-of payload key": { "value": { "payload": [ "dispute.chargeback_opened requires one of: dispute_id, chargeback_id." ] } }, "Security change without changed_field": { "value": { "payload": [ "security.*_changed requires 'changed_field'." ] } }, "Payload too large": { "value": { "payload": [ "payload exceeds 16384 bytes. Summarise telemetry client-side." ] } }, "Too many custom_values": { "value": { "custom_values": [ "custom_values accepts at most 100 keys." ] } }, "Nested custom value": { "value": { "custom_values": [ "custom_values['limits'] must be a scalar - rule conditions cannot address nested values." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Apenas uma chave expirada recebe `401`; uma chave em falta ou inválida recebe `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Um `x-api-key` em falta (uma chave incorreta, revogada ou expirada obtém `401`), uma chave com âmbito restrito sem `transactions: write`, uma chave limitada a alguns fluxos ou a sessões aprovadas (tal chave nunca acede a dados de monitorização de transações), ou um pedido fora da lista de permissões de IP da chave. Também devolvido com `code: event_monitoring_disabled` enquanto a ingestão de eventos estiver desativada para a aplicação; nada é armazenado nesse caso, e a verificação é executada antes da validação do corpo.", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "409": { "description": "`event_id` já foi utilizado para um evento com conteúdo diferente (categoria, tipo de ação, `occurred_at`, `vendor_data` do sujeito ou payload). Envie o evento com um novo `event_id`.", "content": { "application/json": { "examples": { "event_id reused": { "value": { "event_id": "event_id 'login-2026-10-17-000001' already exists with a different payload." } } } } } }, "429": { "description": "Limite de pedidos excedido: a criação de transações e a ingestão de eventos (`POST /v3/transactions/`, `POST /v3/events/`, `POST /v3/events/batch/`) partilham um orçamento de 600 pedidos por minuto por chave de API, separado dos 300 partilhados por todos os outros pedidos de escrita. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente, arredondados para cima para que a nova tentativa ocorra na janela seguinte.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/batch/": { "post": { "summary": "Criar eventos de monitorização em lote", "description": "Submeta 1 a 500 eventos num único pedido, cada um no mesmo envelope que `POST /v3/events/`. Cada item é validado, armazenado e avaliado individualmente e obtém o seu próprio resultado (`accepted`, `replayed` ou `rejected`), pelo que um evento malformado nunca reverte os restantes: a resposta é `201` quando nenhum item foi rejeitado e `207` quando pelo menos um o foi, sendo que ambas significam que o pedido foi processado. Envie `{\"events\": [...]}`; uma matriz JSON simples de eventos também é aceite. A ingestão de eventos tem de estar ativada para a aplicação; caso contrário, todo o pedido devolve `403` com `code: event_monitoring_disabled` e nada é armazenado. Uma chave de API com âmbito necessita de `transactions: write`. Consulte [Batches](https://docs.didit.me/pt/transaction-monitoring/events#lotes).", "operationId": "create_monitoring_events_batch", "x-didit-sdk": { "resource": "monitoring_events", "method": "create_batch", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 500, "description": "1 a 500 eventos. Cada item segue `MonitoringEventCreateRequest`, incluindo a janela de 7 dias no passado e 5 minutos no futuro em `occurred_at`.", "items": { "$ref": "#/components/schemas/MonitoringEventCreateRequest" } } } }, "example": { "events": [ { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "subject": { "vendor_data": "user-42" } }, { "event_id": "deposit-2026-10-17-000002", "event_category": "payment", "action_type": "deposit_completed", "occurred_at": "2026-10-17T09:16:40Z", "subject": { "vendor_data": "user-42" }, "transaction_context": { "amount": "100.00", "currency": "EUR", "payment_reference_id": "dep_736" }, "payload": { "payment_method": "card", "status": "completed" } } ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/batch/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"events\": [\n {\"event_id\": \"login-2026-10-17-000001\", \"event_category\": \"auth\", \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\", \"subject\": {\"vendor_data\": \"user-42\"}},\n {\"event_id\": \"deposit-2026-10-17-000002\", \"event_category\": \"payment\", \"action_type\": \"deposit_completed\",\n \"occurred_at\": \"2026-10-17T09:16:40.000Z\", \"subject\": {\"vendor_data\": \"user-42\"},\n \"transaction_context\": {\"amount\": \"100.00\", \"currency\": \"EUR\", \"payment_reference_id\": \"dep_736\"},\n \"payload\": {\"payment_method\": \"card\", \"status\": \"completed\"}}\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create_batch(\n events=[{\n \"event_id\": \"login-2026-10-17-000001\",\n \"event_category\": \"auth\",\n \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\",\n \"subject\": {\n \"vendor_data\": \"user-42\",\n },\n }, {\n \"event_id\": \"deposit-2026-10-17-000002\",\n \"event_category\": \"payment\",\n \"action_type\": \"deposit_completed\",\n \"occurred_at\": \"2026-10-17T09:16:40Z\",\n \"subject\": {\n \"vendor_data\": \"user-42\",\n },\n \"transaction_context\": {\n \"amount\": \"100.00\",\n \"currency\": \"EUR\",\n \"payment_reference_id\": \"dep_736\",\n },\n \"payload\": {\"payment_method\": \"card\", \"status\": \"completed\"},\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.createBatch({\n events: [{\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n }, {\n event_id: \"deposit-2026-10-17-000002\",\n event_category: \"payment\",\n action_type: \"deposit_completed\",\n occurred_at: \"2026-10-17T09:16:40Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n transaction_context: {\n amount: \"100.00\",\n currency: \"EUR\",\n payment_reference_id: \"dep_736\",\n },\n payload: { payment_method: \"card\", status: \"completed\" },\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.CreateBatch(ctx, didit.MonitoringEventsCreateBatchParams{\n\tEvents: []didit.MonitoringEventCreateRequest{{\n\t\tEventID: \"login-2026-10-17-000001\",\n\t\tEventCategory: \"auth\",\n\t\tActionType: \"login\",\n\t\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\t\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\t\tVendorData: \"user-42\",\n\t\t},\n\t}, {\n\t\tEventID: \"deposit-2026-10-17-000002\",\n\t\tEventCategory: \"payment\",\n\t\tActionType: \"deposit_completed\",\n\t\tOccurredAt: time.Date(2026, 10, 17, 9, 16, 40, 0, time.UTC),\n\t\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\t\tVendorData: \"user-42\",\n\t\t},\n\t\tTransactionContext: didit.Some(didit.MonitoringEventCreateRequestTransactionContext{\n\t\t\tAmount: didit.String(\"100.00\"),\n\t\t\tCurrency: didit.String(\"EUR\"),\n\t\t\tPaymentReferenceID: didit.String(\"dep_736\"),\n\t\t}),\n\t\tPayload: didit.Some(map[string]any{\"payment_method\": \"card\", \"status\": \"completed\"}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventCreateRequest;\nimport me.didit.types.MonitoringEventsCreateBatchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().createBatch(MonitoringEventsCreateBatchParams.builder()\n .events(List.of(\n MonitoringEventCreateRequest.builder()\n .eventId(\"login-2026-10-17-000001\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"auth\"))\n .actionType(\"login\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:15:02.481Z\"))\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .build())\n .build(),\n MonitoringEventCreateRequest.builder()\n .eventId(\"deposit-2026-10-17-000002\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"payment\"))\n .actionType(\"deposit_completed\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:16:40Z\"))\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .build())\n .transactionContext(MonitoringEventCreateRequest.TransactionContext.builder()\n .amount(\"100.00\")\n .currency(\"EUR\")\n .paymentReferenceId(\"dep_736\")\n .build())\n .payload(Map.of(\"payment_method\", \"card\", \"status\", \"completed\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->createBatch([\n 'events' => [[\n 'event_id' => 'login-2026-10-17-000001',\n 'event_category' => 'auth',\n 'action_type' => 'login',\n 'occurred_at' => '2026-10-17T09:15:02.481Z',\n 'subject' => [\n 'vendor_data' => 'user-42',\n ],\n ], [\n 'event_id' => 'deposit-2026-10-17-000002',\n 'event_category' => 'payment',\n 'action_type' => 'deposit_completed',\n 'occurred_at' => '2026-10-17T09:16:40Z',\n 'subject' => [\n 'vendor_data' => 'user-42',\n ],\n 'transaction_context' => [\n 'amount' => '100.00',\n 'currency' => 'EUR',\n 'payment_reference_id' => 'dep_736',\n ],\n 'payload' => ['payment_method' => 'card', 'status' => 'completed'],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create_batch(\n events: [{\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n }, {\n event_id: \"deposit-2026-10-17-000002\",\n event_category: \"payment\",\n action_type: \"deposit_completed\",\n occurred_at: \"2026-10-17T09:16:40Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n transaction_context: {\n amount: \"100.00\",\n currency: \"EUR\",\n payment_reference_id: \"dep_736\",\n },\n payload: { payment_method: \"card\", status: \"completed\" },\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateBatchAsync(new MonitoringEventsCreateBatchParams\n{\n Events = new MonitoringEventCreateRequest[]\n {\n new()\n {\n EventId = \"login-2026-10-17-000001\",\n EventCategory = \"auth\",\n ActionType = \"login\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:15:02.481Z\"),\n Subject = new()\n {\n VendorData = \"user-42\",\n },\n },\n new()\n {\n EventId = \"deposit-2026-10-17-000002\",\n EventCategory = \"payment\",\n ActionType = \"deposit_completed\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:16:40Z\"),\n Subject = new()\n {\n VendorData = \"user-42\",\n },\n TransactionContext = new MonitoringEventCreateRequestTransactionContext\n {\n Amount = \"100.00\",\n Currency = \"EUR\",\n PaymentReferenceId = \"dep_736\",\n },\n Payload = new Dictionary { [\"payment_method\"] = \"card\", [\"status\"] = \"completed\" },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Nenhum item foi rejeitado: todos os itens foram `accepted` ou `replayed`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted_count", "replayed_count", "rejected_count", "results" ], "properties": { "accepted_count": { "type": "integer", "minimum": 0, "description": "Itens guardados e avaliados." }, "replayed_count": { "type": "integer", "minimum": 0, "description": "Itens já guardados com o mesmo conteúdo." }, "rejected_count": { "type": "integer", "minimum": 0, "description": "Itens não guardados." }, "results": { "type": "array", "description": "Uma entrada por item, na ordem do pedido.", "items": { "type": "object", "description": "Resultado de um item. Itens aceites e repetidos também incluem todos os campos de `MonitoringEventIngestResult`; itens rejeitados incluem `event_id` e `errors` em vez disso.", "required": [ "index", "outcome" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Posição do item no seu array `events`." }, "outcome": { "type": "string", "enum": [ "accepted", "replayed", "rejected" ], "description": "`accepted`: armazenado e avaliado. `replayed`: já armazenado com o mesmo conteúdo. `rejected`: não armazenado; consulte `errors`." }, "event_id": { "type": "string", "nullable": true, "description": "O seu `event_id`. Nos itens rejeitados pela validação, é lido a partir da chave snake_case `event_id` do item, pelo que é nulo quando o item o omitiu ou enviou o alias `eventId`." }, "errors": { "type": "object", "additionalProperties": true, "description": "Apenas itens rejeitados. Erros de validação indexados por campo, na mesma estrutura do `400` de `POST /v3/events/`; um `event_id` reutilizado com conteúdo diferente é reportado como uma string sob `errors.event_id`." }, "event_uuid": { "type": "string", "format": "uuid", "description": "Apenas itens aceites e reproduzidos." }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "Apenas itens aceites e reproduzidos." }, "score": { "type": "integer", "description": "Apenas itens aceites e reproduzidos." }, "rules_evaluated_count": { "type": "integer", "description": "Apenas itens aceites e reproduzidos." }, "rules_matched_count": { "type": "integer", "description": "Apenas itens aceites e reproduzidos." }, "correlation_pending": { "type": "boolean", "description": "Apenas itens aceites e reproduzidos." }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "Apenas itens aceites e reproduzidos." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Apenas itens aceites e reproduzidos." }, "idempotent_replay": { "type": "boolean", "description": "Apenas itens aceites e reproduzidos." }, "rule_matches": { "type": "array", "description": "Apenas itens aceites e reproduzidos.", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "UUID da regra." }, "library_key": { "type": "string", "nullable": true, "description": "Chave da biblioteca quando a regra foi instalada a partir da biblioteca de regras; caso contrário, null." }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "As regras `TEST` registam a correspondência, mas não aplicam ações." }, "is_async": { "type": "boolean", "description": "`true` quando a correspondência resultou da passagem assíncrona." } } } } } } } } }, "examples": { "All landed": { "value": { "accepted_count": 1, "replayed_count": 1, "rejected_count": 0, "results": [ { "index": 0, "outcome": "accepted", "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] }, { "index": 1, "outcome": "replayed", "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "deposit-2026-10-17-000002", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "monetary_or_compliance", "expires_at": null, "idempotent_replay": true, "rule_matches": [] } ] } } } } } }, "207": { "description": "Pelo menos um item foi rejeitado. Os restantes itens foram guardados; corrija e reenvie apenas os rejeitados (reenviar um item aceite é seguro, é devolvido como `replayed`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted_count", "replayed_count", "rejected_count", "results" ], "properties": { "accepted_count": { "type": "integer", "minimum": 0, "description": "Itens guardados e avaliados." }, "replayed_count": { "type": "integer", "minimum": 0, "description": "Itens já guardados com o mesmo conteúdo." }, "rejected_count": { "type": "integer", "minimum": 0, "description": "Itens não guardados." }, "results": { "type": "array", "description": "Uma entrada por item, na ordem do pedido.", "items": { "type": "object", "description": "Resultado de um item. Itens aceites e repetidos também incluem todos os campos de `MonitoringEventIngestResult`; itens rejeitados incluem `event_id` e `errors` em vez disso.", "required": [ "index", "outcome" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Posição do item no seu array `events`." }, "outcome": { "type": "string", "enum": [ "accepted", "replayed", "rejected" ], "description": "`accepted`: armazenado e avaliado. `replayed`: já armazenado com o mesmo conteúdo. `rejected`: não armazenado; consulte `errors`." }, "event_id": { "type": "string", "nullable": true, "description": "O seu `event_id`. Nos itens rejeitados pela validação, é lido a partir da chave snake_case `event_id` do item, pelo que é nulo quando o item o omitiu ou enviou o alias `eventId`." }, "errors": { "type": "object", "additionalProperties": true, "description": "Apenas itens rejeitados. Erros de validação indexados por campo, na mesma estrutura do `400` de `POST /v3/events/`; um `event_id` reutilizado com conteúdo diferente é reportado como uma string sob `errors.event_id`." }, "event_uuid": { "type": "string", "format": "uuid", "description": "Apenas itens aceites e reproduzidos." }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "Apenas itens aceites e reproduzidos." }, "score": { "type": "integer", "description": "Apenas itens aceites e reproduzidos." }, "rules_evaluated_count": { "type": "integer", "description": "Apenas itens aceites e reproduzidos." }, "rules_matched_count": { "type": "integer", "description": "Apenas itens aceites e reproduzidos." }, "correlation_pending": { "type": "boolean", "description": "Apenas itens aceites e reproduzidos." }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "Apenas itens aceites e reproduzidos." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Apenas itens aceites e reproduzidos." }, "idempotent_replay": { "type": "boolean", "description": "Apenas itens aceites e reproduzidos." }, "rule_matches": { "type": "array", "description": "Apenas itens aceites e reproduzidos.", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "UUID da regra." }, "library_key": { "type": "string", "nullable": true, "description": "Chave da biblioteca quando a regra foi instalada a partir da biblioteca de regras; caso contrário, null." }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "As regras `TEST` registam a correspondência, mas não aplicam ações." }, "is_async": { "type": "boolean", "description": "`true` quando a correspondência resultou da passagem assíncrona." } } } } } } } } }, "examples": { "Partial success": { "value": { "accepted_count": 1, "replayed_count": 0, "rejected_count": 2, "results": [ { "index": 0, "outcome": "accepted", "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] }, { "index": 1, "event_id": "deposit-2026-10-17-000002", "outcome": "rejected", "errors": { "payload": [ "payment.deposit_completed requires: payment_method, status." ] } }, { "index": 2, "event_id": "login-2026-10-16-000777", "outcome": "rejected", "errors": { "event_id": "event_id 'login-2026-10-16-000777' already exists with a different payload." } } ] } } } } } }, "400": { "description": "O próprio lote está malformado: `events` está em falta ou não é um array, está vazio ou contém mais de 500 itens. Nada é armazenado; divida lotes grandes.", "content": { "application/json": { "examples": { "Not a list": { "value": { "events": "Expected a list of events." } }, "Empty": { "value": { "events": "At least one event is required." } }, "Too many": { "value": { "events": "A batch accepts at most 500 events; received 612." } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Apenas uma chave expirada recebe `401`; uma chave em falta ou inválida recebe `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Um `x-api-key` em falta (uma chave incorreta, revogada ou expirada obtém `401`), uma chave com âmbito restrito sem `transactions: write`, uma chave limitada a alguns fluxos ou a sessões aprovadas (tal chave nunca acede a dados de monitorização de transações), ou um pedido fora da lista de permissões de IP da chave. Também devolvido com `code: event_monitoring_disabled` enquanto a ingestão de eventos estiver desativada para a aplicação; nada é armazenado nesse caso, e a verificação é executada antes da validação do corpo.", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite de pedidos excedido: a criação de transações e a ingestão de eventos (`POST /v3/transactions/`, `POST /v3/events/`, `POST /v3/events/batch/`) partilham um orçamento de 600 pedidos por minuto por chave de API, separado dos 300 partilhados por todos os outros pedidos de escrita. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente, arredondados para cima para que a nova tentativa ocorra na janela seguinte.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/sdk-token/": { "post": { "summary": "Emitir um token do SDK de monitorização", "description": "Emita uma credencial de dispositivo de curta duração vinculada a um sujeito, para que a sua aplicação web ou móvel possa enviar os eventos desse utilizador diretamente para a Didit sem uma chave de API. A aplicação envia o `monitoring_token` retornado no cabeçalho `X-Monitoring-Token` para a via de dispositivos (`POST /v1/events/` e `POST /v1/events/batch/`), onde o sujeito é sempre substituído por este `vendor_data`, eventos fora de `allowed_event_categories` são rejeitados, cada evento submetido gasta uma utilização e um pedido cujo `Origin` não seja igual a `bind_to_origin` é recusado. Chame-o apenas a partir do seu backend; a emissão cria a credencial e nada mais (nenhum utilizador é criado). A ingestão de eventos tem de estar ativada para a aplicação, caso contrário este endpoint devolve `403` com `code: event_monitoring_disabled` em vez de emitir uma credencial que nunca conseguiria escrever. Uma chave de API com âmbito precisa de `transactions: write`. Consulte [Submissão de eventos pelo SDK](https://docs.didit.me/pt/transaction-monitoring/sdk-event-submission).", "operationId": "create_monitoring_event_sdk_token", "x-didit-sdk": { "resource": "monitoring_events", "method": "create_sdk_token", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "São aceites aliases em camelCase: `vendorData`, `entityType`, `allowedEventCategories`, `ttlSeconds`, `maxUses`, `bindToOrigin`.", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "minLength": 1, "maxLength": 255, "description": "O seu id para o sujeito ao qual pertence cada evento enviado com esta credencial." }, "entity_type": { "type": "string", "maxLength": 32, "default": "individual", "description": "`company` vincula um sujeito do tipo empresa; qualquer outro valor (por predefinição `individual`) vincula um indivíduo." }, "allowed_event_categories": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] }, "description": "Categorias que a credencial pode submeter. Omita ou envie `[]` para permitir todas as categorias." }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 900, "description": "Tempo de vida da credencial em segundos." }, "max_uses": { "type": "integer", "minimum": 1, "nullable": true, "default": 1000, "description": "Número de eventos que a credencial pode submeter (um lote consome uma utilização por evento). Envie `null` para não ter limite durante o período de validade." }, "bind_to_origin": { "type": "string", "maxLength": 255, "nullable": true, "description": "Quando definido, o cabeçalho `Origin` do navegador de cada pedido do dispositivo deve ser exatamente igual a este valor; um pedido sem `Origin` é recusado." } } }, "example": { "vendor_data": "user-42", "allowed_event_categories": [ "auth", "session", "gameplay" ], "ttl_seconds": 900, "max_uses": 1000, "bind_to_origin": "https://app.example.com" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/sdk-token/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"vendor_data\": \"user-42\",\n \"allowed_event_categories\": [\"auth\", \"session\", \"gameplay\"],\n \"ttl_seconds\": 900,\n \"max_uses\": 1000,\n \"bind_to_origin\": \"https://app.example.com\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create_sdk_token(\n vendor_data=\"user-42\",\n allowed_event_categories=[\"auth\", \"session\", \"gameplay\"],\n ttl_seconds=900,\n max_uses=1000,\n bind_to_origin=\"https://app.example.com\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.createSdkToken({\n vendor_data: \"user-42\",\n allowed_event_categories: [\"auth\", \"session\", \"gameplay\"],\n ttl_seconds: 900,\n max_uses: 1000,\n bind_to_origin: \"https://app.example.com\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.CreateSDKToken(ctx, didit.MonitoringEventsCreateSDKTokenParams{\n\tVendorData: \"user-42\",\n\tAllowedEventCategories: didit.Some([]didit.MonitoringEventsCreateSDKTokenParamsAllowedEventCategories{\"auth\", \"session\", \"gameplay\"}),\n\tTTLSeconds: didit.Int(900),\n\tMaxUses: didit.Int(1000),\n\tBindToOrigin: didit.String(\"https://app.example.com\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventsCreateSdkTokenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().createSdkToken(MonitoringEventsCreateSdkTokenParams.builder()\n .vendorData(\"user-42\")\n .allowedEventCategories(List.of(MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"auth\"), MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"session\"), MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"gameplay\")))\n .ttlSeconds(900L)\n .maxUses(1000L)\n .bindToOrigin(\"https://app.example.com\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->createSdkToken([\n 'vendor_data' => 'user-42',\n 'allowed_event_categories' => ['auth', 'session', 'gameplay'],\n 'ttl_seconds' => 900,\n 'max_uses' => 1000,\n 'bind_to_origin' => 'https://app.example.com',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create_sdk_token(\n vendor_data: \"user-42\",\n allowed_event_categories: [\"auth\", \"session\", \"gameplay\"],\n ttl_seconds: 900,\n max_uses: 1000,\n bind_to_origin: \"https://app.example.com\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateSdkTokenAsync(new MonitoringEventsCreateSdkTokenParams\n{\n VendorData = \"user-42\",\n AllowedEventCategories = new MonitoringEventsCreateSdkTokenParamsAllowedEventCategories[] { \"auth\", \"session\", \"gameplay\" },\n TtlSeconds = 900,\n MaxUses = 1000,\n BindToOrigin = \"https://app.example.com\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A credencial foi emitida. Transmita o `monitoring_token` para a aplicação e trate-o como segredo até `expires_at`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "monitoring_token", "expires_at", "allowed_event_categories", "max_uses", "bind_to_origin" ], "properties": { "monitoring_token": { "type": "string", "description": "A credencial do dispositivo (um token de 43 carateres compatível com URL). Envie-a no cabeçalho `X-Monitoring-Token`." }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando a credencial deixa de ser aceite." }, "allowed_event_categories": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] }, "description": "Categorias que a credencial pode submeter; `[]` significa todas as categorias." }, "max_uses": { "type": "integer", "nullable": true, "description": "Orçamento de eventos da credencial; null significa sem limite." }, "bind_to_origin": { "type": "string", "nullable": true, "description": "Origem à qual a credencial está vinculada, ou null." } } }, "example": { "monitoring_token": "q7ZtR2xKp9VbN4mWc8LdH1sYfJ3gT6uEaQ0oPiXzBkC", "expires_at": "2026-10-17T09:30:02.481000Z", "allowed_event_categories": [ "auth", "session", "gameplay" ], "max_uses": 1000, "bind_to_origin": "https://app.example.com" } } } }, "400": { "description": "A validação falhou: `vendor_data` em falta, `ttl_seconds` fora do intervalo de 60 a 86400, `max_uses` inferior a 1 ou uma categoria desconhecida (indexada pela sua posição no array).", "content": { "application/json": { "examples": { "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } }, "ttl_seconds too short": { "value": { "ttl_seconds": [ "Ensure this value is greater than or equal to 60." ] } }, "Unknown category": { "value": { "allowed_event_categories": { "1": [ "\"login\" is not a valid choice." ] } } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Apenas uma chave expirada recebe `401`; uma chave em falta ou inválida recebe `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Um `x-api-key` em falta (uma chave incorreta, revogada ou expirada obtém `401`), uma chave com âmbito restrito sem `transactions: write`, uma chave limitada a alguns fluxos ou a sessões aprovadas (tal chave nunca acede a dados de monitorização de transações), ou um pedido fora da lista de permissões de IP da chave. Também devolvido com `code: event_monitoring_disabled` enquanto a ingestão de eventos estiver desativada para a aplicação; nada é armazenado nesse caso, e a verificação é executada antes da validação do corpo.", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite de pedidos excedido: os pedidos de escrita (`POST`, `PATCH`, `DELETE`) partilham um orçamento de 300 pedidos por minuto por chave de API. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/{event_uuid}/": { "get": { "summary": "Obter evento de monitorização", "description": "Obtenha um evento de monitorização com tudo o que a lista retorna, além do payload, valores personalizados, contexto do dispositivo, proveniência dos campos (`field_sources`), os campos de domínio promovidos, `expires_at`, a execução de cada regra correspondente com as respetivas evidências, o enriquecimento de IP e as etiquetas associadas pelas regras. Enquanto `correlation_pending` for `true`, uma regra assíncrona ainda terá de ser executada; leia o evento novamente alguns minutos mais tarde para obter o `status`, `score` e `rule_runs` finais. As leituras funcionam quer a ingestão de eventos esteja ativada ou não. Uma chave de API com âmbito restrito necessita de `transactions: read`. Consulte [Evidências](https://docs.didit.me/pt/transaction-monitoring/event-rules#evidência) e [Enriquecimento de IP](https://docs.didit.me/pt/transaction-monitoring/ip-enrichment).", "operationId": "get_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "event_uuid", "in": "path", "required": true, "description": "Identificador Didit do evento (`event_uuid` da resposta de criação, de processamento em lote, de listagem ou de cronologia), e não o seu próprio `event_id`.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O evento com as suas provas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventDetail" }, "examples": { "Login from a VPN, in review": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481000Z", "received_at": "2026-10-17T09:15:02.903114Z", "status": "IN_REVIEW", "score": 40, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "risk_relevant", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": true, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold", "vpn_or_proxy_detected": true }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42", "ip_country": "Spain", "ip_country_code": "ES", "ip_city": "Madrid", "asn_number": 64500, "asn_organization": "Example Networks", "is_vpn_or_tor": true, "is_data_center": false } }, "field_sources": { "subject.vendor_data": "customer", "event_category": "customer", "action_type": "customer", "occurred_at": "customer", "received_at": "server", "payload.method": "customer", "session.session_id": "customer", "session.sequence": "customer", "device_context.fingerprint": "customer", "device_context.network_context.ip_address": "customer", "device_context.network_context.ip_country": "server", "device_context.network_context.ip_country_code": "server", "device_context.network_context.ip_city": "server", "device_context.network_context.asn_number": "server", "device_context.network_context.asn_organization": "server", "device_context.network_context.is_vpn_or_tor": "server", "device_context.network_context.is_data_center": "server" }, "session_sequence": 142, "table_id": null, "hand_id": null, "match_id": null, "market_id": null, "side": null, "role": null, "net_result_amount": null, "payment_fingerprint": null, "instrument_reference_hash": null, "withdrawal_address_hash": null, "dispute_id": null, "chargeback_id": null, "changed_field": null, "identity_match_ref": null, "schema_version": 1, "expires_at": "2027-01-15T09:15:02.481000Z", "rules_evaluated_count": 6, "rule_runs": [ { "rule_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "rule_title": "Login from VPN or Tor", "library_key": null, "matched": true, "mode": "ACTIVE", "is_async": false, "severity": "MEDIUM", "score_delta": 40, "action_summary": "score +40; add_tag:VPN_LOGIN", "matched_payload": [ { "field": "event.ip.is_vpn_or_tor", "operator": "eq", "expected_value": true, "current_value": true, "matched": true, "group_index": null, "group_logic": "AND", "field_source": "server" } ], "created_at": "2026-10-17T09:15:02.951207Z" } ], "ip_enrichment": { "ip_country_code": "ES", "ip_city": "Madrid", "asn_number": 64500, "asn_organization": "Example Networks", "is_vpn_or_tor": true, "is_data_center": false, "proxy_type": null, "last_enriched_at": "2026-10-17T09:15:02.910442Z" }, "subject_profile": null, "tags": [ "VPN_LOGIN" ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Apenas uma chave expirada recebe `401`; uma chave em falta ou inválida recebe `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Um `x-api-key` em falta (uma chave incorreta, revogada ou expirada obtém `401`), uma chave com âmbito restrito sem `transactions: read`, uma chave limitada a alguns fluxos ou a sessões aprovadas (tal chave nunca acede a dados de monitorização de transações), ou um pedido fora da lista de permissões de IP da chave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhum evento com este `event_uuid` na aplicação: nunca foi armazenado, foi eliminado ou pertence a outra aplicação. Um segmento de caminho que não seja um UUID não corresponde à rota e também retorna `404`.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No MonitoringEvent matches the given query." } } } } } }, "429": { "description": "Limite de pedidos excedido: os pedidos `GET` partilham um orçamento de 600 pedidos por minuto por chave de API. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/subjects/{vendor_data}/": { "get": { "summary": "Obter linha cronológica de eventos do sujeito", "description": "Listar todos os eventos de monitorização de um sujeito, pelo `occurred_at` mais recente primeiro. Um `vendor_data` só é único dentro de um tipo de entidade, pelo que o mesmo id pode identificar um indivíduo e uma empresa: `entity_type` seleciona que cronologia obtém e tem como predefinição `individual`, pelo que os eventos de uma empresa necessitam de `entity_type=company`. Os filtros de `GET /v3/events/` aplicam-se adicionalmente, e um `vendor_data` sem eventos devolve uma página vazia em vez de `404`. Uma chave de API com âmbito restrito necessita de `transactions: read`. Consulte [Ler eventos](https://docs.didit.me/pt/transaction-monitoring/events#consultar-eventos).", "operationId": "get_monitoring_event_subject_timeline", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve_subject_timeline", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "description": "O seu id para o sujeito (`subject.vendor_data` dos respetivos eventos). Codifique-o no URL; um valor contendo `/` não pode ser endereçado por este endpoint.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "user-42" }, { "name": "entity_type", "in": "query", "required": false, "description": "`company` devolve a empresa com este `vendor_data`; qualquer outro valor, ou nenhum, devolve o indivíduo. `subject_entity_type` é aceite como alias quando `entity_type` está ausente.", "schema": { "type": "string", "enum": [ "individual", "company" ], "default": "individual" }, "example": "individual" }, { "name": "limit", "in": "query", "required": false, "description": "Número máximo de eventos por página. O valor predefinido é 50. Valores acima de 1000000 devolvem `400`; um valor não numérico, zero ou negativo reverte para 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Número de eventos a ignorar. A predefinição é 0. É preferível seguir o URL `next` da resposta.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "event_category", "in": "query", "required": false, "description": "Apenas eventos nestas categorias. Repita o parâmetro para vários valores (`?event_category=payment&event_category=dispute`); é devolvido qualquer evento que corresponda a qualquer um deles.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] } }, "example": [ "payment", "dispute" ] }, { "name": "action_type", "in": "query", "required": false, "description": "Apenas eventos com estes tipos de ação (exatos, sensíveis a maiúsculas e minúsculas). Repita para vários valores.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "deposit_completed", "chargeback_opened" ] }, { "name": "status", "in": "query", "required": false, "description": "Apenas eventos com estes estados. Repita para vários valores.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ] } }, "example": [ "IN_REVIEW", "DECLINED" ] }, { "name": "retention_class", "in": "query", "required": false, "description": "Apenas eventos nestas classes de conservação. Repita para vários valores.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ] } }, "example": [ "risk_relevant" ] }, { "name": "business_vendor_data", "in": "query", "required": false, "description": "Correspondência exata no `business.vendor_data` enviado com o evento.", "schema": { "type": "string" }, "example": "merchant-7" }, { "name": "session_id", "in": "query", "required": false, "description": "Correspondência exata em `session.session_id`.", "schema": { "type": "string" }, "example": "web-session-abc" }, { "name": "device_fingerprint", "in": "query", "required": false, "description": "Correspondência exata em `device_context.fingerprint`.", "schema": { "type": "string" }, "example": "fp-a8c1" }, { "name": "ip_address", "in": "query", "required": false, "description": "Correspondência exata no endereço IP do evento.", "schema": { "type": "string" }, "example": "203.0.113.42" }, { "name": "game_id", "in": "query", "required": false, "description": "Correspondência exata no `game_id` promovido.", "schema": { "type": "string" }, "example": "poker-holdem-01" }, { "name": "round_id", "in": "query", "required": false, "description": "Correspondência exata no `round_id` promovido.", "schema": { "type": "string" }, "example": "round-88231" }, { "name": "affiliate_code", "in": "query", "required": false, "description": "Correspondência exata no `affiliate_code` promovido.", "schema": { "type": "string" }, "example": "aff-summer" }, { "name": "payment_reference_id", "in": "query", "required": false, "description": "Correspondência exata na referência de pagamento (de `transaction_context.payment_reference_id` ou `payload.payment_reference_id`).", "schema": { "type": "string" }, "example": "dep_735" }, { "name": "counterparty_vendor_data", "in": "query", "required": false, "description": "Correspondência exata no `counterparty_vendor_data` promovido.", "schema": { "type": "string" }, "example": "user-77" }, { "name": "matched_only", "in": "query", "required": false, "description": "`true` (também `1` ou `yes`, não sensível a maiúsculas/minúsculas) devolve apenas eventos correspondidos por pelo menos uma regra (`rules_matched_count` superior a 0). Qualquer outro valor é ignorado.", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "occurred_from", "in": "query", "required": false, "description": "Apenas eventos com `occurred_at` neste instante ou após o mesmo (inclusive). Envie um valor ISO 8601: `2026-10-01T00:00:00Z`, um deslocamento explícito com o `+` codificado por percentagem (`2026-10-01T02:00:00%2B02:00`; um `+` não codificado é descodificado como um espaço e o valor deixa de ser analisado), ou apenas uma data (`2026-10-01`), o que significa 00:00:00 UTC desse dia. Um valor sem deslocamento é lido como UTC. Valores em qualquer outro formato não são aceites.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "occurred_to", "in": "query", "required": false, "description": "Apenas eventos com `occurred_at` neste instante ou antes do mesmo (inclusive). Uma data por si só significa o início desse dia, pelo que `occurred_to=2026-10-15` exclui o resto de 15 de outubro; envie `2026-10-15T23:59:59Z` para o incluir. Envie um valor ISO 8601: `2026-10-01T00:00:00Z`, um deslocamento explícito com o `+` codificado por percentagem (`2026-10-01T02:00:00%2B02:00`; um `+` não codificado é descodificado como um espaço e o valor deixa de ser analisado), ou apenas uma data (`2026-10-01`), o que significa 00:00:00 UTC desse dia. Um valor sem deslocamento é lido como UTC. Valores em qualquer outro formato não são aceites.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-17T23:59:59Z" }, { "name": "search", "in": "query", "required": false, "description": "Correspondência de subcadeia sem distinção entre maiúsculas e minúsculas em `event_id`, `action_type`, `subject_vendor_data` ou `counterparty_vendor_data`.", "schema": { "type": "string" }, "example": "chargeback" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/subjects/user-42/?entity_type=individual&limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.monitoring_events.retrieve_subject_timeline(\n \"user-42\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.monitoringEvents.retrieveSubjectTimeline(\"user-42\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.MonitoringEvents.RetrieveSubjectTimelineAutoPaging(ctx, \"user-42\", didit.MonitoringEventsRetrieveSubjectTimelineParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.monitoringEvents().retrieveSubjectTimeline(\"user-42\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieveSubjectTimeline('user-42') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.retrieve_subject_timeline(\"user-42\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.MonitoringEvents.RetrieveSubjectTimelineAsync(\"user-42\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de eventos do titular.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventPage" }, "examples": { "Individual timeline": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "received_at": "2026-10-16T14:02:12.418230Z", "status": "IN_REVIEW", "score": 60, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": null, "device_fingerprint": null, "ip_address": null, "ip_country": null, "amount": "250.000000000000000000", "currency": "EUR", "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": "dep_735", "retention_class": "monetary_or_compliance", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": false }, { "event_uuid": "22222222-3333-4444-5555-666666666666", "event_id": "login-2026-10-15-000912", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-15T08:30:00.120000Z", "received_at": "2026-10-15T08:30:00.734512Z", "status": "ACCEPTED", "score": 0, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "standard", "rules_matched_count": 0, "correlation_pending": false, "is_droppable": true } ] } }, "No events": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` ou `offset` é superior a 1000000. O corpo é um array JSON com uma mensagem. Um `limit` não numérico ou não positivo reverte para o valor padrão de 50 em vez de falhar.", "content": { "application/json": { "examples": { "limit too large": { "summary": "limit superior a 1000000", "value": [ "limit must not exceed 1000000." ] }, "offset too large": { "summary": "offset superior a 1000000", "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "A chave de API com âmbito expirou. Apenas uma chave expirada recebe `401`; uma chave em falta ou inválida recebe `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Um `x-api-key` em falta (uma chave incorreta, revogada ou expirada obtém `401`), uma chave com âmbito restrito sem `transactions: read`, uma chave limitada a alguns fluxos ou a sessões aprovadas (tal chave nunca acede a dados de monitorização de transações), ou um pedido fora da lista de permissões de IP da chave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite de pedidos excedido: os pedidos `GET` partilham um orçamento de 600 pedidos por minuto por chave de API. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/enrichment-metrics/": { "get": { "summary": "Obter métricas de enriquecimento de eventos", "description": "Retorna os contadores de ingestão de eventos e de enriquecimento de IP da sua aplicação para um período, somados em todas as vias (servidor, lote e dispositivo), para que possa acompanhar o volume de eventos e confirmar que o enriquecimento é resolvido uma vez por endereço único em vez de uma vez por evento. O período abrange o dia de hoje mais os `days` dias anteriores, contabilizados por data de calendário UTC. Os três rácios são nulos quando o seu denominador é zero. Uma chave de API com âmbito necessita de `transactions: read`. Consulte [Enriquecimento de IP](https://docs.didit.me/pt/transaction-monitoring/events#enriquecimento-de-ip).", "operationId": "get_monitoring_event_enrichment_metrics", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve_enrichment_metrics", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Duração do período em dias. O padrão é 30; os valores são limitados entre 1 e 365, e valores não inteiros revertem para 30. O valor aplicado é devolvido como `period_days`.", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "example": 30 } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/enrichment-metrics/?days=30' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.retrieve_enrichment_metrics()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.retrieveEnrichmentMetrics();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.RetrieveEnrichmentMetrics(ctx, didit.MonitoringEventsRetrieveEnrichmentMetricsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().retrieveEnrichmentMetrics();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieveEnrichmentMetrics();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.retrieve_enrichment_metrics\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.RetrieveEnrichmentMetricsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Contadores e rácios para o período.", "content": { "application/json": { "schema": { "type": "object", "required": [ "events_ingested", "events_rejected", "enrichment_lookups", "enrichment_cache_hits", "enrichment_provider_calls", "enrichment_skipped_low_value", "unique_ips_seen", "period_days", "cache_hit_rate", "unique_ip_ratio", "provider_calls_per_1k_events" ], "properties": { "events_ingested": { "type": "integer", "description": "Novos eventos armazenados. As repetições idempotentes não são contabilizadas." }, "events_rejected": { "type": "integer", "description": "Itens rejeitados em pedidos em lote (canais de servidor e de dispositivo). Um pedido de evento único rejeitado não é contabilizado." }, "enrichment_lookups": { "type": "integer", "description": "Eventos cujo endereço IP público foi resolvido, a partir da cache ou de raiz." }, "enrichment_cache_hits": { "type": "integer", "description": "Consultas respondidas a partir da cache." }, "enrichment_provider_calls": { "type": "integer", "description": "Consultas que necessitaram de uma nova resolução do endereço." }, "enrichment_skipped_low_value": { "type": "integer", "description": "Eventos de telemetria de baixo valor cujo endereço ainda não era conhecido. Nunca acionam uma nova resolução por si próprios." }, "unique_ips_seen": { "type": "integer", "description": "Endereços que necessitaram de uma nova resolução." }, "period_days": { "type": "integer", "description": "O valor de `days` aplicado após o ajuste de limites." }, "cache_hit_rate": { "type": "number", "nullable": true, "description": "`enrichment_cache_hits / enrichment_lookups`, arredondado a 4 casas decimais. Null quando não existiram pesquisas." }, "unique_ip_ratio": { "type": "number", "nullable": true, "description": "`unique_ips_seen / events_ingested`, arredondado a 4 casas decimais. Nulo quando nenhum evento foi ingerido." }, "provider_calls_per_1k_events": { "type": "number", "nullable": true, "description": "Resoluções recentes por 1000 eventos ingeridos, arredondadas a 2 casas decimais. Null quando não foram ingeridos eventos." } } }, "examples": { "Last 30 days": { "value": { "events_ingested": 128450, "events_rejected": 214, "enrichment_lookups": 41230, "enrichment_cache_hits": 40118, "enrichment_provider_calls": 1112, "enrichment_skipped_low_value": 74320, "unique_ips_seen": 1112, "period_days": 30, "cache_hit_rate": 0.973, "unique_ip_ratio": 0.0087, "provider_calls_per_1k_events": 8.66 } }, "No events yet": { "value": { "events_ingested": 0, "events_rejected": 0, "enrichment_lookups": 0, "enrichment_cache_hits": 0, "enrichment_provider_calls": 0, "enrichment_skipped_low_value": 0, "unique_ips_seen": 0, "period_days": 30, "cache_hit_rate": null, "unique_ip_ratio": null, "provider_calls_per_1k_events": null } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Apenas uma chave expirada recebe `401`; uma chave em falta ou inválida recebe `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Um `x-api-key` em falta (uma chave incorreta, revogada ou expirada obtém `401`), uma chave com âmbito restrito sem `transactions: read`, uma chave limitada a alguns fluxos ou a sessões aprovadas (tal chave nunca acede a dados de monitorização de transações), ou um pedido fora da lista de permissões de IP da chave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite de pedidos excedido: os pedidos `GET` partilham um orçamento de 600 pedidos por minuto por chave de API. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/{event_uuid}/delete/": { "delete": { "summary": "Eliminar evento de monitorização", "description": "Elimina permanentemente um evento de monitorização juntamente com as suas execuções de regras, notas e associações de etiquetas, por exemplo, um evento enviado por engano. Após o `204`, o evento desaparece de todas as leituras (a obtenção devolve `404` e deixa de aparecer na lista ou na linha cronológica do sujeito), a eliminação é irreversível e o seu `event_id` fica livre para ser utilizado num novo evento. Não são afetados: o utilizador ou a empresa a que o evento foi associado, os casos abertos por uma regra, as entradas de lista adicionadas por uma regra e as pontuações e estados já aplicados a outros eventos. Para apagar tudo sobre uma pessoa ou empresa, elimine antes o utilizador ou a empresa, o que também elimina os respetivos eventos. Uma chave de API com âmbito necessita de `transactions: write`.", "operationId": "delete_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "event_uuid", "in": "path", "required": true, "description": "Identificador Didit do evento (`event_uuid` da resposta de criação, de processamento em lote, de listagem ou de cronologia), e não o seu próprio `event_id`.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/events/11111111-2222-3333-4444-555555555555/delete/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.monitoring_events.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.monitoringEvents.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.MonitoringEvents.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.monitoringEvents().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.MonitoringEvents.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "O evento foi eliminado. Sem corpo." }, "401": { "description": "A chave de API com âmbito expirou. Apenas uma chave expirada recebe `401`; uma chave em falta ou inválida recebe `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Um `x-api-key` em falta (uma chave incorreta, revogada ou expirada obtém `401`), uma chave com âmbito restrito sem `transactions: write`, uma chave limitada a alguns fluxos ou a sessões aprovadas (tal chave nunca acede a dados de monitorização de transações), ou um pedido fora da lista de permissões de IP da chave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhum evento com este `event_uuid` na aplicação: nunca foi armazenado, foi eliminado ou pertence a outra aplicação. Um segmento de caminho que não seja um UUID não corresponde à rota e também retorna `404`.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No MonitoringEvent matches the given query." } } } } } }, "429": { "description": "Limite de pedidos excedido: os pedidos de escrita (`POST`, `PATCH`, `DELETE`) partilham um orçamento de 300 pedidos por minuto por chave de API. Aguarde `Retry-After` segundos e, em seguida, tente novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/kyb/parties/{partyUuid}/regenerate/": { "post": { "summary": "Regenerar a sessão de KYC de uma parte do tipo pessoas-chave", "description": "Atribua a uma parte de Pessoas-chave de uma sessão de Verificação de empresas (KYB) uma nova sessão de KYC individual depois de a anterior ter sido eliminada ou ter expirado antes de a pessoa a iniciar, para que a verificação de Pessoas-chave possa ser concluída novamente; não envie corpo no pedido. Funciona quando a sessão de KYC da parte foi eliminada (`kyc_session_deleted: true`) ou expirou antes de a pessoa a iniciar (`Expired`, nunca iniciada). Uma sessão ainda em curso ou que tenha terminado em qualquer outro estado (`Approved`, `Declined`, `In Review`, `Abandoned`, ...) devolve `409`, a menos que tenha sido eliminada. Uma parte que nunca teve uma sessão ou uma parte que seja uma empresa devolve sempre `409`. A Didit cria uma nova sessão de KYC alojada com o fluxo com o qual a parte foi verificada (a sua versão publicada mais recente) ou, quando este já não for conhecido, o fluxo que as suas definições de Pessoas-chave atribuem à função da parte, pelo que a sua ligação dura o tempo de expiração da sessão desse fluxo de KYC; envia a ligação por e-mail para a parte se existir um e-mail registado, limpa `is_skipped` e recalcula a verificação de Pessoas-chave e o estado da sessão da empresa. Em seguida, envia um [webhook](https://docs.didit.me/pt/integration/webhooks) `data.updated` para a sessão da empresa com o acionador `console_key_people_regenerate`; para isentar a parte em alternativa, utilize `PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/`. Uma chave de API com escopo necessita de `decisions: write` e, sem `sessions: write`, recebe `kyc_session_url` como `null`. Sessões eliminadas são elegíveis mesmo que a pessoa já tenha iniciado ou concluído a verificação. Sessões importadas não são elegíveis por expiração; têm de ter sido eliminadas.", "operationId": "post_v3_session_kyb_party_regenerate", "x-didit-sdk": { "resource": "sessions", "method": "regenerate_kyb_party", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão-pai de Verificação de empresas (KYB).", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "partyUuid", "in": "path", "required": true, "description": "UUID da parte de Pessoas-chave (`key_people_checks[].submitted.parties[].uuid` na decisão da sessão de empresa). Tem de pertencer à sessão referenciada por `sessionId`.", "schema": { "type": "string", "format": "uuid", "example": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/33333333-4444-5555-6666-777777777777/kyb/parties/0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41/regenerate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.regenerate_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.regenerateKybParty(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RegenerateKYBParty(ctx, \"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().regenerateKybParty(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->regenerateKybParty('33333333-4444-5555-6666-777777777777', '0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.regenerate_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RegenerateKybPartyAsync(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Nova sessão de KYC criada. Devolve a parte atualizada com a sua nova sessão filha, que expira após o tempo de expiração de sessão do respetivo fluxo de KYC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBKeyPeopleParty" }, "example": { "uuid": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41", "entity_type": "person", "source": "USER", "name": "Jane Smith", "first_name": "Jane", "last_name": "Smith", "company_name": null, "registration_number": null, "email": "user@example.com", "nationality": "GB", "phone_number": null, "date_of_birth": "1980-05-04", "position": "Director", "custom_fields": {}, "is_active": true, "is_skipped": false, "requires_verification": true, "roles": [ { "role": "director", "ownership_percent": null, "voting_percent": null } ], "kyc_session_id": "55555555-6666-7777-8888-999999999999", "kyc_session_status": "Not Started", "kyc_session_url": "https://verify.didit.me/session/abc123def456", "kyc_session_deleted": false, "kyb_sub_session_id": null, "kyb_sub_session_status": null, "kyb_sub_session_url": null, "kyb_sub_session_deleted": false, "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada ou está fora dos limites de uma chave com âmbito restrito; não existe nenhuma parte com este UUID na sua aplicação; ou a parte pertence a outra sessão. Cada caso tem o seu próprio `detail`. A pesquisa da sessão é executada antes da verificação de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo sem uma chave válida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "summary": "Não existe nenhuma sessão com este ID ou foi eliminada", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "A sessão está fora dos limites de fluxo ou dos limites que permitem apenas sessões aprovadas de uma chave com âmbito restrito", "value": { "detail": "Session not found." } }, "Unknown party": { "summary": "Nenhuma parte com este UUID na sua aplicação", "value": { "detail": "No BusinessParty matches the given query." } }, "Party of another session": { "summary": "partyUuid existe, mas pertence a uma sessão diferente", "value": { "detail": "Party does not belong to the given session." } } } } } }, "409": { "description": "A parte não tem nenhuma sessão de KYC elegível para substituir. A menos que seja eliminada, uma sessão ainda em curso ou que tenha terminado com outro estado (`Approved`, `Declined`, `In Review`, `Abandoned`, ...) não pode ser regenerada. Uma parte que nunca tenha tido uma ou uma parte empresarial também devolve `409`. Uma sessão elegível foi eliminada ou expirou antes de a pessoa a iniciar. As sessões eliminadas qualificam-se mesmo que a pessoa já tivesse iniciado ou concluído a verificação. As sessões importadas não se qualificam por expiração; têm de ter sido eliminadas. Ramifique consoante o `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." }, "code": { "type": "string", "enum": [ "kyb_party_kyc_session_not_deleted" ], "description": "Código de erro legível por máquina estável." } } }, "example": { "detail": "This party's KYC session is still live (it has neither been deleted nor expired without starting), so it cannot be regenerated.", "code": "kyb_party_kyc_session_not_deleted" } } } }, "429": { "description": "Limite de pedidos excedido: 300 pedidos de escrita (POST, PATCH, DELETE) por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/{transaction_id}/notes/": { "get": { "summary": "Listar notas de transação", "description": "Listar as notas de uma transação monitorizada, das mais recentes para as mais antigas (`created_at` descendente): notas adicionadas por si através da API, notas e alterações de estado efetuadas pelos revisores na Console, e notas adicionadas automaticamente pela Didit (a ação `add_note` de uma regra, ou um problema ao criar a sessão de verificação de ação do utilizador), que apresentam `actor_name` `Rule Engine`. O campo `metadata` distingue os tipos de notas.\n\nPaginado com `limit` e `offset`. `count` é exato até 100 e limitado a 100 acima disso, pelo que deve seguir `next` até ser `null` em vez de calcular páginas a partir de `count`. Esta é uma leitura sem efeitos secundários.\n\nUma chave de API com âmbito restrito necessita de `transactions: read`; uma chave limitada a alguns fluxos ou a sessões aprovadas não pode chamar este endpoint. Os revisores veem a mesma lista em **Notes** nos [detalhes da transação](https://docs.didit.me/pt/transaction-monitoring/console#detalhe-da-transação).", "operationId": "list_transaction_notes", "x-didit-sdk": { "resource": "transactions.notes", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID da transação Didit: o `uuid` devolvido por `POST /v3/transactions/` e `GET /v3/transactions/`. O seu próprio `txn_id` não é aceite.", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Número de notas por página. O valor predefinido é 50. Um valor que não seja um número inteiro positivo reverte para 50; um valor acima de 1000000 devolve `400`." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Posição de base zero da primeira nota a devolver. Prefira seguir `next`. Um valor que não seja um número inteiro reverte para 0; um valor superior a 1000000 devolve `400`." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.notes.list(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.notes.list(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Notes.ListAutoPaging(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().notes().list(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->notes->list('abcdef12-3456-7890-abcd-ef1234567890') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.notes.list(\"abcdef12-3456-7890-abcd-ef1234567890\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Notes.ListAsync(\"abcdef12-3456-7890-abcd-ef1234567890\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de notas, as mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Número de notas na transação: exato até 100, limitado a 100 acima desse valor. Siga `next` em vez de calcular as páginas a partir deste valor." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionNote" } } } }, "examples": { "API, Console and rule notes": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "note": "Customer confirmed the withdrawal by phone.", "actor_email": null, "actor_name": null, "metadata": { "mentioned_emails": [ "analyst@example.com" ] }, "created_at": "2026-10-16T10:05:12.481203Z" }, { "uuid": "c2222222-3333-4444-8555-666666666666", "note": "Status changed from IN_REVIEW to APPROVED. Reason: Source of funds verified", "actor_email": "reviewer@example.com", "actor_name": "Alex Reviewer", "metadata": { "type": "status_change", "previous_status": "IN_REVIEW", "new_status": "APPROVED", "reason_code": "SOF_VERIFIED", "reason_label": "Source of funds verified" }, "created_at": "2026-10-15T17:22:40.103911Z" }, { "uuid": "c3333333-4444-4555-8666-777777777777", "note": "Large withdrawal to a new wallet: check the source of funds.", "actor_email": null, "actor_name": "Rule Engine", "metadata": { "rule_uuid": "d1111111-2222-4333-8444-555555555555", "source": "rule_action" }, "created_at": "2026-10-15T08:42:12.004518Z" } ] } }, "No notes yet": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` ou `offset` é superior a 1000000. O corpo é um array JSON de mensagens, e não um objeto.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "Limit too large": { "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "A chave de API expirou. Apenas uma chave criada com uma data de validade pode expirar; após essa data, cada pedido com ela responde `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Uma chave em falta recebe a mensagem genérica; uma chave incorreta, revogada ou expirada recebe `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhuma transação com este UUID na aplicação (nunca criada, eliminada ou pertencente a outra aplicação). Um `transaction_id` que não seja um UUID não chega à API: devolve uma página HTML `404` em vez deste corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "Mais de 600 pedidos GET por minuto com esta chave de API. Aguarde o número de segundos indicado em `Retry-After` e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos até que a janela atual de um minuto seja reposta.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos por minuto neste orçamento.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Hora Unix em que a janela é reposta.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Criar nota de transação", "description": "Adicione uma nota em texto simples à cronologia de revisão de uma transação monitorizada, onde os revisores da Console a conseguem ver. Uma nota é contexto, não uma decisão: o `status`, o `score` e os alertas da transação não mudam, nenhum webhook é enviado e nada é faturado. O campo `activities` da transação ganha uma entrada `TRANSACTION_NOTE_ADDED`.\n\nAs notas criadas com uma chave de API não têm autor: `actor_email` e `actor_name` são `null`, por isso inclua o autor no texto se necessitar dele. Todos os endereços em `mentioned_emails` têm de pertencer a um membro da sua organização; caso contrário, todo o pedido falha com `400`; as menções são armazenadas em minúsculas e desduplicadas, e este endpoint não notifica os membros mencionados.\n\nCada chamada cria uma nova nota, pelo que tentar novamente um pedido que excedeu o tempo limite pode adicioná-la duas vezes: liste as notas antes de tentar novamente. Não existe nenhum endpoint da API para editar ou remover uma nota. Uma chave de API com âmbito necessita de `transactions: write`; uma chave limitada a alguns fluxos ou a sessões aprovadas não pode chamar este endpoint.", "operationId": "create_transaction_note", "x-didit-sdk": { "resource": "transactions.notes", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID da transação Didit: o `uuid` devolvido por `POST /v3/transactions/` e `GET /v3/transactions/`. O seu próprio `txn_id` não é aceite.", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "note" ], "properties": { "note": { "type": "string", "minLength": 1, "description": "Nota em texto simples. Os espaços em branco no início e no fim são removidos e uma nota em branco é rejeitada. Sem limite de comprimento." }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "default": [], "description": "E-mails de membros da sua organização a mencionar. Cada um tem de ser um e-mail válido de um membro da organização." } } }, "examples": { "Note with a mention": { "value": { "note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": [ "analyst@example.com" ] } }, "Plain note": { "value": { "note": "Source of funds document requested by email." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"note\": \"Customer confirmed the withdrawal by phone.\", \"mentioned_emails\": [\"analyst@example.com\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.notes.create(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n note=\"Customer confirmed the withdrawal by phone.\",\n mentioned_emails=[\"analyst@example.com\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.notes.create(\"abcdef12-3456-7890-abcd-ef1234567890\", {\n note: \"Customer confirmed the withdrawal by phone.\",\n mentioned_emails: [\"analyst@example.com\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Notes.Create(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesCreateParams{\n\tNote: \"Customer confirmed the withdrawal by phone.\",\n\tMentionedEmails: didit.Some([]string{\"analyst@example.com\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionsNotesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().notes().create(\"abcdef12-3456-7890-abcd-ef1234567890\", TransactionsNotesCreateParams.builder()\n .note(\"Customer confirmed the withdrawal by phone.\")\n .mentionedEmails(List.of(\"analyst@example.com\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->notes->create('abcdef12-3456-7890-abcd-ef1234567890', [\n 'note' => 'Customer confirmed the withdrawal by phone.',\n 'mentioned_emails' => ['analyst@example.com'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.notes.create(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n note: \"Customer confirmed the withdrawal by phone.\",\n mentioned_emails: [\"analyst@example.com\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Notes.CreateAsync(\"abcdef12-3456-7890-abcd-ef1234567890\", new TransactionsNotesCreateParams\n{\n Note = \"Customer confirmed the withdrawal by phone.\",\n MentionedEmails = new string[] { \"analyst@example.com\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A nota foi criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionNote" }, "examples": { "Created": { "value": { "uuid": "c1111111-2222-4333-8444-555555555555", "note": "Customer confirmed the withdrawal by phone.", "actor_email": null, "actor_name": null, "metadata": { "mentioned_emails": [ "analyst@example.com" ] }, "created_at": "2026-10-16T10:05:12.481203Z" } } } } } }, "400": { "description": "O corpo é inválido: `note` em falta, nulo ou em branco, um endereço inválido em `mentioned_emails` (erros indexados pela posição na lista) ou um endereço mencionado que não é membro da sua organização. Nada é criado.", "content": { "application/json": { "schema": { "type": "object", "description": "Erros de campos indexados pelo nome do campo.", "additionalProperties": {} }, "examples": { "Missing note": { "value": { "note": [ "This field is required." ] } }, "Blank note": { "value": { "note": [ "This field may not be blank." ] } }, "Invalid email": { "value": { "mentioned_emails": { "0": [ "Enter a valid email address." ] } } }, "Not an organization member": { "value": { "mentioned_emails": [ "Mentioned users must belong to this organization and have access to this application." ] } } } } } }, "401": { "description": "A chave de API expirou. Apenas uma chave criada com uma data de validade pode expirar; após essa data, cada pedido com ela responde `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Uma chave em falta recebe a mensagem genérica; uma chave incorreta, revogada ou expirada recebe `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions write": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhuma transação com este UUID na aplicação (nunca criada, eliminada ou pertencente a outra aplicação). Um `transaction_id` que não seja um UUID não chega à API: devolve uma página HTML `404` em vez deste corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "Mais de 300 pedidos de escrita por minuto com esta chave de API. Aguarde o número de segundos indicado em `Retry-After` e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos até que a janela atual de um minuto seja reposta.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos por minuto neste orçamento.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Hora Unix em que a janela é reposta.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/{transaction_id}/related/": { "get": { "summary": "Listar transações relacionadas", "description": "Liste as outras transações na sua aplicação que envolvam as mesmas pessoas ou empresas que esta. Uma transação está relacionada quando qualquer uma das suas partes, em qualquer função, tem os mesmos `vendor_data` que uma das partes desta transação. A própria transação nunca é devolvida e as partes sem `vendor_data` são ignoradas: quando nenhuma das partes desta transação os tem, o resultado é sempre vazio.\n\nOs resultados utilizam o formato resumido de `GET /v3/transactions/`, os mais recentes primeiro (`txn_date`, depois `created_at`). Paginado com `limit` e `offset`; `count` é exato até 100 e limitado a 100 acima disso, pelo que deve seguir `next` até ser `null`.\n\nUma chave de API com âmbito necessita de `transactions: read`; uma chave limitada a alguns fluxos ou a sessões aprovadas não pode chamar este endpoint. Envie os mesmos `vendor_data` para a mesma pessoa ou empresa em cada [transação](https://docs.didit.me/pt/transaction-monitoring/transactions#sujeito-e-contraparte) para tornar esta lista completa.", "operationId": "list_related_transactions", "x-didit-sdk": { "resource": "transactions", "method": "list_related", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID da transação Didit: o `uuid` devolvido por `POST /v3/transactions/` e `GET /v3/transactions/`. O seu próprio `txn_id` não é aceite.", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Número de transações por página. O valor predefinido é 50. Um valor que não seja um número inteiro positivo reverte para 50; um valor acima de 1000000 devolve `400`." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Posição de base zero da primeira transação a devolver. Prefira seguir `next`. Um valor que não seja um número inteiro reverte para 0; um valor superior a 1000000 devolve `400`." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/related/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.list_related(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.listRelated(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.ListRelatedAutoPaging(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsListRelatedParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().listRelated(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->listRelated('abcdef12-3456-7890-abcd-ef1234567890') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.list_related(\"abcdef12-3456-7890-abcd-ef1234567890\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.ListRelatedAsync(\"abcdef12-3456-7890-abcd-ef1234567890\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de transações relacionadas, as mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Número de transações relacionadas: exato até 100, limitado a 100 acima desse valor. Siga `next` em vez de calcular as páginas a partir deste valor." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL absoluto da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionSummary" } } } }, "examples": { "One related transaction": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "abcdef99-3456-4890-abcd-ef1234567890", "transaction_number": 4087, "txn_id": "your-txn-2026-10-02-017", "transaction_type": "finance", "action_type": "deposit", "status": "APPROVED", "source": "LIVE", "direction": "INBOUND", "amount": "250", "currency": "EUR", "currency_type": "fiat", "preferred_currency_amount": "270.08", "preferred_currency_code": "USD", "payment_details": "Card top-up", "txn_date": "2026-10-02T14:10:00Z", "created_at": "2026-10-02T14:10:03.512244Z", "score": 12, "severity": "LOW", "decision_reason_code": null, "decision_reason_label": null, "tags": [], "subject_name": "Maria Garcia", "subject_vendor_data": "user-12345", "subject_type": "user", "subject_uuid": "e1111111-2222-4333-8444-555555555555", "counterparty_name": null, "counterparty_vendor_data": null, "counterparty_country": null, "subject_country": "ESP", "assigned_to_name": null, "travel_rule_status": null, "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "application_name": "Production app", "organization_id": "11111111-2222-3333-4444-555555555555", "organization_name": "Example Org" } ] } }, "No party has vendor_data": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` ou `offset` é superior a 1000000. O corpo é um array JSON de mensagens, e não um objeto.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "Limit too large": { "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "A chave de API expirou. Apenas uma chave criada com uma data de validade pode expirar; após essa data, cada pedido com ela responde `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Uma chave em falta recebe a mensagem genérica; uma chave incorreta, revogada ou expirada recebe `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhuma transação com este UUID na aplicação (nunca criada, eliminada ou pertencente a outra aplicação). Um `transaction_id` que não seja um UUID não chega à API: devolve uma página HTML `404` em vez deste corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "Mais de 600 pedidos GET por minuto com esta chave de API. Aguarde o número de segundos indicado em `Retry-After` e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos até que a janela atual de um minuto seja reposta.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos por minuto neste orçamento.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Hora Unix em que a janela é reposta.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/{business_session_id}/pdf/": { "get": { "summary": "Descarregar um relatório PDF de uma sessão empresarial", "description": "Gere o relatório em PDF de uma sessão de Verificação de empresas (KYB): dados do registo de empresas, pessoas-chave e beneficiários efetivos, documentos, resultados de AML e as restantes funcionalidades do fluxo, além das etiquetas e da atividade de revisão da sessão. Com a personalização de marca branca ativada, o relatório inclui o seu logótipo e o URL da política de privacidade. O corpo da resposta é o próprio PDF (`application/pdf`), não JSON.\n\nA sessão tem de estar em `Approved`, `Declined` ou `In Review`; qualquer outro estado devolve `403`, pelo que deve aguardar primeiro pelo [webhook](https://docs.didit.me/pt/integration/webhooks) `status.updated`. O relatório é gerado em cada chamada e nada é faturado, pelo que deve guardar o ficheiro em vez de o obter repetidamente. `GET /v3/session/{sessionId}/generate-pdf/` gera o mesmo tipo de relatório apenas através do ID da sessão.\n\nUm relatório em PDF conta como media: uma chave de API com âmbito restrito necessita de `businesses: read` e `media: read`, e uma chave limitada a alguns fluxos ou a sessões aprovadas não o pode chamar.", "operationId": "get_business_session_pdf", "x-didit-sdk": { "resource": "businesses", "method": "generate_session_pdf", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização.", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação. Deve ser a aplicação à qual a chave de API pertence: uma chave usada em qualquer outra aplicação recebe `403`.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "business_session_id", "in": "path", "required": true, "description": "`session_id` da sessão de Verificação de empresas (KYB), conforme devolvido aquando da criação da sessão. Uma sessão de outra aplicação devolve `404`.", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl --fail -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/businesses/22222222-3333-4444-5555-666666666666/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output business_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.businesses.generate_session_pdf(\n \"22222222-3333-4444-5555-666666666666\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.businesses.generateSessionPdf(\"22222222-3333-4444-5555-666666666666\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Businesses.GenerateSessionPDF(ctx, \"22222222-3333-4444-5555-666666666666\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.businesses().generateSessionPdf(\"22222222-3333-4444-5555-666666666666\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "businesses->generateSessionPdf('22222222-3333-4444-5555-666666666666');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.businesses.generate_session_pdf(\"22222222-3333-4444-5555-666666666666\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Businesses.GenerateSessionPdfAsync(\"22222222-3333-4444-5555-666666666666\");\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "O PDF renderizado, devolvido diretamente como binário `application/pdf`.", "headers": { "Content-Disposition": { "description": "Sempre `attachment; filename=business_{business_session_id}.pdf`.", "schema": { "type": "string", "example": "attachment; filename=business_22222222-3333-4444-5555-666666666666.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "A chave de API expirou. Apenas uma chave criada com uma data de validade pode expirar; após essa data, cada pedido com ela responde `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido ou a sessão não está concluída. Consulte `detail`: uma sessão que não está como `Approved`, `Declined` ou `In Review`, uma chave de API em falta (uma chave incorreta, revogada ou expirada recebe `401`), um `application_id` que não pertence à aplicação da chave, uma chave com âmbito restrito sem `media: read` ou `businesses: read`, uma chave limitada a fluxos ou a sessões aprovadas, ou um pedido efetuado fora da lista de IP da chave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Session not finished": { "value": { "detail": "You can only generate a PDF for sessions in review, declined or approved." } }, "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without media read": { "value": { "detail": "This API key has no read access to media." } }, "Scoped key without businesses read": { "value": { "detail": "This API key has no read access to companies." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhuma sessão empresarial com este ID na aplicação (nunca criada, eliminada ou pertencente a outra aplicação). Um valor que não seja um UUID retorna uma página HTML `404` em vez deste corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "Business session not found." } } } } } }, "429": { "description": "Mais de 600 pedidos GET por minuto com esta chave de API. Aguarde o número de segundos indicado em `Retry-After` e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos até que a janela atual de um minuto seja reposta.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos por minuto neste orçamento.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Hora Unix em que a janela é reposta.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/pdf/": { "get": { "summary": "Descarregar um relatório PDF de transação", "description": "Renderize uma transação monitorizada como um relatório em PDF: visão geral e veredito, partes e métodos de pagamento, propriedades personalizadas, alertas e execuções de regras, resultados de triagem e da Travel Rule, o resumo da rede, a discriminação de custos, até 50 transações relacionadas e as 20 entradas de atividade mais recentes. O corpo é o próprio PDF (`application/pdf`), e não JSON.\n\nO relatório é renderizado a partir dos dados atuais da transação em cada chamada, pelo que deve solicitá-lo novamente após uma alteração de estado. Nada é armazenado e nada é faturado. A renderização pode demorar alguns segundos, por isso utilize um tempo limite generoso no cliente.\n\nEste endpoint reside num caminho com âmbito de aplicação: coloque o ID da sua organização e o ID da aplicação à qual a sua chave de API pertence no URL ([encontre o ID da sua organização](https://docs.didit.me/pt/getting-started/api-authentication#encontrar-o-seu-id-da-organização)). Um relatório em PDF conta como ficheiro multimédia: uma chave de API com âmbito restrito precisa de `media: read` e `transactions: read`, e uma chave limitada a certos fluxos ou a sessões aprovadas não pode chamá-lo.", "operationId": "get_transaction_pdf", "x-didit-sdk": { "resource": "transactions", "method": "generate_pdf", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Transactions" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização.", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação. Deve ser a aplicação à qual a chave de API pertence: uma chave usada em qualquer outra aplicação recebe `403`.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "transaction_uuid", "in": "path", "required": true, "description": "UUID da transação Didit: o `uuid` devolvido por `POST /v3/transactions/` e `GET /v3/transactions/`. O seu próprio `txn_id` não é aceite.", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl --fail -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/abcdef12-3456-7890-abcd-ef1234567890/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output transaction_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.transactions.generate_pdf(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.transactions.generatePdf(\"abcdef12-3456-7890-abcd-ef1234567890\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Transactions.GeneratePDF(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.transactions().generatePdf(\"abcdef12-3456-7890-abcd-ef1234567890\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "transactions->generatePdf('abcdef12-3456-7890-abcd-ef1234567890');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.transactions.generate_pdf(\"abcdef12-3456-7890-abcd-ef1234567890\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Transactions.GeneratePdfAsync(\"abcdef12-3456-7890-abcd-ef1234567890\");\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "O PDF renderizado, devolvido diretamente como binário `application/pdf`.", "headers": { "Content-Disposition": { "description": "Sempre `attachment; filename=transaction_{transaction_uuid}.pdf`.", "schema": { "type": "string", "example": "attachment; filename=transaction_abcdef12-3456-7890-abcd-ef1234567890.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "A chave de API expirou. Apenas uma chave criada com uma data de validade pode expirar; após essa data, cada pedido com ela responde `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Consulte `detail`: uma chave de API em falta (uma chave incorreta, revogada ou expirada recebe `401`), um `application_id` que não corresponde à aplicação da chave, uma chave com âmbito sem `media: read` ou `transactions: read`, uma chave limitada a fluxos ou a sessões aprovadas, ou um pedido efetuado fora da lista de IPs da chave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without media read": { "value": { "detail": "This API key has no read access to media." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Não existe nenhuma transação com este UUID na aplicação (nunca criada, eliminada ou pertencente a outra aplicação). Um `transaction_uuid` que não seja um UUID não chega à API: devolve uma página HTML `404` em vez deste corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "Mais de 600 pedidos GET por minuto com esta chave de API. Aguarde o número de segundos indicado em `Retry-After` e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos até que a janela atual de um minuto seja reposta.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos por minuto neste orçamento.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Hora Unix em que a janela é reposta.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/analytics/": { "get": { "summary": "Obter métricas da aplicação", "description": "Consulte os números por detrás do [painel analítico](https://docs.didit.me/pt/console/analytics) da Business Console para um intervalo de datas. Sem `scope` e `widget_keys`, a resposta é o resumo da verificação de utilizadores (KYC) (`ApplicationAnalyticsSummary`): contagens diárias de sessões, totais de estados, taxa de conversão, os mesmos valores para o período anterior de igual duração, localizações, dados demográficos, dispositivos, funis de fluxos, tempo de verificação ativo, reenvios, avisos e séries temporais. Com `scope` ou `widget_keys`, corresponde aos widgets de um separador do painel (`ApplicationAnalyticsWidgetResponse`): `kyc`, `kyb`, `transactions` ou `home`.\n\nAs contagens de sessões são feitas pela data de criação da sessão (UTC) e refletem o estado atual de cada sessão. Têm origem em consolidações diárias atualizadas em segundo plano, pelo que a atividade mais recente pode demorar alguns instantes a surgir. Os IDs e versões de fluxos inválidos são ignorados em vez de serem rejeitados. Nada é faturado.\n\nApenas uma chave de API de acesso total pode chamar este endpoint: qualquer chave com âmbito obtém `403`, independentemente do acesso que possua, assim como a chave de outra aplicação. Consulte [Chaves de API](https://docs.didit.me/pt/console/api-keys).", "operationId": "get_application_analytics", "x-didit-sdk": { "resource": "analytics", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Analytics" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização.", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação. Deve ser a aplicação à qual a chave de API pertence: uma chave usada em qualquer outra aplicação recebe `403`.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-10-01" }, "description": "Primeiro dia do intervalo, `YYYY-MM-DD`, inclusive (UTC). Envie-o juntamente com `end_date`: quando algum estiver em falta, ambos são ignorados e o intervalo abrange desde 30 dias antes de hoje até hoje." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-10-15" }, "description": "Último dia do intervalo, `YYYY-MM-DD`, inclusive (UTC). Uma data futura conta como hoje. O intervalo não pode exceder 730 dias." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "home", "kyc", "kyb", "transactions" ] }, "description": "Separador do painel para o qual devolver widgets (insensível a maiúsculas e minúsculas). Omita-o, juntamente com `widget_keys`, para o resumo de KYC. Enviar apenas `widget_keys` pressupõe `kyc`. `home` aceita qualquer widget de KYC, KYB ou transação e usa por predefinição o esquema inicial guardado da aplicação." }, { "name": "widget_keys", "in": "query", "required": false, "schema": { "type": "string", "example": "tx_count_total,tx_count_daily" }, "description": "Chaves de widgets separadas por vírgulas, respondidas por esta ordem. As chaves não aceites pelo âmbito são ignoradas; se nenhuma restar, obtém as predefinições do âmbito. KYC: `kyc_sessions_volume`, `kyc_warning_insights`, `kyc_id_locations`, `kyc_ip_locations`, `kyc_workflow_funnel`, `kyc_average_verification_time`, `kyc_conversion_rate`, `kyc_conversion_by_country`, `kyc_resubmission_insights`, `kyc_original_status_distribution`, `kyc_database_validation_coverage`, `kyc_database_validation_latency`, `kyc_demographics`, `kyc_device_details`. KYB: `kyb_sessions_volume`, `kyb_workflow_funnel`, `kyb_average_verification_time`, `kyb_ip_locations`, `kyb_business_country_distribution`, `kyb_warning_insights`, `kyb_conversion_rate`, `kyb_conversion_by_country`, `kyb_industry_breakdown`, `kyb_resubmission_insights`, `kyb_original_status_distribution`, `kyb_registry_coverage`, `kyb_registry_data_completeness`, `kyb_device_details`. Transações: `tx_count_total`, `tx_count_daily`, `tx_volume_total_preferred_currency`, `tx_volume_daily_preferred_currency`, `tx_average_amount`, `tx_average_amount_daily`, `tx_transaction_category_breakdown`, `tx_action_type_breakdown`, `tx_status_volume_trend`, `tx_user_ip_or_country_distribution`, `tx_tag_breakdown`, `tx_top_rules_triggered`, `tx_team_member_performance`, `tx_score_histogram`." }, { "name": "workflow_ids", "in": "query", "required": false, "schema": { "type": "string", "example": "33333333-4444-5555-6666-777777777777" }, "description": "IDs de fluxos separados por vírgulas. Limita o resumo de KYC e os widgets de KYC e KYB a esses fluxos. Os valores que não sejam UUIDs são ignorados; quando nenhum for válido, o filtro é descartado. O resumo também aceita `workflow_id`." }, { "name": "versions", "in": "query", "required": false, "schema": { "type": "string", "example": "3,4" }, "description": "Números de versão do fluxo separados por vírgulas. Aplica-se apenas em conjunto com `workflow_ids`; os valores que não sejam números inteiros são ignorados. `version` é aceite como alias." }, { "name": "branch_path_ids", "in": "query", "required": false, "schema": { "type": "string", "example": "default" }, "description": "IDs de caminhos de ramificação separados por vírgulas. Aplica-se apenas em conjunto com `workflow_ids` e apenas a números de KYC. Os números são registados atualmente apenas para `default` (todos os caminhos combinados), pelo que qualquer outro valor devolve valores vazios. `branch_path_id` é aceite como alias." }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Apenas widgets de transações: UUIDs de etiquetas ou nomes de etiquetas separados por vírgulas." }, { "name": "transaction_type", "in": "query", "required": false, "schema": { "type": "string", "example": "finance" }, "description": "Apenas widgets de transações: categorias de transação separadas por vírgulas." }, { "name": "action_type", "in": "query", "required": false, "schema": { "type": "string", "example": "withdrawal" }, "description": "Apenas widgets de transações: tipos de ação separados por vírgulas (insensível a maiúsculas/minúsculas)." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/analytics/?start_date=2026-10-01&end_date=2026-10-15' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.analytics.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.analytics.retrieve();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Analytics.Retrieve(ctx, didit.AnalyticsRetrieveParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.analytics().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "analytics->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.analytics.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Analytics.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O resumo de KYC, ou os widgets solicitados quando `scope` ou `widget_keys` é enviado.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApplicationAnalyticsSummary" }, { "$ref": "#/components/schemas/ApplicationAnalyticsWidgetResponse" } ] }, "examples": { "KYC summary": { "value": { "grouping_mode": "day", "data_points": [ { "rounded_date": "2026-10-14", "total": 12, "approved": 8, "declined": 1, "canceled": 1, "pending": 2, "in_review": 1, "expired": 1, "abandoned": 0, "in_progress": 1, "not_started": 0, "manually_approved": 1, "manually_declined": 0 }, { "rounded_date": "2026-10-15", "total": 10, "approved": 6, "declined": 2, "canceled": 0, "pending": 2, "in_review": 2, "expired": 0, "abandoned": 0, "in_progress": 0, "not_started": 0, "manually_approved": 0, "manually_declined": 1 } ], "request_breakdown": { "total_approved": 14, "total_in_review": 3, "total_declined": 3, "total_canceled": 1, "total_pending": 4, "total_expired": 1, "total_abandoned": 0, "total_in_progress": 1, "total_not_started": 0, "total_manually_approved": 1, "total_manually_declined": 1 }, "conversion_rate": 70.0, "location_stats": { "countries": [ { "session_count": 15, "country": "Spain", "country_code": "ES" }, { "session_count": 7, "country": "Portugal", "country_code": "PT" } ], "ip_countries": [ { "session_count": 15, "country": "Spain", "country_code": "ES" }, { "session_count": 7, "country": "Portugal", "country_code": "PT" } ], "id_countries": [ { "country": "Spain", "country_code": "ES", "session_count": 14 }, { "country": "Portugal", "country_code": "PT", "session_count": 6 } ], "conversion_by_country": [ { "country": "Spain", "country_code": "ES", "finished": 13, "approved": 10 }, { "country": "Portugal", "country_code": "PT", "finished": 6, "approved": 4 } ], "cities": [ { "session_count": 9, "location": "Madrid, Spain", "latitude": 40.4168, "longitude": -3.7038 } ] }, "demographic_stats": { "age_distribution": { "under_18": 0, "18_24": 5, "25_34": 8, "35_44": 4, "45_64": 2, "65_plus": 1 }, "gender_distribution": { "M": 11, "F": 9 } }, "device_details": { "device_models": [ { "device": "Apple", "count": 12 }, { "device": "Android", "count": 10 } ], "browsers": [ { "browser": "Safari", "count": 12 }, { "browser": "Chrome", "count": 10 } ], "operating_systems": [ { "os": "iOS", "count": 12 }, { "os": "Android", "count": 10 } ] }, "workflow_funnel_stats": { "33333333-4444-5555-6666-777777777777": { "total": 22, "steps": { "OCR": { "reached": 21 }, "LIVENESS": { "reached": 19 }, "FACE_MATCH": { "reached": 19 }, "AML": { "reached": 18 } } } }, "verification_time_stats": { "overall_avg_seconds": 64.0, "overall_count": 18, "per_feature": { "OCR": { "avg_seconds": 41.2, "total_seconds": 741.6, "count": 18 }, "LIVENESS": { "avg_seconds": 22.8, "total_seconds": 410.4, "count": 18 } }, "per_sub_step": { "OCR": { "front_id_photo": { "avg_seconds": 18.3, "total_seconds": 329.4, "count": 18 } } } }, "resubmission_stats": { "first_pass": 17, "second": 2, "third_plus": 1, "abandoned": 0 }, "warning_stats": { "ID_VERIFICATION": { "total": 21, "risks": { "DOCUMENT_EXPIRED": { "error": 1, "warning": 0, "information": 0 } } }, "LIVENESS": { "total": 19, "risks": { "LOW_LIVENESS_SCORE": { "error": 0, "warning": 2, "information": 0 } } } }, "original_status_stats": { "approved": 13, "in_review": 5, "declined": 2 }, "demographic_time_series": [ { "date": "2026-10-14", "age_distribution": { "under_18": 0, "18_24": 3, "25_34": 4, "35_44": 2, "45_64": 1, "65_plus": 0 }, "gender_distribution": { "M": 6, "F": 4 } }, { "date": "2026-10-15", "age_distribution": { "under_18": 0, "18_24": 2, "25_34": 4, "35_44": 2, "45_64": 1, "65_plus": 1 }, "gender_distribution": { "M": 5, "F": 5 } } ], "device_time_series": [ { "date": "2026-10-14", "devices": { "Apple": 7, "Android": 5 }, "browsers": { "Safari": 7, "Chrome": 5 }, "operating_systems": { "iOS": 7, "Android": 5 } }, { "date": "2026-10-15", "devices": { "Apple": 5, "Android": 5 }, "browsers": { "Safari": 5, "Chrome": 5 }, "operating_systems": { "iOS": 5, "Android": 5 } } ], "verification_time_time_series": [ { "date": "2026-10-14", "overall_avg": 66.1, "per_feature": { "OCR": 42.0, "LIVENESS": 24.1 } }, { "date": "2026-10-15", "overall_avg": 61.5, "per_feature": { "OCR": 40.2, "LIVENESS": 21.3 } } ], "resubmission_time_series": [ { "date": "2026-10-14", "first_pass": 9, "second": 1, "third_plus": 0, "abandoned": 0 }, { "date": "2026-10-15", "first_pass": 8, "second": 1, "third_plus": 1, "abandoned": 0 } ], "original_status_time_series": [ { "date": "2026-10-14", "approved": 7, "in_review": 3, "declined": 1 }, { "date": "2026-10-15", "approved": 6, "in_review": 2, "declined": 1 } ], "previous_data_points": [ { "rounded_date": "2026-10-12", "total": 9, "approved": 6, "declined": 1, "canceled": 1, "pending": 1 }, { "rounded_date": "2026-10-13", "total": 11, "approved": 7, "declined": 2, "canceled": 0, "pending": 2 } ], "previous_request_breakdown": { "total_approved": 13, "total_in_review": 2, "total_declined": 3, "total_canceled": 1, "total_pending": 3 } } }, "Transaction widgets": { "value": { "scope": "transactions", "available_widget_keys": [ "tx_count_total", "tx_count_daily", "tx_volume_total_preferred_currency", "tx_volume_daily_preferred_currency", "tx_average_amount", "tx_average_amount_daily", "tx_transaction_category_breakdown", "tx_action_type_breakdown", "tx_status_volume_trend", "tx_user_ip_or_country_distribution", "tx_tag_breakdown", "tx_top_rules_triggered", "tx_team_member_performance", "tx_score_histogram" ], "requested_widget_keys": [ "tx_count_total", "tx_count_daily" ], "widgets": { "tx_count_total": { "kind": "metric", "title": "Transaction count", "value": 42 }, "tx_count_daily": { "kind": "time_series", "title": "Transaction count", "items": [ { "date": "2026-10-14", "value": 20 }, { "date": "2026-10-15", "value": 22 } ], "previous_items": [ { "date": "2026-10-12", "value": 18 }, { "date": "2026-10-13", "value": 15 } ] } } } } } } } }, "400": { "description": "Intervalo de datas ou âmbito inválido. O corpo é um objeto com uma chave correspondente ao parâmetro problemático, com uma mensagem de texto.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "examples": { "Bad date format": { "value": { "start_date": "Invalid date format. Use YYYY-MM-DD (e.g., 2024-01-15)." } }, "Start after end": { "value": { "start_date": "Start date must be before or equal to end date." } }, "Range too long": { "value": { "date_range": "Date range cannot exceed 730 days (2 years)." } }, "Unknown scope": { "value": { "scope": "Unsupported analytics scope." } } } } } }, "401": { "description": "A chave de API expirou. Apenas uma chave criada com uma data de validade pode expirar; após essa data, cada pedido com ela responde `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Consulte `detail`: uma chave de API em falta (uma chave incorreta, revogada ou expirada recebe `401`), uma chave de outra aplicação, qualquer chave com âmbito ou um pedido efetuado fora da lista de IPs da chave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key": { "value": { "detail": "This API key has no access to this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Mais de 600 pedidos GET por minuto com esta chave de API. Aguarde o número de segundos indicado em `Retry-After` e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos até que a janela atual de um minuto seja reposta.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos por minuto neste orçamento.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Hora Unix em que a janela é reposta.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/analytics/today/": { "get": { "summary": "Obter as verificações de hoje por hora", "operationId": "get_application_analytics_today", "x-didit-sdk": { "resource": "analytics", "method": "retrieve_today", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Analytics" ], "description": "Sessões de verificação de utilizadores (KYC) de hoje, a partir da meia-noite local em `tz`, contabilizadas por hora local em que foram criadas, ao lado das mesmas horas do mesmo dia da semana uma semana antes, e divididas pelo resultado que cada uma tem agora: aprovada, em análise ou recusada. Este é o cartão de volume da Página Inicial da Business Console.\n\n`total` é o total de hoje até ao momento. `previous_total_so_far` contabiliza o dia de comparação apenas até à mesma hora local, pelo que uma alteração entre eles compara o mesmo período de ambos os dias. As horas que ainda faltam hoje têm o valor `0`. Um dia em que os relógios mudam de hora tem 23 ou 25 horas: a hora em falta permanece a `0` e a hora repetida inclui ambas.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização.", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação. Deve ser a aplicação à qual a chave de API pertence: uma chave usada em qualquer outra aplicação recebe `403`.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "string", "default": "UTC", "example": "Europe/Madrid" }, "description": "Fuso horário IANA cuja meia-noite inicia o dia de hoje, por exemplo `Europe/Madrid` ou `America/Mexico_City`. Omita para UTC." } ], "responses": { "200": { "description": "Verificações de hoje por hora local, as do dia de comparação e os resultados de hoje.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationAnalyticsToday" }, "examples": { "Madrid, 14:00": { "value": { "time_zone": "Europe/Madrid", "date": "2026-10-30", "current_hour": 14, "previous_date": "2026-10-23", "hours": [ 3, 1, 0, 0, 1, 2, 4, 9, 14, 18, 21, 19, 22, 24, 27, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "previous_hours": [ 2, 1, 1, 0, 1, 3, 5, 8, 12, 16, 19, 18, 20, 22, 24, 26, 23, 19, 15, 12, 9, 7, 5, 3 ], "total": 165, "previous_total_so_far": 151, "outcomes": { "approved": 139, "in_review": 6, "declined": 18 } } } } } } }, "400": { "description": "Fuso horário desconhecido. O corpo é indexado pelo parâmetro, com uma lista de mensagens.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Unknown time zone": { "value": { "tz": [ "Unknown time zone: Europe/Atlantis." ] } } } } } }, "401": { "description": "A chave de API expirou. Apenas uma chave criada com uma data de validade pode expirar; após essa data, cada pedido com ela responde `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. Consulte `detail`: uma chave de API em falta ou inválida (nunca `401`), uma chave de outra aplicação, qualquer chave com âmbito ou um pedido efetuado fora da lista de IPs da chave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key": { "value": { "detail": "This API key has no access to this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Mais de 600 pedidos GET por minuto com esta chave de API. Aguarde o número de segundos indicado em `Retry-After` e tente novamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos até que a janela atual de um minuto seja reposta.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos por minuto neste orçamento.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Hora Unix em que a janela é reposta.", "schema": { "type": "integer" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/analytics/today/?tz=Europe%2FMadrid' \\\n -H 'x-api-key: YOUR_API_KEY'" } ], "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhooks/": { "get": { "summary": "Listar entregas de webhooks da sessão", "description": "Listar todos os registos de entrega de webhook registados pela Didit para uma sessão de verificação, utilizador (KYC) ou empresa (KYB), dos mais recentes para os mais antigos, como um array JSON simples (não paginado). Cada entrada corresponde a uma tentativa para um destino: o primeiro envio, cada [nova tentativa](https://docs.didit.me/pt/integration/webhooks#política-de-novas-tentativas) automática e cada reenvio são entradas separadas com o seu próprio `uuid`, sendo que as novas tentativas e os reenvios mantêm o `event_id` do payload. O `request_header` e o `request_body` são texto em JSON; faça o parsing para consultar as assinaturas e o payload. Os registos de entrega ficam disponíveis durante cerca de 30 dias, pelo que um array vazio significa que ainda não foi enviado nenhum webhook para a sessão ou que todas as entregas são anteriores a esse período. Uma chave de API com âmbito restrito necessita de `sessions: read` e `decisions: read`.", "operationId": "get_v3_session_webhooks", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação, utilizador (KYC) ou empresa (KYB): o `session_id` retornado por `POST /v3/session/`. O servidor resolve-o em ambos os tipos de sessão.\n\n**Deve ser um UUID válido.** A rota apenas faz correspondência com UUIDs bem formatados, pelo que um valor mal formatado é rejeitado pelo router de URL antes da execução de qualquer código da aplicação e a resposta é uma página **HTML** de `404` em vez do envelope JSON `{\"detail\": ...}` apresentado abaixo.", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhooks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.list(\n \"22222222-3333-4444-5555-666666666666\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.list(\"22222222-3333-4444-5555-666666666666\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.List(ctx, \"22222222-3333-4444-5555-666666666666\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().list(\"22222222-3333-4444-5555-666666666666\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->list('22222222-3333-4444-5555-666666666666');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.webhooks.list(\"22222222-3333-4444-5555-666666666666\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.ListAsync(\"22222222-3333-4444-5555-666666666666\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Todas as entregas registadas para a sessão, da mais recente para a mais antiga.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionWebhookDelivery" } }, "examples": { "Failed delivery and its successful retry": { "value": [ { "uuid": "66666666-7777-8888-9999-000000000002", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"9188851d160b5b3aacfc946e4dde1f061b7e568662518942c927ddaf507f533d\", \"X-Signature-V2\": \"381236af514d3fb538579365ac5a24f2464ce1b8224c6e770c60d8201c43ecc5\", \"X-Signature-Simple\": \"4740131dc38f29e78a8508371979be74967d5307464494bd3148a03b4d6c8716\", \"X-Timestamp\": \"1792056139\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056139,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:22:19.104233Z" }, { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:21:18.412345Z" } ] }, "No webhook sent yet": { "value": [] } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. A ausência de `x-api-key`, ou uma chave inválida ou revogada, recebe `Authentication credentials were not provided or are invalid.` Uma chave de outra aplicação recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.` Um `sessionId` desconhecido devolve `404` antes de a credencial ser verificada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe ou foi eliminada (`Not found.`, devolvido antes de a credencial ser verificada), ou está fora dos limites de fluxo ou de estado de uma chave com âmbito restrito (`Session not found.`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 600 pedidos GET na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhook/{webhook_uuid}": { "get": { "summary": "Obter entrega de webhook da sessão", "description": "Obtenha uma entrega de webhook de uma sessão de verificação: o URL para onde foi enviada, o estado HTTP retornado pelo seu endpoint e os cabeçalhos e o corpo JSON exatos que a Didit enviou. `request_header` e `request_body` são texto em JSON; para testar a sua [verificação da assinatura](https://docs.didit.me/pt/integration/webhooks#verificação-da-assinatura), recalcule o `X-Signature-V2` a partir do corpo analisado com o segredo do destino para onde foi enviado (ou o segredo ao nível da aplicação para uma entrega no URL de webhook legado). O caminho não tem barra final: com uma, retorna `404`. Uma chave de API com âmbito restrito necessita de `sessions: read` e `decisions: read`.", "operationId": "get_v3_session_webhook", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação, utilizador (KYC) ou empresa (KYB): o `session_id` retornado por `POST /v3/session/`. O servidor resolve-o em ambos os tipos de sessão.\n\n**Deve ser um UUID válido.** A rota apenas faz correspondência com UUIDs bem formatados, pelo que um valor mal formatado é rejeitado pelo router de URL antes da execução de qualquer código da aplicação e a resposta é uma página **HTML** de `404` em vez do envelope JSON `{\"detail\": ...}` apresentado abaixo.", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" }, { "name": "webhook_uuid", "in": "path", "required": true, "description": "UUID da entrega: o `uuid` de uma entrada retornada por `GET /v3/session/{sessionId}/webhooks/`. Tem de pertencer à sessão no caminho.", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhook/66666666-7777-8888-9999-000000000001' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.Retrieve(ctx, \"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().retrieve(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->retrieve('22222222-3333-4444-5555-666666666666', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.RetrieveAsync(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A entrega, com os respetivos cabeçalhos e corpo do pedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionWebhookDelivery" }, "examples": { "Connection failure": { "value": { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:21:18.412345Z" } } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. A ausência de `x-api-key`, ou uma chave inválida ou revogada, recebe `Authentication credentials were not provided or are invalid.` Uma chave de outra aplicação recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.` Um `sessionId` desconhecido devolve `404` antes de a credencial ser verificada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe ou foi eliminada (`Not found.`, devolvido antes de a credencial ser verificada), ou está fora dos limites de fluxo ou de estado de uma chave com âmbito restrito (`Session not found.`). Uma entrega que não exista, pertença a outra sessão ou já não esteja disponível devolve `No WebhookLog matches the given query.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } }, "Delivery not in this session": { "value": { "detail": "No WebhookLog matches the given query." } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 600 pedidos GET na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhook/{webhook_uuid}/resend": { "post": { "summary": "Reenviar entrega de webhook da sessão", "description": "Envie novamente um webhook de sessão gravado para o URL de envio original, com o mesmo payload e `event_id` e com `timestamp`, cabeçalho `X-Timestamp` e assinaturas atualizados. A Didit assina-o com o segredo atual do destino a que a entrega pertence (ou com o segredo ao nível da aplicação para uma entrega no URL de webhook legado), aguarda até 5 segundos pelo seu endpoint, regista a tentativa como uma nova entrega e devolve-a com `200`, independentemente da resposta do seu endpoint: consulte `response_status`. Um reenvio não é repetido automaticamente e cada chamada envia novamente, pelo que deve garantir que o seu endpoint é idempotente com base em `event_id`. O caminho não tem barra final e o pedido não tem corpo. Uma chave de API com âmbito necessita de `webhooks: write` e `decisions: read`.", "operationId": "post_v3_session_webhook_resend", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "resend", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação, utilizador (KYC) ou empresa (KYB): o `session_id` retornado por `POST /v3/session/`. O servidor resolve-o em ambos os tipos de sessão.\n\n**Deve ser um UUID válido.** A rota apenas faz correspondência com UUIDs bem formatados, pelo que um valor mal formatado é rejeitado pelo router de URL antes da execução de qualquer código da aplicação e a resposta é uma página **HTML** de `404` em vez do envelope JSON `{\"detail\": ...}` apresentado abaixo.", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" }, { "name": "webhook_uuid", "in": "path", "required": true, "description": "UUID da entrega a reenviar: o `uuid` de uma entrada retornada por `GET /v3/session/{sessionId}/webhooks/`. Tem de pertencer à sessão no caminho.", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhook/66666666-7777-8888-9999-000000000001/resend' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.Resend(ctx, \"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().resend(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->resend('22222222-3333-4444-5555-666666666666', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.ResendAsync(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A nova entrega, já tentada. `response_status` é o que o seu endpoint respondeu desta vez. A entrega original permanece inalterada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionWebhookDelivery" }, "examples": { "Accepted on resend": { "value": { "uuid": "66666666-7777-8888-9999-000000000004", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"b8eb1e376517ee0cad8ba98ff7f8fd35fc72eca231000963a96a335f82328835\", \"X-Signature-V2\": \"9efd2ce9ed1303e1d05273ef9608a59363ed9789a05253db4748b3e8e50cb109\", \"X-Signature-Simple\": \"bf3a9dc04b2c20ab539203b0cd5cca2a10f630bf62d8feb6d68d82af80f64774\", \"X-Timestamp\": \"1792159542\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792159542,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-16T14:05:42.330981Z" } } } } } }, "400": { "description": "Não foi possível reenviar a entrega. Efetue a ramificação com base em `code`: `webhook_url_missing` significa que a entrega não tem nenhum URL registado e nada é enviado; `webhook_resend_error` significa que a entrega armazenada não pôde ser assinada novamente ou a tentativa não pôde ser concluída. Após `webhook_resend_error`, o campo `detail` começa com `Error processing webhook resend:` seguido de um texto de diagnóstico que pode mudar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." }, "code": { "type": "string", "description": "Código de erro legível por máquina estável. Crie ramificações com base neste campo, e não em `detail`." } } }, "examples": { "No recorded URL": { "value": { "detail": "The webhook delivery does not have a request URL configured", "code": "webhook_url_missing" } }, "Resend failed": { "value": { "detail": "Error processing webhook resend: Invalid webhook data format", "code": "webhook_resend_error" } } } } } }, "401": { "description": "A chave de API expirou: foi criada com uma data de validade que já passou. Uma chave incorreta ou revogada também recebe `401`; uma chave em falta recebe `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "O pedido não é permitido. A ausência de `x-api-key`, ou uma chave inválida ou revogada, recebe `Authentication credentials were not provided or are invalid.` Uma chave de outra aplicação recebe `You do not have permission to perform this action.` Uma chave com âmbito sem o acesso de que este endpoint necessita recebe uma mensagem a indicar o acesso em falta, e uma chave utilizada fora da sua lista de permissões de IP recebe `This API key can't be used from this IP address.` Um `sessionId` desconhecido devolve `404` antes de a credencial ser verificada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe ou foi eliminada (`Not found.`, devolvido antes de a credencial ser verificada), ou está fora dos limites de fluxo ou de estado de uma chave com âmbito restrito (`Session not found.`). Uma entrega que não exista, pertença a outra sessão ou já não esteja disponível devolve `Webhook log not found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } }, "Delivery not in this session": { "value": { "detail": "Webhook log not found" } } } } } }, "429": { "description": "Limite de pedidos excedido: mais de 300 pedidos de escrita (POST, PATCH, PUT, DELETE) na janela atual de um minuto para esta chave de API. Aguarde `Retry-After` segundos antes de tentar novamente.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Pedidos permitidos na janela de um minuto (300).", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "Pedidos restantes na janela atual.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Hora Unix (segundos) em que a janela atual é reposta.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome do orçamento que foi excedido.", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/events/": { "get": { "summary": "Listar eventos da sessão", "description": "Consulte a cronologia de eventos de uma sessão de verificação, dos mais recentes para os mais antigos por `sent_at`: os ecrãs que o utilizador viu, botões e carregamentos de ficheiros, tentativas falhadas, alterações de estado e de passos de funcionalidades, e o rastreio de encaminhamento do fluxo. Funciona para IDs de sessões de Verificação de utilizadores (KYC) e Verificação de empresas (KYB). Os eventos são armazenados assincronamente, pelo que um novo evento pode demorar alguns segundos a surgir. Os resultados são paginados com `limit` e `offset`; siga `next` até que seja `null`. Uma chave de API com âmbito precisa de `sessions: read` e `decisions: read` e, sem `media: read`, recebe `file_url` como `null`. Os eventos de encaminhamento estão descritos em [Consultar sessão](https://docs.didit.me/pt/sessions-api/retrieve-session).", "operationId": "get_v3_session_events", "x-didit-sdk": { "resource": "sessions", "method": "list_events", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação (o `session_id` retornado por `POST /v3/session/`). Aceita IDs de sessão de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB): o servidor resolve o ID em ambos os tipos de sessão. Deve ser um UUID bem formatado; um valor mal formatado não corresponde à rota e retorna um `404` em HTML.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "limit", "in": "query", "required": false, "description": "Número máximo de eventos por página. O valor predefinido é 50. Um valor inferior a 1 ou um valor não numérico reverte para 50; um valor acima de 1,000,000 devolve `400`.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Número de resultados a ignorar antes do primeiro devolvido. O valor predefinido é 0; um valor negativo ou não numérico reverte para 0, um valor acima de 1,000,000 devolve `400`. Prefira seguir os URLs `next` e `previous`.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "Substituição opcional da ordenação. A ordem predefinida é `-sent_at`. Indique o nome de um campo de resultado (por exemplo `sent_at`, `created_at`, `event_type`, `feature_step` ou `step`) para ordenar ascendentemente, use o prefixo `-` para ordenar descendentemente e separe múltiplos campos com vírgulas. Campos desconhecidos são ignorados.", "schema": { "type": "string", "example": "sent_at" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/events/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list_events(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.listEvents(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListEventsAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsListEventsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().listEvents(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->listEvents('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list_events(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListEventsAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de eventos da sessão, os mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Número total de eventos da sessão." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SessionEvent" } } } }, "examples": { "Completed session": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "aaaaaaaa-1111-2222-3333-444444444444", "event_type": "SESSION_STATUS_CHANGED", "created_at": "2026-09-14T10:02:13.904512Z", "component": null, "feature_step": null, "step": null, "details": { "old_status": "In Progress", "current_status": "Approved" }, "ip_address": null, "user_agent": null, "device_info": null, "file_url": null, "sent_at": 1789380131482 }, { "uuid": "bbbbbbbb-1111-2222-3333-444444444444", "event_type": "FEATURE_STEP_CHANGED", "created_at": "2026-09-14T10:01:49.210377Z", "component": null, "feature_step": null, "step": null, "details": { "old_feature_step": "OCR", "current_feature_step": "LIVENESS" }, "ip_address": null, "user_agent": null, "device_info": null, "file_url": null, "sent_at": 1789380107103 }, { "uuid": "cccccccc-1111-2222-3333-444444444444", "event_type": "STEP_RENDERED", "created_at": "2026-09-14T10:01:00.581930Z", "component": "DocumentCapture", "feature_step": "OCR", "step": "DOCUMENT_CAPTURE_FRONT", "details": {}, "ip_address": "203.0.113.24", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1", "device_info": { "device_model": "iPhone" }, "file_url": null, "sent_at": 1789380058776 } ] } } } } } }, "400": { "description": "`limit` ou `offset` é superior a 1,000,000. O corpo é um array JSON com uma mensagem.", "content": { "application/json": { "examples": { "Limit too large": { "summary": "limit=2000000", "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "summary": "offset=2000000", "value": [ "offset must not exceed 1000000." ] } }, "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "summary": "Chave com âmbito não tem sessions: read", "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "summary": "Chave com âmbito não tem decisions: read", "value": { "detail": "This API key has no read access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada ou está fora dos limites de fluxo ou limites que permitem apenas sessões aprovadas de uma chave com âmbito restrito. A pesquisa da sessão é executada antes da verificação de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo sem uma chave válida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "summary": "Não existe nenhuma sessão com este ID ou foi eliminada", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "A sessão está fora dos limites de fluxo ou dos limites que permitem apenas sessões aprovadas de uma chave com âmbito restrito", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite de pedidos excedido: 600 pedidos GET por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento disponível.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/aml-screening-history/": { "get": { "summary": "Listar histórico de triagem AML", "description": "Listar todas as retriagens de monitorização contínua concluídas da verificação AML de uma sessão, da mais recente para a mais antiga por `completed_at`, incluindo as execuções em que nada mudou: os alertas, entradas de atividade e webhooks só são acionados quando um resultado é alterado, pelo que este histórico serve como prova de que um sujeito sem ocorrências continuava a ser triado. Funciona para IDs de sessão de KYC e KYB; passe `node_id` quando a sessão tiver executado mais do que um passo de AML. Apenas as retriagens de monitorização contínua são listadas (a primeira triagem faz parte da decisão da sessão) e as execuções anteriores à existência deste histórico não são reconstruídas, pelo que uma sessão sem monitorização contínua devolve uma lista vazia. O `count` é exato até 100 e limitado a 100 acima desse valor, pelo que deve seguir `next` até ser `null`. Passe `month` para consultar um mês civil de cada vez. Uma chave de API com âmbito restrito necessita de `decisions: read`; consulte [Monitorização AML contínua](https://docs.didit.me/pt/core-technology/aml-screening/continuous-monitoring-aml-screening).", "operationId": "get_v3_session_aml_screening_history", "x-didit-sdk": { "resource": "sessions", "method": "list_aml_screening_history", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação (o `session_id` retornado por `POST /v3/session/`). Aceita IDs de sessão de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB): o servidor resolve o ID em ambos os tipos de sessão. Deve ser um UUID bem formatado; um valor mal formatado não corresponde à rota e retorna um `404` em HTML.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "ID do nó do grafo do fluxo da verificação AML. Necessário apenas quando a sessão executou mais de um passo AML; sem ele, é utilizada a verificação AML mais recente. Um nó desconhecido devolve `404`.", "schema": { "type": "string", "example": "feature_aml_1" } }, { "name": "month", "in": "query", "required": false, "description": "Um mês de calendário UTC no formato `YYYY-MM`. Apenas são devolvidas as triagens concluídas nesse mês; sem este parâmetro, são devolvidos todos os meses. Um mês mal formatado devolve `400`.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } }, { "name": "limit", "in": "query", "required": false, "description": "Número máximo de execuções de triagem por página. O valor predefinido é 50. Um valor inferior a 1 ou um valor não numérico reverte para 50; um valor acima de 1,000,000 devolve `400`.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Número de resultados a ignorar antes do primeiro devolvido. O valor predefinido é 0; um valor negativo ou não numérico reverte para 0, um valor acima de 1,000,000 devolve `400`. Prefira seguir os URLs `next` e `previous`.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "Substituição opcional da ordenação. A ordem predefinida é `-completed_at`. Indique o nome de um campo de resultado (por exemplo `completed_at`, `started_at`, `outcome` ou `score`) para ordenar ascendentemente, use o prefixo `-` para ordenar descendentemente e separe múltiplos campos com vírgulas. Campos desconhecidos são ignorados.", "schema": { "type": "string", "example": "completed_at" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/aml-screening-history/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list_aml_screening_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.listAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAMLScreeningHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsListAMLScreeningHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().listAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->listAmlScreeningHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list_aml_screening_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListAmlScreeningHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de execuções de triagem, as mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "maximum": 100, "description": "Número de execuções, exato até 100 e limitado a 100 acima desse valor." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página seguinte, ou `null` na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página anterior, ou `null` na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AMLScreeningRun" } } } }, "examples": { "Monitored subject": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "dddddddd-1111-2222-3333-444444444444", "run_id": "aaaaaaaa-1111-2222-3333-444444444444", "completed_at": "2026-09-14T04:12:33.481207Z", "started_at": "2026-09-14T04:00:01.002311Z", "outcome": "NO_CHANGE", "trigger": "ONGOING_MONITORING", "provider": "aml_data_source", "status": "Approved", "score": 0.0, "total_hits": 0, "new_hits": 0, "entities_screened": 1, "dataset_freshness": { "captured_at": "2026-09-14T03:58:02.114820+00:00", "provider": "aml_data_source", "catalog_version": "2026-09-13", "sources": { "sanctions": { "last_updated_at": "2026-09-13T21:10:00+00:00", "oldest_updated_at": "2026-09-11T06:00:00+00:00", "dataset_count": 120, "dated_dataset_count": 120 }, "pep": { "last_updated_at": "2026-09-13T08:00:00+00:00", "oldest_updated_at": null, "dataset_count": 45, "dated_dataset_count": 44 }, "warnings": { "last_updated_at": "2026-09-12T18:45:00+00:00", "oldest_updated_at": "2026-09-01T00:00:00+00:00", "dataset_count": 30, "dated_dataset_count": 30 } } } }, { "uuid": "eeeeeeee-1111-2222-3333-444444444444", "run_id": "bbbbbbbb-1111-2222-3333-444444444444", "completed_at": "2026-09-13T04:11:58.020914Z", "started_at": "2026-09-13T04:00:00.871022Z", "outcome": "FAILED", "trigger": "ONGOING_MONITORING", "provider": "aml_data_source", "status": "Approved", "score": 0.0, "total_hits": 0, "new_hits": null, "entities_screened": 0, "dataset_freshness": null } ] } } } } } }, "400": { "description": "`limit` ou `offset` é superior a 1,000,000 (um array JSON com uma mensagem), ou `month` não é um mês civil no formato `YYYY-MM` (um objeto cuja chave é `month`).", "content": { "application/json": { "examples": { "Limit too large": { "summary": "limit=2000000", "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "summary": "offset=2000000", "value": [ "offset must not exceed 1000000." ] }, "Malformed month": { "summary": "month=2026-13", "value": { "month": [ "Not a calendar month. Use YYYY-MM." ] } } }, "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "month": { "type": "array", "items": { "type": "string" } } } } ] } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions read": { "summary": "Chave com âmbito não tem decisions: read", "value": { "detail": "This API key has no read access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada ou está fora dos limites de uma chave com âmbito restrito, ou não tem uma verificação AML (para o `node_id` indicado). A pesquisa da sessão é executada antes da verificação de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo sem uma chave válida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "summary": "Não existe nenhuma sessão com este ID ou foi eliminada", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "A sessão está fora dos limites de uma chave com âmbito restrito (também devolvido para uma sessão eliminada há momentos)", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "A sessão nunca executou um passo AML", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id não corresponde a uma verificação AML da sessão", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "Limite de pedidos excedido: 600 pedidos GET por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento disponível.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/aml-screening-history/export/": { "get": { "summary": "Exportar histórico de triagem AML como CSV", "description": "Descarregue o mesmo histórico de monitorização contínua que `GET /v3/session/{sessionId}/aml-screening-history/` como um ficheiro CSV, uma linha por nova triagem concluída, a mais recente primeiro, pronto para entregar a um auditor. O ficheiro é transmitido por streaming na totalidade (sem paginação) e começa com uma linha de cabeçalho; uma célula vazia significa desconhecido, as datas do conjunto de dados nunca são estimadas e um valor que iniciaria uma fórmula de folha de cálculo é prefixado com um apóstrofo. Funciona para IDs de sessão de KYC e KYB; passe `node_id` quando a sessão tiver executado mais de um passo de AML. Passe `month` para exportar um mês civil. Os erros são devolvidos como JSON, não CSV. Uma chave de API com âmbito requer `decisions: read` e `media: read`: a resposta é um ficheiro, pelo que uma chave sem `media: read` recebe `403`.", "operationId": "get_v3_session_aml_screening_history_export", "x-didit-sdk": { "resource": "sessions", "method": "export_aml_screening_history", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação (o `session_id` retornado por `POST /v3/session/`). Aceita IDs de sessão de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB): o servidor resolve o ID em ambos os tipos de sessão. Deve ser um UUID bem formatado; um valor mal formatado não corresponde à rota e retorna um `404` em HTML.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "ID do nó do grafo do fluxo da verificação AML. Necessário apenas quando a sessão executou mais de um passo AML; sem ele, é utilizada a verificação AML mais recente. Um nó desconhecido devolve `404`.", "schema": { "type": "string", "example": "feature_aml_1" } }, { "name": "month", "in": "query", "required": false, "description": "Um mês de calendário UTC no formato `YYYY-MM`. Apenas são devolvidas as triagens concluídas nesse mês; sem este parâmetro, são devolvidos todos os meses. Um mês mal formatado devolve `400`.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/aml-screening-history/export/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -o aml-screening-history.csv" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.export_aml_screening_history(\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.exportAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.ExportAMLScreeningHistory(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsExportAMLScreeningHistoryParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().exportAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->exportAmlScreeningHistory('11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.export_aml_screening_history(\"11111111-2222-3333-4444-555555555555\")\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.ExportAmlScreeningHistoryAsync(\"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.csv\");" } ], "responses": { "200": { "description": "O ficheiro CSV, transmitido como `text/csv` com quebras de linha CRLF. Colunas, por ordem: `screened_at` (quando a nova triagem terminou), `outcome` (`NO_CHANGE`, `CHANGED` ou `FAILED`), `provider` (identificador opaco da fonte de dados de AML; não crie ramificações com base nele), `aml_status`, `aml_score`, `total_hits`, `datasets_captured_at`, `datasets_sanctions_last_updated_at`, `datasets_pep_last_updated_at`, `datasets_warnings_last_updated_at`, `datasets_adverse_media_last_updated_at`, `datasets_catalog_version`, `run_id` (a execução de monitorização), `entities_screened` (`1` ou `0` para uma execução com falha) e `new_hits` (vazio quando desconhecido). As datas estão no formato ISO 8601 com desvio UTC. Uma sessão sem novas triagens até ao momento devolve apenas a linha de cabeçalho.", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"aml-screening-history-{sessionId}.csv\"`, ou `aml-screening-history-{sessionId}-{month}.csv` quando `month` for transmitido.", "schema": { "type": "string", "example": "attachment; filename=\"aml-screening-history-11111111-2222-3333-4444-555555555555.csv\"" } } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "screened_at,outcome,provider,aml_status,aml_score,total_hits,datasets_captured_at,datasets_sanctions_last_updated_at,datasets_pep_last_updated_at,datasets_warnings_last_updated_at,datasets_adverse_media_last_updated_at,datasets_catalog_version,run_id,entities_screened,new_hits\r\n2026-09-14T04:12:33.481207+00:00,NO_CHANGE,aml_data_source,Approved,0.0,0,2026-09-14T03:58:02.114820+00:00,2026-09-13T21:10:00+00:00,2026-09-13T08:00:00+00:00,2026-09-12T18:45:00+00:00,,2026-09-13,aaaaaaaa-1111-2222-3333-444444444444,1,0\r\n2026-09-13T04:11:58.020914+00:00,FAILED,aml_data_source,Approved,0.0,0,,,,,,,bbbbbbbb-1111-2222-3333-444444444444,0,\r\n" } } }, "400": { "description": "`month` não é um mês civil no formato `YYYY-MM`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Malformed month": { "summary": "month=2026-13", "value": { "month": [ "Not a calendar month. Use YYYY-MM." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions read": { "summary": "Chave com âmbito não tem decisions: read", "value": { "detail": "This API key has no read access to decisions." } }, "Scoped key without media read": { "summary": "Chave com âmbito não tem media: read (a resposta é um ficheiro)", "value": { "detail": "This API key has no read access to media." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada ou está fora dos limites de uma chave com âmbito restrito, ou não tem uma verificação AML (para o `node_id` indicado). A pesquisa da sessão é executada antes da verificação de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo sem uma chave válida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "summary": "Não existe nenhuma sessão com este ID ou foi eliminada", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "A sessão está fora dos limites de uma chave com âmbito restrito (também devolvido para uma sessão eliminada há momentos)", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "A sessão nunca executou um passo AML", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id não corresponde a uma verificação AML da sessão", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "Limite de pedidos excedido: 600 pedidos GET por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento disponível.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/add-images/": { "patch": { "summary": "Adicionar uma imagem a uma sessão", "description": "Anexe uma imagem ou PDF adicional ao resultado da Verificação de identidade (`model_type=kyc`) ou Comprovativo de morada (`model_type=poa`) de uma sessão de Verificação de utilizadores (KYC) concluída, por exemplo, provas recolhidas fora do fluxo. A sessão deve estar como `Approved`, `Declined`, `In Review` ou `Kyc Expired` e incluir o resultado indicado por `model_type`; sessões de Verificação de empresas (KYB) não são suportadas. Cada chamada acrescenta um ficheiro (ao resultado mais recente se o passo tiver sido executado mais do que uma vez), mantém os ficheiros existentes e regista uma entrada `FILE_ADDED` no registo de atividade da sessão; o carregamento não envia nenhum webhook e não altera o estado da sessão. O ficheiro é comprimido durante o carregamento e é devolvido em `extra_files` da decisão da sessão. Este endpoint está limitado a 10 pedidos por minuto por chave de API. Uma chave de API com âmbito necessita de `sessions: write`, e sem `media: read` recebe as ligações de `extra_files` como `null`.", "operationId": "patch_v3_session_add_images", "x-didit-sdk": { "resource": "sessions", "method": "add_images", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de utilizadores (KYC) à qual adicionar o ficheiro (o `session_id` retornado por `POST /v3/session/`). O ID de uma sessão de Verificação de empresas (KYB) devolve `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "model_type" ], "properties": { "file": { "type": "string", "format": "binary", "description": "A imagem ou PDF. Extensões permitidas: `jpg`, `jpeg`, `png`, `webp`, `tiff`, `pdf`. No máximo 15 MB aquando do carregamento; o ficheiro é depois comprimido e rejeitado com `400` se continuar a ter mais de 2 MB (2 097 152 bytes). Ficheiros vazios são rejeitados." }, "model_type": { "type": "string", "enum": [ "kyc", "poa" ], "description": "`kyc` adiciona o ficheiro ao resultado da Verificação de identidade, `poa` ao resultado do Comprovativo de morada.", "example": "kyc" }, "file_password": { "type": "string", "description": "Palavra-passe de um PDF encriptado. Sem ela, ou com uma incorreta, um PDF encriptado devolve `400`." } } }, "example": { "file": "(binary)", "model_type": "kyc" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@./back-of-id.jpg' \\\n -F 'model_type=kyc'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.add_images(\n \"11111111-2222-3333-4444-555555555555\",\n file=open(\"image.jpg\", \"rb\"),\n model_type=\"kyc\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.addImages(\"11111111-2222-3333-4444-555555555555\", {\n file: await fileFromPath(\"image.jpg\"),\n model_type: \"kyc\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.AddImages(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsAddImagesParams{\n\tFile: didit.FileFromPath(\"image.jpg\"),\n\tModelType: \"kyc\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.SessionsAddImagesParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().addImages(\"11111111-2222-3333-4444-555555555555\", SessionsAddImagesParams.builder()\n .file(Path.of(\"image.jpg\"))\n .modelType(SessionsAddImagesParams.ModelType.of(\"kyc\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->addImages('11111111-2222-3333-4444-555555555555', [\n 'file' => File::fromPath('image.jpg'),\n 'model_type' => 'kyc',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.add_images(\n \"11111111-2222-3333-4444-555555555555\",\n file: Pathname(\"image.jpg\"),\n model_type: \"kyc\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.AddImagesAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsAddImagesParams\n{\n File = FileUpload.FromPath(\"image.jpg\"),\n ModelType = \"kyc\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Ficheiro adicionado. Devolve todos os ficheiros adicionais desse resultado, incluindo o novo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "extra_files" ], "properties": { "extra_files": { "type": "array", "description": "Ligações pré-assinadas de curta duração para todos os ficheiros adicionais do resultado designado por `model_type`, do mais antigo para o mais recente. Cada ligação é `null` para uma chave de API com âmbito restrito sem `media: read`. Obtenha ligações atualizadas posteriormente a partir da decisão da sessão.", "items": { "type": "string", "format": "uri", "nullable": true } } } }, "example": { "extra_files": [ "https://media.example.com/session/11111111-2222-3333-4444-555555555555/kyc-extra-files/66666666-7777-8888-9999-000000000000.jpg?expires=1789383731&signature=abc123" ] } } } }, "400": { "description": "Erro de validação. Os erros de campo chegam como `{\"\": [\"\"]}`; erros de PDF encriptado como `{\"detail\": \"...\"}`.", "content": { "application/json": { "examples": { "Missing file": { "summary": "Nenhuma parte de ficheiro no formulário", "value": { "file": [ "No file was submitted." ] } }, "Missing model_type": { "summary": "model_type omitido", "value": { "model_type": [ "This field is required." ] } }, "Invalid model_type": { "summary": "model_type não é kyc nem poa", "value": { "model_type": [ "\"passport\" is not a valid choice." ] } }, "File too large": { "summary": "Carregamento superior a 15 MB", "value": { "file": [ "File size should not exceed 15 MB" ] } }, "Too large after compression": { "summary": "Ainda superior a 2 MB após compressão", "value": { "file": [ "File size is too big. Max allowed size is 2097152 bytes." ] } }, "Encrypted PDF": { "summary": "PDF encriptado sem file_password", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "file_password não abre o PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions write": { "summary": "Chave com âmbito não tem sessions: write", "value": { "detail": "This API key has no write access to sessions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada ou está fora dos limites de uma chave com âmbito restrito; é uma sessão KYB ou não está em `Approved`, `Declined`, `In Review` ou `Kyc Expired`; ou não tem nenhum resultado do `model_type` solicitado (verificado antes de o ficheiro ser validado). A pesquisa da sessão é executada antes da verificação de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo sem uma chave válida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "summary": "Não existe nenhuma sessão com este ID ou foi eliminada", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "A sessão está fora dos limites de fluxo ou dos limites que permitem apenas sessões aprovadas de uma chave com âmbito restrito", "value": { "detail": "Session not found." } }, "Not eligible": { "summary": "Sessão ainda não concluída, ou um ID de sessão KYB", "value": { "detail": "No Session matches the given query." } }, "No ID verification": { "summary": "model_type=kyc numa sessão sem verificação de identidade", "value": { "detail": "The session does not have KYC data." } }, "No Proof of Address": { "summary": "model_type=poa numa sessão sem comprovativo de morada", "value": { "detail": "The session does not have POA data." } } } } } }, "429": { "description": "Limite de pedidos excedido: 10 pedidos add-images por minuto por chave de API (pedidos rejeitados também contam). O orçamento partilhado de 300 pedidos de escrita por minuto também se aplica. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Session add-images rate limit exceeded. You can make up to 10 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/update-aml-status/": { "patch": { "summary": "Atualizar o estado de uma verificação AML", "description": "Defina o estado da verificação de triagem AML de uma sessão no seu todo (o `status` de uma entrada `aml_screenings[]` na decisão da sessão), por exemplo, `Approved` após a sua equipa ter tratado cada hit. Funciona para IDs de sessão de KYC e KYB; passe `node_id` (parâmetro de consulta ou campo do corpo) quando a sessão tiver executado mais de um passo de AML; caso contrário, é atualizada a verificação AML mais recente. Quando o estado muda efetivamente, é registada uma entrada de atividade `AML_STATUS_UPDATED` e é enviado um [webhook](https://docs.didit.me/pt/integration/webhooks) `data.updated`; enviar o estado atual devolve `200` e não altera nada. O estado da sessão não é recalculado: utilize `PATCH /v3/session/{sessionId}/update-status/` para a decisão da sessão e `PATCH /v3/session/{sessionId}/update-aml-hit-status/` para hits individuais. Uma chave de API com âmbito necessita de `decisions: write`.", "operationId": "patch_v3_session_update_aml_status", "x-didit-sdk": { "resource": "sessions", "method": "update_aml_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação (o `session_id` retornado por `POST /v3/session/`). Aceita IDs de sessão de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB): o servidor resolve o ID em ambos os tipos de sessão. Deve ser um UUID bem formatado; um valor mal formatado não corresponde à rota e retorna um `404` em HTML.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "ID do nó do grafo do fluxo da verificação AML a atualizar. Necessário apenas quando a sessão executou mais de um passo AML. Tem precedência sobre `node_id` no corpo.", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Novo estado da verificação AML.", "example": "Approved" }, "node_id": { "type": "string", "description": "ID do nó do grafo do fluxo da verificação AML, como alternativa ao parâmetro de consulta.", "example": "feature_aml_1" } } }, "example": { "status": "Approved" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"Approved\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_aml_status(\n \"11111111-2222-3333-4444-555555555555\",\n status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateAmlStatus(\"11111111-2222-3333-4444-555555555555\", {\n status: \"Approved\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateAMLStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateAMLStatusParams{\n\tStatus: \"Approved\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateAmlStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateAmlStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateAmlStatusParams.builder()\n .status(SessionsUpdateAmlStatusParams.Status.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateAmlStatus('11111111-2222-3333-4444-555555555555', [\n 'status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_aml_status(\n \"11111111-2222-3333-4444-555555555555\",\n status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateAmlStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateAmlStatusParams\n{\n Status = \"Approved\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Estado da verificação AML definido (ou inalterado quando já tinha este valor).", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "status", "previous_status" ], "properties": { "message": { "type": "string", "description": "Sempre `AML status updated successfully`." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado da verificação AML agora." }, "previous_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado antes da chamada. Igual a `status` quando nada foi alterado." } } }, "example": { "message": "AML status updated successfully", "status": "Approved", "previous_status": "In Review" } } } }, "400": { "description": "Erro de validação: `status` em falta ou não é um dos valores permitidos. A pesquisa da verificação AML é executada primeiro, pelo que uma sessão sem uma verificação AML devolve `404` mesmo com um corpo inválido.", "content": { "application/json": { "examples": { "Missing status": { "summary": "Corpo vazio ou sem estado", "value": { "status": [ "This field is required." ] } }, "Invalid status": { "summary": "status não consta do enum", "value": { "status": [ "\"Cleared\" is not a valid choice." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada ou está fora dos limites de uma chave com âmbito restrito, ou não tem uma verificação AML (para o `node_id` indicado). A pesquisa da sessão é executada antes da verificação de credenciais, pelo que um `sessionId` desconhecido devolve `404` mesmo sem uma chave válida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Unknown session": { "summary": "Não existe nenhuma sessão com este ID ou foi eliminada", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "A sessão está fora dos limites de uma chave com âmbito restrito (também devolvido para uma sessão eliminada há momentos)", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "A sessão nunca executou um passo AML", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id não corresponde a uma verificação AML da sessão", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "Limite de pedidos excedido: 300 pedidos de escrita (POST, PATCH, DELETE) por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/status/": { "get": { "summary": "Obter estado do serviço (público, não autenticado)", "description": "Devolve o estado de cada serviço Didit (`operational`, `degraded` ou `down`), o estado global (o pior de entre eles) e os incidentes em curso ou resolvidos nos últimos 7 dias. Utilize-o para alimentar um widget de estado ou para verificar o estado da Didit a partir da sua integração.\n\nPúblico: não envie cabeçalho de autenticação. A resposta não contém dados da organização e é igual para todos os autores de chamadas. As respostas ficam em cache durante 30 segundos, pelo que não deve consultar mais do que uma vez a cada 30 segundos.", "operationId": "get_v3_status", "tags": [ "Status" ], "security": [ {} ], "parameters": [], "responses": { "200": { "description": "Estado atual do serviço.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceStatusFeed" }, "examples": { "One service degraded": { "summary": "Um incidente em curso e um resolvido esta semana", "value": { "status": "degraded", "updated_at": "2026-10-13T09:41:07.512345Z", "services": [ { "key": "service_id_verification", "name": "ID verification", "status": "operational" }, { "key": "service_liveness_face_match", "name": "Liveness and face match", "status": "operational" }, { "key": "service_aml_screening", "name": "AML screening", "status": "operational" }, { "key": "service_kyb_registries", "name": "KYB registries", "status": "operational" }, { "key": "service_database_validation", "name": "Database validation", "status": "degraded" }, { "key": "service_phone_delivery", "name": "Phone verification delivery", "status": "operational" }, { "key": "service_email_delivery", "name": "Email verification delivery", "status": "operational" }, { "key": "service_transaction_monitoring", "name": "Transaction monitoring", "status": "operational" } ], "incidents": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "service": "service_database_validation", "service_name": "Database validation", "state": "degraded", "status": "ongoing", "title": "Database validation is degraded in Brazil.", "body": "Checks against Brazil (CPF) may be slow or fail since 08:55 UTC.", "affected": "Brazil (CPF)", "country_name": "Brazil", "started_at": "2026-10-13T08:55:00Z", "resolved_at": null, "duration_minutes": null }, { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "service": "service_aml_screening", "service_name": "AML screening", "state": "down", "status": "resolved", "title": "AML screening is back to normal.", "body": "Recovered at 14:32 UTC after 17 minutes.", "affected": "", "country_name": "", "started_at": "2026-10-11T14:15:00Z", "resolved_at": "2026-10-11T14:32:00Z", "duration_minutes": 17 } ] } }, "All operational": { "summary": "Nenhum incidente nos últimos 7 dias", "value": { "status": "operational", "updated_at": "2026-10-13T09:41:07.512345Z", "services": [ { "key": "service_id_verification", "name": "ID verification", "status": "operational" }, { "key": "service_liveness_face_match", "name": "Liveness and face match", "status": "operational" }, { "key": "service_aml_screening", "name": "AML screening", "status": "operational" }, { "key": "service_kyb_registries", "name": "KYB registries", "status": "operational" }, { "key": "service_database_validation", "name": "Database validation", "status": "operational" }, { "key": "service_phone_delivery", "name": "Phone verification delivery", "status": "operational" }, { "key": "service_email_delivery", "name": "Email verification delivery", "status": "operational" }, { "key": "service_transaction_monitoring", "name": "Transaction monitoring", "status": "operational" } ], "incidents": [] } } } } } }, "429": { "description": "Mais de 600 pedidos GET num minuto a partir do mesmo endereço IP (ou da mesma chave de API, caso envie uma). Respeite o cabeçalho `Retry-After` antes de tentar novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string" } } }, "example": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -fsS https://verification.didit.me/v3/status/" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresp = requests.get('https://verification.didit.me/v3/status/', timeout=5)\nresp.raise_for_status()\nfeed = resp.json()\nprint(feed['status'])\nfor service in feed['services']:\n if service['status'] != 'operational':\n print(service['key'], service['status'])" }, { "lang": "javascript", "label": "JavaScript", "source": "const feed = await fetch('https://verification.didit.me/v3/status/').then((r) => r.json());\nconsole.log(feed.status);\nconst affected = feed.services.filter((s) => s.status !== 'operational');\nconsole.log(affected.map((s) => `${s.key}: ${s.status}`));" } ], "x-didit-sdk": { "resource": "system", "method": "retrieve_status", "auth": "public", "server": false } } }, "/v3/organization/bank-verification-pricing/": { "get": { "summary": "Obter preços de verificação bancária (público, não autenticado)", "description": "Devolve o preço de tabela de cada método de Verificação bancária em cada país: início de sessão bancário com os respetivos complementos de saldo e transações, e a verificação de conta. Um método que um país não disponibilize atualmente é apresentado como não disponível, sem preço. Utilize-o para orçamentar um passo bancário antes de criar um fluxo, ou para apresentar preços bancários no seu próprio produto.\n\nPúblico: não envie cabeçalho de autenticação. A resposta não contém dados da organização e é igual para todos os chamadores. Fica em cache publicamente durante uma hora e contém um `ETag`, pelo que deve enviar `If-None-Match` para obter um `304 Not Modified` quando nada tiver mudado.\n\nUm método só está `available` onde a Didit o disponibiliza em produção atualmente, e o respetivo `price_usd` é `null` em todos os outros casos, pelo que o feed nunca apresenta um preço que não possa adquirir. `available: false` abrange um país sem preço aprovado, um método que o país não suporta e uma rota que ainda não está ativa.\n\nEstes são preços de tabela antes do desconto do seu plano. O desconto do seu plano aplica-se ao preço bancário total, e um preço negociado ou sob contrato substitui o preço de tabela para a sua organização.", "operationId": "get_v3_bank_verification_pricing", "tags": [ "Pricing" ], "security": [ {} ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -fsS https://verification.didit.me/v3/organization/bank-verification-pricing/" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# This call needs no API key.\nclient = Didit()\n\nresult = client.pricing.bank_verification()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// This call needs no API key.\nconst didit = new Didit();\n\nconst result = await didit.pricing.bankVerification();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// This call needs no API key.\nclient := didit.NewClient()\n\nresult, err := client.Pricing.BankVerification(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// This call needs no API key.\nDidit client = new Didit();\n\nvar result = client.pricing().bankVerification();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "pricing->bankVerification();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# This call needs no API key.\ndidit = Didit::Client.new\n\nresult = didit.pricing.bank_verification\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// This call needs no API key.\nusing var client = new DiditClient();\n\nvar result = await client.Pricing.BankVerificationAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "pricing", "method": "bank_verification", "auth": "none", "server": true }, "responses": { "200": { "description": "Preços de tabela de Verificação bancária por país.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankVerificationPricing" }, "examples": { "Two countries": { "summary": "Um país com ambos os métodos, um sem nenhum", "value": { "currency": "USD", "statement_upload": { "price_usd": "0.0000", "included_after_charged_bank_attempt": true, "standalone_available": false }, "own_provider_fee_usd": "0.0200", "countries": { "GBR": { "name": "United Kingdom", "methods": { "open_banking": { "available": true, "market": "UK and EEA", "price_usd": "0.7900", "add_ons": { "balance": "0.3500", "transactions": "1.3000" } }, "account_lookup": { "available": true, "price_usd": "0.4000" } } }, "CAN": { "name": "Canada", "methods": { "open_banking": { "available": false, "market": null, "price_usd": null, "add_ons": {} }, "account_lookup": { "available": false, "price_usd": null } } } } } } } } } }, "304": { "description": "Não modificado: o `ETag` que enviou em `If-None-Match` ainda corresponde. Sem corpo." } } } }, "/v3/session/{sessionId}/simulate/": { "post": { "summary": "Simular o estado de uma sessão de sandbox", "description": "Forçar um estado terminal numa sessão de sandbox posteriormente, a partir do seu backend, sem executar o fluxo. Apenas aplicações de sandbox: uma sessão de produção devolve `404`. Funciona para sessões de Verificação de utilizadores (KYC) e Verificação de empresas (KYB).\n\nDefina `new_status`, ou deixe que `scenario` ou `risk` o forneçam. `risk` (ou o primeiro risco que os valores mágicos do cenário transportam) adiciona esse aviso à sessão. A alteração é registada na atividade da sessão.\n\n`send_webhooks` (predefinição `true`) envia exatamente os webhooks que uma alteração de estado real envia. Com `false`, o estado continua a mudar e a consola continua a atualizar em tempo real, mas nenhum webhook é registado ou enviado, a recuperação de webhooks em falta nunca reenvia essa decisão e a próxima alteração de estado envia webhooks normalmente. A resposta reflete o valor aplicado.\n\nRequer o privilégio `write:sessions`; uma chave de API com âmbito precisa de acesso de escrita a sessões. Um `session_id` desconhecido devolve `404` e a sessão de outra aplicação devolve `403`, ambos antes de o corpo ser lido; uma sessão de produção devolve `404` apenas após o corpo ser validado. Para simular a partir do fluxo alojado com o próprio token da sessão, utilize `POST /v3/session/{sessionId}/sandbox/simulate/`. Consulte [Sandbox e dados de teste](/pt/integration/sandbox-testing) para o catálogo de cenários.", "operationId": "post_v3_session_simulate", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação em sandbox. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateRequest" }, "examples": { "Scenario Without Webhooks": { "summary": "Recusar através de um cenário sem enviar webhooks", "value": { "scenario": "decline_aml_hit", "send_webhooks": false } }, "Status Only": { "summary": "Aprovar e enviar os webhooks habituais", "value": { "new_status": "Approved" } } } } } }, "responses": { "200": { "description": "O estado mudou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateResponse" }, "examples": { "Simulated": { "summary": "Recusada através de um cenário, webhooks não enviados", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "previous_status": "In Progress", "status": "Declined", "scenario": "decline_aml_hit", "risk": "POSSIBLE_MATCH_FOUND", "send_webhooks": false } } } } } }, "400": { "description": "Erro de validação: um cenário ou risco desconhecido, ausência de `new_status` quando nem `scenario` nem `risk` fornecem um, um estado que este endpoint não define ou a sessão já tem o estado solicitado (um array JSON simples).", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "o cenário não está no catálogo", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-scenario'." ] } }, "Unknown Risk": { "summary": "risk não se encontra no catálogo", "value": { "risk": [ "Unknown sandbox risk case: 'NOT_A_RISK'." ] } }, "Missing new_status": { "summary": "Sem new_status, scenario ou risk", "value": { "new_status": [ "This field is required." ] } }, "Invalid new_status": { "summary": "Um estado que a simulação não define", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Same Status": { "summary": "A sessão já tem este estado", "value": [ "The new status is the same as the current status." ] } } } } }, "401": { "description": "A chave de API com âmbito expirou.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chave de API com âmbito cuja data de validade já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenciais em falta, um chamador sem o privilégio `write:sessions`, uma chave de API com âmbito sem o acesso de que este endpoint necessita, ou um `session_id` que pertence a outra aplicação.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "O autor da chamada não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chave de API com âmbito sem este acesso", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "404": { "description": "Não existe nenhuma sessão com este `session_id` ou é uma sessão de produção (não sandbox).", "content": { "application/json": { "examples": { "Not Found": { "summary": "Sessão desconhecida ou de produção", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulate/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"scenario\": \"decline_aml_hit\", \"send_webhooks\": false}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.simulate(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n scenario=\"decline_aml_hit\",\n send_webhooks=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.simulate(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n scenario: \"decline_aml_hit\",\n send_webhooks: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Simulate(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.SandboxSimulateRequest{\n\tScenario: didit.String(\"decline_aml_hit\"),\n\tSendWebhooks: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SandboxSimulateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().simulate(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", SandboxSimulateRequest.builder()\n .scenario(\"decline_aml_hit\")\n .sendWebhooks(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->simulate('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'scenario' => 'decline_aml_hit',\n 'send_webhooks' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.simulate(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n scenario: \"decline_aml_hit\",\n send_webhooks: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.SimulateAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new SandboxSimulateRequest\n{\n Scenario = \"decline_aml_hit\",\n SendWebhooks = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "simulate", "auth": "api_key", "server": true } } }, "/v3/session/{sessionId}/sandbox/simulate/": { "post": { "summary": "Simular o estado de uma sessão de sandbox a partir do cliente", "description": "A mesma simulação que `POST /v3/session/{sessionId}/simulate/`, autenticada com o próprio `Session-Token` da sessão (devolvido em `session_token` por [Create Session](/pt/sessions-api/create-session)) em vez da sua chave de API, para que um sistema de testes ou o fluxo alojado possa chamá-la a partir do cliente. O corpo, a resposta e `send_webhooks` comportam-se exatamente como nesse endpoint.\n\nUm `Session-Token` de uma aplicação de produção (não sandbox), ou um que não corresponda ao `sessionId` no caminho, devolve `404`. Consulte [Sandbox & Test Data](/pt/integration/sandbox-testing).", "operationId": "post_v3_session_sandbox_simulate", "tags": [ "Sessions" ], "security": [ { "SessionTokenAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação em sandbox. Deve coincidir com a sessão codificada no Session-Token utilizado para autenticar.", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateRequest" }, "examples": { "Scenario Without Webhooks": { "summary": "Recusar através de um cenário sem enviar webhooks", "value": { "scenario": "decline_aml_hit", "send_webhooks": false } }, "Status Only": { "summary": "Aprovar e enviar os webhooks habituais", "value": { "new_status": "Approved" } } } } } }, "responses": { "200": { "description": "O estado mudou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateResponse" }, "examples": { "Simulated": { "summary": "Recusada através de um cenário, webhooks não enviados", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "previous_status": "In Progress", "status": "Declined", "scenario": "decline_aml_hit", "risk": "POSSIBLE_MATCH_FOUND", "send_webhooks": false } } } } } }, "400": { "description": "Erro de validação: um cenário ou risco desconhecido, ausência de `new_status` quando nem `scenario` nem `risk` fornecem um, um estado que este endpoint não define ou a sessão já tem o estado solicitado (um array JSON simples).", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "o cenário não está no catálogo", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-scenario'." ] } }, "Unknown Risk": { "summary": "risk não se encontra no catálogo", "value": { "risk": [ "Unknown sandbox risk case: 'NOT_A_RISK'." ] } }, "Missing new_status": { "summary": "Sem new_status, scenario ou risk", "value": { "new_status": [ "This field is required." ] } }, "Invalid new_status": { "summary": "Um estado que a simulação não define", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Same Status": { "summary": "A sessão já tem este estado", "value": [ "The new status is the same as the current status." ] } } } } }, "403": { "description": "O cabeçalho `Session-Token` está em falta ou é inválido.", "content": { "application/json": { "examples": { "Invalid Session Token": { "summary": "Session-Token em falta ou inválido", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "O `Session-Token` pertence a uma aplicação de produção (não sandbox) ou não corresponde ao `sessionId` no caminho.", "content": { "application/json": { "examples": { "Not Found": { "summary": "Sessão ativa, ou discrepância entre session_id / token", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/sandbox/simulate/ \\\n -H 'Session-Token: YOUR_SESSION_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\"new_status\": \"Approved\", \"send_webhooks\": false}'" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/sandbox/simulate/\",\n headers={\"Session-Token\": \"YOUR_SESSION_TOKEN\"},\n json={\"new_status\": \"Approved\", \"send_webhooks\": False},\n)\nresponse.raise_for_status()\nprint(response.json())" } ], "x-didit-sdk": { "resource": "sessions", "method": "simulate_sandbox", "auth": "device_token", "server": false } } }, "/v3/session/{sessionId}/features/overrides/": { "get": { "summary": "Listar substituições das verificações de uma sessão", "description": "Cada anulação do estado de uma funcionalidade individual (passo) numa sessão de Verificação de utilizadores (KYC) ou Verificação de empresas (KYB), da mais recente para a mais antiga e não paginada: as aplicadas, as que aguardam que a pessoa termine o fluxo (`pending_until_flow_finishes`) e as canceladas, cada uma com quem a solicitou, o respetivo motivo e se foi aplicada enquanto a pessoa ainda estava no fluxo (`forced`).\n\n`person_in_flow` indica se uma nova anulação com `defer_until_flow_finishes: true` ficaria em espera. `flow_finished_at` é a data e hora em que a pessoa terminou o fluxo pela última vez; é `null` enquanto ainda estiver no fluxo (incluindo um novo envio) e quando a sessão tiver sido encerrada antes de terminar.\n\nRequer o privilégio `read:sessions`; uma chave de API com escopo necessita de acesso de leitura a decisões.", "operationId": "get_v3_session_feature_overrides", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "responses": { "200": { "description": "As substituições da verificação da sessão, da mais recente para a mais antiga.", "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "person_in_flow", "flow_finished_at", "overrides" ], "properties": { "session_id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "person_in_flow": { "type": "boolean", "description": "Se a pessoa ainda está no fluxo, pelo que uma nova substituição com `defer_until_flow_finishes: true` aguardaria.", "example": true }, "flow_finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a pessoa concluiu o fluxo pela última vez. `null` enquanto ainda estiver no mesmo (incluindo uma ressubmissão) e quando a sessão foi encerrada antes de terminar (abandonada, expirada ou quando foi tomada uma decisão a meio do fluxo).", "example": null }, "overrides": { "type": "array", "description": "Cada anulação da sessão, da mais recente para a mais antiga.", "items": { "$ref": "#/components/schemas/FeatureStatusOverride" } } } }, "examples": { "Overrides": { "summary": "Uma sobreposição pendente, uma aplicada", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "person_in_flow": true, "flow_finished_at": null, "overrides": [ { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "pending_until_flow_finishes", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": null, "cancel_reason": null }, { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "node_id": "feature_ocr_1", "feature_type": "", "feature_model": "KYC", "previous_status": "In Review", "new_status": "Approved", "state": "applied", "forced": true, "reason": "Document manually verified by compliance.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": "2026-10-13T09:15:00Z", "cancelled_at": null, "cancel_reason": null } ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chave de API com âmbito cuja data de validade já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenciais em falta, um chamador sem o privilégio `read:sessions`, uma chave de API com âmbito sem o acesso de que este endpoint necessita, ou um `session_id` que pertence a outra aplicação.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "O autor da chamada não tem read:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chave de API com âmbito sem este acesso", "value": { "detail": "This API key has no read access to decisions." } } } } } }, "404": { "description": "Não existe nenhuma sessão de KYC ou KYB com este `session_id`.", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id desconhecido", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/features/overrides/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_feature_overrides(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listFeatureOverrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListFeatureOverrides(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listFeatureOverrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listFeatureOverrides('3fa85f64-5717-4562-b3fc-2c963f66afa6');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_feature_overrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListFeatureOverridesAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "list_feature_overrides", "auth": "api_key", "server": true } } }, "/v3/session/{sessionId}/features/overrides/{overrideId}/cancel/": { "post": { "summary": "Cancelar uma sobreposição de verificação que aguarda que o fluxo termine", "description": "Cancela uma sobreposição do estado de uma funcionalidade (passo) que ainda esteja `pending_until_flow_finishes`, para que nunca seja aplicada. A verificação mantém o respetivo estado, o cancelamento é registado na atividade da sessão como `FEATURE_OVERRIDE_CANCELLED` e nenhum webhook é enviado. A resposta é a sobreposição com `state: cancelled` e `cancel_reason: cancelled_by_reviewer`.\n\nUma sobreposição que já tenha sido aplicada ou cancelada devolve `409` com o código `feature_override_not_pending`. Encontre os IDs das sobreposições com `GET /v3/session/{sessionId}/features/overrides/` ou no objeto `override` devolvido pela atualização de estado da funcionalidade.\n\nRequer o privilégio `write:sessions`; uma chave de API com âmbito restrito precisa de acesso de escrita a decisões.", "operationId": "post_v3_session_feature_override_cancel", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "in": "path", "name": "overrideId", "required": true, "description": "O `id` da substituição a cancelar.", "schema": { "type": "string", "format": "uuid", "example": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3" } } ], "responses": { "200": { "description": "A substituição foi cancelada e nunca será aplicada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureStatusOverride" }, "examples": { "Cancelled": { "summary": "A substituição cancelada", "value": { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "cancelled", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": "2026-10-13T09:20:00Z", "cancel_reason": "cancelled_by_reviewer" } } } } } }, "401": { "description": "A chave de API com âmbito expirou.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chave de API com âmbito cuja data de validade já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenciais em falta, um chamador sem o privilégio `write:sessions`, uma chave de API com âmbito sem o acesso de que este endpoint necessita, ou um `session_id` que pertence a outra aplicação.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "O autor da chamada não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chave de API com âmbito sem este acesso", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "Não existe nenhuma sessão de KYC ou KYB com este `session_id`, ou a sessão não tem nenhum override com este `overrideId`.", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id desconhecido", "value": { "detail": "Not found." } }, "Override Not Found": { "summary": "Nenhum override com este id na sessão", "value": { "detail": "Override not found." } } } } } }, "409": { "description": "A substituição já foi aplicada ou foi cancelada.", "content": { "application/json": { "examples": { "Not Pending": { "summary": "Apenas uma substituição em espera pode ser cancelada", "value": { "detail": "This override is no longer pending: it already applied or was cancelled.", "code": "feature_override_not_pending" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/features/overrides/9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3/cancel/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.cancel_feature_override(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.cancelFeatureOverride(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.CancelFeatureOverride(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().cancelFeatureOverride(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->cancelFeatureOverride('3fa85f64-5717-4562-b3fc-2c963f66afa6', '9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.cancel_feature_override(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CancelFeatureOverrideAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "cancel_feature_override", "auth": "api_key", "server": true } } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/add/": { "post": { "summary": "Adicionar uma etiqueta a uma rede", "description": "Coloca uma das etiquetas da sua aplicação na rede. Devolve os detalhes da rede, cuja propriedade `tags` lista as etiquetas da sua aplicação na rede, com `201` quando a etiqueta foi adicionada e `200` quando já se encontrava na rede. Uma etiqueta que pertença a outra aplicação, ou que não exista, devolve 404 `Tag not found.`. Requer uma chave de API de acesso total, ou `write:networks` para um membro da consola.", "operationId": "add_network_tag", "tags": [ "Networks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "description": "UUID da rede." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkTagRequest" }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/tags/add/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"tag_uuid\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.add_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid=\"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.addTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.AddTag(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.NetworkTagRequest{\n\tTagUUID: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.NetworkTagRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().addTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", NetworkTagRequest.builder()\n .tagUuid(\"7c9e6679-7425-40de-944b-e07fc1f90ae7\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->addTag('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'tag_uuid' => '7c9e6679-7425-40de-944b-e07fc1f90ae7',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.add_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.AddTagAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new NetworkTagRequest\n{\n TagUuid = \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "A etiqueta foi adicionada. Devolve os detalhes da rede.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "200": { "description": "A etiqueta já se encontrava na rede e foi mantida como estava. Devolve os detalhes da rede.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "400": { "description": "Corpo inválido: o `tag_uuid` está em falta ou não é um UUID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_uuid": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Missing tag_uuid": { "summary": "tag_uuid em falta", "value": { "tag_uuid": [ "This field is required." ] } }, "Invalid tag_uuid": { "summary": "tag_uuid inválido", "value": { "tag_uuid": [ "Must be a valid UUID." ] } } } } } }, "401": { "description": "Credenciais em falta ou inválidas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenciais em falta ou inválidas", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "A chave de API pertence a outra aplicação ou é uma chave com acesso restrito: os endpoints de Networks necessitam de uma chave de acesso total. Um token de membro da consola necessita de `write:networks`. Também é devolvido com `code: networks_not_entitled` quando o Networks não está ativado para a organização.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Redes não ativadas", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chave de API restrita", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Sem permissão", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não encontrado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Network not found": { "summary": "Rede não encontrada", "value": { "detail": "Network not found." } }, "Tag not found": { "summary": "Etiqueta não encontrada", "value": { "detail": "Tag not found." } } } } } } }, "x-didit-sdk": { "resource": "networks", "method": "add_tag", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/remove/": { "post": { "summary": "Remover uma etiqueta de uma rede", "description": "Remove uma das etiquetas da sua aplicação da rede. Devolve os detalhes da rede. 404 quando a etiqueta não estiver na rede ou não pertencer à sua aplicação. Requer uma chave de API com acesso total ou `write:networks` para um membro da consola.", "operationId": "remove_network_tag", "tags": [ "Networks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "description": "UUID da rede." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkTagRequest" }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/tags/remove/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"tag_uuid\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.remove_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid=\"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.removeTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RemoveTag(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.NetworkTagRequest{\n\tTagUUID: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.NetworkTagRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().removeTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", NetworkTagRequest.builder()\n .tagUuid(\"7c9e6679-7425-40de-944b-e07fc1f90ae7\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->removeTag('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'tag_uuid' => '7c9e6679-7425-40de-944b-e07fc1f90ae7',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.remove_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RemoveTagAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new NetworkTagRequest\n{\n TagUuid = \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A etiqueta foi removida da rede. Devolve os detalhes da rede.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "400": { "description": "Corpo inválido: o `tag_uuid` está em falta ou não é um UUID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_uuid": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Missing tag_uuid": { "summary": "tag_uuid em falta", "value": { "tag_uuid": [ "This field is required." ] } }, "Invalid tag_uuid": { "summary": "tag_uuid inválido", "value": { "tag_uuid": [ "Must be a valid UUID." ] } } } } } }, "401": { "description": "Credenciais em falta ou inválidas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenciais em falta ou inválidas", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "A chave de API pertence a outra aplicação ou é uma chave com acesso restrito: os endpoints de Networks necessitam de uma chave de acesso total. Um token de membro da consola necessita de `write:networks`. Também é devolvido com `code: networks_not_entitled` quando o Networks não está ativado para a organização.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Redes não ativadas", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chave de API restrita", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Sem permissão", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Não encontrado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente em erros codificados, por exemplo `networks_not_entitled`." } } }, "examples": { "Network not found": { "summary": "Rede não encontrada", "value": { "detail": "Network not found." } }, "Tag not found": { "summary": "Etiqueta não encontrada", "value": { "detail": "Tag not found." } }, "Tag not on the network": { "summary": "Etiqueta não presente na rede", "value": { "detail": "This tag is not on the network." } } } } } } }, "x-didit-sdk": { "resource": "networks", "method": "remove_tag", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/remind/": { "post": { "summary": "Lembrar o cliente de um pedido", "description": "Envie novamente o e-mail de um pedido pendente de cliente, para o mesmo destinatário verificado, com o mesmo conteúdo. Pode enviar um lembrete para um pedido no máximo uma vez a cada 24 horas. Um lembrete não altera mais nada: o pedido mantém o seu prazo limite e o caso mantém o seu estado. Cada lembrete é registado no caso como um evento CUSTOMER_REQUEST com a ação `reminded`. O `delivery_status` da resposta indica como terminou a entrega deste lembrete: SENT, SIMULATED (o e-mail não foi enviado) ou UNKNOWN (o e-mail pode ter sido aceite; não é enviado novamente de forma automática). `next_reminder_at` indica quando poderá enviar um novo lembrete para este pedido. Devolve 409 com um `reason` se o cliente já não tiver o pedido disponível para responder, e 429 com `retry_at` e um cabeçalho `Retry-After` se tiver sido enviado um lembrete para o pedido nas últimas 24 horas. Requer `write:cases`.", "operationId": "organization_application_cases_requests_remind_create", "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID da organização." }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID da aplicação." }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID do caso." }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID do pedido do cliente, a partir da lista de pedidos do caso." } ], "tags": [ "Case Management" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/requests/3fa85f64-5717-4562-b3fc-2c963f66afa6/remind/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Remind(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().remind(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->remind('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.RemindAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O lembrete foi registado e o respetivo e-mail enviado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "request", "reminded_at", "delivery_status", "next_reminder_at" ], "properties": { "request": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" }, "reminded_at": { "type": "string", "format": "date-time", "description": "Quando este lembrete foi registado." }, "delivery_status": { "type": "string", "enum": [ "SENT", "SIMULATED", "UNKNOWN" ], "description": "Como terminou a entrega deste lembrete. SIMULATED: o e-mail não foi enviado. UNKNOWN: o e-mail pode ter sido aceite; não é enviado novamente de forma automática." }, "next_reminder_at": { "type": "string", "format": "date-time", "description": "Quando pode enviar novamente um lembrete para este pedido: `reminded_at` mais 24 horas." } } }, "example": { "request": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "purpose": "confirm_details", "language": "en", "recipient": "customer@example.com", "expires_at": "2026-10-20T09:00:00Z", "actor_email": "reviewer@example.com", "delivery_status": "SENT", "delivered_at": "2026-10-13T09:00:04Z", "cancelled_at": null, "responded_at": null, "response": null, "has_attachment": false, "created_at": "2026-10-13T09:00:00Z" }, "reminded_at": "2026-10-14T10:30:00Z", "delivery_status": "SENT", "next_reminder_at": "2026-10-15T10:30:00Z" } } } }, "400": { "description": "O caso tem uma resolução pendente de aprovação. O corpo é uma lista de cadeias de caracteres.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Customer messages require an active case without a pending resolution." ] } } }, "403": { "description": "O chamador não possui a permissão de casos necessária." }, "404": { "description": "O pedido ou caso não está disponível para este chamador." }, "409": { "description": "O pedido já não está a aguardar o cliente, pelo que não há nada a lembrar. O campo `reason` indica o motivo: `answered` (o cliente respondeu), `cancelled`, `expired`, `closed` (o caso foi resolvido após o envio do pedido, mesmo que tenha sido reaberto entretanto), `not_actionable` (uma atualização de revisão em curso não solicita nada), `not_delivered` (o primeiro e-mail ainda não foi enviado) ou `contact_unavailable` (o e-mail verificado já não está disponível).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "case_request_not_waiting" ] }, "reason": { "type": "string", "enum": [ "answered", "cancelled", "expired", "closed", "not_actionable", "not_delivered", "contact_unavailable" ] } } }, "example": { "detail": "This request no longer waits on the customer, so there is nothing to remind them of.", "code": "case_request_not_waiting", "reason": "answered" } } } }, "429": { "description": "Já foi enviado um lembrete relativo ao pedido nas últimas 24 horas. `retry_at` e o cabeçalho `Retry-After` indicam quando pode voltar a enviar um lembrete.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de poder enviar novamente um lembrete para este pedido.", "schema": { "type": "integer", "minimum": 1, "example": 3600 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "case_request_reminder_too_soon" ] }, "retry_at": { "type": "string", "format": "date-time" } } }, "example": { "detail": "This request was already reminded in the last 24 hours.", "code": "case_request_reminder_too_soon", "retry_at": "2026-10-15T10:30:00Z" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "cases.requests", "method": "remind", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/session/{sessionId}/decision-email-preview/": { "post": { "summary": "Pré-visualizar o e-mail de decisão de uma sessão", "description": "Gere o e-mail que a pessoa recebe quando você define uma sessão como `Approved` ou `Declined` com `send_email: true`, sem alterar a sessão nem enviar nada. A resposta mostra o assunto e o HTML exatamente como são enviados, o destinatário, o remetente, o idioma e se a confirmação da alteração chega a enviar o e-mail (`will_be_sent`, `not_sent_reason`).\n\nO destinatário é o próprio endereço da pessoa: o endereço que a pessoa verificou num passo de verificação de e-mail do fluxo, ou então o fornecido em `contact_details` aquando da criação da sessão. O remetente é o domínio de remetente verificado da sua aplicação quando a marca branca se aplica (`sender_kind: customer`), caso contrário o remetente da Didit (`sender_kind: didit`).\n\nPara enviar exatamente o que pré-visualizou, chame [Update Session Status](/pt/sessions-api/update-status) com o mesmo `new_status`, `send_email: true`, `email_address` definido como `recipient`, `email_language` definido como `language` e `email_preview_token` definido como `preview_token`. O comprovativo expira após 15 minutos. Quando o destinatário, o idioma, o estado da sessão, o remetente ou o e-mail tiverem mudado desde a pré-visualização, a atualização devolve `409` antes de qualquer alteração; volte a pré-visualizar e confirme com o novo comprovativo.\n\nFunciona para sessões de Verificação de utilizadores (KYC) e Verificação de empresas (KYB) nos estados `Approved`, `Declined`, `In Review`, `Kyc Expired`, `Abandoned` ou `Resubmitted`. A verificação do estado é executada antes da validação do corpo. Requer o privilégio `write:sessions`; uma chave de API com âmbito precisa de acesso de escrita a decisões. As respostas utilizam `Cache-Control: no-store`: trate-as como conteúdo de verificação sensível.", "operationId": "post_v3_session_decision_email_preview", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID da sessão de verificação. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "A decisão cujo e-mail pretende pré-visualizar.", "example": "Approved" }, "email_language": { "type": "string", "default": "en", "description": "Idioma do e-mail, a mesma predefinição que Atualizar Estado da Sessão. Um idioma que não esteja disponível reverte para inglês; o campo `language` na resposta indica qual é utilizado.", "example": "en" } } }, "examples": { "Approved": { "summary": "Pré-visualizar o e-mail de aprovação em inglês", "value": { "new_status": "Approved" } }, "Declined in Spanish": { "summary": "Pré-visualizar o e-mail de recusa em espanhol", "value": { "new_status": "Declined", "email_language": "es" } } } } } }, "responses": { "200": { "description": "Apenas pré-visualização. A sessão permanece inalterada e nenhum e-mail é enviado.", "headers": { "Cache-Control": { "description": "Sempre `no-store`: a pré-visualização contém conteúdo de verificação e não deve ser guardada em cache.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "recipient_source", "sender", "sender_name", "sender_email", "sender_kind", "subject", "html", "text", "language", "will_be_sent", "not_sent_reason", "preview_token" ], "properties": { "recipient": { "type": "string", "description": "O endereço para o qual o e-mail é enviado. Uma string vazia quando não se conhece qualquer endereço para a pessoa: nesse caso, nenhum e-mail pode ser enviado e `preview_token` fica também vazio. Passe-o como `email_address` quando confirmar.", "example": "person@example.com" }, "recipient_source": { "type": "string", "enum": [ "email_verification", "contact_details", "" ], "description": "De onde provém `recipient`. `email_verification`: o endereço que a pessoa verificou num passo de verificação de e-mail do fluxo. `contact_details`: o endereço fornecido em `contact_details` aquando da criação da sessão. Uma string vazia quando não existir endereço.", "example": "email_verification" }, "sender": { "type": "string", "description": "O cabeçalho `From` com o qual o e-mail é enviado.", "example": "Example App " }, "sender_name": { "type": "string", "description": "A parte do nome de apresentação de `sender`.", "example": "Example App" }, "sender_email": { "type": "string", "format": "email", "description": "A parte da morada de `sender`.", "example": "no-reply@mail.example.com" }, "sender_kind": { "type": "string", "enum": [ "customer", "didit" ], "description": "`customer`: o e-mail sai a partir do domínio de remetente verificado da sua aplicação (marca branca). `didit`: sai a partir do remetente próprio da Didit.", "example": "customer" }, "subject": { "type": "string", "description": "A linha de assunto exatamente como é enviada.", "example": "Your verification has been approved in Example App" }, "html": { "type": "string", "description": "O HTML do e-mail exatamente como é enviado, com o respetivo logótipo incorporado como data URL. Renderize-o numa frame isolada (sandbox), nunca diretamente no DOM da sua aplicação.", "example": "..." }, "text": { "type": "string", "description": "O texto simples do e-mail, tal como o histórico de Mensagens da pessoa o guarda, para uma pré-visualização compacta (o HTML continua a ser o e-mail que a pessoa recebe).", "example": "Verification Approved\n\nYour identity has been successfully verified with Acme Pay. No further action is needed on your part." }, "language": { "type": "string", "description": "O idioma em que o e-mail está escrito. Inglês (`en`) quando o `email_language` solicitado não estiver disponível.", "example": "en" }, "will_be_sent": { "type": "boolean", "description": "Se confirmar a alteração com `send_email: true` envia este e-mail. `false` quando `not_sent_reason` estiver definido.", "example": true }, "not_sent_reason": { "type": "string", "nullable": true, "enum": [ "status_unchanged", "notification_emails_disabled", "no_recipient", "sandbox", null ], "description": "O motivo pelo qual a confirmação não enviaria nenhum e-mail, ou `null` quando será enviado. `status_unchanged`: a sessão já tem este estado, pelo que a atualização não altera nada nem envia nada. `notification_emails_disabled`: a sessão foi criada sem `contact_details.send_notification_emails: true`, pelo que nenhum e-mail de decisão é enviado para o endereço fornecido em `contact_details`. `no_recipient`: nenhum endereço é conhecido para a pessoa. `sandbox`: uma sessão de sandbox cujo destinatário não aceitou a entrega de e-mails em sandbox, pelo que o envio é apenas simulado.", "example": null }, "preview_token": { "type": "string", "description": "Recibo assinado para este e-mail exato, válido por 15 minutos. Passe-o como `email_preview_token` para [Atualizar estado da sessão](/pt/sessions-api/update-status). Uma string vazia quando não há destinatário.", "example": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } }, "examples": { "Will Be Sent": { "summary": "O e-mail de aprovação é enviado para o endereço verificado no fluxo", "value": { "recipient": "person@example.com", "recipient_source": "email_verification", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Your verification has been approved in Example App", "html": "...", "language": "en", "will_be_sent": true, "not_sent_reason": null, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } }, "No Recipient": { "summary": "Não se conhece nenhuma morada da pessoa", "value": { "recipient": "", "recipient_source": "", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Your verification has been declined in Example App", "html": "...", "language": "en", "will_be_sent": false, "not_sent_reason": "no_recipient", "preview_token": "" } } } } } }, "400": { "description": "A sessão não está num estado aceite por este endpoint (`{\"detail\": ...}`), ou o corpo é inválido (`{\"\": [\"\"]}`).", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "A sessão não está num estado aceite por este endpoint", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Invalid new_status": { "summary": "new_status não é Approved nem Declined", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Missing new_status": { "summary": "Campo obrigatório omitido", "value": { "new_status": [ "This field is required." ] } } } } } }, "401": { "description": "A chave de API com âmbito expirou.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chave de API com âmbito cuja data de validade já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenciais em falta, um chamador sem o privilégio `write:sessions`, uma chave de API com âmbito sem o acesso de que este endpoint necessita, ou um `session_id` que pertence a outra aplicação.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key em falta ou inválido", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "O autor da chamada não tem write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chave de API com âmbito sem este acesso", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "Não existe nenhuma sessão de KYC ou KYB com este `session_id`.", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id desconhecido", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"new_status\": \"Approved\", \"email_language\": \"en\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.preview_decision_email(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n new_status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.previewDecisionEmail(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n new_status: \"Approved\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.PreviewDecisionEmail(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.SessionsPreviewDecisionEmailParams{\n\tNewStatus: \"Approved\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsPreviewDecisionEmailParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().previewDecisionEmail(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", SessionsPreviewDecisionEmailParams.builder()\n .newStatus(SessionsPreviewDecisionEmailParams.NewStatus.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->previewDecisionEmail('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'new_status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.preview_decision_email(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n new_status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.PreviewDecisionEmailAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new SessionsPreviewDecisionEmailParams\n{\n NewStatus = \"Approved\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "preview_decision_email", "auth": "api_key", "server": true } } }, "/v3/travel-rule/join/{token}/": { "get": { "summary": "Obter um convite para adesão gratuita", "description": "Público, não autenticado. Mostra o convite a que uma ligação de adesão se refere enquanto estiver aberto: quem fez o pedido, o endereço para o qual foi enviado e os valores do diretório que serão pré-preenchidos. O token é a autenticação.", "operationId": "getTravelRuleJoinInvitation", "x-didit-sdk": { "resource": "travel_rule.join", "method": "get_invitation", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O token de convite a partir da ligação de adesão." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/join/{token}/" } ], "responses": { "200": { "description": "O convite.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinInvitation" } } } }, "404": { "description": "Nenhum convite tem esta ligação." }, "410": { "description": "O convite já não está em aberto: expirou, já foi utilizado ou foi revogado." } } }, "post": { "summary": "Registar uma conta gratuita de Travel Rule", "description": "Público, não autenticado. Cria uma conta Travel Rule gratuita para um VASP de contraparte que recebeu um pedido. O e-mail tem de ser o endereço para o qual o convite foi enviado. Um código de 6 carateres é enviado para o mesmo; envie-o para o endpoint de verificação para terminar. As tentativas de registo estão sujeitas a um limite de pedidos por endereço e por IP.", "operationId": "registerTravelRuleJoin", "x-didit-sdk": { "resource": "travel_rule.join", "method": "register", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O token de convite a partir da ligação de adesão." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinRegisterRequest" }, "example": { "email": "compliance@example.com", "password": "a-long-passphrase" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/join/{token}/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\": \"compliance@example.com\", \"password\": \"a-long-passphrase\"}'" } ], "responses": { "202": { "description": "A conta foi criada e foi enviado um código por e-mail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Indica à contraparte para verificar o seu e-mail para obter o código de verificação." }, "email": { "type": "string", "format": "email", "description": "O endereço para o qual o código foi enviado." } } } } } }, "400": { "description": "O e-mail não corresponde ao endereço convidado, ou a palavra-passe ou o endereço foram recusados." }, "404": { "description": "Nenhum convite tem esta ligação." }, "410": { "description": "O convite já não está em aberto: expirou, já foi utilizado ou foi revogado." }, "429": { "description": "Demasiadas tentativas de adesão. Os cabeçalhos `X-RateLimit-*` indicam o limite que foi consumido." } } } }, "/v3/travel-rule/join/{token}/verify/": { "post": { "summary": "Verificar uma conta Travel Rule gratuita", "description": "Público, não autenticado. Utiliza o código enviado por e-mail, cria a organização gratuita e responde com as credenciais que a sua aplicação utiliza nos endpoints da área de trabalho. A receção de dados da Travel Rule é gratuita.", "operationId": "verifyTravelRuleJoin", "x-didit-sdk": { "resource": "travel_rule.join", "method": "verify", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "O token de convite a partir da ligação de adesão." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinVerifyRequest" }, "example": { "email": "compliance@example.com", "code": "123456" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/join/{token}/verify/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\": \"compliance@example.com\", \"code\": \"123456\"}'" } ], "responses": { "201": { "description": "As credenciais da organização e da aplicação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinCredentials" } } } }, "400": { "description": "O código ou e-mail foi recusado." }, "404": { "description": "Nenhum convite tem esta ligação." }, "410": { "description": "O convite já não está em aberto: expirou, já foi utilizado ou foi revogado." }, "429": { "description": "Demasiadas tentativas de adesão. Os cabeçalhos `X-RateLimit-*` indicam o limite que foi consumido." } } } }, "/v3/travel-rule/workspace/": { "get": { "summary": "Obter a área de trabalho gratuita de Travel Rule", "description": "Consulta o espaço de trabalho gratuito de uma aplicação que aderiu gratuitamente: reivindicação de diretório, comprovação de domínio, faturação e listagem na rede Didit.", "operationId": "getTravelRuleWorkspace", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "get", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/workspace/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.get()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.get();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.Get(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().get();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->get();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.get\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.GetAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A área de trabalho.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "404": { "description": "Esta aplicação não aderiu de forma gratuita, pelo que não tem uma área de trabalho gratuita." } } } }, "/v3/travel-rule/workspace/claim/": { "post": { "summary": "Reivindicar uma entrada do diretório", "description": "Reivindica a entrada do diretório correspondente a este espaço de trabalho. Quando o e-mail profissional pertence a um domínio listado na entrada, a reivindicação é comprovada e aplica-se de imediato: o perfil do VASP e as definições da Travel Rule são preenchidos a partir da entrada e a Travel Rule é ativada, pelo que a transferência seguinte para essa entidade é encaminhada através da rede Didit. Caso contrário, a reivindicação aguarda revisão (`pending_review`).", "operationId": "claimTravelRuleWorkspace", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "claim", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceClaimRequest" }, "example": { "vasp_id": "0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/claim/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vasp_id\": \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.claim(\n vasp_id=\"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.claim({\n vasp_id: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.Claim(ctx, didit.TravelRuleWorkspaceClaimRequest{\n\tVASPID: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceClaimRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().claim(TravelRuleWorkspaceClaimRequest.builder()\n .vaspId(\"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->claim([\n 'vasp_id' => '0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.claim(vasp_id: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.ClaimAsync(new TravelRuleWorkspaceClaimRequest\n{\n VaspId = \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A área de trabalho com o respetivo estado da reivindicação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "Nenhuma entrada do diretório tem este id." }, "404": { "description": "Esta aplicação não aderiu de forma gratuita, pelo que não tem uma área de trabalho gratuita." } } } }, "/v3/travel-rule/workspace/domain/code/": { "post": { "summary": "Enviar por e-mail um código de verificação de domínio", "description": "Envia um código de utilização única por e-mail para o endereço de trabalho da área de trabalho a fim de comprovar o controlo sobre o domínio de e-mail. Sujeito a limitação de pedidos, sendo aceite um número limitado de tentativas incorretas por código. Também devolve o registo TXT para a alternativa por DNS.", "operationId": "sendTravelRuleWorkspaceDomainCode", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "send_domain_code", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/code/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.send_domain_code()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.sendDomainCode();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.SendDomainCode(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().sendDomainCode();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->sendDomainCode();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.send_domain_code\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.SendDomainCodeAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O domínio, o respetivo estado e o registo TXT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceDomainCodeResponse" } } } }, "404": { "description": "Esta aplicação não aderiu de forma gratuita, pelo que não tem uma área de trabalho gratuita." } } } }, "/v3/travel-rule/workspace/domain/confirm/": { "post": { "summary": "Confirmar o código de verificação de domínio", "description": "Consome o código enviado por e-mail e marca o domínio de e-mail como verificado.", "operationId": "confirmTravelRuleWorkspaceDomain", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "confirm_domain", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceDomainConfirmRequest" }, "example": { "code": "123456" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/confirm/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"code\": \"123456\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.confirm_domain(\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.confirmDomain({\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.ConfirmDomain(ctx, didit.TravelRuleWorkspaceDomainConfirmRequest{\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceDomainConfirmRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().confirmDomain(TravelRuleWorkspaceDomainConfirmRequest.builder()\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->confirmDomain([\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.confirm_domain(code: \"123456\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.ConfirmDomainAsync(new TravelRuleWorkspaceDomainConfirmRequest\n{\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A área de trabalho.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "O código está incorreto, expirado ou já foi utilizado." }, "404": { "description": "Esta aplicação não aderiu de forma gratuita, pelo que não tem uma área de trabalho gratuita." } } } }, "/v3/travel-rule/workspace/domain/dns/": { "post": { "summary": "Verifique o domínio a partir do seu registo TXT", "description": "Verifica o registo TXT `didit-tr-verify.` devolvido pelo endpoint de código e marca o domínio como verificado quando coincide. Uma das duas provas, o código enviado por e-mail ou o registo TXT, é suficiente.", "operationId": "verifyTravelRuleWorkspaceDomainDns", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "verify_domain_dns", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/dns/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.verify_domain_dns()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.verifyDomainDns();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.VerifyDomainDNS(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().verifyDomainDns();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->verifyDomainDns();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.verify_domain_dns\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.VerifyDomainDnsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A área de trabalho.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "O registo TXT não foi encontrado ou não corresponde." }, "404": { "description": "Esta aplicação não aderiu de forma gratuita, pelo que não tem uma área de trabalho gratuita." } } } }, "/v3/travel-rule/workspace/billing/": { "post": { "summary": "Ativar a faturação de saída", "description": "Ativa a faturação de saídas da Travel Rule para o espaço de trabalho. A receção permanece gratuita. Esta ação não pode ser revertida através da API: contacte o suporte da Didit.", "operationId": "enableTravelRuleWorkspaceBilling", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "enable_billing", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceBillingRequest" }, "example": { "enabled": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/billing/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"enabled\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.enable_billing(\n enabled=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.enableBilling({\n enabled: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.EnableBilling(ctx, didit.TravelRuleWorkspaceBillingRequest{\n\tEnabled: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceBillingRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().enableBilling(TravelRuleWorkspaceBillingRequest.builder()\n .enabled(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->enableBilling([\n 'enabled' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.enable_billing(enabled: true)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.EnableBillingAsync(new TravelRuleWorkspaceBillingRequest\n{\n Enabled = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A área de trabalho com `billing_enabled` definido como verdadeiro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "`enabled` era false." }, "404": { "description": "Esta aplicação não aderiu de forma gratuita, pelo que não tem uma área de trabalho gratuita." } } } }, "/v3/investigator/summary/": { "get": { "operationId": "investigator_summary", "summary": "Resumo do investigador", "description": "Etapa, contagens de filas, relatórios preparados e decididos hoje, concordância de 30 dias, preços e o nível de autonomia de cada fila. As chaves restritas necessitam do âmbito `decisions` (leitura); os alertas de transações também necessitam de `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "stage": { "type": "string" }, "last_report_at": { "type": "string", "format": "date-time", "nullable": true }, "prepared_today": { "type": "integer" }, "ready_to_accept": { "type": "integer" }, "open": { "type": "integer" }, "decided_today": { "type": "integer" }, "automation_rate_month": { "type": "number", "nullable": true }, "preparing": { "type": "integer" } } } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessões e casos não abertos por uma regra de transação) ou `transactions` (alertas de transação e casos que uma regra de transação abriu)." }, { "in": "query", "name": "timezone", "schema": { "type": "string" }, "description": "Fuso horário IANA (por exemplo `Europe/Madrid`) a partir do qual \"hoje\" é contabilizado. UTC por predefinição." } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_summary", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_summary()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveSummary();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveSummary(ctx, didit.InvestigatorRetrieveSummaryParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveSummary();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveSummary();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_summary\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveSummaryAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/queue/": { "get": { "operationId": "investigator_queue", "summary": "Listar a fila do Investigator", "description": "Relatórios abertos, **Pronto a aceitar** primeiro, depois por prazo, risco e espera. `counts` abrange todos os tipos no âmbito. `count` está limitado a 100. Chaves restritas necessitam do âmbito `decisions` (leitura); alertas de transações também necessitam de `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "counts": { "type": "object", "additionalProperties": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/InvestigatorQueueRow" } } } } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessões e casos não abertos por uma regra de transação) ou `transactions` (alertas de transação e casos que uma regra de transação abriu)." }, { "in": "query", "name": "kind", "schema": { "type": "string" }, "description": "`session`, `business_session`, `transaction` ou `case`, ou vários separados por vírgulas." }, { "in": "query", "name": "queue", "schema": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] } }, { "in": "query", "name": "recommendation", "schema": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] } }, { "in": "query", "name": "confidence", "schema": { "type": "string", "enum": [ "high", "moderate", "low" ] } }, { "in": "query", "name": "ready", "schema": { "type": "boolean" } }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Nome, empresa, título do caso, número, ID da transação ou ID do item." }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "x-didit-sdk": { "resource": "investigator", "method": "list_queue", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.investigator.list_queue():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.investigator.listQueue()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Investigator.ListQueueAutoPaging(ctx, didit.InvestigatorListQueueParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.investigator().listQueue()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "investigator->listQueue() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.investigator.list_queue.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Investigator.ListQueueAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/investigator/runs/{run_id}/": { "get": { "operationId": "investigator_run_retrieve", "summary": "Obter relatório do Investigator", "description": "O relatório completo de uma execução. 404 quando a execução não tem um relatório concluído ou o respetivo item foi eliminado. As chaves restritas necessitam do âmbito `decisions` (leitura); os alertas de transação também necessitam de `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorRunDetail" } } } }, "404": { "description": "Não encontrado ou sem relatório." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_run(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveRun(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveRun(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveRun(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveRun('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_run(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveRunAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/{run_id}/accept/": { "post": { "operationId": "investigator_run_accept", "summary": "Aceitar uma recomendação", "description": "Aplica a ação recomendada através do caminho normal do item, pelo que os seus webhooks habituais são acionados. Uma `narrative` faz com que seja editada e aceite. Chaves restritas necessitam do âmbito `decisions` (escrita); alertas de transações também necessitam de `transactions` (escrita). O escalonamento de uma verificação ou transação abre um caso.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorDecision" } } } }, "409": { "description": "Já decidido, relatório não pronto ou uma barreira de segurança retém o item." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorAcceptRequest" }, "example": { "send_email": false } } } }, "x-didit-sdk": { "resource": "investigator", "method": "accept_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.accept_run(\n \"11111111-2222-3333-4444-555555555555\",\n send_email=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.acceptRun(\"11111111-2222-3333-4444-555555555555\", {\n send_email: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.AcceptRun(ctx, \"11111111-2222-3333-4444-555555555555\", didit.InvestigatorAcceptRequest{\n\tSendEmail: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorAcceptRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().acceptRun(\"11111111-2222-3333-4444-555555555555\", InvestigatorAcceptRequest.builder()\n .sendEmail(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->acceptRun('11111111-2222-3333-4444-555555555555', [\n 'send_email' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.accept_run(\n \"11111111-2222-3333-4444-555555555555\",\n send_email: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.AcceptRunAsync(\"11111111-2222-3333-4444-555555555555\", new InvestigatorAcceptRequest\n{\n SendEmail = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/{run_id}/override/": { "post": { "operationId": "investigator_run_override", "summary": "Substituir uma recomendação", "description": "Executa outra ação com uma categoria e um motivo. Também substitui uma decisão que o Investigador tenha tomado por si próprio enquanto esta ainda vigorar. As chaves restritas necessitam do âmbito `decisions` (escrita); os alertas de transação também necessitam de `transactions` (escrita). Escalar uma verificação ou transação abre um caso.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorDecision" } } } }, "409": { "description": "Já decidido, ou uma barreira de segurança retém o item." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorOverrideRequest" }, "example": { "action": "decline", "category": "evidence_misread", "reason": "The proof of address is older than three months." } } } }, "x-didit-sdk": { "resource": "investigator", "method": "override_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.override_run(\n \"11111111-2222-3333-4444-555555555555\",\n action=\"decline\",\n category=\"evidence_misread\",\n reason=\"The proof of address is older than three months.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.overrideRun(\"11111111-2222-3333-4444-555555555555\", {\n action: \"decline\",\n category: \"evidence_misread\",\n reason: \"The proof of address is older than three months.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.OverrideRun(ctx, \"11111111-2222-3333-4444-555555555555\", didit.InvestigatorOverrideRequest{\n\tAction: \"decline\",\n\tCategory: \"evidence_misread\",\n\tReason: \"The proof of address is older than three months.\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorOverrideRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().overrideRun(\"11111111-2222-3333-4444-555555555555\", InvestigatorOverrideRequest.builder()\n .action(InvestigatorOverrideRequest.Action.of(\"decline\"))\n .category(InvestigatorOverrideRequest.Category.of(\"evidence_misread\"))\n .reason(\"The proof of address is older than three months.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->overrideRun('11111111-2222-3333-4444-555555555555', [\n 'action' => 'decline',\n 'category' => 'evidence_misread',\n 'reason' => 'The proof of address is older than three months.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.override_run(\n \"11111111-2222-3333-4444-555555555555\",\n action: \"decline\",\n category: \"evidence_misread\",\n reason: \"The proof of address is older than three months.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.OverrideRunAsync(\"11111111-2222-3333-4444-555555555555\", new InvestigatorOverrideRequest\n{\n Action = \"decline\",\n Category = \"evidence_misread\",\n Reason = \"The proof of address is older than three months.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/batch-accept/": { "post": { "operationId": "investigator_batch_accept", "summary": "Aceitar recomendações em lote", "description": "Aceita até 50 relatórios marcados como Prontos para aceitar. Cada um é a sua própria decisão: aquele que não puder ser aceite é ignorado juntamente com o respetivo motivo. Chaves restritas necessitam do âmbito `decisions` (escrita); alertas de transações também necessitam de `transactions` (escrita). Escalar uma verificação ou transação abre um caso.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorBatchAcceptResponse" } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorBatchAcceptRequest" } } } }, "x-didit-sdk": { "resource": "investigator", "method": "batch_accept_runs", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.batch_accept_runs(\n run_ids=[\"11111111-2222-3333-4444-555555555555\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.batchAcceptRuns({\n run_ids: [\"11111111-2222-3333-4444-555555555555\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.BatchAcceptRuns(ctx, didit.InvestigatorBatchAcceptRequest{\n\tRunIDs: []string{\"11111111-2222-3333-4444-555555555555\"},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.InvestigatorBatchAcceptRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().batchAcceptRuns(InvestigatorBatchAcceptRequest.builder()\n .runIds(List.of(\"11111111-2222-3333-4444-555555555555\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->batchAcceptRuns([\n 'run_ids' => ['11111111-2222-3333-4444-555555555555'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.batch_accept_runs(run_ids: [\"11111111-2222-3333-4444-555555555555\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.BatchAcceptRunsAsync(new InvestigatorBatchAcceptRequest\n{\n RunIds = new string[] { \"11111111-2222-3333-4444-555555555555\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/transactions/{transaction_id}/": { "get": { "operationId": "investigator_transaction_retrieve", "summary": "Obter revisão do Investigator de uma transação", "description": "A revisão mais recente da transação, ou `investigator: null` caso nunca tenha tido uma. Chaves restritas necessitam dos âmbitos `decisions` e `transactions` (leitura).", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "investigator": { "$ref": "#/components/schemas/InvestigatorBlock" } } } } } }, "404": { "description": "Não é a transação desta aplicação." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "path", "name": "transaction_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_transaction", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_transaction(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveTransaction(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveTransaction(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveTransaction(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveTransaction('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_transaction(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveTransactionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/guardrails/": { "get": { "operationId": "investigator_guardrails", "summary": "Listar as barreiras de proteção bloqueadas", "description": "As cinco salvaguardas que se aplicam a todas as filas. Não podem ser desativadas. As chaves restritas necessitam do âmbito `decisions` (leitura); os alertas de transação também necessitam de `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "sanctions_to_person", "no_tipping_off", "no_protected_characteristics", "never_files_reports", "every_decision_logged" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "locked": { "type": "boolean" } } } } } } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "x-didit-sdk": { "resource": "investigator", "method": "list_guardrails", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.list_guardrails()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.listGuardrails();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.ListGuardrails(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().listGuardrails();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->listGuardrails();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.list_guardrails\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.ListGuardrailsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/dashboard/": { "get": { "operationId": "investigator_dashboard", "summary": "Painel do investigador", "description": "Os últimos 30 dias: revisões, decisões, taxa de automatização, horas poupadas, despesas, substituições, amostras de qualidade desde a entrada em produção, valores por fila e semanais. Chaves com restrições requerem o âmbito `decisions` (leitura); alertas de transações também requerem `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "stage": { "type": "string" }, "window_days": { "type": "integer" }, "reviews": { "type": "integer" }, "decided": { "type": "integer" }, "automated": { "type": "integer" }, "automation_rate": { "type": "number", "nullable": true }, "hours_saved": { "type": "number", "nullable": true } } } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessões e casos não abertos por uma regra de transação) ou `transactions` (alertas de transação e casos que uma regra de transação abriu)." } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_dashboard", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_dashboard()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveDashboard();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveDashboard(ctx, didit.InvestigatorRetrieveDashboardParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveDashboard();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveDashboard();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_dashboard\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveDashboardAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/performance/": { "get": { "operationId": "investigator_performance", "summary": "Desempenho do investigador", "description": "Concordância com a sua equipa, volume, tempo poupado, calibração de confiança, resultados por fila, motivos de substituição e desacordos para um período. Chaves restritas necessitam do âmbito `decisions` (leitura); alertas de transações também necessitam de `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "period": { "type": "integer" }, "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" }, "investigated": { "type": "integer" } } } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessões e casos não abertos por uma regra de transação) ou `transactions` (alertas de transação e casos que uma regra de transação abriu)." }, { "in": "query", "name": "period", "schema": { "type": "string", "enum": [ "7", "30", "90" ], "default": "30" }, "description": "Dias, terminando hoje." } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_performance", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_performance()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrievePerformance();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrievePerformance(ctx, didit.InvestigatorRetrievePerformanceParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrievePerformance();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrievePerformance();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_performance\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrievePerformanceAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/activity/": { "get": { "operationId": "investigator_activity", "summary": "Listar atividade do Investigator", "description": "O registo de auditoria apenas para anexar, do mais recente para o mais antigo. Uma aceitação em lote constitui uma entrada. Adiciona `counts` por grupo e `actors`. Chaves restritas necessitam do âmbito `decisions` (leitura); alertas de transações também necessitam de `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "counts": { "type": "object", "additionalProperties": true }, "actors": { "type": "array", "items": {} }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "`id`, `at`, `kind`, `group`, `queue`, `run_id`, `item`, `actor`, `agent_version`, `data`, `report_version`, `steps`, `sources`, `batch`." } } } } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessões e casos não abertos por uma regra de transação) ou `transactions` (alertas de transação e casos que uma regra de transação abriu)." }, { "in": "query", "name": "group", "schema": { "type": "string", "enum": [ "agent", "decisions", "overrides", "autonomy" ] } }, { "in": "query", "name": "actor", "schema": { "type": "string" }, "description": "`agent` para o Investigator, ou o e-mail de uma pessoa." }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "until", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "x-didit-sdk": { "resource": "investigator", "method": "list_activity", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.investigator.list_activity():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.investigator.listActivity()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Investigator.ListActivityAutoPaging(ctx, didit.InvestigatorListActivityParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.investigator().listActivity()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "investigator->listActivity() as $item) {\n print_r($item);\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.investigator.list_activity.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Investigator.ListActivityAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/investigator/activity/export/": { "get": { "operationId": "investigator_activity_export", "summary": "Exportar atividade do Investigador", "description": "As mesmas entradas em formato CSV, uma linha por decisão, da mais recente para a mais antiga, até 10,000 entradas. As chaves restritas necessitam do âmbito `decisions` (leitura); os alertas de transação também necessitam de `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessões e casos não abertos por uma regra de transação) ou `transactions` (alertas de transação e casos que uma regra de transação abriu)." }, { "in": "query", "name": "group", "schema": { "type": "string", "enum": [ "agent", "decisions", "overrides", "autonomy" ] } }, { "in": "query", "name": "actor", "schema": { "type": "string" }, "description": "`agent` para o Investigator, ou o e-mail de uma pessoa." }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "until", "schema": { "type": "string", "format": "date-time" } } ], "x-didit-sdk": { "resource": "investigator", "method": "export_activity", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.investigator.export_activity()\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.investigator.exportActivity();\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Investigator.ExportActivity(ctx, didit.InvestigatorExportActivityParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.investigator().exportActivity()\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "investigator->exportActivity();\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.investigator.export_activity\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Investigator.ExportActivityAsync();\nawait content.SaveToAsync(\"download.csv\");" } ] } }, "/v3/investigator/settings/": { "get": { "operationId": "investigator_settings_retrieve", "summary": "Obter definições do Investigator", "description": "A fase (`none`, `shadow` ou `live`) e o limite de gastos mensal com os gastos deste mês. As chaves restritas necessitam do âmbito `applications` (leitura).", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "x-didit-sdk": { "resource": "investigator", "method": "retrieve_settings", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_settings()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveSettings();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveSettings(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveSettings();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveSettings();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_settings\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveSettingsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "operationId": "investigator_settings_update", "summary": "Atualizar definições do Investigator", "description": "Alterar a fase, o limite de gastos mensal ou ambos. Passar de `none` requer um plano que inclua o Investigator (Growth ou superior); `live` também requer um contrato que defina o respetivo preço, caso tenha um. As chaves restritas necessitam do âmbito `applications` (escrita).", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" } } } }, "400": { "description": "Nenhum dos campos foi enviado, ou valor inválido." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "A chave não tem o âmbito necessário, o tipo de item não pode ser lido ou o plano não inclui o Investigador." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" }, "example": { "stage": "shadow", "monthly_spend_limit": "500.00" } } } }, "x-didit-sdk": { "resource": "investigator", "method": "update_settings", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.update_settings(\n stage=\"shadow\",\n monthly_spend_limit=\"500.00\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.updateSettings({\n stage: \"shadow\",\n monthly_spend_limit: \"500.00\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.UpdateSettings(ctx, didit.InvestigatorSettingsParam{\n\tStage: didit.Some(didit.InvestigatorSettingsStage(\"shadow\")),\n\tMonthlySpendLimit: didit.String(\"500.00\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorSettings;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().updateSettings(InvestigatorSettings.builder()\n .stage(InvestigatorSettings.Stage.of(\"shadow\"))\n .monthlySpendLimit(\"500.00\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->updateSettings([\n 'stage' => 'shadow',\n 'monthly_spend_limit' => '500.00',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.update_settings(\n stage: \"shadow\",\n monthly_spend_limit: \"500.00\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.UpdateSettingsAsync(new InvestigatorSettings\n{\n Stage = new InvestigatorSettingsStage(\"shadow\"),\n MonthlySpendLimit = \"500.00\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/travel-rule/wallet-addresses/import/": { "post": { "summary": "Importar endereços de carteira em massa", "description": "Adicione até 10 000 carteiras ao seu livro de endereços da Travel Rule numa única chamada, como JSON ou como ficheiro CSV. Uma carteira pode ser enviada pelo seu endereço, pelo SHA-256 do seu endereço em minúsculas (`address_hash`) para manter o endereço privado, ou por ambos. A importação é idempotente: uma carteira que já esteja no livro é reportada como `existing` e não é modificada, pelo que o mesmo ficheiro pode ser enviado novamente. Cada linha é validada individualmente, pelo que uma linha inválida nunca faz falhar as outras. Uma carteira importada pelo respetivo hash só corresponde a transferências para esse endereço e pode ser comprovada com o widget de propriedade da carteira tal como qualquer outra entrada.", "operationId": "importTravelRuleWalletAddresses", "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "bulk_import", "auth": "api_key", "server": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/WalletAddressImportRow" } } } }, { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/WalletAddressImportRow" } } ] }, "example": { "entries": [ { "address": "0xBeneficiaryWallet01", "chain": "ETH", "holder_name": "Ana Diaz", "holder_vendor_data": "user-042" }, { "address_hash": "4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e", "chain": "bitcoin", "holder_vendor_data": "user-043" }, { "address": "rExchangeSharedAddress01", "chain": "XRP", "memo": "104729", "holder_name": "Ana Diaz" } ] } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Um ficheiro CSV UTF-8 de no máximo 5 MB com uma linha de cabeçalho que identifica as suas colunas (os campos de linha ou os respetivos aliases). As células vazias contam como não enviadas; as colunas que a importação não lê são ignoradas." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl (JSON)", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/import/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"entries\": [{\"address\": \"0xBeneficiaryWallet01\", \"chain\": \"ETH\", \"holder_name\": \"Ana Diaz\"}, {\"address\": \"rExchangeSharedAddress01\", \"chain\": \"XRP\", \"memo\": \"104729\"}]}'" }, { "lang": "curl", "label": "curl (CSV)", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/import/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@wallets.csv;type=text/csv'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.bulk_import(\n body={\n \"entries\": [{\n \"address\": \"0xBeneficiaryWallet01\",\n \"chain\": \"ETH\",\n \"holder_name\": \"Ana Diaz\",\n \"holder_vendor_data\": \"user-042\",\n }, {\n \"address_hash\": \"4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e\",\n \"chain\": \"bitcoin\",\n \"holder_vendor_data\": \"user-043\",\n }, {\n \"address\": \"rExchangeSharedAddress01\",\n \"chain\": \"XRP\",\n \"memo\": \"104729\",\n \"holder_name\": \"Ana Diaz\",\n }],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.bulkImport({\n file: await fileFromPath(\"wallet-addresses.csv\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.BulkImport(ctx, didit.TravelRuleWalletAddressesBulkImportParams{\n\tFile: didit.Some(didit.FileFromPath(\"wallet-addresses.csv\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleWalletAddressesBulkImportParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().bulkImport(TravelRuleWalletAddressesBulkImportParams.builder()\n .file(Path.of(\"wallet-addresses.csv\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->bulkImport([\n 'file' => File::fromPath('wallet-addresses.csv'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.bulk_import(\n body: {\n entries: [{\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_name: \"Ana Diaz\",\n holder_vendor_data: \"user-042\",\n }, {\n address_hash: \"4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e\",\n chain: \"bitcoin\",\n holder_vendor_data: \"user-043\",\n }, {\n address: \"rExchangeSharedAddress01\",\n chain: \"XRP\",\n memo: \"104729\",\n holder_name: \"Ana Diaz\",\n }],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.BulkImportAsync(new TravelRuleWalletAddressesBulkImportParams\n{\n File = FileUpload.FromPath(\"wallet-addresses.csv\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Cada linha foi criada, já se encontrava no registo ou era uma repetição de uma linha anterior.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressImportReport" }, "example": { "total": 3, "created": 2, "existing": 1, "duplicate": 0, "failed": 0, "rows": [ { "row": 1, "status": "existing", "entry_id": "11111111-2222-3333-4444-555555555555", "errors": {}, "duplicate_of_row": null }, { "row": 2, "status": "created", "entry_id": "22222222-3333-4444-5555-666666666666", "errors": {}, "duplicate_of_row": null }, { "row": 3, "status": "created", "entry_id": "33333333-4444-5555-6666-777777777777", "errors": {}, "duplicate_of_row": null } ] } } } }, "207": { "description": "Pelo menos uma linha falhou; as outras foram importadas. Cada linha com falha indica os seus erros.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressImportReport" }, "example": { "total": 2, "created": 1, "existing": 0, "duplicate": 0, "failed": 1, "rows": [ { "row": 1, "status": "created", "entry_id": "44444444-5555-6666-7777-888888888888", "errors": {}, "duplicate_of_row": null }, { "row": 2, "status": "failed", "entry_id": null, "errors": { "address": [ "Send address, address_hash or both." ] }, "duplicate_of_row": null } ] } } } }, "400": { "description": "O pedido em si não pode ser lido: foram fornecidos em simultâneo `entries` e um `file`, ou nenhum deles; mais de 10,000 linhas; um ficheiro com mais de 5 MB, que não seja CSV em UTF-8, sem linha de cabeçalho ou sem linhas.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "file": [ "At most 10000 rows per import." ] } } } } } } }, "/v3/travel-rule/counterparty-contacts/": { "get": { "summary": "Listar contactos da contraparte", "description": "Os endereços de conformidade aos quais a via EMAIL pode enviar mensagens para a sua aplicação: os contactos da plataforma Didit mais os contactos privados da sua própria aplicação, incluindo os que foram devolvidos, dos mais recentes para os mais antigos. Paginado com `limit` (por omissão 50) e `offset`; `count` para em 100, pelo que 100 significa 100 ou mais.", "operationId": "listTravelRuleCounterpartyContacts", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "counterparty", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Apenas os contactos desta entrada de diretório. Tem de ser um UUID; um valor vazio significa ausência de filtro." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Tamanho da página, predefinição 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Linhas a ignorar." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/counterparty-contacts/?counterparty={vasp_id}' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.counterparty_contacts.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.counterpartyContacts.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.CounterpartyContacts.ListAutoPaging(ctx, didit.TravelRuleCounterpartyContactsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().counterpartyContacts().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.counterparty_contacts.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.CounterpartyContacts.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Os contactos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyContact" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "counterparty_name": "Example Counterparty VASP", "email": "compliance@counterparty.example", "name": "Compliance desk", "source": "application", "scope": "application", "created_by": "", "verified_at": null, "is_invalid": false, "invalid_reason": "", "invalid_detail": "", "invalid_at": null, "created_at": "2026-10-19T09:00:00Z" } ] } } } }, "400": { "description": "`counterparty` não é um UUID.", "content": { "application/json": { "example": { "counterparty": [ "Must be a valid UUID." ] } } } } } }, "post": { "summary": "Adicionar um contacto da contraparte", "description": "Adiciona um endereço de conformidade privado a uma entrada do diretório. Apenas a sua aplicação o vê e utiliza, e o canal EMAIL escreve para ele antes de qualquer contacto da plataforma. Adicionar um endereço que a entrada já possui nos seus próprios contactos devolve esse contacto.", "operationId": "createTravelRuleCounterpartyContact", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyContactCreate" }, "example": { "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "email": "compliance@counterparty.example", "name": "Compliance desk" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/counterparty-contacts/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"counterparty\": \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\", \"email\": \"compliance@counterparty.example\", \"name\": \"Compliance desk\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.counterparty_contacts.create(\n counterparty=\"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email=\"compliance@counterparty.example\",\n name=\"Compliance desk\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.counterpartyContacts.create({\n counterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email: \"compliance@counterparty.example\",\n name: \"Compliance desk\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.CounterpartyContacts.Create(ctx, didit.TravelRuleCounterpartyContactCreate{\n\tCounterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n\tEmail: \"compliance@counterparty.example\",\n\tName: didit.String(\"Compliance desk\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyContactCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().counterpartyContacts().create(TravelRuleCounterpartyContactCreate.builder()\n .counterparty(\"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\")\n .email(\"compliance@counterparty.example\")\n .name(\"Compliance desk\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->create([\n 'counterparty' => '0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91',\n 'email' => 'compliance@counterparty.example',\n 'name' => 'Compliance desk',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.counterparty_contacts.create(\n counterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email: \"compliance@counterparty.example\",\n name: \"Compliance desk\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.CounterpartyContacts.CreateAsync(new TravelRuleCounterpartyContactCreate\n{\n Counterparty = \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n Email = \"compliance@counterparty.example\",\n Name = \"Compliance desk\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "O contacto foi adicionado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyContact" }, "example": { "uuid": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "counterparty_name": "Example Counterparty VASP", "email": "compliance@counterparty.example", "name": "Compliance desk", "source": "application", "scope": "application", "created_by": "", "verified_at": null, "is_invalid": false, "invalid_reason": "", "invalid_detail": "", "invalid_at": null, "created_at": "2026-10-19T09:00:00Z" } } } }, "400": { "description": "Um campo está em falta ou é inválido, ou nenhuma entrada do diretório tem este id.", "content": { "application/json": { "example": { "counterparty": [ "No directory entry with this id." ] } } } } } } }, "/v3/travel-rule/counterparty-contacts/{contact_uuid}/": { "delete": { "summary": "Eliminar um contacto de contraparte", "description": "Elimina um dos contactos próprios da sua aplicação. O canal EMAIL deixa imediatamente de escrever no mesmo. Os contactos da plataforma não podem ser eliminados.", "operationId": "deleteTravelRuleCounterpartyContact", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "contact_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/counterparty-contacts/{contact_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.travel_rule.counterparty_contacts.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.travelRule.counterpartyContacts.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.TravelRule.CounterpartyContacts.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.travelRule().counterpartyContacts().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.counterparty_contacts.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.TravelRule.CounterpartyContacts.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "Eliminado." }, "404": { "description": "Nenhum contacto da sua aplicação tem este id. Um contacto da plataforma também responde 404." } } } }, "/v3/travel-rule/transfers/": { "get": { "summary": "Listar transferências de Travel Rule", "description": "As transferências de Travel Rule da sua aplicação, as mais recentes primeiro, paginadas com `limit` (predefinição 50) e `offset`. As linhas contêm apenas nomes de VASPs, carteiras e memos, nunca dados pessoais. Valores separados por vírgulas selecionam vários. Um valor desconhecido responde 400 indicando o parâmetro, por exemplo `{\"direction\": [\"Unknown value(s): inbound.\"]}`.", "operationId": "listTravelRuleTransfers", "x-didit-sdk": { "resource": "travel_rule.transfers", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "INBOUND, OUTBOUND, ou ambos separados por vírgula. Sensível a maiúsculas e minúsculas." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Um ou mais estados de transferência, separados por vírgulas." }, { "name": "rail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Um ou mais de INTERNAL, TRP, GTR, TRUST, VERIFYVASP, SYGNA, EMAIL, TEST_VASP, separados por vírgulas." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "withdrawal, deposit ou message, separados por vírgulas." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A moeda da transação, sem distinção entre maiúsculas e minúsculas." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Transferências criadas neste dia ou após o mesmo (UTC), AAAA-MM-DD." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Transferências criadas neste dia ou antes do mesmo (UTC), AAAA-MM-DD." }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "O `id` de uma entrada do diretório ou membro da rede Didit a partir de GET /v3/travel-rule/vasps/: as suas transferências com essa contraparte. Um valor que não seja um id válido responde com 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Tamanho da página, predefinição 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Linhas a ignorar." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/transfers/?direction=OUTBOUND&status=AWAITING_COUNTERPARTY' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.transfers.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.transfers.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.Transfers.ListAutoPaging(ctx, didit.TravelRuleTransfersListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().transfers().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->transfers->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.transfers.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.Transfers.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Uma página de transferências.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "id": "5b0f6c2e-2a4d-4f0e-9a41-0c3f9a7e1d22", "transaction_id": "a3c1e8f4-7b62-4d1a-8e0b-2f9d6c4b7a10", "txn_id": "wd-2026-10-19-0042", "txn_date": "2026-10-19T08:41:12Z", "kind": "withdrawal", "direction": "OUTBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Origin CASP SL", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": "2026-10-21T08:41:13Z", "created_at": "2026-10-19T08:41:13Z" } ] } } } }, "400": { "description": "Um valor de filtro não é válido.", "content": { "application/json": { "example": { "start_date": [ "Use the YYYY-MM-DD format." ] } } } } } } }, "/v3/session/imports/providers/": { "get": { "summary": "Listar prestadores de migração", "description": "Os 15 fornecedores a partir dos quais pode migrar verificações: o que cada um necessita para a ligação, se a respetiva API permite listar registos, as permissões de que a respetiva chave necessita e o respetivo mapeamento de estados predefinido.", "operationId": "get_v3_session_imports_providers_list", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_providers", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "Fornecedores de migração.", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ImportProvider" } }, "mapping_targets": { "type": "array", "items": { "type": "string" } }, "skipped_statuses": { "type": "array", "items": { "type": "string" } } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_providers()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listProviders();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListProviders(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listProviders();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listProviders();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_providers\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListProvidersAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/providers/check/": { "post": { "summary": "Verificar uma chave de fornecedor", "description": "Consulte o fornecedor com a sua chave antes de criar uma migração. Nada é armazenado.", "operationId": "post_v3_session_imports_providers_check", "x-didit-sdk": { "resource": "sessions.imports", "method": "check_provider", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "Origem da migração, de `GET /v3/session/imports/providers/`. Obrigatório quando `source` é `provider`." }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A chave apenas de leitura do fornecedor, com os nomes de campos listados por `credential_fields`. Encriptada em repouso, nunca devolvida e apagada quando a importação termina. Envie-a como uma string JSON em multipart." }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "A região do fornecedor, uma das suas `regions` (Onfido: `eu`, `us`, `ca`)." } } }, "record_ids": { "type": "array", "items": { "type": "string" }, "description": "Para fornecedores com `api_ids`: o ID do primeiro registo da sua exportação." } }, "required": [ "provider", "credentials" ] }, "example": { "provider": "sumsub", "credentials": { "app_token": "YOUR_PROVIDER_APP_TOKEN", "secret_key": "YOUR_PROVIDER_SECRET_KEY" } } } } }, "responses": { "200": { "description": "A chave pode ler registos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "provider": { "type": "string" }, "credential_hint": { "type": "string", "nullable": true } } } } } }, "400": { "description": "O fornecedor recusou a chave: `code`, `detail`, `missing_permissions`, `suggested_region`." }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.check_provider(\n provider=\"sumsub\",\n credentials={\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.checkProvider({\n provider: \"sumsub\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.CheckProvider(ctx, didit.SessionsImportsCheckProviderParams{\n\tProvider: \"sumsub\",\n\tCredentials: map[string]string{\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsImportsCheckProviderParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().checkProvider(SessionsImportsCheckProviderParams.builder()\n .provider(SessionsImportsCheckProviderParams.Provider.of(\"sumsub\"))\n .credentials(Map.of(\"app_token\", \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\", \"YOUR_PROVIDER_SECRET_KEY\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->checkProvider([\n 'provider' => 'sumsub',\n 'credentials' => ['app_token' => 'YOUR_PROVIDER_APP_TOKEN', 'secret_key' => 'YOUR_PROVIDER_SECRET_KEY'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.check_provider(\n provider: \"sumsub\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CheckProviderAsync(new SessionsImportsCheckProviderParams\n{\n Provider = \"sumsub\",\n Credentials = new Dictionary { [\"app_token\"] = \"YOUR_PROVIDER_APP_TOKEN\", [\"secret_key\"] = \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/start/": { "post": { "summary": "Iniciar uma execução de teste", "description": "Iniciar uma migração cuja simulação (dry run) terminou (`READY`): a mesma tarefa executa a importação real, com o mapeamento de estados e a escolha de modelos faciais conforme enviados agora.", "operationId": "post_v3_session_imports_start", "x-didit-sdk": { "resource": "sessions.imports", "method": "start", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "Edições ao mapeamento de estado predefinido do fornecedor: estado de origem para estado da Didit. `Not Finished` e `Abandoned` são ignorados e contabilizados, nunca importados." }, "face_templates": { "type": "boolean", "default": false, "description": "Cria modelos faciais a partir das selfies importadas e pesquisa-os nos rostos e na lista de bloqueio da aplicação. As correspondências são sinalizadas apenas para revisão. Requer `lawful_basis_confirmed`." }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "Confirma que tem uma base legal para partilhar estas selfies com a Didit na qualidade de subcontratante." } } } } } }, "responses": { "200": { "description": "A tarefa de importação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "A tarefa não se encontra num estado ao qual esta ação se aplique." }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.start(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.start(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Start(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsStartParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().start(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->start('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.start(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.StartAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/pause/": { "post": { "summary": "Pausar uma tarefa de importação", "description": "Pausar uma importação em fila ou em execução.", "operationId": "post_v3_session_imports_pause", "x-didit-sdk": { "resource": "sessions.imports", "method": "pause", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A tarefa de importação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "A tarefa não se encontra num estado ao qual esta ação se aplique." }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.pause(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.pause(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Pause(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().pause(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->pause('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.pause(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.PauseAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/resume/": { "post": { "summary": "Retomar um trabalho de importação", "description": "Retome uma importação que pausou. Um trabalho pausado pelo limite de pedidos do fornecedor é retomado automaticamente.", "operationId": "post_v3_session_imports_resume", "x-didit-sdk": { "resource": "sessions.imports", "method": "resume", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A tarefa de importação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "A tarefa não se encontra num estado ao qual esta ação se aplique." }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.resume(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.resume(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Resume(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().resume(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->resume('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.resume(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ResumeAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/cancel/": { "post": { "summary": "Cancelar uma tarefa de importação", "description": "Cancelar uma importação. O que foi importado é mantido; o ficheiro carregado e a chave são eliminados.", "operationId": "post_v3_session_imports_cancel", "x-didit-sdk": { "resource": "sessions.imports", "method": "cancel", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A tarefa de importação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "A tarefa não se encontra num estado ao qual esta ação se aplique." }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.cancel(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Cancel(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().cancel(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->cancel('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.cancel(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CancelAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/retry/": { "post": { "summary": "Tentar novamente uma migração", "description": "Executar novamente uma migração terminada como uma nova tarefa, com uma nova chave (a antiga foi apagada). Mantém o fornecedor, o fluxo, a região, o mapeamento de estados e a escolha de modelos faciais; tudo o que já estiver no Didit é ignorado.", "operationId": "post_v3_session_imports_retry", "x-didit-sdk": { "resource": "sessions.imports", "method": "retry", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A chave apenas de leitura do fornecedor, com os nomes de campos listados por `credential_fields`. Encriptada em repouso, nunca devolvida e apagada quando a importação termina. Envie-a como uma string JSON em multipart." }, "file": { "type": "string", "format": "binary", "description": "Os IDs dos registos ou o ficheiro de exportação novamente, para fornecedores de `api_ids` e `export_file`." } } }, "example": { "credentials": { "app_token": "YOUR_PROVIDER_APP_TOKEN", "secret_key": "YOUR_PROVIDER_SECRET_KEY" } } } } }, "responses": { "201": { "description": "O novo trabalho de importação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "Não é uma migração, não foi terminada ou o fornecedor recusou a chave." }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.retry(\n \"11111111-2222-3333-4444-555555555555\",\n credentials={\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.retry(\"11111111-2222-3333-4444-555555555555\", {\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Retry(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsRetryParams{\n\tCredentials: didit.Some(map[string]string{\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsImportsRetryParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().retry(\"11111111-2222-3333-4444-555555555555\", SessionsImportsRetryParams.builder()\n .credentials(Map.of(\"app_token\", \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\", \"YOUR_PROVIDER_SECRET_KEY\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retry('11111111-2222-3333-4444-555555555555', [\n 'credentials' => ['app_token' => 'YOUR_PROVIDER_APP_TOKEN', 'secret_key' => 'YOUR_PROVIDER_SECRET_KEY'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.retry(\n \"11111111-2222-3333-4444-555555555555\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.RetryAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsImportsRetryParams\n{\n Credentials = new Dictionary { [\"app_token\"] = \"YOUR_PROVIDER_APP_TOKEN\", [\"secret_key\"] = \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/import-jobs/": { "get": { "summary": "Listar tarefas de importação", "description": "Todas as importações da aplicação num único formato: importações e migrações de verificações, pessoas e empresas.", "operationId": "get_v3_import_jobs_list", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_jobs", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "all", "sessions", "users", "businesses" ], "default": "all" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Tarefas de importação, as mais recentes primeiro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJobSummary" } }, "counts": { "type": "object", "properties": { "all": { "type": "integer" }, "running_and_waiting": { "type": "integer" }, "needs_attention": { "type": "integer" }, "done": { "type": "integer" } } } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_jobs()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listJobs();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListJobs(ctx, didit.SessionsImportsListJobsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listJobs();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listJobs();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_jobs\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListJobsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/import-jobs/active/": { "get": { "summary": "Listar tarefas de importação ativas", "description": "O que está em execução ou em espera, mais o que acabou de terminar, para um indicador de progresso.", "operationId": "get_v3_import_jobs_active", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_active_jobs", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "Trabalhos de importação ativos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJobSummary" } }, "running": { "type": "integer" } } } } } }, "403": { "description": "Chave de API em falta, inválida ou revogada, ou o chamador não pode importar verificações para esta aplicação.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_active_jobs()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listActiveJobs();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListActiveJobs(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listActiveJobs();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listActiveJobs();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_active_jobs\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListActiveJobsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/delete/": { "delete": { "summary": "Eliminar transações em lote", "description": "Elimine permanentemente uma ou mais transações. Selecione-as com `transaction_uuids`, ou elimine todas as transações na aplicação com `delete_all: true`.\n\nUma transação eliminada é removida juntamente com os registos exclusivos da mesma: as suas partes, etiquetas, notas, ligações de métodos de pagamento, documentos e todas as versões armazenadas dos respetivos ficheiros, execuções de regras, alertas, resultados de fornecedores, snapshot de rede e dados de Travel Rule. Casos, pessoas e empresas permanecem; a ligação destes à transação eliminada é desfeita. Os rascunhos de relatórios regulamentares deixam de a listar e são reconstruídos sem ela. A eliminação é permanente e irreversível; não existe qualquer endpoint de anulação.\n\nSe alguma transação selecionada constar num relatório regulamentar finalizado, todo o pedido é recusado com `409` e nada é eliminado. O corpo utiliza `code: in_filed_report` e indica cada transação e os relatórios que a listam. Elimine esses relatórios e, em seguida, repita o pedido.", "operationId": "batch_delete_transactions", "x-didit-sdk": { "resource": "transactions", "method": "batch_delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Transactions" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da organização." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID da aplicação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "title": "Selected transactions", "required": [ "transaction_uuids" ], "properties": { "transaction_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "UUIDs de transação Didit a eliminar. Obrigatórios, exceto se `delete_all` for true.", "minItems": 1 }, "delete_all": { "type": "boolean", "enum": [ false ], "default": false, "description": "Omita ou envie `false` quando selecionar transações com `transaction_uuids`." } } }, { "title": "All transactions", "required": [ "delete_all" ], "properties": { "delete_all": { "type": "boolean", "enum": [ true ], "description": "Eliminar todas as transações na aplicação. `transaction_uuids` é ignorado." }, "transaction_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Ignorado quando `delete_all` é true." } } } ] }, "examples": { "Selected transactions": { "value": { "transaction_uuids": [ "abcdef12-3456-7890-abcd-ef1234567890", "12345678-90ab-cdef-1234-567890abcdef" ] } }, "All transactions": { "value": { "delete_all": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl (selected transactions)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"transaction_uuids\": [\"abcdef12-3456-7890-abcd-ef1234567890\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.transactions.batch_delete(\n body={\n \"transaction_uuids\": [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n },\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.transactions.batchDelete({\n transaction_uuids: [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n});" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionsBatchDeleteParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.transactions().batchDelete(TransactionsBatchDeleteParams.builder()\n .putAdditionalProperty(\"transaction_uuids\", List.of(\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"))\n .build());" }, { "lang": "php", "label": "PHP", "source": "transactions->batchDelete([\n 'transaction_uuids' => ['abcdef12-3456-7890-abcd-ef1234567890', '12345678-90ab-cdef-1234-567890abcdef'],\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.transactions.batch_delete(\n body: {\n transaction_uuids: [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n }\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Transactions.BatchDeleteAsync(new TransactionsBatchDeleteParams\n{\n TransactionUuids = new string[] { \"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\" },\n});" } ], "responses": { "204": { "description": "Transações selecionadas eliminadas." }, "400": { "description": "Nenhum seletor de transações foi fornecido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_uuids": { "type": "array", "items": { "type": "string" } } } }, "example": { "transaction_uuids": [ "This field is required unless delete_all is true." ] } } } }, "403": { "description": "A chave de API não pode eliminar transações. O endpoint requer `write:transactions`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "Pelo menos uma transação selecionada está listada num relatório regulamentar finalizado. Nada é eliminado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/travel-rule/networks/": { "get": { "summary": "Obter redes de Travel Rule", "description": "Consulte, para esta aplicação, o verdadeiro estado de cada rede: se envia através da sua própria adesão ou através da da Didit, e o motivo pelo qual ainda não o pode fazer. Também devolve o questionário de diligência devida e os seus participantes. A consulta não cria nada.", "operationId": "getTravelRuleNetworks", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/networks/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.retrieve();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Estados da rede, questionário e participantes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworksOverview" }, "examples": { "Before the questionnaire": { "value": { "platform_networks_enabled": false, "questionnaire": { "status": "draft", "answers": {}, "submitted_at": null, "reviewed_at": null, "review_note": "", "history": [], "updated_at": null }, "participants": [], "networks": { "gtr": { "rail": "GTR", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "trust": { "rail": "TRUST", "mode": "unavailable", "state": "unavailable", "reason": "own_membership_only", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "verifyvasp": { "rail": "VERIFYVASP", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "sygna": { "rail": "SYGNA", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 } } } } } } } }, "401": { "description": "Chave de API em falta ou inválida." } } } }, "/v3/travel-rule/networks/questionnaire/": { "get": { "summary": "Obter o questionário de rede", "description": "Leia o questionário de devida diligência de rede do Didit para esta aplicação, o respetivo estado e a nota de revisão do Didit. Uma aplicação que nunca tenha guardado um lê um rascunho vazio.", "operationId": "getTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "retrieve_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/networks/questionnaire/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.retrieve_questionnaire()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.retrieveQuestionnaire();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().retrieveQuestionnaire();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->retrieveQuestionnaire();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.retrieve_questionnaire\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RetrieveQuestionnaireAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O questionário.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "401": { "description": "Chave de API em falta ou inválida." } } }, "put": { "summary": "Guardar respostas do questionário de rede", "description": "Guarde as respostas ao questionário enquanto este estiver em draft ou changes_requested. As gravações são parciais: as respostas que não enviar são mantidas.", "operationId": "updateTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "update_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/networks/questionnaire/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"legal_name\": \"Example VASP Ltd\", \"incorporation_country\": \"ES\", \"aml_ctf_policy_attested\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.update_questionnaire(\n legal_name=\"Example VASP Ltd\",\n incorporation_country=\"ES\",\n aml_ctf_policy_attested=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.updateQuestionnaire({\n legal_name: \"Example VASP Ltd\",\n incorporation_country: \"ES\",\n aml_ctf_policy_attested: true,\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleNetworkQuestionnaireAnswers;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().updateQuestionnaire(TravelRuleNetworkQuestionnaireAnswers.builder()\n .legalName(\"Example VASP Ltd\")\n .incorporationCountry(\"ES\")\n .amlCtfPolicyAttested(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->updateQuestionnaire([\n 'legal_name' => 'Example VASP Ltd',\n 'incorporation_country' => 'ES',\n 'aml_ctf_policy_attested' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.update_questionnaire(\n legal_name: \"Example VASP Ltd\",\n incorporation_country: \"ES\",\n aml_ctf_policy_attested: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.UpdateQuestionnaireAsync(new TravelRuleNetworkQuestionnaireAnswers\n{\n LegalName = \"Example VASP Ltd\",\n IncorporationCountry = \"ES\",\n AmlCtfPolicyAttested = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaireAnswers" }, "example": { "legal_name": "Example VASP Ltd", "incorporation_country": "ES", "aml_ctf_policy_attested": true } } } }, "responses": { "200": { "description": "O questionário com as respostas combinadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "400": { "description": "Erro de validação, indexado por campo." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "O acesso à rede através da adesão da Didit ainda não está aberto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } }, "409": { "description": "O questionário está com a Didit ou decidido: só pode mudar enquanto estiver como draft ou changes_requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_questionnaire_not_editable" ] } } } } } } } } }, "/v3/travel-rule/networks/questionnaire/submit/": { "post": { "summary": "Submeter o questionário da rede", "description": "Envie o questionário guardado para revisão pela Didit. As respostas guardadas devem estar completas: todos os campos, exceto lei e data_protection_contact_email, com as três atestações como true. A Didit aprova-o, solicita alterações (editar e submeter novamente) ou rejeita-o. As redes solicitadas enquanto estava pendente são transferidas para o onboarding respetivo assim que for aprovado.", "operationId": "submitTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "submit_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/networks/questionnaire/submit/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.submit_questionnaire()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.submitQuestionnaire();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().submitQuestionnaire();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->submitQuestionnaire();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.submit_questionnaire\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.SubmitQuestionnaireAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O questionário submetido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "400": { "description": "As respostas guardadas estão incompletas ou são inválidas, indexadas por campo." }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "O acesso à rede através da adesão da Didit ainda não está aberto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } }, "409": { "description": "O questionário está com a Didit ou decidido: só pode mudar enquanto estiver como draft ou changes_requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_questionnaire_not_editable" ] } } } } } } } } }, "/v3/travel-rule/networks/{network}/request/": { "post": { "summary": "Pedir uma rede Travel Rule", "description": "Pedir o participante próprio desta aplicação numa rede suportada pela adesão da Didit (GTR ou Sygna). Sem um questionário aprovado, o participante fica a aguardar pelo mesmo (questionnaire_pending); com este aprovado, segue para o onboarding da rede (submitted_to_network) e torna-se ativo assim que a rede lhe atribuir um código. Idempotente: um participante pendente, em onboarding ou em produção é devolvido inalterado. Se a rede recusou o registo (last_error definido), efetuar novo pedido tenta novamente. O TRUST e o VerifyVASP só estão acessíveis através da sua própria adesão: o TRUST admite membros por VASP e um Enclave VerifyVASP serve um ID de VASP.", "operationId": "requestTravelRuleNetworkAccess", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "request_access", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "network", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "gtr", "sygna" ] }, "description": "A rede à qual aderir através da adesão da Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/networks/gtr/request/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.request_access(\n \"your-network\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.requestAccess(\"your-network\");\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().requestAccess(\"your-network\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->requestAccess('your-network');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.request_access(\"your-network\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RequestAccessAsync(\"your-network\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O seu participante na rede.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkParticipant" } } } }, "400": { "description": "Rede desconhecida, uma rede que a Didit não suporta (associe a sua própria adesão) ou uma aplicação sandbox.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_network_own_membership_only", "travel_rule_network_sandbox_application" ] } } } } } }, "401": { "description": "Chave de API em falta ou inválida." }, "403": { "description": "O acesso à rede através da adesão da Didit ainda não está aberto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } } } } }, "/v3/address-validation/": { "post": { "summary": "Validar uma morada", "description": "Confirme que uma morada existe e obtenha-a normalizada: as suas linhas de entrega, componentes e coordenadas. Confirma apenas a morada; nunca associa a morada a uma pessoa.\n\n**Pedido.** Envie a morada numa única linha (`address`) ou como campos estruturados (`address_line_1` e, opcionalmente, `address_line_2`, `city`, `region`, `postal_code`), nunca ambos, e sempre o seu `country` (ISO 3166-1 alfa-2 ou alfa-3).\n\n**Resultado.** `address_validation.status` é `verified` (confirmado até ao edifício), `partially_verified` (confirmado apenas até à rua ou acima), `not_verified` (apenas a região ou cidade coincidiram, ou nada coincidiu) ou `unavailable` (não foi possível executar a validação). O código HTTP é `200` para todos os pedidos concluídos, incluindo `unavailable`; tente novamente um resultado `unavailable` mais tarde.\n\n**Faturação.** Uma chamada em produção custa $0.10 por morada validada. Um resultado `unavailable` não é cobrado. Nada é armazenado além do registo de utilização: nenhuma sessão é criada e o resultado é devolvido apenas nesta resposta.\n\n**Sandbox.** As chaves de sandbox validam o pedido e devolvem sempre um resultado determinístico `verified` que reflete a morada enviada, sem consumir créditos.\n\n**Autenticação.** Envie a chave de API da sua aplicação em `x-api-key`. Credenciais em falta ou inválidas devolvem `403` - esta API nunca devolve `401`.\n\n**Limite de pedidos.** Orçamento de escrita partilhado de 300 pedidos por minuto por chave de API entre endpoints POST/PATCH/DELETE (a criação de transações e a ingestão de eventos têm um orçamento separado de 600).", "operationId": "post_v3_address_validation", "x-didit-sdk": { "resource": "address_validation", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/address-validation/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n \"city\": \"Mountain View\",\n \"region\": \"CA\",\n \"postal_code\": \"94043\",\n \"country\": \"US\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.address_validation.validate(\n address_line_1=\"1600 Amphitheatre Pkwy\",\n city=\"Mountain View\",\n region=\"CA\",\n postal_code=\"94043\",\n country=\"US\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.addressValidation.validate({\n address_line_1: \"1600 Amphitheatre Pkwy\",\n city: \"Mountain View\",\n region: \"CA\",\n postal_code: \"94043\",\n country: \"US\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.AddressValidationRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.addressValidation().validate(AddressValidationRequest.builder()\n .addressLine1(\"1600 Amphitheatre Pkwy\")\n .city(\"Mountain View\")\n .region(\"CA\")\n .postalCode(\"94043\")\n .country(\"US\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "addressValidation->validate([\n 'address_line_1' => '1600 Amphitheatre Pkwy',\n 'city' => 'Mountain View',\n 'region' => 'CA',\n 'postal_code' => '94043',\n 'country' => 'US',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.address_validation.validate(\n address_line_1: \"1600 Amphitheatre Pkwy\",\n city: \"Mountain View\",\n region: \"CA\",\n postal_code: \"94043\",\n country: \"US\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AddressValidation.ValidateAsync(new AddressValidationRequest\n{\n AddressLine1 = \"1600 Amphitheatre Pkwy\",\n City = \"Mountain View\",\n Region = \"CA\",\n PostalCode = \"94043\",\n Country = \"US\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationRequest" }, "examples": { "Structured": { "summary": "Campos de morada estruturada", "value": { "address_line_1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "region": "CA", "postal_code": "94043", "country": "US" } }, "One line": { "summary": "A morada completa numa linha", "value": { "address": "Paseo de la Castellana 259, 28046 Madrid", "country": "ES" } } } } } }, "responses": { "200": { "description": "A validação foi concluída. Consulte `address_validation.status`; o HTTP é sempre `200` para um pedido concluído.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationResponse" }, "examples": { "Verified": { "summary": "Uma morada real, confirmada até ao edifício", "value": { "request_id": "6f7d2c1e-1c5a-4a1e-9b8f-2a1f0f4b9c3d", "address_validation": { "status": "verified", "verification_level": "premise", "address": { "address_line_1": "1600 Amphitheatre Pkwy", "address_line_2": null, "city": "Mountain View", "region": "CA", "postal_code": "94043-1351", "country": "US" }, "formatted_address": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351", "latitude": 37.422022, "longitude": -122.08429 }, "created_at": "2026-10-27T11:20:00.000000+00:00" } }, "Not verified": { "summary": "Uma rua inventada: apenas a cidade correspondeu", "value": { "request_id": "0b9e3f4a-6c2d-4e8b-a1f7-5d3c2b1a0e9f", "address_validation": { "status": "not_verified", "verification_level": "locality", "address": { "address_line_1": "Calle Inventada Que No Existe 99999 28046", "address_line_2": null, "city": "Madrid", "region": "Madrid", "postal_code": null, "country": "ES" }, "formatted_address": "Calle Inventada Que No Existe 99999 28046, Madrid, MADRID, SPAIN", "latitude": 40.42603054, "longitude": -3.68645331 }, "created_at": "2026-10-27T11:21:00.000000+00:00" } }, "Unavailable": { "summary": "Não foi possível executar a validação; não é cobrada", "value": { "request_id": "3c1b2a0f-9e8d-4c7b-b6a5-1f0e9d8c7b6a", "address_validation": { "status": "unavailable", "verification_level": null, "address": null, "formatted_address": null, "latitude": null, "longitude": null }, "created_at": "2026-10-27T11:22:00.000000+00:00" } } } } } }, "400": { "$ref": "#/components/responses/AddressValidationValidationError" }, "403": { "$ref": "#/components/responses/AddressValidationPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } } } }, "/v3/travel-rule/wallet-proofs/": { "get": { "summary": "Listar comprovativos de carteira através de capturas de ecrã para rever", "description": "A sua fila de revisão para comprovativos de propriedade da carteira por captura de ecrã. Uma captura de ecrã é o único comprovativo que a Didit não consegue verificar autonomamente: assim que o utilizador final a envia a partir do widget, aguarda em PENDING até que aprove ou recuse com POST /v3/travel-rule/wallet-proofs/{proof_uuid}/decision/. Do mais antigo para o mais recente, para que a fila seja processada a partir do comprovativo que aguarda há mais tempo. Apenas aparecem capturas de ecrã enviadas, nunca um comprovativo cujo utilizador final ainda não tenha enviado um ficheiro, e nunca um relativo a uma carteira que tenha eliminado do seu livro de endereços (a Didit fecha esses como OWNERSHIP_CHANGED).", "operationId": "listTravelRuleWalletProofs", "x-didit-sdk": { "resource": "travel_rule.wallet_proofs", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "description": "Quais os comprovativos a listar. A predefinição é PENDING, aqueles que ainda estão por decidir.", "schema": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "default": "PENDING" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/wallet-proofs/?status=PENDING \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.wallet_proofs.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.walletProofs.list()) {\n console.log(item);\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().walletProofs().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletProofs->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_proofs.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.WalletProofs.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Comprovativos por captura de ecrã paginados. count é exato até 100 e limitado a 100 acima desse valor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleWalletProofReview" } } } } } } }, "400": { "description": "Estado desconhecido." }, "401": { "description": "x-api-key em falta ou inválido." }, "403": { "description": "O chamador não possui a permissão de transações." } } } }, "/v3/travel-rule/wallet-proofs/{proof_uuid}/decision/": { "post": { "summary": "Aprovar ou rejeitar um comprovativo de carteira por captura de ecrã", "description": "Decidir sobre um comprovativo por captura de ecrã da sua fila de revisão. approve verifica o comprovativo e a entrada no livro de endereços e aplica a propriedade à transferência para a qual a sessão do widget foi gerada, exatamente como uma assinatura verificada faz. Uma captura de ecrã nunca confirma uma transferência que outro cliente Didit enviou através da via INTERNAL: isso requer uma mensagem assinada ou um depósito de teste. reject encerra o comprovativo como REJECTED com o failure_reason REVIEW_REJECTED; o utilizador final pode iniciar um novo comprovativo a partir do widget. A nota é mantida com o comprovativo.", "operationId": "decideTravelRuleWalletProof", "x-didit-sdk": { "resource": "travel_rule.wallet_proofs", "method": "decide", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "proof_uuid", "in": "path", "required": true, "description": "proof_id da fila de revisão.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWalletProofDecision" }, "example": { "decision": "approve", "note": "Address matches the wallet app." } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-proofs/{proof_uuid}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"approve\", \"note\": \"Address matches the wallet app.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_proofs.decide(\n \"11111111-2222-3333-4444-555555555555\",\n decision=\"approve\",\n note=\"Address matches the wallet app.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletProofs.decide(\"11111111-2222-3333-4444-555555555555\", {\n decision: \"approve\",\n note: \"Address matches the wallet app.\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWalletProofDecision;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletProofs().decide(\"11111111-2222-3333-4444-555555555555\", TravelRuleWalletProofDecision.builder()\n .decision(TravelRuleWalletProofDecision.Decision.of(\"approve\"))\n .note(\"Address matches the wallet app.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletProofs->decide('11111111-2222-3333-4444-555555555555', [\n 'decision' => 'approve',\n 'note' => 'Address matches the wallet app.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_proofs.decide(\n \"11111111-2222-3333-4444-555555555555\",\n decision: \"approve\",\n note: \"Address matches the wallet app.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletProofs.DecideAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleWalletProofDecision\n{\n Decision = \"approve\",\n Note = \"Address matches the wallet app.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "O comprovativo decidido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWalletProofReview" } } } }, "400": { "description": "Decisão inválida ou uma nota com mais de 512 carateres." }, "401": { "description": "x-api-key em falta ou inválido." }, "403": { "description": "O chamador não possui a permissão de transações." }, "404": { "description": "Nenhum comprovativo de captura de ecrã submetido com este id na sua aplicação." }, "409": { "description": "O comprovativo já está decidido (o corpo contém o respetivo estado) ou código OWNERSHIP_CHANGED: o titular da carteira mudou ou a carteira foi eliminada após a criação da sessão do widget, pelo que o comprovativo está fechado e o titular atual necessita de um novo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } } } } }, "/v3/travel-rule/widget/{token}/proofs/": { "post": { "summary": "Iniciar uma prova de propriedade da carteira", "description": "Endpoint público associado ao token de sessão do widget, sem necessidade de chave de API: o widget alojado chama-o quando o utilizador final escolhe um método de prova. Uma prova só existe, e só conta no seu funil de provas, a partir desta chamada. Escolher novamente o mesmo método devolve a prova já aberta (200, mesmo desafio ou montante de depósito) em vez de iniciar uma segunda; escolher outro método fecha a prova não finalizada como METHOD_SWITCHED, exceto uma captura de ecrã enviada ou um depósito de teste ainda em verificação. MESSAGE_SIGNING devolve o desafio a assinar; SATOSHI_TEST o endereço de depósito, o montante exato e a janela; SELF_DECLARATION é verificada de imediato (estado VERIFIED). Formatos de assinatura verificados por família de blockchain: cadeias EVM aceitam uma assinatura personal_sign (EIP-191), codificada em hex; Bitcoin aceita uma assinatura signmessage BIP-137 (endereços P2PKH, P2SH-P2WPKH e P2WPKH) ou uma assinatura simples BIP-322 (endereços P2WPKH e P2TR), codificada em base64; Solana aceita uma assinatura Ed25519 sobre o desafio, codificada em base58; Tron aceita uma assinatura signMessageV2 (TIP-191), codificada em hex. Uma assinatura completa ou de comprovativo de fundos BIP-322, ou um endereço multisig, falha com SIGNATURE_UNSUPPORTED_SCHEME.", "operationId": "createTravelRuleWidgetProof", "x-didit-sdk": { "resource": "travel_rule", "method": "create_widget_proof", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token de sessão opaco devolvido quando a sessão do widget foi gerada.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofCreate" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/proofs/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"method\": \"MESSAGE_SIGNING\"}'" } ], "responses": { "201": { "description": "Uma nova prova PENDING (VERIFIED para SELF_DECLARATION).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } } } }, "200": { "description": "O comprovativo já aberto para este método, retomado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } } } }, "400": { "description": "Corpo inválido, uma carteira que não coincide com a transferência, SCREENSHOT não permitido ou código CHAIN_UNSUPPORTED quando o método não está disponível na blockchain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "403": { "description": "SELF_DECLARATION não é permitida para esta aplicação." }, "404": { "description": "Token desconhecido." }, "409": { "description": "código OWNERSHIP_CHANGED: o titular da carteira mudou ou a carteira foi eliminada após a sessão ter sido criada; crie uma nova sessão para o titular atual. Também devolvido para SATOSHI_TEST quando a sessão não tem satoshi_deposit_address e quando a sessão não tem tentativas restantes (sem código; o corpo inclui max_attempts, attempts_used e attempts_remaining 0): crie uma nova sessão.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "410": { "description": "A sessão expirou." } } } }, "/v3/travel-rule/widget/{token}/proofs/{proof_id}/verify/": { "post": { "summary": "Submeter a prova de propriedade da carteira", "description": "Endpoint público associado ao token de sessão do widget, sem necessidade de chave de API. Envie a evidência necessária para o método da prova: assinatura para MESSAGE_SIGNING, txid para SATOSHI_TEST (JSON) ou um ficheiro para SCREENSHOT (multipart). Cada envio conta como uma tentativa. Uma assinatura que não seja verificada ou um depósito que não coincida responde com 400 com um código e deixa a prova como PENDING para que o utilizador final possa tentar novamente. Um depósito detetado mas ainda não confirmado responde com 200 com o estado PENDING e é verificado novamente de forma automática até ao fecho da janela. Uma captura de ecrã responde com 200 com o estado PENDING e aguarda na sua fila de revisão (GET /v3/travel-rule/wallet-proofs/). Uma prova EXPIRED ou REJECTED nunca é verificada mais tarde: inicie uma nova. Formatos de assinatura verificados por família de blockchain: cadeias EVM aceitam uma assinatura personal_sign (EIP-191), codificada em hex; Bitcoin aceita uma assinatura signmessage BIP-137 (endereços P2PKH, P2SH-P2WPKH e P2WPKH) ou uma assinatura simples BIP-322 (endereços P2WPKH e P2TR), codificada em base64; Solana aceita uma assinatura Ed25519 sobre o desafio, codificada em base58; Tron aceita uma assinatura signMessageV2 (TIP-191), codificada em hex. Uma assinatura completa ou de comprovativo de fundos BIP-322, ou um endereço multisig, falha com SIGNATURE_UNSUPPORTED_SCHEME.", "operationId": "verifyTravelRuleWidgetProof", "x-didit-sdk": { "resource": "travel_rule", "method": "verify_widget_proof", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token de sessão opaco devolvido quando a sessão do widget foi gerada.", "schema": { "type": "string" } }, { "name": "proof_id", "in": "path", "required": true, "description": "proof_id devolvido quando a prova foi iniciada.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "description": "MESSAGE_SIGNING: a assinatura da carteira sobre o desafio da prova." }, "txid": { "type": "string", "description": "SATOSHI_TEST: o ID da transação do depósito de teste." } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "SCREENSHOT: uma imagem que mostra a carteira na aplicação de carteira do utilizador final." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/proofs/{proof_id}/verify/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"signature\": \"0x...\"}'" } ], "responses": { "200": { "description": "VERIFIED, ou ainda PENDING (uma captura de ecrã a aguardar revisão, um depósito ainda não indexado ou não confirmado, com o código DEPOSIT_NOT_FOUND ou DEPOSIT_UNCONFIRMED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofVerifyResult" } } } }, "400": { "description": "Evidência em falta; uma tentativa falhada que mantém a prova como PENDING para que o utilizador final possa tentar novamente (código SIGNATURE_INVALID, SIGNATURE_UNSUPPORTED_SCHEME ou DEPOSIT_LOOKUP_FAILED); ou um depósito de teste que rejeita a prova (código DEPOSIT_MISMATCH, DEPOSIT_STALE ou TXID_REUSED, estado REJECTED, com as contagens de tentativas da sessão): escolher um método novamente inicia uma nova prova enquanto attempts_remaining for superior a 0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "404": { "description": "Token desconhecido ou nenhum comprovativo deste tipo nesta sessão." }, "409": { "description": "código OWNERSHIP_CHANGED (a prova é encerrada com este); uma prova encerrada (REJECTED ou EXPIRED), com o seu estado, o código com que encerrou e as contagens de tentativas da sessão: escolha novamente um método para iniciar uma nova prova; ou uma prova SELF_DECLARATION, que é verificada quando iniciada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "410": { "description": "A sessão expirou, ou código WINDOW_EXPIRED quando a janela do teste satoshi fechou.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } } } } }, "/v3/id-verification/wallets/verifications/{request_id}/response/": { "post": { "operationId": "submit_wallet_verification_response", "x-didit-sdk": { "resource": "id_wallets", "method": "submit_verification_response", "auth": "api_key", "server": true }, "description": "Carteiras da Digital Credentials API (Google Wallet): envie o que a carteira devolveu para a sua página ou aplicação para uma verificação cujo next_action seja request_digital_credential. A Didit desencripta os dados, verifica a assinatura do emissor contra as raízes de confiança do emissor, cada valor devolvido contra o respetivo digest assinado e a assinatura do dispositivo sobre a sua origem e este pedido; de seguida, decide a verificação: verificada (faturada uma vez) ou recusada com o código de erro. Utilização única: uma segunda submissão devolve a verificação já decidida.", "summary": "Submeter uma resposta da carteira", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "O request_id devolvido pelo endpoint de início.", "required": true } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "google_wallet", "name": "Google Wallet", "issuing_authority": "Google Wallet (ID pass) and US state issuers (mobile driving licence)" }, "country": "USA", "status": "Approved", "outcome": "verified", "error": null, "interaction": "digital_credentials", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": null, "identity": { "full_name": "Alex Example", "first_name": "Alex", "last_name": "Example", "date_of_birth": "1990-01-31", "nationality": "USA", "issuing_state": "USA" }, "attributes": { "document_number": "X0000000", "document_expiry_date": "2030-01-31" }, "level_of_assurance": "substantial", "verified_at": "2026-01-01T10:01:00Z", "signature_valid": true, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenciais em falta (x-api-key ou Authorization: Bearer)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro not_found: nenhuma verificação de carteira desta aplicação tem este request_id." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]})." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro not_a_digital_credentials_wallet: esta verificação não aceita uma resposta de carteira." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue verificar a carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/response/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"response\": {\n \"protocol\": \"openid4vp-v1-signed\",\n \"data\": {\n \"response\": \"\"\n }\n }\n}'" } ] } }, "/v3/id-verification/wallets/google-wallet/": { "post": { "operationId": "start_google_wallet_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_google_wallet", "auth": "api_key", "server": true }, "description": "Inicie uma sessão com Google Wallet (Google Wallet (ID pass) e emissores estatais dos EUA (carta de condução móvel); USA, GBR, BRA, SGP, TWN) sem qualquer fluxo. Faturado uma única vez, apenas quando a identidade for verificada. A resposta contém next_action.type=request_digital_credential com um pedido que a Didit assinou para a sua aplicação, utilizável apenas a partir da origem. Num gesto do utilizador nessa origem, passe next_action.digital_credentials.request para navigator.credentials.get({digital: ...}) (ou para o Android Credential Manager como GetDigitalCredentialOption requestJson) e, em seguida, envie, através de POST, o que a carteira devolver para /v3/id-verification/wallets/verifications/{request_id}/response/. O navegador apresenta o seu próprio código QR quando a carteira estiver noutro dispositivo. As aplicações em sandbox obtêm uma simulação determinística (simulated: true) que nunca contacta o fornecedor.", "summary": "Iniciar verificação Google Wallet", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chave opcional de segurança contra tentativas repetidas (máx. 255 caracteres). Tentar novamente com a mesma chave, carteira e corpo devolve a verificação original sem iniciar sessão uma segunda vez; a mesma chave com outra carteira ou corpo devolve 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" }, "example": { "country": "USA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "origin": "https://app.example.com" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "google_wallet", "name": "Google Wallet", "issuing_authority": "Google Wallet (ID pass) and US state issuers (mobile driving licence)" }, "country": "USA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "digital_credentials", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "request_digital_credential", "digital_credentials": { "protocol": "openid4vp-v1-signed", "request": { "requests": [ { "protocol": "openid4vp-v1-signed", "data": { "request": "" } } ] } } }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Erros de validação de campos ({field: [messages]}), ou erro return_url_invalid, return_url_not_allowed, origin_invalid, origin_not_allowed, invalid_personal_code, invalid_phone_number ou idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenciais em falta ({detail}), ou erro wallet_unavailable, insufficient_credits ou contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro idempotency_key_reused ou idempotency_key_in_progress (com Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_provider_unavailable: o fornecedor não conseguiu iniciar; nada foi criado." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "erro wallet_not_configured: este ambiente não consegue aceder à carteira." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"USA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"origin\": \"https://app.example.com\"\n}'" } ], "x-didit-wallet-id": "google_wallet" } }, "/v3/session/{sessionId}/kyb/documents/": { "post": { "summary": "Carregar documentos de KYB para uma sessão", "description": "Carregue um ou mais documentos societários (estatutos sociais, registo de acionistas, certidão de constituição, ...) para o passo KYB Documents de uma sessão de Verificação de empresas, a partir do seu próprio servidor em vez da página alojada. A Didit executa o pipeline alojado: compressão, OCR, verificações de adulteração e entre documentos, agrupamento de documentos e avança a sessão quando os grupos de documentos obrigatórios são cumpridos. O passo custa uma taxa fixa única, independentemente de quantos ficheiros enviar. A sessão tem de estar aberta e no passo KYB Documents, e a empresa escolhida no passo do registo tem de existir. Consulte as pessoas mencionadas nos documentos com `GET /v3/session/{sessionId}/kyb/extracted-parties/`. Requer `write:businesses`.", "operationId": "post_v3_session_kyb_documents", "x-didit-sdk": { "resource": "sessions", "method": "upload_kyb_documents", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de empresas (KYB). Tem de pertencer à aplicação da chave de API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do fluxo do passo de KYB. Apenas necessário quando o fluxo tem mais de um nó de KYB; por predefinição, a Didit utiliza o nó próprio da sessão.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Ficheiros a carregar: JPG, JPEG, PNG, TIFF, WEBP, PDF ou ficheiros ZIP que os contenham. Ficheiros PDF até 50 MB, fotos até 6 MB antes da compressão." }, "document_passwords": { "type": "array", "items": { "type": "string" }, "description": "Uma entrada por ficheiro em `documents`, na mesma ordem: a palavra-passe de um PDF protegido, vazia para qualquer outro ficheiro." }, "document_group": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION" ], "description": "Grupo de documentos obrigatório ao qual este carregamento responde." }, "locale": { "type": "string", "maxLength": 10, "description": "Localidade utilizada para traduzir a resposta do próximo passo." } } } } } }, "responses": { "200": { "description": "Documentos processados. Quando todos os grupos obrigatórios são cumpridos, a sessão avança e `next_step` indica o passo seguinte; caso contrário, permanece no passo Documentos e `document_groups` e `document_answer` indicam o que ainda está em falta.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "next_step": { "type": "string", "nullable": true, "description": "Passo em que a sessão se encontra após o carregamento." }, "kyb_status": { "type": "string", "description": "Estado da verificação da empresa." }, "document_answer": { "type": "object", "additionalProperties": true, "description": "Resultado por documento carregado e os carregamentos restantes." } }, "additionalProperties": true }, "example": { "valid": true, "next_step": "KYB_KEY_PEOPLE", "kyb_status": "In Progress" } } } }, "400": { "description": "Um documento foi rejeitado (adulteração, ilegível ou não suportado) ou a sessão ainda não tem uma empresa de KYB associada. Tente novamente com outro ficheiro enquanto restarem tentativas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "message": "No KYB company found. Submit company data first." } } } }, "402": { "description": "A organização já não tem crédito para o passo de documentos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Insufficient credits." } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada, pertence a outra aplicação ou está fora dos limites de uma chave com âmbito restrito; nenhum detalhe os distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "A sessão está finalizada (`kyb_session_not_writable`) ou não está no passo KYB Documents (`kyb_step_mismatch`, com `next_step` a indicar o passo em que se encontra).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." }, "code": { "type": "string" }, "next_step": { "type": "string" } } }, "example": { "detail": "The session is not on the step this operation completes.", "code": "kyb_step_mismatch", "next_step": "KYB_REGISTRY" } } } }, "429": { "description": "Limite de pedidos excedido: 300 pedidos de escrita (POST, PATCH, DELETE) por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.upload_kyb_documents(\n \"33333333-4444-5555-6666-777777777777\",\n documents=[open(\"document.pdf\", \"rb\")],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.uploadKybDocuments(\"33333333-4444-5555-6666-777777777777\", {\n documents: [await fileFromPath(\"document.pdf\")],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UploadKYBDocuments(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsUploadKYBDocumentsParams{\n\tDocuments: []didit.File{didit.FileFromPath(\"document.pdf\")},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUploadKybDocumentsParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().uploadKybDocuments(\"33333333-4444-5555-6666-777777777777\", SessionsUploadKybDocumentsParams.builder()\n .documents(List.of(Path.of(\"document.pdf\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->uploadKybDocuments('33333333-4444-5555-6666-777777777777', [\n 'documents' => [File::fromPath('document.pdf')],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.upload_kyb_documents(\n \"33333333-4444-5555-6666-777777777777\",\n documents: [Pathname(\"document.pdf\")]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UploadKybDocumentsAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsUploadKybDocumentsParams\n{\n Documents = new FileUpload[] { FileUpload.FromPath(\"document.pdf\") },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/extracted-parties/": { "get": { "summary": "Listar as partes indicadas nos documentos carregados", "description": "Retorna os acionistas e administradores indicados nos documentos carregados para esta sessão de KYB, consolidados por pessoa e atribuídos aos documentos que os indicaram. Apresente-os ao seu requerente para confirmação e, em seguida, declare-os com os endpoints de rascunho de partes. Um intervalo permanece um intervalo: `ownership_percent.text` mantém o valor literal e `min` / `max` os números lidos a partir dele. Ninguém é classificado como UBO aqui; isso é decidido quando as partes são submetidas, a partir das definições de funções e dos limiares de propriedade do fluxo. A mesma lista encontra-se na decisão da sessão como `document_verifications[].extracted_parties`. Requer `read:businesses` ou `read:sessions`.", "operationId": "get_v3_session_kyb_extracted_parties", "x-didit-sdk": { "resource": "sessions", "method": "list_kyb_extracted_parties", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de empresas (KYB). Tem de pertencer à aplicação da chave de API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do fluxo do passo de KYB. Apenas necessário quando o fluxo tem mais de um nó de KYB; por predefinição, a Didit utiliza o nó próprio da sessão.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partes indicadas pelos documentos atuais.", "content": { "application/json": { "schema": { "type": "object", "required": [ "parties", "document_count" ], "properties": { "parties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "roles": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "ownership_percent": { "type": "object", "properties": { "text": { "type": "string", "nullable": true, "description": "O valor da propriedade exatamente como indicado no documento, como `25-50%`, `>50%` ou `NO EXHIBE`." }, "min": { "type": "number", "nullable": true, "description": "Número inferior lido a partir de `text`; null quando não indica nenhum." }, "max": { "type": "number", "nullable": true, "description": "Número superior lido a partir de `text`; null quando não indica nenhum." } } } } } }, "documents": { "type": "array", "description": "Os documentos carregados que indicaram esta parte.", "items": { "type": "object", "properties": { "document_uuid": { "type": "string", "format": "uuid" }, "document_type": { "type": "string", "nullable": true }, "document_subtype": { "type": "string", "nullable": true }, "original_filename": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } } } } } }, "description": "Os acionistas e administradores indicados pelos documentos carregados, agregados por pessoa. Ninguém é rotulado como UBO aqui: isso é decidido quando as partes são submetidas." }, "document_count": { "type": "integer", "description": "Número de documentos carregados a partir dos quais a lista foi lida." }, "node_id": { "type": "string", "nullable": true } } }, "example": { "parties": [ { "name": "Ana Lopez", "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "appointment_date": null, "designation": "Administrador unico", "roles": [ { "role": "shareholder", "ownership_percent": { "text": "60%", "min": 60, "max": 60 } } ], "documents": [ { "document_uuid": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41", "document_type": "OWNERSHIP_STRUCTURE", "document_subtype": "ARTICLES_OF_INCORPORATION", "original_filename": "acta_constitutiva.pdf", "status": "Approved" } ] } ], "document_count": 1, "node_id": "node_kyb_documents" } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada, pertence a outra aplicação ou está fora dos limites de uma chave com âmbito restrito; nenhum detalhe os distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Session not found." } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_kyb_extracted_parties(\n \"33333333-4444-5555-6666-777777777777\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listKybExtractedParties(\"33333333-4444-5555-6666-777777777777\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListKYBExtractedParties(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsListKYBExtractedPartiesParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listKybExtractedParties(\"33333333-4444-5555-6666-777777777777\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listKybExtractedParties('33333333-4444-5555-6666-777777777777');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_kyb_extracted_parties(\"33333333-4444-5555-6666-777777777777\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListKybExtractedPartiesAsync(\"33333333-4444-5555-6666-777777777777\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/drafts/": { "get": { "summary": "Listar os rascunhos de partes de KYB", "description": "Liste as partes que está a preparar para esta sessão de KYB, as mais antigas primeiro. Um rascunho não é uma parte declarada: não aparece na decisão nem na consola e não cria nenhuma sessão de verificação até que o submeta com `POST /v3/session/{sessionId}/kyb/parties/submit/`. Requer `write:businesses`.", "operationId": "get_v3_session_kyb_party_drafts", "x-didit-sdk": { "resource": "sessions", "method": "list_kyb_party_drafts", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de empresas (KYB). Tem de pertencer à aplicação da chave de API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do fluxo do passo de KYB. Apenas necessário quando o fluxo tem mais de um nó de KYB; por predefinição, a Didit utiliza o nó próprio da sessão.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Os rascunhos guardados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "parties": { "type": "array", "items": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se a parte é uma pessoa singular ou uma empresa." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo de uma pessoa. Envie este campo, ou `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Função desempenhada pela parte. Intercambiável com `roles`; quando ambas forem enviadas, são combinadas." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Cada função que a parte desempenha. Uma pessoa necessita de pelo menos uma função (aqui ou em `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Cargo de uma pessoa." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome de uma parte da empresa. Obrigatório quando `entity_type` é `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Número de registo de uma entidade empresarial." }, "email": { "type": "string", "format": "email", "description": "Para onde a ligação de verificação é enviada. Obrigatório quando a parte tem de concluir a verificação, o que depende das definições de funções e dos limiares de propriedade do fluxo." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem da empresa que a parte detém." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nacionalidade de uma pessoa ou país de constituição de uma empresa. Obrigatório para todas as partes." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campos adicionais definidos pelo fluxo." }, "skip_verification": { "type": "boolean", "default": false, "description": "Pedir para ignorar a verificação desta parte. Respeitado apenas quando a função da parte permite ignorar nas definições de Pessoas-chave do fluxo." } } } } } }, "node_id": { "type": "string", "nullable": true } } }, "example": { "parties": [ { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } ], "node_id": "node_kyb_key_people" } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada, pertence a outra aplicação ou está fora dos limites de uma chave com âmbito restrito; nenhum detalhe os distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Session not found." } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_kyb_party_drafts(\n \"33333333-4444-5555-6666-777777777777\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listKybPartyDrafts(\"33333333-4444-5555-6666-777777777777\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListKYBPartyDrafts(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsListKYBPartyDraftsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listKybPartyDrafts(\"33333333-4444-5555-6666-777777777777\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listKybPartyDrafts('33333333-4444-5555-6666-777777777777');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_kyb_party_drafts(\"33333333-4444-5555-6666-777777777777\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListKybPartyDraftsAsync(\"33333333-4444-5555-6666-777777777777\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "post": { "summary": "Criar um rascunho de interveniente de KYB", "description": "Adicione uma parte (uma pessoa ou uma empresa) à lista que está a preparar para esta sessão de KYB. Aplicam-se os mesmos campos e regras do ecrã alojado de pessoas-chave: uma pessoa necessita de `full_name` ou de `first_name` e `last_name`, de pelo menos uma função e de uma nacionalidade; uma empresa necessita de `company_name` e do país de constituição em `nationality`. Nada é declarado ou faturado até `POST /v3/session/{sessionId}/kyb/parties/submit/`. Requer `write:businesses`.", "operationId": "post_v3_session_kyb_party_drafts", "x-didit-sdk": { "resource": "sessions", "method": "create_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de empresas (KYB). Tem de pertencer à aplicação da chave de API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do fluxo do passo de KYB. Apenas necessário quando o fluxo tem mais de um nó de KYB; por predefinição, a Didit utiliza o nó próprio da sessão.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se a parte é uma pessoa singular ou uma empresa." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo de uma pessoa. Envie este campo, ou `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Função desempenhada pela parte. Intercambiável com `roles`; quando ambas forem enviadas, são combinadas." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Cada função que a parte desempenha. Uma pessoa necessita de pelo menos uma função (aqui ou em `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Cargo de uma pessoa." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome de uma parte da empresa. Obrigatório quando `entity_type` é `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Número de registo de uma entidade empresarial." }, "email": { "type": "string", "format": "email", "description": "Para onde a ligação de verificação é enviada. Obrigatório quando a parte tem de concluir a verificação, o que depende das definições de funções e dos limiares de propriedade do fluxo." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem da empresa que a parte detém." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nacionalidade de uma pessoa ou país de constituição de uma empresa. Obrigatório para todas as partes." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campos adicionais definidos pelo fluxo." }, "skip_verification": { "type": "boolean", "default": false, "description": "Pedir para ignorar a verificação desta parte. Respeitado apenas quando a função da parte permite ignorar nas definições de Pessoas-chave do fluxo." } } }, "example": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } }, "responses": { "201": { "description": "Rascunho criado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se a parte é uma pessoa singular ou uma empresa." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo de uma pessoa. Envie este campo, ou `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Função desempenhada pela parte. Intercambiável com `roles`; quando ambas forem enviadas, são combinadas." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Cada função que a parte desempenha. Uma pessoa necessita de pelo menos uma função (aqui ou em `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Cargo de uma pessoa." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome de uma parte da empresa. Obrigatório quando `entity_type` é `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Número de registo de uma entidade empresarial." }, "email": { "type": "string", "format": "email", "description": "Para onde a ligação de verificação é enviada. Obrigatório quando a parte tem de concluir a verificação, o que depende das definições de funções e dos limiares de propriedade do fluxo." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem da empresa que a parte detém." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nacionalidade de uma pessoa ou país de constituição de uma empresa. Obrigatório para todas as partes." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campos adicionais definidos pelo fluxo." }, "skip_verification": { "type": "boolean", "default": false, "description": "Pedir para ignorar a verificação desta parte. Respeitado apenas quando a função da parte permite ignorar nas definições de Pessoas-chave do fluxo." } } } } }, "example": { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } } }, "400": { "description": "Um campo de uma parte é inválido ou falta um obrigatório.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "non_field_errors": [ "Person parties require at least one role." ] } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada, pertence a outra aplicação ou está fora dos limites de uma chave com âmbito restrito; nenhum detalhe os distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "A sessão está finalizada (`kyb_session_not_writable`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "Limite de pedidos excedido: 300 pedidos de escrita (POST, PATCH, DELETE) por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.create_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n entity_type=\"person\",\n first_name=\"Ana\",\n last_name=\"Lopez\",\n roles=[\"ubo\", \"director\"],\n date_of_birth=\"1984-06-12\",\n email=\"ana.lopez@example.com\",\n ownership_percent=60.0,\n nationality=\"MEX\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.createKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", {\n entity_type: \"person\",\n first_name: \"Ana\",\n last_name: \"Lopez\",\n roles: [\"ubo\", \"director\"],\n date_of_birth: \"1984-06-12\",\n email: \"ana.lopez@example.com\",\n ownership_percent: 60.0,\n nationality: \"MEX\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.CreateKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsCreateKYBPartyDraftParams{\n\tEntityType: \"person\",\n\tFirstName: didit.String(\"Ana\"),\n\tLastName: didit.String(\"Lopez\"),\n\tRoles: didit.Some([]didit.SessionsCreateKYBPartyDraftParamsRoles{\"ubo\", \"director\"}),\n\tDateOfBirth: didit.String(\"1984-06-12\"),\n\tEmail: didit.String(\"ana.lopez@example.com\"),\n\tOwnershipPercent: didit.Float(60.0),\n\tNationality: \"MEX\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsCreateKybPartyDraftParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().createKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", SessionsCreateKybPartyDraftParams.builder()\n .entityType(SessionsCreateKybPartyDraftParams.EntityType.of(\"person\"))\n .firstName(\"Ana\")\n .lastName(\"Lopez\")\n .roles(List.of(SessionsCreateKybPartyDraftParams.Roles.of(\"ubo\"), SessionsCreateKybPartyDraftParams.Roles.of(\"director\")))\n .dateOfBirth(LocalDate.parse(\"1984-06-12\"))\n .email(\"ana.lopez@example.com\")\n .ownershipPercent(60.0)\n .nationality(\"MEX\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->createKybPartyDraft('33333333-4444-5555-6666-777777777777', [\n 'entity_type' => 'person',\n 'first_name' => 'Ana',\n 'last_name' => 'Lopez',\n 'roles' => ['ubo', 'director'],\n 'date_of_birth' => '1984-06-12',\n 'email' => 'ana.lopez@example.com',\n 'ownership_percent' => 60.0,\n 'nationality' => 'MEX',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.create_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n entity_type: \"person\",\n first_name: \"Ana\",\n last_name: \"Lopez\",\n roles: [\"ubo\", \"director\"],\n date_of_birth: \"1984-06-12\",\n email: \"ana.lopez@example.com\",\n ownership_percent: 60.0,\n nationality: \"MEX\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CreateKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsCreateKybPartyDraftParams\n{\n EntityType = \"person\",\n FirstName = \"Ana\",\n LastName = \"Lopez\",\n Roles = new SessionsCreateKybPartyDraftParamsRoles[] { \"ubo\", \"director\" },\n DateOfBirth = \"1984-06-12\",\n Email = \"ana.lopez@example.com\",\n OwnershipPercent = 60.0,\n Nationality = \"MEX\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/drafts/{draftId}/": { "patch": { "summary": "Editar um rascunho de parte de KYB", "description": "Alterar campos de um rascunho de parte interveniente. A edição é incorporada no rascunho armazenado e a parte resultante é validada no seu todo, pelo que qualquer edição que deixe a parte incompleta é rejeitada. Alterar `first_name` ou `last_name` substitui o nome completo armazenado. Requer `write:businesses`.", "operationId": "patch_v3_session_kyb_party_draft", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de empresas (KYB). Tem de pertencer à aplicação da chave de API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "draftId", "in": "path", "required": true, "description": "UUID do rascunho de parte (`draft_id` retornado quando foi criado).", "schema": { "type": "string", "format": "uuid", "example": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do fluxo do passo de KYB. Apenas necessário quando o fluxo tem mais de um nó de KYB; por predefinição, a Didit utiliza o nó próprio da sessão.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Qualquer subconjunto dos campos da parte. A edição é fundida com o rascunho guardado e a parte resultante é validada na totalidade, pelo que um rascunho que podia ser submetido antes de uma edição continua a poder ser submetido depois dela.", "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se a parte é uma pessoa singular ou uma empresa." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo de uma pessoa. Envie este campo, ou `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Função desempenhada pela parte. Intercambiável com `roles`; quando ambas forem enviadas, são combinadas." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Cada função que a parte desempenha. Uma pessoa necessita de pelo menos uma função (aqui ou em `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Cargo de uma pessoa." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome de uma parte da empresa. Obrigatório quando `entity_type` é `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Número de registo de uma entidade empresarial." }, "email": { "type": "string", "format": "email", "description": "Para onde a ligação de verificação é enviada. Obrigatório quando a parte tem de concluir a verificação, o que depende das definições de funções e dos limiares de propriedade do fluxo." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem da empresa que a parte detém." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nacionalidade de uma pessoa ou país de constituição de uma empresa. Obrigatório para todas as partes." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campos adicionais definidos pelo fluxo." }, "skip_verification": { "type": "boolean", "default": false, "description": "Pedir para ignorar a verificação desta parte. Respeitado apenas quando a função da parte permite ignorar nas definições de Pessoas-chave do fluxo." } } }, "example": { "ownership_percent": 55 } } } }, "responses": { "200": { "description": "Rascunho atualizado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se a parte é uma pessoa singular ou uma empresa." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo de uma pessoa. Envie este campo, ou `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Função desempenhada pela parte. Intercambiável com `roles`; quando ambas forem enviadas, são combinadas." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Cada função que a parte desempenha. Uma pessoa necessita de pelo menos uma função (aqui ou em `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Cargo de uma pessoa." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome de uma parte da empresa. Obrigatório quando `entity_type` é `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Número de registo de uma entidade empresarial." }, "email": { "type": "string", "format": "email", "description": "Para onde a ligação de verificação é enviada. Obrigatório quando a parte tem de concluir a verificação, o que depende das definições de funções e dos limiares de propriedade do fluxo." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem da empresa que a parte detém." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nacionalidade de uma pessoa ou país de constituição de uma empresa. Obrigatório para todas as partes." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campos adicionais definidos pelo fluxo." }, "skip_verification": { "type": "boolean", "default": false, "description": "Pedir para ignorar a verificação desta parte. Respeitado apenas quando a função da parte permite ignorar nas definições de Pessoas-chave do fluxo." } } } } }, "example": { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 55, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } } }, "400": { "description": "A parte unificada é inválida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "non_field_errors": [ "Person parties require at least one role." ] } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão ou o rascunho não existe, ou a sessão está fora da aplicação da chave ou dos limites de uma chave com âmbito restrito.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "A sessão está finalizada (`kyb_session_not_writable`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "Limite de pedidos excedido: 300 pedidos de escrita (POST, PATCH, DELETE) por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n ownership_percent=55.0,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybPartyDraft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n {\n ownership_percent: 55.0,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", didit.SessionsUpdateKYBPartyDraftParams{\n\tOwnershipPercent: didit.Float(55.0),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybPartyDraftParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", SessionsUpdateKybPartyDraftParams.builder()\n .ownershipPercent(55.0)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybPartyDraft('33333333-4444-5555-6666-777777777777', '5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d', [\n 'ownership_percent' => 55.0,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n ownership_percent: 55.0\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", new SessionsUpdateKybPartyDraftParams\n{\n OwnershipPercent = 55.0,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Eliminar um rascunho de interveniente de KYB", "description": "Eliminar um rascunho de parte. As partes declaradas não são afetadas. Requer `write:businesses`.", "operationId": "delete_v3_session_kyb_party_draft", "x-didit-sdk": { "resource": "sessions", "method": "delete_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de empresas (KYB). Tem de pertencer à aplicação da chave de API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "draftId", "in": "path", "required": true, "description": "UUID do rascunho de parte (`draft_id` retornado quando foi criado).", "schema": { "type": "string", "format": "uuid", "example": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do fluxo do passo de KYB. Apenas necessário quando o fluxo tem mais de um nó de KYB; por predefinição, a Didit utiliza o nó próprio da sessão.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Rascunho eliminado. Sem corpo." }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão ou o rascunho não existe, ou a sessão está fora da aplicação da chave ou dos limites de uma chave com âmbito restrito.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "A sessão está finalizada (`kyb_session_not_writable`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "Limite de pedidos excedido: 300 pedidos de escrita (POST, PATCH, DELETE) por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.sessions.delete_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.sessions.deleteKybPartyDraft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Sessions.DeleteKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", didit.SessionsDeleteKYBPartyDraftParams{}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().deleteKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\");" }, { "lang": "php", "label": "PHP", "source": "sessions->deleteKybPartyDraft('33333333-4444-5555-6666-777777777777', '5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.delete_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Sessions.DeleteKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\");" } ] } }, "/v3/session/{sessionId}/kyb/parties/submit/": { "post": { "summary": "Submeter os rascunhos das partes do KYB", "description": "Declarar os rascunhos guardados como as pessoas-chave da empresa. Este é o passo alojado de Pessoas-chave sob a sua chave de API: a Didit decide, a partir das definições de funções e limiares de propriedade do fluxo, quais as partes que têm de ser verificadas, cria uma sessão individual de KYC (ou uma subsessão de KYB para um proprietário que seja uma empresa) para cada uma delas, envia os e-mails solicitados pelo fluxo e avança a sessão. Cada sessão dependente é faturada como no fluxo alojado. Os rascunhos são consumidos. Repetir a chamada após um envio bem-sucedido não altera nada e responde `200` com `already_submitted: true` e as partes que já existem. A sessão tem de estar no passo de Pessoas-chave. Envie o `kyc_session_url` de cada pessoa para a própria, ou incorpore-o. Requer `write:businesses`.", "operationId": "post_v3_session_kyb_parties_submit", "x-didit-sdk": { "resource": "sessions", "method": "submit_kyb_parties", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de Verificação de empresas (KYB). Tem de pertencer à aplicação da chave de API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nó do fluxo do passo de KYB. Apenas necessário quando o fluxo tem mais de um nó de KYB; por predefinição, a Didit utiliza o nó próprio da sessão.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "maxLength": 10, "description": "Localidade utilizada para traduzir a resposta do passo para o qual a sessão avança." } } }, "example": { "locale": "es" } } } }, "responses": { "200": { "description": "Partes declaradas (ou já declaradas).", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "next_step": { "type": "string", "nullable": true, "description": "Passo em que a sessão se encontra." }, "status": { "type": "string", "description": "Estado da sessão da empresa." }, "advanced": { "type": "boolean", "description": "`true` quando esta chamada declarou as partes e avançou a sessão." }, "already_submitted": { "type": "boolean", "description": "`true` quando as partes tinham sido declaradas por uma chamada anterior." }, "kyb_key_people_status": { "type": "string" }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/KYBKeyPeopleParty" } } } }, "example": { "valid": true, "next_step": "FINISHED", "status": "In Progress", "advanced": true, "already_submitted": false, "kyb_key_people_status": "In Progress", "parties": [] } } } }, "402": { "description": "A organização já não tem crédito para as sessões de verificação subordinadas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Insufficient credits." } } } }, "401": { "description": "A chave de API com âmbito expirou. Este é o único caso que devolve `401`: uma chave em falta, inválida ou revogada devolve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Expired key": { "summary": "A data de validade da chave já passou", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Falha de autenticação ou autorização. Uma chave em falta devolve `403`, assim como uma chave de outra aplicação, uma chave com âmbito restrito sem a permissão que este endpoint requer e um pedido proveniente de fora da lista de IPs permitidos da chave; uma chave incorreta, revogada ou expirada devolve `401`. Distinga-as através de `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Missing or invalid credentials": { "summary": "Sem cabeçalho x-api-key ou a chave falhou a validação", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Uma chave válida que pertence a uma aplicação diferente da sessão", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "Chave com âmbito não tem decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Pedido proveniente de fora da lista de permissões de IP da chave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "A sessão não existe, foi eliminada, pertence a outra aplicação ou está fora dos limites de uma chave com âmbito restrito; nenhum detalhe os distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "`kyb_no_party_drafts`: não há nada a submeter. `kyb_parties_already_submitted`: foram adicionados rascunhos após a declaração das partes. `kyb_step_mismatch`: a sessão não se encontra no passo de Pessoas-chave (`next_step` indica o respetivo passo). `kyb_session_not_writable`: a sessão está terminada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." }, "code": { "type": "string" }, "next_step": { "type": "string" } } }, "example": { "detail": "There are no draft parties to submit.", "code": "kyb_no_party_drafts" } } } }, "429": { "description": "Limite de pedidos excedido: 300 pedidos de escrita (POST, PATCH, DELETE) por minuto por chave de API. Aguarde `Retry-After` segundos antes de tentar novamente; os cabeçalhos `X-RateLimit-*` mostram o orçamento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem de erro legível." } } }, "examples": { "Rate limited": { "summary": "Orçamento esgotado para o minuto atual", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Segundos a aguardar antes de tentar novamente.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.submit_kyb_parties(\n \"33333333-4444-5555-6666-777777777777\",\n locale=\"es\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.submitKybParties(\"33333333-4444-5555-6666-777777777777\", {\n locale: \"es\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.SubmitKYBParties(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsSubmitKYBPartiesParams{\n\tLocale: didit.String(\"es\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsSubmitKybPartiesParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().submitKybParties(\"33333333-4444-5555-6666-777777777777\", SessionsSubmitKybPartiesParams.builder()\n .locale(\"es\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->submitKybParties('33333333-4444-5555-6666-777777777777', [\n 'locale' => 'es',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.submit_kyb_parties(\n \"33333333-4444-5555-6666-777777777777\",\n locale: \"es\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.SubmitKybPartiesAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsSubmitKybPartiesParams\n{\n Locale = \"es\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/files-export/": { "post": { "summary": "Exportar todos os ficheiros de uma sessão", "description": "Iniciar a preparação de um ficheiro ZIP com todas as imagens, vídeos e documentos de uma sessão de Verificação de utilizadores (KYC) ou de Verificação de empresas (KYB), na qualidade original: os ficheiros são guardados no ZIP tal como foram capturados, sem nunca serem recomprimidos. Responde `202` com a exportação; consulte-a com `GET /v3/session/{sessionId}/files-export/{exportId}/` até que `status` seja `READY` e, em seguida, transfira `download_url`. Enquanto uma exportação da mesma sessão ainda estiver a ser preparada, essa exportação é devolvida em vez de uma nova.\n\nO ficheiro ZIP é eliminado 24 horas após estar pronto e imediatamente quando a sessão for eliminada. Uma sessão eliminada não pode ser exportada. Todas as exportações e todas as ligações de transferência fornecidas são registadas no registo de auditoria da sessão. Uma chave de API com âmbito restrito necessita de `media: read` e `decisions: read`; um utilizador da consola necessita do privilégio para ler sessões.", "operationId": "post_v3_session_files_export", "x-didit-sdk": { "resource": "sessions", "method": "export_files", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação (o `session_id` retornado por `POST /v3/session/`). Aceita IDs de sessão de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB). Uma sessão eliminada retorna `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/files-export/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.export_files(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.exportFiles(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ExportFiles(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().exportFiles(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->exportFiles('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.export_files(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ExportFilesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "A exportação, a ser preparada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFilesExport" }, "example": { "export_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_id": "11111111-2222-3333-4444-555555555555", "status": "PENDING", "file_count": null, "size_bytes": null, "download_url": null, "expires_at": null, "error": null, "created_at": "2026-10-29T12:00:03Z", "completed_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/files-export/{exportId}/": { "get": { "summary": "Obter exportação de ficheiros de sessão", "description": "Progresso de uma exportação iniciada com `POST /v3/session/{sessionId}/files-export/`. Assim que `status` for `READY`, `download_url` é um URL assinado do ZIP que permanece válido por um curto período de tempo; leia a exportação novamente para obter um novo até `expires_at`. Cada leitura que forneça uma ligação de transferência é registada no registo de auditoria da sessão. Uma exportação de uma sessão eliminada devolve `404`.", "operationId": "get_v3_session_files_export", "x-didit-sdk": { "resource": "sessions", "method": "get_files_export", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID da sessão de verificação (o `session_id` retornado por `POST /v3/session/`). Aceita IDs de sessão de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB). Uma sessão eliminada retorna `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "exportId", "in": "path", "required": true, "description": "O `export_id` devolvido por `POST /v3/session/{sessionId}/files-export/`.", "schema": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/files-export/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.get_files_export(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.getFilesExport(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.GetFilesExport(ctx, \"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().getFilesExport(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->getFilesExport('11111111-2222-3333-4444-555555555555', 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.get_files_export(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.GetFilesExportAsync(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "A exportação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFilesExport" }, "example": { "export_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_id": "11111111-2222-3333-4444-555555555555", "status": "READY", "file_count": 9, "size_bytes": 18734120, "download_url": "https://storage.example.com/session/11111111-2222-3333-4444-555555555555/files-export/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/session-42-files.zip?X-Amz-Signature=...", "expires_at": "2026-10-30T12:00:41Z", "error": null, "created_at": "2026-10-29T12:00:03Z", "completed_at": "2026-10-29T12:00:41Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/travel-rule/unmatched/": { "get": { "summary": "Listar depósitos não correspondidos da Travel Rule", "description": "Depósitos de entrada que ainda aguardam os dados da Travel Rule do VASP de origem: a sua transferência tem o estado `AWAITING_COUNTERPARTY`, `NOT_ENOUGH_COUNTERPARTY_DATA` ou `COUNTERPARTY_VASP_NOT_FOUND`, nenhuma mensagem recebida está emparelhada com eles e ninguém os fez corresponder manualmente. As linhas e os filtros são os mesmos que em `GET /v3/travel-rule/transfers/`, as mais recentes primeiro, paginadas com `limit` (predefinição 50) e `offset`. Emparelhe um depósito com a mensagem enviada pelo VASP de origem com `POST /v3/travel-rule/unmatched/{transaction_uuid}/match/`.", "operationId": "listUnmatchedTravelRuleDeposits", "x-didit-sdk": { "resource": "travel_rule.unmatched_deposits", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "INBOUND, OUTBOUND, ou ambos separados por vírgula. Sensível a maiúsculas e minúsculas." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Um ou mais estados de transferência, separados por vírgulas." }, { "name": "rail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Um ou mais de INTERNAL, TRP, GTR, TRUST, VERIFYVASP, SYGNA, EMAIL, TEST_VASP, separados por vírgulas." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "withdrawal, deposit ou message, separados por vírgulas." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A moeda da transação, sem distinção entre maiúsculas e minúsculas." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Transferências criadas neste dia ou após o mesmo (UTC), AAAA-MM-DD." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Transferências criadas neste dia ou antes do mesmo (UTC), AAAA-MM-DD." }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "O `id` de uma entrada do diretório ou membro da rede Didit a partir de GET /v3/travel-rule/vasps/: as suas transferências com essa contraparte. Um valor que não seja um id válido responde com 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "description": "Tamanho da página, predefinição 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "description": "Linhas a ignorar." } ], "responses": { "200": { "description": "Uma página de depósitos sem correspondência.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "id": "7d3a1c55-0b9e-4d52-8a3c-1f6e2b9d4a08", "transaction_id": "c41f9b2e-5a8d-4e0c-9f17-3b6d8a2e5c91", "txn_id": "dep-2026-10-20-0007", "txn_date": "2026-10-19T08:41:12Z", "kind": "deposit", "direction": "INBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": null, "created_at": "2026-10-19T08:41:13Z" } ] } } } }, "400": { "description": "Um valor de filtro não é válido.", "content": { "application/json": { "example": { "start_date": [ "Use the YYYY-MM-DD format." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.unmatched_deposits.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.unmatchedDeposits.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.UnmatchedDeposits.ListAutoPaging(ctx, didit.TravelRuleUnmatchedDepositsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().unmatchedDeposits().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->unmatchedDeposits->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.unmatched_deposits.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.UnmatchedDeposits.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/travel-rule/unmatched/{transaction_uuid}/match/": { "post": { "summary": "Associar um depósito da Travel Rule a uma mensagem recebida", "operationId": "matchUnmatchedTravelRuleDeposit", "x-didit-sdk": { "resource": "travel_rule.unmatched_deposits", "method": "match", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "description": "Associe um depósito recebido que ainda está a aguardar os dados do ordenante com a mensagem Travel Rule enviada pela VASP ordenante correspondente. O depósito assume os dados do ordenante, a VASP da contraparte e a rede da mensagem, e ambas as transferências registam a correspondência nas suas respetivas linhas cronológicas. `transaction_uuid` é o `transaction_id` do depósito proveniente de `GET /v3/travel-rule/unmatched/`. O `transaction_id` no corpo é o `transaction_id` da mensagem recebida, a partir de uma linha de `GET /v3/travel-rule/transfers/?kind=message`; o `id` próprio da transferência não é encontrado. A mensagem deve ser referente ao mesmo ativo do depósito. Um depósito ou mensagem eliminado da Consola responde com `404`; um que já tenha avançado (correspondido, ou já não esteja a aguardar) responde com `409`.", "parameters": [ { "name": "transaction_uuid", "in": "path", "required": true, "description": "O `transaction_id` do depósito não correspondido.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleManualMatchRequest" }, "example": { "transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24" } } } }, "responses": { "200": { "description": "Ambas as transferências após a correspondência.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleManualMatchResponse" }, "example": { "deposit": { "id": "7d3a1c55-0b9e-4d52-8a3c-1f6e2b9d4a08", "transaction_id": "c41f9b2e-5a8d-4e0c-9f17-3b6d8a2e5c91", "txn_id": "dep-2026-10-20-0007", "txn_date": "2026-10-19T08:41:12Z", "kind": "deposit", "direction": "INBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Example Counterparty VASP", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24", "deadline_at": null, "created_at": "2026-10-19T08:41:13Z" }, "message": { "id": "2b8e6f10-9c3a-47d1-b5e2-0a4c7d9f3e66", "transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24", "txn_id": "msg-2026-10-20-0003", "txn_date": "2026-10-19T08:41:12Z", "kind": "message", "direction": "INBOUND", "status": "COMPLETED", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Origin CASP SL", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": "2026-10-21T08:41:13Z", "created_at": "2026-10-19T08:41:13Z" } } } } }, "400": { "description": "Erro de validação: `transaction_id` está em falta, é o próprio depósito, não é uma mensagem Travel Rule recebida ou refere-se a um ativo diferente do depósito; ou a transação no caminho não é um depósito de entrada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Error": { "value": { "transaction_id": [ "The travel rule message is for a different asset than the deposit." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Depósito ou mensagem desconhecidos, ou um deles foi eliminado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No TravelRuleTransfer matches the given query." } } } }, "409": { "description": "O depósito já não está a aguardar dados do ordenante ou a mensagem já foi associada a um depósito.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Error": { "value": { "detail": "This deposit is no longer waiting for originator data." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.unmatched_deposits.match(\n \"11111111-2222-3333-4444-555555555555\",\n transaction_id=\"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.unmatchedDeposits.match(\"11111111-2222-3333-4444-555555555555\", {\n transaction_id: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UnmatchedDeposits.Match(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleManualMatchRequest{\n\tTransactionID: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleManualMatchRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().unmatchedDeposits().match(\"11111111-2222-3333-4444-555555555555\", TravelRuleManualMatchRequest.builder()\n .transactionId(\"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->unmatchedDeposits->match('11111111-2222-3333-4444-555555555555', [\n 'transaction_id' => 'e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.unmatched_deposits.match(\n \"11111111-2222-3333-4444-555555555555\",\n transaction_id: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UnmatchedDeposits.MatchAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleManualMatchRequest\n{\n TransactionId = \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } } }, "components": { "schemas": { "DocumentAIDetectedCode": { "type": "object", "required": [ "type", "page_number", "position", "x", "y", "width", "height", "page_width", "page_height", "raw_payload", "parsed_payload" ], "properties": { "type": { "type": "string", "description": "Simbologia detetada, por exemplo `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` ou `PDF_417`." }, "page_number": { "type": "integer", "minimum": 1, "description": "Número de página de base 1." }, "position": { "type": "array", "nullable": true, "description": "Polígono detetado em coordenadas de píxeis da página renderizada. `null` quando não está disponível nenhuma localização fiável.", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "integer" } } }, "x": { "type": "integer", "nullable": true, "description": "Margem esquerda da caixa delimitadora em píxeis da página renderizada." }, "y": { "type": "integer", "nullable": true, "description": "Limite superior da caixa delimitadora em píxeis da página renderizada." }, "width": { "type": "integer", "nullable": true, "description": "Largura da caixa delimitadora em píxeis da página renderizada." }, "height": { "type": "integer", "nullable": true, "description": "Altura da caixa delimitadora em píxeis da página renderizada." }, "page_width": { "type": "integer", "description": "Largura da página renderizada em píxeis." }, "page_height": { "type": "integer", "description": "Altura da página renderizada em píxeis." }, "raw_payload": { "type": "string", "description": "Payload do descodificador em bruto como string base64 quando disponível; caso contrário, uma string vazia." }, "parsed_payload": { "nullable": true, "description": "String descodificada ou valor estruturado. `null` quando o código foi localizado mas não pôde ser descodificado." } } }, "SessionImportJob": { "type": "object", "required": [ "uuid", "status", "import_type", "source_format", "source_filename", "total_rows", "processed_rows", "created_count", "updated_count", "skipped_count", "failed_count" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID da tarefa de importação. Utilize este valor para consultar o progresso e obter erros das linhas." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "PAUSED", "CANCELLED", "READY" ] }, "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ] }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ] }, "source_filename": { "type": "string" }, "total_rows": { "type": "integer", "format": "int64" }, "processed_rows": { "type": "integer", "format": "int64" }, "checkpoint_row": { "type": "integer", "format": "int64" }, "created_count": { "type": "integer", "format": "int64" }, "updated_count": { "type": "integer", "format": "int64" }, "skipped_count": { "type": "integer", "format": "int64" }, "failed_count": { "type": "integer", "format": "int64" }, "total_media_bytes": { "type": "integer", "format": "int64" }, "last_error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "state": { "type": "string", "enum": [ "ready", "queued", "running", "paused", "completed", "errors", "failed", "cancelled" ], "description": "O estado da tarefa tal como apresentado na consola; `errors` corresponde a uma tarefa concluída com linhas rejeitadas." }, "source": { "type": "string", "enum": [ "file", "api", "provider" ] }, "provider": { "type": "string", "description": "Origem da migração; vazio para uma importação por ficheiro ou API." }, "provider_options": { "type": "object" }, "credential_hint": { "type": "string", "description": "Os primeiros carateres da chave que a migração contém. A chave em si nunca é devolvida." }, "credentials_expires_at": { "type": "string", "format": "date-time", "nullable": true }, "resumes_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando uma tarefa pausada pelo limite de pedidos do fornecedor é retomada autonomamente." }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "is_dry_run": { "type": "boolean" }, "dry_run_summary": { "type": "object", "description": "O que uma execução de teste encontrou: `total`, `by_status`, `already_in_didit`, `same_person`, `not_finished`, `failed`, `unmapped_statuses`." }, "face_templates_enabled": { "type": "boolean" }, "lawful_basis_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "not_finished_count": { "type": "integer", "format": "int64" }, "same_person_count": { "type": "integer", "format": "int64" }, "face_templates_count": { "type": "integer", "format": "int64" }, "face_duplicates_count": { "type": "integer", "format": "int64" }, "face_blocklist_hits_count": { "type": "integer", "format": "int64" }, "created_by_name": { "type": "string", "nullable": true }, "created_by_email": { "type": "string", "nullable": true } } }, "SessionImportError": { "type": "object", "required": [ "uuid", "row_number", "error", "raw_row" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "row_number": { "type": "integer", "format": "int64" }, "external_id": { "type": "string", "nullable": true }, "error": { "type": "string" }, "raw_row": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "BrandingCustomizationUpdate": { "type": "object", "description": "Corpo de atualização parcial de personalização de marca. Forneça apenas os campos que pretende alterar. Cores hexadecimais aceitam `#RRGGBB` ou `#RRGGBBAA`. Domínio personalizado e e-mail com marca branca não são aceites aqui.", "properties": { "color_primary": { "type": "string", "description": "Cor dos cabeçalhos / texto principal." }, "color_secondary": { "type": "string", "description": "Cor do parágrafo / texto secundário." }, "color_background": { "type": "string", "description": "Cor de fundo da página." }, "color_panel": { "type": "string", "description": "Cor do painel / de destaque." }, "color_panel_10": { "type": "string", "description": "Cor do painel com 10% de opacidade." }, "color_on_panel_1": { "type": "string", "description": "Cor do texto de apoio nos painéis." }, "color_on_panel_2": { "type": "string", "description": "Cor da etiqueta / do distintivo nos painéis." }, "color_on_background": { "type": "string", "description": "Cor do texto sobre o fundo." }, "color_button_1": { "type": "string", "description": "Cor do botão principal." }, "color_button_2": { "type": "string", "description": "Cor do botão secundário." }, "color_button_text_1": { "type": "string", "description": "Cor do texto do botão principal." }, "color_button_text_2": { "type": "string", "description": "Cor do texto do botão secundário." }, "color_pill_text": { "type": "string", "description": "Cor do texto para pílulas, campos de entrada e seletores." }, "border_radius_panel": { "type": "integer", "minimum": 0, "description": "Raio dos cantos do painel em píxeis." }, "border_radius_buttons": { "type": "integer", "minimum": 0, "description": "Raio dos cantos do botão em píxeis." }, "font_family": { "type": "string", "description": "Nome da família de tipos de letra do Google (ex.: `Inter`, `AR One Sans`)." }, "font_weight": { "type": "string", "description": "Espessura da fonte disponível para a família selecionada (por exemplo, `regular`, `500`, `700`)." }, "app_public_name": { "type": "string", "nullable": true, "description": "Nome público apresentado no fluxo de verificação." }, "privacy_policy_url": { "type": "string", "nullable": true, "description": "URL da política de privacidade apresentado ao utilizador final." }, "skip_welcome_screen": { "type": "boolean", "description": "Ignorar o ecrã inicial de boas-vindas." }, "disable_login_with_didit": { "type": "boolean", "description": "Continuar como convidado em vez de mostrar o ecrã de início de sessão com o Didit. Não pode ser reposto para `false` enquanto um domínio personalizado estiver configurado (400)." }, "hide_progress_bar": { "type": "boolean", "description": "Ocultar a barra de progresso durante o fluxo." }, "callback_seconds": { "type": "integer", "minimum": 0, "description": "Atraso (segundos) antes de redirecionar para o URL de retorno." }, "delete_logo_square": { "type": "boolean", "description": "Quando `true`, remove o logótipo quadrado atual." }, "delete_logo_rectangular": { "type": "boolean", "description": "Quando `true`, remove o logótipo retangular atual." }, "delete_logo_rectangular_dark": { "type": "boolean", "description": "Quando `true`, remove o logótipo atual do modo escuro, e `logo_rectangular_dark` passa a apresentar `null`. Se o mesmo pedido multipart também enviar `image_rectangular_dark`, o carregamento prevalece." }, "delete_favicon": { "type": "boolean", "description": "Quando `true`, remove o favicon atual." } } }, "BrandingCustomization": { "type": "object", "description": "Personalização de marca branca para uma aplicação: cores, tipos de letra, raios, URLs do logótipo e opções de UI/UX. Os URLs do logótipo são apenas de leitura (defina-os carregando imagens). O domínio personalizado e o e-mail de marca branca não estão incluídos.", "properties": { "color_primary": { "type": "string" }, "color_secondary": { "type": "string" }, "color_background": { "type": "string" }, "color_panel": { "type": "string" }, "color_panel_10": { "type": "string" }, "color_on_panel_1": { "type": "string" }, "color_on_panel_2": { "type": "string" }, "color_on_background": { "type": "string" }, "color_button_1": { "type": "string" }, "color_button_2": { "type": "string" }, "color_button_text_1": { "type": "string" }, "color_button_text_2": { "type": "string" }, "color_pill_text": { "type": "string" }, "border_radius_panel": { "type": "integer" }, "border_radius_buttons": { "type": "integer" }, "font_family": { "type": "string" }, "font_weight": { "type": "string" }, "font_url": { "type": "string", "nullable": true, "description": "Apenas de leitura. URL resolvido da folha de estilos do Google Fonts para a família selecionada." }, "logo_square": { "type": "string", "nullable": true, "description": "URL apenas de leitura do logótipo quadrado. Carregue através de `image_square`." }, "logo_rectangular": { "type": "string", "nullable": true, "description": "URL apenas de leitura do logótipo retangular. Carregue através de `image_rectangular`." }, "logo_rectangular_dark": { "type": "string", "format": "uri", "nullable": true, "description": "Apenas de leitura. URL assinado temporário do logótipo retangular para o modo escuro, apresentado num fundo escuro. `null` quando nenhum logótipo escuro estiver definido ou logótipos retangulares não forem apresentados para a sua conta. Carregue-o com `image_rectangular_dark`." }, "favicon": { "type": "string", "nullable": true, "description": "URL apenas de leitura do favicon. Carregue através de `image_favicon`." }, "app_public_name": { "type": "string", "nullable": true }, "privacy_policy_url": { "type": "string", "nullable": true }, "skip_welcome_screen": { "type": "boolean" }, "disable_login_with_didit": { "type": "boolean" }, "hide_progress_bar": { "type": "boolean" }, "callback_seconds": { "type": "integer" } } }, "WebhookEvent": { "type": "string", "description": "Nome de evento de webhook suportado. Utilize estas strings exatas em `subscribed_events`; valores não suportados são rejeitados.", "enum": [ "status.updated", "data.updated", "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created", "transaction.created", "transaction.status.updated", "travel_rule.status.updated", "workflow.compliance_changed", "transaction_rule_suggestions.created", "auth.signup", "auth.login", "auth.login_failed", "auth.password_reset_requested", "auth.password_reset_completed", "auth.mfa_changed", "auth.new_device", "auth.account_locked", "investigator.report.ready", "investigator.decision.automated", "investigator.decision.overridden", "investigator.decision.contested", "investigator.question.raised", "investigator.automation.paused", "investigator.rfi.answered", "investigator.rfi.overdue", "investigator.drift.detected", "investigator.sla.breached", "investigator.qa.failed", "investigator.external.report.ready" ] }, "WebhookSubscribedEvents": { "type": "array", "description": "Filtro de eventos para este destino do webhook. O Didit entrega apenas webhooks cujo tipo de evento corresponda exatamente a um destes valores — não existe subscrição com carateres universais. Ao ser enviada, a lista deve conter pelo menos um evento válido (um `[]` explícito é rejeitado com 400); um destino cuja lista esteja vazia (campo omitido na criação) não recebe nada. Na atualização, a lista é substituída integralmente, nunca fundida.", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEvent" }, "example": [ "status.updated", "data.updated" ] }, "PhoneVerificationSendResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID de sessão da verificação. Um envio de `Retry` devolve o mesmo `request_id` que o envio original. Este id surge na Business Console, é devolvido novamente por um `POST /v3/phone/check/` finalizado e pode ser passado para `GET /v3/session/{sessionId}/decision/`." }, "status": { "type": "string", "enum": [ "Success", "Retry", "Blocked" ], "description": "`Success` — OTP enviado para uma nova verificação. `Retry` — OTP reenviado para a verificação pendente criada por um envio anterior. `Blocked` — a camada antifraude recusou o envio; a verificação é imediatamente finalizada como `Declined` e nada é faturado." }, "reason": { "type": "string", "nullable": true, "description": "O motivo pelo qual um envio foi `Blocked` (por exemplo, `repeated_attempts`, `suspicious`, `spam`). `null` em `Success` e `Retry`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do objeto `vendor_data` armazenado na sessão (do primeiro envio)." }, "metadata": { "type": "object", "nullable": true, "description": "Eco do objeto `metadata` armazenado na sessão (do primeiro envio)." } } }, "PhoneVerificationCheckResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Em `Approved`/`Declined`: o id da sessão da verificação correspondente — idêntico ao `request_id` devolvido por `POST /v3/phone/send/`. Em `Failed` e `Expired or Not Found`: um UUID pontual aleatório que não pode ser consultado mais tarde." }, "status": { "type": "string", "enum": [ "Approved", "Declined", "Failed", "Expired or Not Found" ], "description": "`Approved` — código correto, sem risco de recusa. `Declined` — terminal: um risco de recusa correspondeu ou o limite de tentativas (3) esgotou-se. `Failed` — código incorreto, tentativas restantes. `Expired or Not Found` — nenhuma verificação pendente para este número nos últimos 5 minutos." }, "message": { "type": "string", "description": "Explicação legível do resultado, incluindo o número de tentativas restantes após um código incorreto." }, "phone": { "type": "object", "nullable": true, "description": "Relatório telefónico completo. Presente (não nulo) apenas em resultados finalizados (`Approved`/`Declined`); `null` em `Failed` e ausente em `Expired or Not Found`.", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished", "Expired" ], "description": "Estado final da verificação de telefone. Corresponde ao `status` de nível superior para verificações finalizadas." }, "phone_number_prefix": { "type": "string", "description": "Indicativo telefónico do país com `+` inicial (ex.: `+1`).", "example": "+1" }, "phone_number": { "type": "string", "description": "Número nacional sem o indicativo do país.", "example": "4155552671" }, "full_number": { "type": "string", "description": "Número completo no formato E.164.", "example": "+14155552671" }, "country_code": { "type": "string", "nullable": true, "description": "País ISO 3166-1 alfa-2 do número.", "example": "US" }, "country_name": { "type": "string", "description": "Nome completo do país derivado de `country_code`.", "example": "United States" }, "carrier": { "type": "object", "description": "Rede atual que serve o número, a partir da consulta de operadora executada na finalização.", "properties": { "name": { "type": "string", "description": "Nome da operadora. Cadeia vazia quando a pesquisa não a conseguiu identificar." }, "type": { "type": "string", "description": "Tipo de linha comunicado pela consulta: `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `pager`, `payphone`, `satellite`, `service`, `shared_cost`, `short_codes_commercial`, `calling_cards`, `local_rate`, `universal_access`, `voice_mail`, `other` ou `unknown`." } } }, "is_disposable": { "type": "boolean", "description": "`true` quando o número pertence a um serviço de números temporários/descartáveis." }, "is_virtual": { "type": "boolean", "description": "`true` quando o tipo de linha é virtual (`voip`, `isp` ou `vpn`)." }, "verification_method": { "type": "string", "description": "Canal que efetivamente entregou o OTP após a confirmação da entrega (por exemplo, `whatsapp`, `sms`); até lá, o canal solicitado." }, "verification_attempts": { "type": "integer", "description": "Número de envios de OTP para esta verificação (1, ou 2 após tentar novamente)." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o código correto foi introduzido. `null` se a verificação nunca tiver sido aprovada." }, "warnings": { "type": "array", "description": "Avisos de risco registados durante a verificação (duplicado, descartável, VoIP, tentativas excedidas, lista de bloqueio, etc.). Array vazio quando não existirem.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Funcionalidade que gerou o aviso. Aqui é sempre `PHONE`." }, "risk": { "type": "string", "description": "Código de risco legível por máquina." }, "additional_data": { "type": "object", "nullable": true, "description": "Contexto específico do risco (por exemplo, o ID de sessão duplicado para riscos de duplicado). `null` quando o risco não contiver dados adicionais." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravidade. Os riscos `error` levam à recusa da verificação, `warning` sinaliza-a para revisão e `information` é registada sem afetar o estado." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos sobre o risco." }, "long_description": { "type": "string", "description": "Explicação legível do risco." } } } }, "lifecycle": { "type": "array", "description": "Registo de auditoria cronológico da verificação. O `type` de evento é um dos seguintes: `PHONE_VERIFICATION_MESSAGE_SENT`, `PHONE_VERIFICATION_RETRY_MESSAGE_SENT`, `PHONE_VERIFICATION_BLOCKED`, `PHONE_DELIVERY_DELIVERED`, `PHONE_DELIVERY_UNDELIVERABLE`, `VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`, `PHONE_VERIFICATION_APPROVED`, `PHONE_VERIFICATION_DECLINED`, `PHONE_VERIFICATION_IN_REVIEW`, `PHONE_VERIFICATION_EXPIRED`.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo de evento." }, "timestamp": { "type": "string", "format": "date-time", "description": "Quando o evento aconteceu." }, "details": { "type": "object", "nullable": true, "description": "Payload específico do evento. Eventos de envio: `{status, reason, channel, actual_channel}` (`actual_channel` é preenchido assim que a entrega for confirmada). Eventos de entrega: `{channel, status}`. Eventos de introdução de código: `{code_tried, status}`. Eventos de estado final: `null`, ou `{reason}` quando recusada ou em análise." }, "fee": { "type": "number", "description": "Montante em USD faturado por este evento. Diferente de zero apenas em eventos de envio (o preço de entrega); 0 para introduções de código, confirmações de entrega e eventos de estado." } } } }, "matches": { "type": "array", "description": "Outras sessões da sua aplicação (KYC, KYB ou API) onde o mesmo número de telefone foi utilizado por um utilizador diferente (`vendor_data` diferente). Até 5 entradas; uma correspondência sintética de entrada na lista de bloqueio surge primeiro, quando presente (correspondências derivadas de sessões mantêm a ordem da consulta). Array vazio quando não existirem correspondências.", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID de sessão da outra verificação que utilizou este número de telefone." }, "session_number": { "type": "integer", "description": "Número sequencial legível da sessão." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` dessa sessão." }, "verification_date": { "type": "string", "description": "Quando essa sessão foi criada (`YYYY-MM-DDTHH:MM:SSZ`)." }, "phone_number": { "type": "string", "description": "O número de telefone correspondido." }, "status": { "type": "string", "description": "Estado dessa sessão (por exemplo, `Approved`, `Declined`, `In Progress`)." }, "is_blocklisted": { "type": "boolean", "description": "Se o número de telefone está na lista de bloqueio da sua aplicação." }, "api_service": { "type": "string", "nullable": true, "description": "Para sessões do tipo API, a API autónoma que a criou (por exemplo, `PHONE_VERIFICATION`); `null` para sessões de verificação normais." }, "source": { "type": "string", "description": "Onde a correspondência foi encontrada. Habitualmente `session`; uma ocorrência na lista de bloqueio através de uma entrada de lista da organização prefixa uma correspondência sintética com `source: \"list_entry\"` e `session_id`/`session_number` nulos." } } } }, "phone_social": { "$ref": "#/components/schemas/PhoneSocialFootprint" }, "phone_intelligence": { "allOf": [ { "$ref": "#/components/schemas/PhoneIntelligence" } ], "description": "Sinais de inteligência telefónica. Presente apenas quando `enable_enrichment` foi `true` na verificação." } } }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` da sessão da verificação correspondente. `null` em `Expired or Not Found`." }, "metadata": { "type": "object", "nullable": true, "description": "`metadata` da sessão da verificação correspondente. `null` em `Expired or Not Found`." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora desta resposta de verificação." } } }, "EmailVerificationSendResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID de sessão da verificação. Um envio de `Retry` devolve o mesmo `request_id` que o envio original. Este id surge na Business Console, é devolvido novamente por um `POST /v3/email/check/` finalizado e pode ser passado para `GET /v3/session/{sessionId}/decision/`." }, "status": { "type": "string", "enum": [ "Success", "Retry", "Undeliverable" ], "description": "`Success` — OTP enviado por e-mail para uma nova verificação (faturado). `Retry` — novo OTP enviado por e-mail para a verificação pendente criada por um envio anterior (gratuito). `Undeliverable` — o endereço falhou a validação de capacidade de entrega ou a mensagem não pôde ser enviada; a verificação é imediatamente finalizada como `Declined` e nada é faturado." }, "reason": { "type": "string", "nullable": true, "enum": [ "email_can_not_be_delivered", null ], "description": "`email_can_not_be_delivered` quando `status` é `Undeliverable`; `null` caso contrário." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do objeto `vendor_data` armazenado na sessão (do primeiro envio)." }, "metadata": { "type": "object", "nullable": true, "description": "Eco do objeto `metadata` armazenado na sessão (do primeiro envio)." } } }, "EmailVerificationCheckResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Em `Approved`/`Declined`: o id da sessão da verificação correspondente — idêntico ao `request_id` devolvido por `POST /v3/email/send/`. Em `Failed` e `Expired or Not Found`: um UUID pontual aleatório que não pode ser consultado mais tarde." }, "status": { "type": "string", "enum": [ "Approved", "Declined", "Failed", "Expired or Not Found" ], "description": "`Approved` — código correto, sem risco de recusa. `Declined` — terminal: um risco de recusa correspondeu ou o limite de tentativas (3) esgotou-se. `Failed` — código incorreto, tentativas restantes. `Expired or Not Found` — nenhuma verificação pendente para este endereço nos últimos 5 minutos." }, "message": { "type": "string", "description": "Explicação legível do resultado, incluindo o número de tentativas restantes após um código incorreto." }, "email": { "type": "object", "nullable": true, "description": "Relatório completo de e-mail. Presente (não nulo) apenas em resultados finalizados (`Approved`/`Declined`); `null` em `Failed` e ausente em `Expired or Not Found`.", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished", "Expired" ], "description": "Estado final da verificação de e-mail. Corresponde ao `status` de nível superior para verificações finalizadas." }, "email": { "type": "string", "format": "email", "description": "O endereço de e-mail verificado.", "example": "alice@example.com" }, "is_breached": { "type": "boolean", "description": "`true` quando o endereço surge em violações de dados conhecidas (pesquisa de informações sobre violações executada na finalização)." }, "breaches": { "type": "array", "description": "Até 5 violações conhecidas mais recentes que contêm este endereço. Array vazio (ou omitido) quando `is_breached` for `false`.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Identificador da violação." }, "domain": { "type": "string", "description": "Domínio do serviço afetado pela violação." }, "breach_date": { "type": "string", "format": "date", "description": "Data em que a violação ocorreu." }, "breach_emails_count": { "type": "integer", "description": "Número total de contas expostas na violação de dados." }, "description": { "type": "string", "description": "Descrição legível da violação (pode conter marcação HTML)." }, "logo_path": { "type": "string", "description": "URL do logótipo do serviço comprometido." }, "data_classes": { "type": "array", "items": { "type": "string" }, "description": "Categorias de dados expostos, em snake_case (por ex., `email_addresses`, `passwords`)." }, "is_verified": { "type": "boolean", "description": "Indica se a violação foi verificada como legítima." } } } }, "is_disposable": { "type": "boolean", "description": "`true` quando o domínio pertence a um fornecedor conhecido de e-mail descartável/temporário." }, "is_undeliverable": { "type": "boolean", "description": "`true` quando o endereço não pode receber correio (falha na validação de sintaxe ou DNS/MX, ou a mensagem foi devolvida)." }, "verification_attempts": { "type": "integer", "description": "Número de envios de OTP para esta verificação (1, ou 2 após tentar novamente)." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o código correto foi introduzido. `null` se a verificação nunca tiver sido aprovada." }, "warnings": { "type": "array", "description": "Avisos de risco registados durante a verificação (duplicado, violado, descartável, não entregue, tentativas excedidas, lista de bloqueio, etc.). Array vazio quando não existirem.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Funcionalidade que gerou o aviso. Aqui é sempre `EMAIL`." }, "risk": { "type": "string", "description": "Código de risco legível por máquina." }, "additional_data": { "type": "object", "nullable": true, "description": "Contexto específico do risco (por exemplo, o ID de sessão duplicado para riscos de duplicado). `null` quando o risco não contiver dados adicionais." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravidade. Os riscos `error` levam à recusa da verificação, `warning` sinaliza-a para revisão e `information` é registada sem afetar o estado." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos sobre o risco." }, "long_description": { "type": "string", "description": "Explicação legível do risco." } } } }, "lifecycle": { "type": "array", "description": "Registo de auditoria cronológico da verificação. O `type` de evento é um dos seguintes: `EMAIL_VERIFICATION_MESSAGE_SENT`, `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`, `VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`, `EMAIL_VERIFICATION_APPROVED`, `EMAIL_VERIFICATION_DECLINED`, `EMAIL_VERIFICATION_IN_REVIEW`, `EMAIL_VERIFICATION_EXPIRED`.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo de evento." }, "timestamp": { "type": "string", "format": "date-time", "description": "Quando o evento aconteceu." }, "details": { "type": "object", "nullable": true, "description": "Payload específico do evento. Eventos de envio: `{status, reason}`. Eventos de introdução de código: `{code_tried, status}`. Eventos de estado final: `null`, ou `{reason}` quando recusada ou em análise." }, "fee": { "type": "number", "description": "Montante em USD faturado por este evento. Diferente de zero apenas no primeiro envio bem-sucedido; 0 para novas tentativas, introduções de código e eventos de estado." } } } }, "matches": { "type": "array", "description": "Outras sessões da sua aplicação (KYC, KYB ou API) onde o mesmo endereço de e-mail foi utilizado por um utilizador diferente (`vendor_data` diferente). Até 5 entradas; uma correspondência sintética de lista de bloqueio de uma entrada de lista é adicionada no início quando presente (e apenas quando não existir nenhum e-mail na lista de bloqueio derivado da sessão) — as correspondências derivadas da sessão mantêm a ordem de created_at. Matriz vazia quando não existirem correspondências.", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID de sessão da outra verificação que utilizou este endereço de e-mail." }, "session_number": { "type": "integer", "description": "Número sequencial legível da sessão." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` dessa sessão." }, "verification_date": { "type": "string", "description": "Quando essa sessão foi criada (`YYYY-MM-DDTHH:MM:SSZ`)." }, "email": { "type": "string", "description": "O endereço de e-mail correspondido." }, "status": { "type": "string", "description": "Estado dessa sessão (por exemplo, `Approved`, `Declined`, `In Progress`)." }, "is_blocklisted": { "type": "boolean", "description": "Indica se o endereço de e-mail está na lista de bloqueio da sua aplicação." }, "api_service": { "type": "string", "nullable": true, "description": "Para sessões do tipo API, a API autónoma que a criou (por exemplo, `PHONE_VERIFICATION`); `null` para sessões de verificação normais." }, "source": { "type": "string", "description": "Onde a correspondência foi encontrada. Habitualmente `session`; uma ocorrência na lista de bloqueio através de uma entrada de lista da organização prefixa uma correspondência sintética com `source: \"list_entry\"` e `session_id`/`session_number` nulos." } } } }, "email_social": { "$ref": "#/components/schemas/EmailSocialFootprint" }, "email_intelligence": { "allOf": [ { "$ref": "#/components/schemas/EmailIntelligence" } ], "description": "Sinais de inteligência de e-mail. Presentes apenas quando `enable_enrichment` foi `true` na verificação." } } }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` da sessão da verificação correspondente. `null` em `Expired or Not Found`." }, "metadata": { "type": "object", "nullable": true, "description": "`metadata` da sessão da verificação correspondente. `null` em `Expired or Not Found`." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora desta resposta de verificação." } } }, "WorkflowListItem": { "type": "object", "description": "Uma versão do fluxo na vista de lista.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID por versão. Utilize como `{settings_uuid}` para obter/atualizar/eliminar e como `workflow_id` ao criar sessões." }, "workflow_id": { "type": "string", "format": "uuid", "description": "ID de grupo estável partilhado por todas as versões do mesmo fluxo. É igual a `uuid` para a versão 1." }, "workflow_label": { "type": "string", "description": "Nome de apresentação do fluxo." }, "workflow_type": { "type": "string", "nullable": true, "description": "Tipo base para fluxos simples: `kyc`, `kyb`, `adaptive_age_verification`, `biometric_authentication`, etc. `null` para fluxos baseados em grafos sem a funcionalidade de KYB." }, "is_default": { "type": "boolean", "description": "Se este é o fluxo predefinido para novas sessões." }, "is_archived": { "type": "boolean" }, "is_white_label_enabled": { "type": "boolean", "description": "Se a personalização de marca branca se aplica às sessões criadas com este fluxo." }, "total_price": { "type": "number", "description": "Preço fixo por verificação em USD (número JSON, exclui funcionalidades com preços variáveis, como DATABASE_VALIDATION e PHONE_VERIFICATION)." }, "min_price": { "type": "number", "description": "Preço fixo mais baixo entre os caminhos do grafo de fluxo, em USD." }, "max_price": { "type": "number", "description": "Preço fixo mais elevado entre os caminhos do grafo do fluxo, em USD." }, "features": { "type": "string", "description": "Funcionalidades ativadas como uma única string unida por `\" + \"`, por exemplo `\"OCR + LIVENESS + FACE_MATCH\"`. Divida por `\" + \"` para obter uma lista." }, "is_simple_workflow": { "type": "boolean", "description": "True quando o fluxo não possui um grafo de fluxo personalizado." }, "is_editable": { "type": "boolean", "description": "Verdadeiro quando esta versão é um `draft` (os rascunhos são editáveis diretamente; as versões publicadas são imutáveis na Console)." }, "workflow_url": { "type": "string", "format": "uri", "description": "URL de verificação partilhável público para este fluxo (`https://verify.didit.me/u/`)." }, "max_retry_attempts": { "type": "integer", "description": "Número máximo de novas tentativas permitidas após uma verificação recusada (0-10)." }, "retry_window_days": { "type": "integer", "nullable": true, "description": "Janela móvel em dias utilizada para contar tentativas (1-365). `null` = limite histórico total." }, "session_expiration_time": { "type": "integer", "description": "Segundos até uma sessão inacabada expirar (3600-2419200)." }, "version": { "type": "integer", "description": "Número da versão dentro do grupo `workflow_id`, começando em 1." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Estado da versão. As novas sessões utilizam a versão `published` mais recente de um grupo." }, "has_draft": { "type": "boolean", "description": "True quando qualquer versão neste grupo `workflow_id` é atualmente um rascunho." }, "created_by": { "type": "object", "nullable": true, "description": "Quem criou esta versão: `{name, email, type}` onde `type` é `user` (utilizador da consola, com `email` definido) ou `api_key` (`name` é o id do cliente, `email` é nulo). `null` quando não foi registado qualquer criador.", "properties": { "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "user", "api_key" ] } } }, "updated_at": { "type": "string", "format": "date-time" } } }, "SimpleWorkflowRequest": { "type": "object", "description": "Crie um fluxo linear simples. A API converte internamente esta lista de funcionalidades num grafo de fluxo baseado em nós. Lista de permissões ESTRITA de campos: qualquer chave não listada aqui (incluindo `workflow_type`) é rejeitada com o código 400.", "required": [ "features" ], "properties": { "workflow_label": { "type": "string", "maxLength": 50, "default": "ID Verification", "description": "Nome de apresentação do fluxo (máx. 50 carateres). Assume por predefinição `\"ID Verification\"` quando omitido — configure-o sempre para que os fluxos permaneçam distinguíveis.", "example": "Standard KYC" }, "is_default": { "type": "boolean", "description": "Defina este fluxo como o padrão para novas sessões." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Omita este campo para criar um fluxo publicado pronto para sessões. Utilize `draft` apenas quando pretender guardar sem publicar." }, "features": { "type": "array", "minItems": 1, "description": "Funcionalidades de verificação por ordem de execução. A API liga cada item ao seguinte e adiciona automaticamente um nó final de estado.", "items": { "$ref": "#/components/schemas/SimpleWorkflowFeature" } }, "is_white_label_enabled": { "type": "boolean", "description": "Ativar a personalização em marca branca para sessões criadas com este fluxo.", "default": false }, "is_desktop_allowed": { "type": "boolean", "description": "Permitir que o fluxo de verificação seja executado em navegadores de computador.", "default": false }, "max_retry_attempts": { "type": "integer", "minimum": 0, "maximum": 10, "default": 3, "description": "Número máximo de novas tentativas permitidas após uma verificação recusada. `0` bloqueia o utilizador após a primeira recusa." }, "retry_window_days": { "type": "integer", "minimum": 1, "maximum": 365, "nullable": true, "default": 7, "description": "Janela móvel em dias utilizada para contar tentativas. `null` aplica um limite histórico total." }, "face_liveness_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "default": 3, "description": "Número máximo de envios de prova de vida por sessão. Padrão: 3 (uma tentativa inicial e duas novas tentativas). Este valor também é copiado para os nós do fluxo de prova de vida e de estimativa de idade gerados, a menos que a configuração ao nível da funcionalidade o substitua." }, "face_match_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "default": 3, "description": "Número máximo de envios de correspondência facial por sessão. Padrão: 3 (uma tentativa inicial e duas novas tentativas). Este valor também é copiado para os nós do fluxo de correspondência facial gerados, a menos que a configuração ao nível da funcionalidade o substitua." }, "session_expiration_time": { "type": "integer", "minimum": 3600, "maximum": 2419200, "default": 604800, "description": "Segundos até uma sessão inacabada expirar. Mínimo de 1 hora (3600), máximo de 4 semanas (2419200)." } } }, "SimpleWorkflowUpdateRequest": { "type": "object", "description": "Atualizar os metadados do fluxo ou substituir a lista linear completa de funcionalidades. Lista de permissões ESTRITA de campos: qualquer chave não listada aqui é rejeitada com um 400.", "properties": { "workflow_label": { "type": "string", "maxLength": 50, "description": "Nome de apresentação do fluxo (máx. 50 carateres)." }, "is_default": { "type": "boolean", "description": "Defina este fluxo como o padrão para novas sessões." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Controla o versionamento. Omita para atualizar a versão atual no local (os rascunhos são publicados automaticamente). `published` numa versão já publicada cria e devolve uma NOVA versão. `draft` só é válido enquanto a versão ainda for um rascunho." }, "features": { "type": "array", "minItems": 1, "description": "Se fornecido, substitui toda a ordem e configuração das funcionalidades.", "items": { "$ref": "#/components/schemas/SimpleWorkflowFeature" } }, "is_white_label_enabled": { "type": "boolean", "description": "Ativar a personalização em marca branca para sessões criadas com este fluxo." }, "is_desktop_allowed": { "type": "boolean", "description": "Permitir que o fluxo de verificação seja executado em navegadores de computador." }, "max_retry_attempts": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Número máximo de novas tentativas permitidas após uma verificação recusada. `0` bloqueia o utilizador após a primeira recusa." }, "retry_window_days": { "type": "integer", "minimum": 1, "maximum": 365, "nullable": true, "description": "Janela móvel em dias utilizada para contar tentativas. `null` aplica um limite histórico total." }, "face_liveness_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "Número máximo de envios de prova de vida por sessão. Este valor também é copiado para os nós do fluxo de prova de vida e de estimativa de idade gerados, a menos que a configuração ao nível da funcionalidade o substitua." }, "face_match_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "Número máximo de envios de correspondência facial por sessão. Este valor também é copiado para os nós do fluxo de correspondência facial gerados, a menos que a configuração ao nível da funcionalidade o substitua." }, "session_expiration_time": { "type": "integer", "minimum": 3600, "maximum": 2419200, "description": "Segundos até uma sessão inacabada expirar. Mínimo de 1 hora (3600), máximo de 4 semanas (2419200)." } } }, "SimpleWorkflowFeature": { "type": "object", "required": [ "feature" ], "properties": { "feature": { "type": "string", "description": "Funcionalidade a executar. Utilize os valores em maiúsculas aqui apresentados.", "enum": [ "OCR", "NFC", "LIVENESS", "FACE_MATCH", "PROOF_OF_ADDRESS", "QUESTIONNAIRE", "DOCUMENT_AI", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "DATABASE_VALIDATION", "AML", "IP_ANALYSIS", "AGE_ESTIMATION", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "SIGNATURE" ] }, "config": { "type": "object", "description": "Definições específicas da funcionalidade. Para `QUESTIONNAIRE`, inclua `questionnaire_uuid` com o `questionnaire_id` devolvido pelo endpoint de criação de questionários. Para `SIGNATURE`, um fluxo que passa a produção precisa de um documento para assinar: defina `signature_documents_source` como `session` ou `both` para que cada sessão possa fornecer o seu próprio, ou envie `status: \"draft\"` e adicione os documentos antes de publicar. `signature_level: \"aes\"` é recusado com `aes_not_available` enquanto `signature_availability.aes` for `false` no fluxo. Para `OCR`, `methods` seleciona quais os métodos de Verificação de identidade que cada país pode utilizar (captura de documentos, consulta sem documento junto de uma fonte governamental ou de outra autoridade, e carteiras de identidade digital); omita-o e todos os países utilizarão apenas a captura de documentos. Para `SIGNATURE`, consulte [Definições de Assinatura eletrónica](/pt/management-api/workflows/feature-configs#assinatura-eletrónica): `signature_level` aceita `simple` (a predefinição; não é necessária verificação de identidade, e-mail ou telefone) e `aes` de momento, e os documentos do fluxo e respetivos campos são geridos na consola, pelo que, através da API, envie documentos e campos por sessão com `signature_documents_source: \"session\"`.", "additionalProperties": true }, "label": { "type": "string", "description": "Etiqueta interna opcional para este nó do fluxo." } } }, "ReviewItem": { "type": "object", "description": "Uma entrada no feed de atividade/revisão de uma sessão. As alterações de estado incluem `previous_status`, `new_status`, `previous_value`, `new_value` e `changed_fields`; os comentários incluem `comment` e (para comentários da consola) `mentioned_emails`; os restantes campos são `null` ou vazios quando não se aplicam ao tipo de atividade.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador único desta entrada de feed.", "example": "de0561bc-5583-4409-9171-1a31a4c8a5f4" }, "activity_type": { "type": "string", "enum": [ "COMMENT", "STATUS_UPDATED", "KYC_DATA_UPDATED", "POA_DATA_UPDATED", "FILE_ADDED", "FILE_REMOVED", "AML_ONGOING_MATCH", "AML_STATUS_UPDATED", "AML_HIT_STATUS_UPDATED", "KYB_DATA_UPDATED", "KYB_DOCUMENT_UPLOADED", "TAG_ADDED", "TAG_REMOVED", "FEATURE_OVERRIDE_PENDING", "FEATURE_OVERRIDE_APPLIED", "FEATURE_OVERRIDE_CANCELLED" ], "description": "Que tipo de atividade este registo guarda. As linhas `STATUS_UPDATED` provêm de decisões manuais (`PATCH /v3/session/{session_id}/update-status/`) e de registos adicionados via `POST …/reviews/` (cujo padrão é este tipo, mesmo quando nenhum estado é registado). As linhas `COMMENT` provêm de revisores da Console; as visualizações da página de detalhes na Console também são armazenadas como linhas `COMMENT` sinalizadas com `metadata.system_event = \"DETAIL_VIEWED\"`. Os restantes tipos acompanham edições de dados, alterações de ficheiros, etiquetas e atividade de monitorização AML. As linhas STATUS_UPDATED também são escritas por agentes do sistema (por exemplo, monitorização AML contínua com actor_type SYSTEM e atualizações automáticas de estado de funcionalidades), não apenas pelo endpoint update-status e publicações de revisão manual. `FEATURE_OVERRIDE_PENDING`, `FEATURE_OVERRIDE_APPLIED` e `FEATURE_OVERRIDE_CANCELLED` registam a sobreposição do estado de uma verificação (`PATCH /v3/session/{session_id}/features/{node_id}/update-status/`): solicitada para aguardar a conclusão do fluxo, aplicada ou cancelada. Estas transmitem o estado da verificação em `previous_value` / `new_value` (`{\"status\": ...}`), mantêm `previous_status` e `new_status` como `null`, e indicam a sobreposição em `metadata` (`feature_override_id`, `node_id`, `feature_model`, `forced`, `state`, `cancel_reason`). O registo do pedido inclui o `comment` do revisor; uma sobreposição aplicada quando o fluxo termina é registada com `actor_type` `SYSTEM`.", "example": "STATUS_UPDATED" }, "actor_display": { "type": "string", "description": "Rótulo de autor legível, resolvido pela seguinte ordem: nome completo do interveniente → identificador de conta da Console → parte local de `actor_email` → `\"API Client\"` (para intervenientes `API_KEY`) → `\"System\"` (para intervenientes `SYSTEM`) → `\"Unknown\"`. As entradas criadas através de `POST …/reviews/` apresentam sempre `\"Unknown\"` porque esse endpoint não regista a atribuição de interveniente.", "example": "API Client" }, "actor_email": { "type": "string", "nullable": true, "description": "E-mail do utilizador da Consola que realizou a ação. `null` para atores do sistema e de chave de API.", "example": null }, "actor_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ], "description": "Quem executou a ação: uma chave de API, um utilizador da consola ou a própria Didit (`SYSTEM`, p. ex., monitorização AML contínua). As entradas criadas através de `POST …/reviews/` assumem o valor predefinido `CONSOLE_USER`, independentemente de quem chamou.", "example": "API_KEY" }, "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Estado da sessão registado por esta entrada (para atualizações de estado). `null` para comentários e entradas de alteração de dados.", "example": "Approved" }, "previous_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Estado que a sessão tinha antes da alteração. Preenchido nas entradas `STATUS_UPDATED` gravadas pelo endpoint de atualização de estado; `null` nas entradas adicionadas via `POST …/reviews/`. Também preenchido nas linhas STATUS_UPDATED geradas pelo sistema.", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "Nota em texto livre associada à entrada, ou `null`.", "example": "Document re-checked manually; address matches." }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Utilizadores da consola mencionados com `@email` no comentário. Sempre vazio para entradas criadas através desta API — o processamento de menções é uma funcionalidade exclusiva da consola.", "example": [] }, "previous_value": { "type": "object", "nullable": true, "description": "Instantâneo dos dados alterados antes da ação, por exemplo, `{\"status\": \"In Review\"}` numa alteração de estado. `null` quando nada foi alterado.", "example": { "status": "In Review" } }, "new_value": { "type": "object", "nullable": true, "description": "Instantâneo dos dados alterados após a ação, por exemplo, `{\"status\": \"Approved\"}`. `null` quando nada foi alterado.", "example": { "status": "Approved" } }, "changed_fields": { "type": "array", "items": { "type": "string" }, "description": "Nomes dos campos modificados por esta atividade (por exemplo, `[\"status\"]`). Vazio para comentários e para entradas adicionadas através de `POST …/reviews/`.", "example": [ "status" ] }, "metadata": { "type": "object", "nullable": true, "description": "Contexto adicional para entradas geradas pelo sistema. As visualizações da página de detalhes na Console incluem `{\"system_event\": \"DETAIL_VIEWED\", \"detail_type\": \"verification\"}` para que possam ser filtradas da lógica de notificações. Um `COMMENT` editado pelo seu autor na Console inclui `edited_at`, a data e hora ISO 8601 da última edição (`comment` e `mentioned_emails` contêm então o texto editado e as suas menções). `null` para entradas normais.", "example": null }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a entrada foi gravada, ISO 8601 UTC.", "example": "2026-06-12T00:19:31.918735Z" } } }, "QuestionnaireListItem": { "type": "object", "description": "Uma versão do questionário na vista de lista.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID por versão. Utilize como `{questionnaire_uuid}` para obter/atualizar/eliminar e como `questionnaire_uuid` na configuração da funcionalidade QUESTIONNAIRE de um fluxo." }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "is_simple_questionnaire": { "type": "boolean", "description": "True para questionários lineares criados através desta API; false para questionários baseados em grafos construídos na consola." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "question_types": { "type": "array", "items": { "type": "string" }, "description": "Tipos de elementos em maiúsculas das perguntas que admitem resposta, pela ordem de criação (por exemplo, `SHORT_TEXT`, `MULTIPLE_CHOICE`, `FILE_UPLOAD`). Elementos estruturais `SECTION_HEADER` e `SEPARATOR` são excluídos. Uma entrada por pergunta, pelo que os valores podem repetir-se." }, "workflow_names": { "type": "array", "items": { "type": "string" }, "description": "Nomes dos fluxos que utilizam este questionário. Atualmente sempre `[]` neste endpoint (preenchido apenas na listagem da Consola)." }, "questionnaire_group_id": { "type": "string", "format": "uuid", "description": "Identificador estável que agrupa todas as versões do mesmo questionário." }, "version": { "type": "integer", "description": "Número da versão dentro do grupo, começando em 1." }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando esta versão foi publicada. `null` para rascunhos." }, "is_editable": { "type": "boolean", "description": "Verdadeiro quando esta versão é um `draft`." } } }, "SimpleQuestionnaireRequest": { "type": "object", "description": "Crie um questionário linear simples. A API converte `form_elements` no grafo interno do questionário.", "required": [ "title", "languages", "form_elements" ], "properties": { "title": { "type": "string", "description": "Nome interno do questionário." }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "description": "Idiomas incluídos em cada rótulo. Tem de incluir `en`.", "items": { "type": "string" }, "example": [ "en" ] }, "default_language": { "type": "string", "description": "Idioma predefinido. Tem de estar incluído em `languages`.", "example": "en" }, "is_active": { "type": "boolean", "default": true }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Omita este campo para criar um questionário publicado pronto para fluxos." }, "form_elements": { "type": "array", "minItems": 1, "description": "Perguntas na ordem exata em que os utilizadores as devem ver. Ramificações e campos condicionais não são suportados.", "items": { "$ref": "#/components/schemas/SimpleQuestionnaireElement" } } } }, "SimpleQuestionnaireUpdateRequest": { "type": "object", "description": "Atualizar os metadados do questionário ou substituir a lista linear completa de `form_elements`.", "properties": { "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "form_elements": { "type": "array", "minItems": 1, "description": "Se fornecido, substitui toda a lista linear de perguntas.", "items": { "$ref": "#/components/schemas/SimpleQuestionnaireElement" } } } }, "SimpleQuestionnaireElement": { "type": "object", "required": [ "element_type", "label" ], "properties": { "id": { "type": "string", "description": "ID estável da pergunta, opcional. Se for omitido, a API gera `q1`, `q2`, etc. Utilize letras minúsculas, números e sublinhados para facilitar a leitura.", "example": "source_of_funds" }, "element_type": { "type": "string", "description": "Tipo de pergunta. A API aceita estes valores em minúsculas e os seus equivalentes em maiúsculas.", "enum": [ "short_text", "long_text", "dropdown", "single_choice", "multiple_choice", "number", "image", "file_upload", "time", "email", "address", "phone", "country", "date_picker", "consent", "section_header", "separator", "heading", "paragraph" ] }, "label": { "type": "object", "description": "Rótulo da pergunta por código de idioma, por exemplo `{ \"en\": \"Source of funds\" }`.", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "placeholder": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "is_required": { "type": "boolean", "default": false }, "options": { "type": "array", "description": "Utilize para `dropdown`, `single_choice` e `multiple_choice`. Se `value` for omitido, a API gera um a partir do rótulo da opção.", "items": { "type": "object", "required": [ "label" ], "properties": { "value": { "type": "string" }, "label": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "max_files": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Utilize com `file_upload` ou `image`." }, "validation": { "type": "object", "nullable": true, "description": "Validação de formato opcional para `short_text`, `long_text` ou `number`. Aplicada enquanto o utilizador preenche o campo (não pode avançar até ser validado com sucesso) e verificada novamente pela API na submissão.", "properties": { "pattern": { "type": "string", "description": "Expressão regular (subconjunto ECMA-262) à qual o valor deve corresponder na totalidade. Para `short_text` e `long_text`. Não adicione âncoras ^/$; o valor inteiro é comparado." }, "min_length": { "type": "integer", "minimum": 0, "description": "Número mínimo de carateres. Para `short_text` e `long_text`." }, "max_length": { "type": "integer", "minimum": 0, "description": "Número máximo de carateres. Para `short_text` e `long_text`." }, "min": { "type": "number", "description": "Valor numérico mínimo. Para `number`." }, "max": { "type": "number", "description": "Valor numérico máximo. Para `number`." }, "error_message": { "type": "object", "description": "Mensagem traduzida apresentada quando a validação falha, indexada pelo código de idioma.", "additionalProperties": { "type": "string" } } } } } }, "QuestionnaireDetail": { "type": "object", "description": "Detalhe completo do questionário retornado pelos endpoints GET, POST (criar) e PATCH (atualizar).", "properties": { "questionnaire_id": { "type": "string", "format": "uuid", "description": "Identificador único do questionário. Utilize este id ao referenciar o questionário a partir de um fluxo ou em pedidos subsequentes de atualização/eliminação." }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "is_simple_questionnaire": { "type": "boolean" }, "graph": { "type": "object", "description": "Estrutura em grafo com start_node e mapa de nós." }, "sections": { "type": "array", "description": "Conteúdo do questionário agrupado em secções (derivado do grafo).", "items": { "type": "object" } }, "questionnaire_group_id": { "type": "string", "format": "uuid", "description": "Identificador estável que agrupa todas as versões do mesmo questionário." }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "is_editable": { "type": "boolean", "description": "True quando o questionário ainda pode ser editado no local (versões de rascunho)." } } }, "UserListItem": { "type": "object", "description": "Um utilizador verificado.", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "UUID interno estável da Didit para este utilizador." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu identificador exclusivo para este utilizador (transmitido ao criar sessões). Pode ser nulo quando não tiver sido fornecido nenhum identificador de fornecedor." }, "display_name": { "type": "string", "nullable": true, "description": "Nome de apresentação personalizado definido por si" }, "full_name": { "type": "string", "nullable": true, "description": "Nome completo extraído de documentos verificados" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "effective_name": { "type": "string", "nullable": true, "description": "Melhor nome disponível: display_name se definido, caso contrário full_name" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Estado do ciclo de vida do registo do utilizador (NÃO é um estado da sessão). `ACTIVE` é o padrão, `FLAGGED` marca o utilizador para atenção manual, `BLOCKED` impede novas sessões para este `vendor_data`." }, "portrait_image_url": { "type": "string", "nullable": true, "description": "URL pré-assinado da fotografia de retrato do utilizador (expira após algumas horas)" }, "session_count": { "type": "integer", "description": "Número total de sessões de verificação para este utilizador" }, "approved_count": { "type": "integer", "description": "Número de sessões aprovadas" }, "declined_count": { "type": "integer", "description": "Número de sessões recusadas" }, "in_review_count": { "type": "integer", "description": "Número de sessões em análise" }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "Códigos ISO 3166-1 alfa-3 dos países emissores observados nos documentos de identificação aprovados deste utilizador, por exemplo, `[\"USA\", \"ESP\"]`. Array vazio quando não houver nenhum." }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "Endereços de e-mail verificados recolhidos a partir das sessões aprovadas deste utilizador, por exemplo, `[\"john@example.com\"]`." }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "Números de telefone verificados recolhidos a partir das sessões aprovadas deste utilizador, por exemplo, `[\"+14155551234\"]`." }, "features": { "type": "object", "description": "Estado agregado por funcionalidade em todas as sessões deste utilizador. Chaves possíveis: `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACE_MATCH`, `POA`, `QUESTIONNAIRE`, `EMAIL_VERIFICATION`, `PHONE`, `AML`, `IP_ANALYSIS`, `AGE_ESTIMATION`, `DATABASE_VALIDATION`. Valores possíveis: `Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`." }, "features_list": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "status": { "type": "string" } } }, "description": "Os mesmos dados que `features`, como um array ordenado de objetos `{feature, status}`." }, "last_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da sessão mais recente" }, "first_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da primeira sessão" }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da atividade mais recente neste utilizador (sessão, transação, mudança de estado, edição de dados, etc.)." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "description": "Etiquetas atribuídas a este utilizador" }, "created_at": { "type": "string", "format": "date-time" } } }, "BlocklistItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "face", "document", "phone", "email" ] }, "session_id": { "type": "string", "format": "uuid" }, "session_number": { "type": "integer" }, "blocklisted_at": { "type": "string", "format": "date-time" }, "face_image": { "type": "string", "nullable": true }, "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "phone_number": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "UserDetailItem": { "type": "object", "description": "Detalhe completo do utilizador. Estende UserListItem com metadados, comentários e updated_at.", "allOf": [ { "$ref": "#/components/schemas/UserListItem" }, { "type": "object", "properties": { "metadata": { "type": "object", "description": "JSON de metadados personalizados que associou a este utilizador. O valor predefinido é `{}`." }, "tags": { "type": "array", "description": "Atribuições de etiquetas. NOTA: nas respostas detalhadas, cada entrada é um objeto de *ligação* de etiqueta (`{uuid, tag: {...}, added_by_email, added_by_name, created_at}`), ao contrário do formato simples `{uuid, name, color}` utilizado nas respostas de listagem.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID da atribuição de etiqueta (não da etiqueta em si)." }, "tag": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "added_by_email": { "type": "string", "nullable": true }, "added_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "comment_type": { "type": "string", "enum": [ "COMMENT", "STATUS_CHANGED", "METADATA_UPDATED", "TAG_ADDED", "TAG_REMOVED", "PROFILE_UPDATED" ] }, "comment": { "type": "string", "nullable": true }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "previous_status": { "type": "string", "nullable": true, "enum": [ "ACTIVE", "FLAGGED", "BLOCKED", null ] }, "new_status": { "type": "string", "nullable": true, "enum": [ "ACTIVE", "FLAGGED", "BLOCKED", null ] }, "previous_value": { "type": "object", "nullable": true, "description": "Valores anteriores dos campos para entradas PROFILE_UPDATED." }, "new_value": { "type": "object", "nullable": true, "description": "Novos valores de campo para entradas PROFILE_UPDATED." }, "changed_fields": { "type": "array", "items": { "type": "string" }, "description": "Nomes dos campos alterados por uma entrada PROFILE_UPDATED." }, "metadata": { "type": "object", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "Registo de atividade e comentários para este utilizador (alterações de estado, edições de perfil, notas manuais)." }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "BusinessListItem": { "type": "object", "description": "Uma empresa verificada.", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "UUID interno estável da Didit para esta empresa." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu identificador exclusivo para esta empresa (transmitido ao criar sessões). Pode ser nulo quando não tiver sido fornecido nenhum identificador de fornecedor." }, "display_name": { "type": "string", "nullable": true, "description": "Nome de apresentação personalizado definido por si" }, "legal_name": { "type": "string", "nullable": true, "description": "Denominação legal oficial proveniente do registo ou introduzida manualmente" }, "registration_number": { "type": "string", "nullable": true, "description": "Número de registo ou de constituição da empresa" }, "country_code": { "type": "string", "nullable": true, "description": "País de constituição (ISO 3166-1 alpha-2, por ex., `GB`, `US`)." }, "effective_name": { "type": "string", "nullable": true, "description": "Melhor nome disponível: display_name se definido, caso contrário legal_name" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Estado do ciclo de vida do registo da empresa (NÃO é um estado da sessão). `ACTIVE` é o padrão, `FLAGGED` marca-o para atenção manual, `BLOCKED` impede novas sessões para este `vendor_data`." }, "session_count": { "type": "integer", "description": "Número total de sessões de verificação para esta empresa" }, "approved_count": { "type": "integer", "description": "Número de sessões aprovadas" }, "declined_count": { "type": "integer", "description": "Número de sessões recusadas" }, "in_review_count": { "type": "integer", "description": "Número de sessões em análise" }, "features": { "type": "object", "description": "Estado agregado por funcionalidade em todas as sessões de KYB desta empresa. Atualmente, a única chave é `KYB` (o estado da verificação da empresa no registo). Valores possíveis: `Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`." }, "features_list": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "status": { "type": "string" } } }, "description": "Os mesmos dados que `features`, como um array ordenado de objetos `{feature, status}`." }, "last_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da sessão mais recente" }, "first_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da primeira sessão" }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da atividade mais recente (mudança de estado, atualização da sessão, etc.)" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "description": "Etiquetas atribuídas a esta empresa" }, "created_at": { "type": "string", "format": "date-time" } } }, "BusinessDetailItem": { "type": "object", "description": "Detalhe completo da empresa. Estende BusinessListItem com metadados e updated_at.", "allOf": [ { "$ref": "#/components/schemas/BusinessListItem" }, { "type": "object", "properties": { "metadata": { "type": "object", "description": "JSON de metadados personalizados que associou a esta empresa. O valor predefinido é `{}`." }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "TransactionDetail": { "type": "object", "description": "Registo completo de monitorização de uma transação, conforme retornado por `GET /v3/transactions/{transaction_id}/` e `POST /v3/transactions/`.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador de transação estável da Didit. Utilize como `{transaction_id}` para chamadas de seguimento." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente da aplicação proprietária da transação. Uma transação em `sandbox` é armazenada, mas nunca avaliada, sujeita a triagem, notificada ou faturada, pelo que o seu `rule_runs` vazio significa \"não avaliada\"." }, "transaction_number": { "type": "integer", "description": "Número sequencial da transação no âmbito da aplicação apresentado na Consola (ex.: `4123`)." }, "txn_id": { "type": "string", "description": "O `transaction_id` que indicou no momento da criação (máx. 128 carateres). Único por aplicação." }, "txn_date": { "type": "string", "format": "date-time", "description": "Quando a transação ocorreu (a partir de `transaction_at`; o padrão é a hora de submissão)." }, "zone_id": { "type": "string", "nullable": true, "description": "Identificador de fuso horário IANA fornecido no momento da criação." }, "transaction_type": { "type": "string", "description": "Categoria de nível superior tal como armazenada: `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`, `gamblingLimitChange`, `gamblingBonusChange`, `auditTrailEvent`. Tenha em atenção que os valores com várias palavras são devolvidos em camelCase, mesmo quando enviados em snake_case." }, "action_type": { "type": "string", "description": "Subtipo dentro da categoria (p. ex. `deposit`, `withdrawal`, `transfer`). É predefinido como a categoria quando não é fornecido." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direção em relação ao sujeito. Armazenada em maiúsculas independentemente da capitalização submetida (`in`/`out`/`inbound`/`outbound` são aceites na entrada)." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Veredito atual de monitorização. As transações são criadas como `APPROVED`; as regras podem alterá-las sincronamente para `IN_REVIEW`/`DECLINED`." }, "source": { "type": "string", "enum": [ "LIVE", "IMPORTED" ], "description": "Como o registo teve origem: `LIVE` para transações submetidas através da API ou SDK, `IMPORTED` para transações carregadas através da importação da consola." }, "amount": { "type": "string", "description": "Montante da transação como uma string decimal sem zeros à direita (por exemplo, `\"1500\"`, `\"0.5\"`, `\"0.123456789012345678\"`). Até 18 casas decimais." }, "currency": { "type": "string", "description": "Código de moeda de `amount`. Qualquer código alfabético ISO 4217 é aceite (por exemplo, `EUR`, `USD`, `NGN`), bem como um símbolo de ativo criptográfico (por exemplo, `BTC`). Dê preferência a um código atualmente em circulação. Nem todos os códigos aceites têm uma taxa de câmbio: quando nenhuma estiver disponível para o código (por exemplo, a unidade contabilística ISO `XSU`, ou um símbolo criptográfico que a Didit não precifique), a conversão automática falha e `preferred_currency_amount` é devolvido a null, a menos que o pedido tenha fornecido um `amount_in_default_currency` pré-convertido." }, "currency_type": { "type": "string", "nullable": true, "description": "`fiat` ou `crypto`, conforme submetido em `currency_kind`." }, "amount_in_default_currency": { "type": "string", "nullable": true, "description": "Montante pré-convertido fornecido por si, como uma cadeia decimal sem zeros à direita." }, "default_currency_code": { "type": "string", "nullable": true }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` convertido para a moeda preferida da aplicação, quando disponível." }, "preferred_currency_code": { "type": "string", "nullable": true }, "payment_details": { "type": "string", "nullable": true, "description": "Referência ou memorando de pagamento em texto livre proveniente do envio." }, "payment_txn_id": { "type": "string", "nullable": true, "description": "Referência externa do sistema de pagamento (por exemplo, hash de transação na blockchain) a partir de `payment_reference_id`." }, "score": { "type": "integer", "description": "Pontuação de risco acumulada por regras (normalmente 0–100). Mais alta = maior risco." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Gravidade de risco categórica definida por regras/fornecedores (`UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`). `null` até que algo a defina." }, "decision_reason_code": { "type": "string", "nullable": true, "description": "Motivo legível por máquina para o `status` atual." }, "decision_reason_label": { "type": "string", "nullable": true, "description": "Rótulo legível para `decision_reason_code`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Cópia de conveniência dos `vendor_data` do requerente." }, "metadata": { "type": "object", "description": "Instantâneo dos payloads de `subject` e `counterparty` conforme enviados no momento da criação." }, "props": { "type": "object", "description": "As `custom_properties` que forneceu no momento da criação. Cada chave pode ser referenciada nas condições das regras como `custom_values.`." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "Se a etiqueta é uma predefinição da Didit ou uma etiqueta personalizada." } } }, "description": "Etiquetas associadas à transação (manualmente ou por regras)." }, "parties": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "APPLICANT", "REMITTER", "BENEFICIARY", "COUNTERPARTY" ], "description": "Função da parte. O endpoint de criação atribui `APPLICANT` (o sujeito) e `COUNTERPARTY`." }, "entity_type": { "type": "string", "enum": [ "individual", "company", "external", "unhostedWallet" ] }, "kind": { "type": "string", "enum": [ "USER", "BUSINESS", "EXTERNAL" ], "description": "As partes `USER`/`BUSINESS` ligam-se a uma entidade detida pela Didit através de `vendor_data`. As partes `EXTERNAL` não têm nenhuma entidade Didit associada." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu identificador interno de utilizador/empresa." }, "full_name": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true, "description": "Código do país a partir do `address.country` submetido (normalmente ISO 3166-1 alpha-3)." }, "dob": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento a partir do `date_of_birth` submetido." }, "address": { "type": "object", "description": "Objeto de morada conforme submetido. `{}` quando omitido." }, "institution_info": { "type": "object", "description": "Detalhes da instituição conforme submetidos. `{}` quando omitidos." }, "device": { "type": "object", "description": "Contexto de dispositivo normalizado, incluindo enriquecimento de IP do lado do servidor sob network_context (geolocalização, flags de VPN/centro de dados) quando foi fornecido um IP.", "properties": { "fingerprint": { "type": "string", "description": "Impressão digital única do dispositivo." }, "persistent_device_id": { "type": "string", "description": "Identificador estável de dispositivo entre sessões (esquema de fingerprint v2)." }, "user_agent": { "type": "string", "description": "Cadeia de caracteres do agente do utilizador do navegador ou da aplicação." }, "browser_family": { "type": "string", "description": "Família do navegador (por exemplo, Chrome, Firefox, Safari)." }, "browser_version": { "type": "string", "description": "Cadeia de caracteres da versão do navegador." }, "platform": { "type": "string", "description": "Identificador da plataforma (web, ios, android, macos, windows, linux)." }, "os_family": { "type": "string", "description": "Família do sistema operativo (por exemplo, iOS, Android, Windows)." }, "os_version": { "type": "string", "description": "String da versão do sistema operativo." }, "accept_language": { "type": "string", "description": "Valor do cabeçalho Accept-Language." }, "session_id": { "type": "string", "description": "Identificador da sessão (armazenado nos metadados)." }, "session_age_ms": { "type": "number", "description": "Idade da sessão em milissegundos." }, "network_context": { "type": "object", "description": "Contexto de rede com endereço IP e geolocalização.", "properties": { "ip_address": { "type": "string", "description": "Endereço IP do cliente." }, "ip_country_code": { "type": "string", "description": "País determinado por geolocalização do IP (ISO 3166-1 alfa-3)." }, "latitude": { "type": "number", "description": "Latitude geográfica do IP." }, "longitude": { "type": "number", "description": "Longitude geográfica do IP." } } } } }, "external_party_snapshot": { "type": "object", "nullable": true, "description": "Cópia congelada dos dados da parte para partes `EXTERNAL`. `null` enquanto a parte estiver associada a um utilizador ou empresa Didit." } } }, "description": "Partes da transação (requerente, contraparte)." }, "payment_methods": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "payment_method_type": { "type": "string", "enum": [ "bank_card", "bank_account", "e_wallet", "crypto_wallet", "unhosted_wallet", "other" ] }, "label": { "type": "string", "nullable": true }, "fingerprint": { "type": "string", "nullable": true, "description": "SHA-256 sobre `type:account_id:issuing_country` — identificador estável para correlacionar a reutilização do mesmo instrumento." }, "account_id": { "type": "string", "nullable": true, "description": "Identificador de conta (IBAN, endereço de carteira, token de cartão, …)." }, "issuing_country": { "type": "string", "nullable": true }, "owner_kind": { "type": "string", "enum": [ "USER", "BUSINESS", "EXTERNAL" ] }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu identificador para o utilizador/empresa proprietário." }, "owner_name": { "type": "string", "nullable": true }, "institution_info": { "type": "object" }, "details": { "type": "object", "description": "Objeto `payment_method` em bruto conforme submetido." }, "external_owner_snapshot": { "type": "object", "nullable": true }, "role": { "type": "string", "enum": [ "SOURCE", "DESTINATION", "FUNDING", "BENEFICIARY" ], "description": "Como este método foi utilizado na transação. O endpoint de criação atribui `SOURCE`/`DESTINATION` a partir do sentido (saída: sujeito = SOURCE; entrada: sujeito = DESTINATION)." } } }, "description": "Métodos de pagamento associados à transação." }, "documents": { "type": "array", "description": "Ficheiros anexados à transação a partir da consola. `[]` quando não existem ficheiros.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "uploaded_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL de transferência assinado de curta duração; obtenha-o quando necessário em vez de o guardar." }, "original_filename": { "type": "string", "nullable": true }, "file_size": { "type": "integer", "nullable": true } } } } } } }, "activities": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "activity_type": { "type": "string", "description": "Por exemplo, `TRANSACTION_CREATED`, `TRANSACTION_NOTE_ADDED`, `TRANSACTION_STATUS_CHANGED`." }, "source": { "type": "string" }, "status": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "occurred_at": { "type": "string", "format": "date-time" } } }, "description": "Entradas do registo de atividade (criação, notas, revisões manuais, alterações de estado)." }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "status": { "type": "string", "enum": [ "OPEN", "INVESTIGATING", "AWAITING_USER", "PENDING_SAR", "SAR_FILED", "RESOLVED", "DISMISSED" ] }, "source": { "type": "string", "enum": [ "RULE", "PROVIDER", "MANUAL" ] }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time", "nullable": true } } }, "description": "Sempre vazio atualmente. Um alerta em aberto é uma transação com o estado `IN_REVIEW` ou `AWAITING_USER`." }, "rule_runs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "rule": { "type": "string", "format": "uuid", "description": "UUID da regra que foi executada." }, "rule_title": { "type": "string" }, "rule_description": { "type": "string", "nullable": true }, "rule_category": { "type": "string" }, "matched": { "type": "boolean", "description": "Se as condições da regra corresponderam a esta transação. Uma execução só é registada para regras correspondentes, pelo que as avaliações em tempo real contêm sempre `true`." }, "is_test": { "type": "boolean", "description": "True quando a regra foi executada no modo TEST (sem efeito no estado/pontuação)." }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ] }, "severity": { "type": "string", "nullable": true }, "score_delta": { "type": "integer", "description": "Pontuação adicionada pelas ações `add_score` desta regra." }, "status_target": { "type": "string", "nullable": true, "description": "Estado definido por uma ação `change_status`, se houver." }, "action_summary": { "type": "string", "nullable": true, "description": "Resumo das ações que a regra executou, unidas com `; ` (por exemplo, `score +30; change_status:IN_REVIEW; add_tag:high_risk_country`). Partes: `score +N`, `change_status:`, `add_tag:`, `add_note`, `add_to_list`, `open_case`. `null` quando a regra não executou nenhuma ação." }, "metadata": { "type": "object", "description": "Detalhe da avaliação: `scope_match`, `conditions[]` e `aggregations[]`. Cada entrada de condição inclui `field`, `operator`, `expected_value`, o `current_value` lido a partir da transação, `matched`, `group_index` e `group_logic`. Cada entrada de agregação (velocidade / contagem / soma) inclui `metric`, `field`, `operator`, `expected_value`, o `computed_value` resultante da avaliação do agregado, `window`, `filters`, `matched` e `sample_references`; as agregações assíncronas diferidas têm `computed_value: null` e `deferred: true`. Um grupo de condições aninhado é uma entrada de `conditions[]` com `operator` `any_of` ou `all_of`, `field` null e os resultados dos seus membros sob as suas próprias `conditions`." }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "Resultados da execução por regra — que regra foi acionada, com que impacto na pontuação." }, "provider_results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "result_type": { "type": "string", "enum": [ "FIAT_MONITORING", "WALLET_SCREENING", "TRANSACTION_SCREENING", "TRAVEL_RULE", "NETWORK_GRAPH", "CUSTOM" ] }, "status": { "type": "string" }, "severity": { "type": "string", "nullable": true }, "score": { "type": "integer" }, "summary": { "type": "string", "nullable": true }, "payload": { "type": "object", "description": "Payload de resposta em bruto do fornecedor." }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "Payloads em bruto do fornecedor (triagem AML, análise de blockchain, etc.)." }, "travel_rule": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionTravelRule" } ], "description": "Transferência ou verificação da Travel Rule. Preenchido quando `travel_rule_details` foi submetido, e também quando a Travel Rule está ativada e a transação foi criada com `transaction_category: travelRule` (a Didit inicia a troca por si própria, mesmo sem `travel_rule_details`). `null` quando não existe qualquer transferência ou verificação. Numa transferência de entrada, os dados `originator_data` e `beneficiary_data` da contraparte permanecem mascarados (`data_masked: true`) até que a propriedade da carteira seja confirmada." }, "network_snapshot": { "type": "object", "nullable": true, "description": "Instantâneo do grafo de transações/partes relacionadas utilizado pelo motor de regras. Corresponde ao `network_snapshot` submetido com a transação ou ao grafo que a Didit gera a partir de uma triagem AML de carteiras bem-sucedida (o qual substitui o submetido). `null` quando nenhum deles existe.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "nodes": { "type": "array", "items": { "type": "object" } }, "edges": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "object" } } }, "remediation": { "type": "object", "nullable": true, "description": "Sessão de remediação oferecida ao utilizador quando é necessária reverificação. Substituída por `action_required`, que é o bloco canónico; mantida para retrocompatibilidade.", "properties": { "session_id": { "type": "string" }, "session_token": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string" } } }, "action_required": { "type": "object", "nullable": true, "description": "Ação pendente do utilizador final necessária para concluir esta transação, ou null quando não houver nenhuma. Os SDKs da Didit iniciam automaticamente a ação por predefinição e atualizam a transação quando esta termina. Duas variantes, distinguidas por `type`: `verification_session` (uma sessão de verificação alojada criada por uma ação de regra) e `wallet_ownership` (uma sessão de widget de propriedade da carteira criada automaticamente para uma transferência da Travel Rule que necessita de comprovativo de controlo da carteira, condicionada pela definição da Travel Rule `auto_wallet_verification`). Quando ambas se podem aplicar, `wallet_ownership` tem precedência porque bloqueia a troca da Travel Rule.", "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } } }, "cost_breakdown": { "type": "object", "nullable": true, "description": "Custo desta transação: `total_price` e `items`, um por cobrança, cada um com `usage_type`, `price`, `details` e `created_at`. Uma nova triagem da mesma transação constitui um novo item." } } }, "TravelRuleSettingsDetail": { "type": "object", "properties": { "is_enabled": { "type": "boolean", "description": "Indica se o fluxo de negociação gerida de Travel Rule está ativo para transações de saída `travelRule` nesta aplicação." }, "jurisdiction": { "type": "string", "maxLength": 8, "description": "O código de jurisdição operacional do seu VASP. Predefinição `\"EU\"`. A Didit mapeia-o para o regime que estampa nas suas transações de Travel Rule como `travel_rule_regime` (por exemplo, `EU` ou o código de um Estado-membro da UE passa a `eu`), que as regras de transação podem utilizar como chave. Outros clientes da Didit veem-no como a sua jurisdição no diretório de VASPs assim que a rede Didit listar o seu perfil." }, "name_matching_strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Com que rigor os nomes dos beneficiários têm de coincidir antes de uma transferência poder atingir o estado COMPLETED. `CONTAINS` aceita um nome cujas palavras apareçam todas no outro." }, "confirmation_timeout_hours": { "type": "integer", "minimum": 1, "description": "Horas que uma transferência AWAITING_COUNTERPARTY pode permanecer por confirmar antes de o processo periódico de limpeza a expirar. Predefinição: 48." }, "timeout_outcome": { "type": "string", "enum": [ "HOLD", "REJECT", "PROCEED" ], "description": "O que acontece à transação subjacente quando uma transferência expira. Predefinição HOLD. sunrise_policy e non_responsive_policy têm precedência quando se aplicam e estão definidas." }, "threshold_amount": { "type": "string", "description": "String decimal, na moeda predefinida da sua aplicação. Montante mínimo de transferência que aciona uma partilha gerida; transferências abaixo dele resolvem diretamente para NOT_APPLICABLE. A Didit compara o montante da transação convertido para a sua moeda predefinida, ou o `amount_in_default_currency` enviado; quando nenhum montante convertido estiver disponível, o limiar não se aplica. O valor predefinido é \"0.00\" (o TFR da UE não aplica montante mínimo)." }, "ownership_validation_mode": { "type": "string", "enum": [ "FULL", "SIMPLIFIED", "AUTOMATED" ], "description": "Quanto comprovativo é necessário para comprovar a propriedade de uma carteira. `FULL` exige sempre um comprovativo (mensagem assinada, depósito de teste ou captura de ecrã revista), nunca a palavra do utilizador final. `SIMPLIFIED` aceita uma autodeclaração abaixo de `simplified_validation_threshold` e um comprovativo acima dele. `AUTOMATED` permite que o livro de endereços e comprovativos anteriores respondam por si próprios, incluindo autodeclarações enquanto `allow_self_declaration` for verdadeiro. Predefinição: `AUTOMATED`." }, "simplified_validation_threshold": { "type": "string", "description": "String decimal, por predefinição \"0.00\". No modo `SIMPLIFIED`, uma transferência abaixo deste montante (na moeda do limiar) aceita uma autodeclaração. Uma transferência sem montante nessa moeda conta como estando acima dele." }, "data_sharing_fields": { "$ref": "#/components/schemas/TravelRuleDataSharingFields" }, "matching_rules": { "$ref": "#/components/schemas/TravelRuleMatchingRules" }, "legal_name": { "type": "string", "description": "A denominação social do seu VASP. Obrigatória (não vazia) para definir is_enabled como true." }, "lei": { "type": "string", "description": "O seu Identificador de Entidade Jurídica (LEI), apresentado no diretório de VASP." }, "compliance_email": { "type": "string", "format": "email", "description": "E-mail de contacto de conformidade para o seu perfil de VASP. A rede Didit lista o seu perfil apenas após este endereço ser confirmado através de uma ligação enviada por e-mail (POST /v3/travel-rule/settings/compliance-email/confirmation/); a sua alteração requer uma nova confirmação." }, "is_discoverable": { "type": "boolean", "description": "Se o seu perfil de VASP pode ser listado na rede Didit: encontrado em GET /v3/travel-rule/vasps/ por outros clientes Didit e contactado na via INTERNAL. A listagem também requer uma aplicação de produção, o Travel Rule ativo, uma denominação social e um e-mail de conformidade confirmado; didit_network indica quais estão em falta. O valor predefinido é true." }, "inbound_auto_accept": { "type": "boolean", "description": "Quando for true, um inquérito TRP de entrada cuja carteira do beneficiário seja uma entrada verificada no livro de endereços com um nome correspondente é aprovado automaticamente. Quando for false, esse inquérito aguarda em ON_HOLD que o aprove ou recuse com o endpoint de propriedade. As transferências pela via INTERNAL e após depósito não são afetadas. O padrão é true." }, "allow_self_declaration": { "type": "boolean", "description": "Quando for true, o widget de propriedade da carteira disponibiliza a autodeclaração como método de prova alternativo. O valor predefinido é true." }, "allow_screenshot_proof": { "type": "boolean", "description": "Quando for true, o widget de propriedade da carteira disponibiliza o carregamento de capturas de ecrã como método de prova de propriedade. O padrão é true." }, "auto_wallet_verification": { "type": "boolean", "description": "Quando for true, a submissão de uma transferência da Travel Rule de saída que necessite de comprovativo de controlo da carteira por parte do utilizador final gera automaticamente uma sessão do widget de propriedade da carteira vinculada à transação e expõe-na no bloco action_required da transação. O padrão é true." }, "vasp_attribution_enabled": { "type": "boolean", "description": "Quando for true, uma transferência da Travel Rule de saída que nenhuma via consiga encaminhar é atribuída através de análise de blockchain: a carteira de destino é associada ao respetivo VASP proprietário, a entidade é registada na transferência e no diretório de VASP, e as vias são executadas novamente uma vez com o nome atribuído. O padrão é true." }, "counterparty_screening_enabled": { "type": "boolean", "description": "Triagem opcional de sanções e notícias adversas de VASPs de contraparte, faturada por triagem ao preço da Triagem AML da empresa. Quando ativada, a Didit analisa a contraparte que uma exchange de saída alcança (reutilizando uma triagem com menos de 30 dias) e pode analisar uma com POST /v3/travel-rule/vasps/{vasp_id}/screening/. Predefinição false: nada é analisado ou faturado." }, "sunrise_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "O impacto que uma transferência expirada tem na sua transação quando a contraparte é uma entrada do diretório numa jurisdição em sunrise_jurisdictions, que ainda não aplica a Travel Rule: HOLD move-a para análise, REJECT recusa-a, PROCEED mantém o seu estado inalterado. Vazio (a predefinição) segue timeout_outcome. Aplica-se antes de non_responsive_policy." }, "sunrise_jurisdictions": { "type": "array", "items": { "type": "string" }, "readOnly": true, "description": "Apenas de leitura. Os países (ISO 3166 alfa-2) que a Didit trata como estando num período de transição da Travel Rule, onde sunrise_policy se aplica. Atualmente CO, KH e VN. Qualquer outra jurisdição, bem como uma vazia ou desconhecida, segue timeout_outcome." }, "non_responsive_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "O impacto que uma transferência expirada tem na sua transação quando a contraparte é uma entrada do diretório cuja capacidade de resposta é UNRESPONSIVE: HOLD, REJECT ou PROCEED, tal como em timeout_outcome. Vazio (a predefinição) segue timeout_outcome. sunrise_policy aplica-se primeiro quando ambas forem aplicáveis." }, "travel_address": { "type": "string", "description": "Apenas de leitura. O Travel Address próprio do seu VASP - o endpoint codificado de consulta TRP de entrada que outros VASP utilizam para entrar em contacto consigo. Vazio enquanto `is_enabled` for false." }, "disabled_networks": { "type": "array", "items": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "description": "Redes que optaram por não aderir à plataforma. Não desativa as suas adesões próprias associadas nem disponibiliza redes indisponíveis.", "default": [] }, "networks": { "type": "object", "readOnly": true, "description": "Por rede, como esta aplicação enviaria e por que motivo não o consegue fazer. Nenhuma rede, incluindo a GTR, está incluída por predefinição: uma rede fica acessível através da sua própria adesão ligada, ou através da adesão da Didit assim que a adesão da Didit a essa rede estiver ativa e o seu próprio participante nela estiver ativo. Não se trata de uma verificação de estado ou de entrega em tempo real.", "properties": { "gtr": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "trust": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "verifyvasp": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "sygna": { "$ref": "#/components/schemas/TravelRuleNetworkState" } } }, "didit_network": { "type": "object", "readOnly": true, "description": "Indica se a rede Didit lista o seu perfil de VASP, para que outros clientes Didit o encontrem no diretório e o contactem pela via INTERNAL, bem como cada condição que ainda falta cumprir.", "properties": { "listed": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "travel_rule_off", "sandbox_application", "not_discoverable", "legal_name_missing", "compliance_email_missing", "compliance_email_unconfirmed", "excluded_by_staff", "internal_organization" ] }, "description": "Vazio quando listado. compliance_email_unconfirmed: envie a confirmação com POST /v3/travel-rule/settings/compliance-email/confirmation/ e abra a ligação enviada por e-mail. excluded_by_staff: a Didit marcou a aplicação como de teste, demonstração ou interna." }, "compliance_email_confirmed": { "type": "boolean", "description": "Indica se o compliance_email atual foi confirmado através da ligação enviada por e-mail." } } } } }, "TravelRuleSettingsUpdate": { "type": "object", "properties": { "is_enabled": { "type": "boolean" }, "legal_name": { "type": "string", "maxLength": 255 }, "lei": { "type": "string", "maxLength": 20 }, "jurisdiction": { "type": "string", "maxLength": 8 }, "name_matching_strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "`CONTAINS` aceita um nome cujas palavras aparecem todas no outro." }, "confirmation_timeout_hours": { "type": "integer", "minimum": 1 }, "timeout_outcome": { "type": "string", "enum": [ "HOLD", "REJECT", "PROCEED" ] }, "compliance_email": { "type": "string", "format": "email", "description": "E-mail de contacto de conformidade para o seu perfil de VASP. A rede Didit lista o seu perfil apenas após este endereço ser confirmado através de uma ligação enviada por e-mail (POST /v3/travel-rule/settings/compliance-email/confirmation/); a sua alteração requer uma nova confirmação." }, "is_discoverable": { "type": "boolean", "description": "Se o seu perfil de VASP pode ser listado na rede Didit: encontrado em GET /v3/travel-rule/vasps/ por outros clientes Didit e contactado na via INTERNAL. A listagem também requer uma aplicação de produção, o Travel Rule ativo, uma denominação social e um e-mail de conformidade confirmado; didit_network indica quais estão em falta. O valor predefinido é true." }, "threshold_amount": { "type": "string", "description": "String decimal, zero ou superior, na moeda predefinida da sua aplicação. Montante mínimo de transferência que aciona um câmbio gerido." }, "ownership_validation_mode": { "type": "string", "enum": [ "FULL", "SIMPLIFIED", "AUTOMATED" ], "description": "Consulte o campo da resposta com o mesmo nome." }, "simplified_validation_threshold": { "type": "string", "description": "String decimal, 0 ou superior." }, "data_sharing_fields": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleDataSharingFields" } ], "description": "Fundido por tipo de entidade: um tipo de entidade que omitir mantém a sua escolha atual. Uma escolha que não consiga cumprir as obrigações de ordenante do regime da sua `jurisdiction` (TFR da UE ou Recomendação 16 da FATF), incluindo uma lista vazia, é recusada com `400`." }, "matching_rules": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleMatchingRules" } ], "description": "Fundido por tipo de entidade e por campo dentro do mesmo. Um campo que esse tipo de entidade não compare (por exemplo, `date_of_birth` para `company`) é recusado com `400`." }, "inbound_auto_accept": { "type": "boolean" }, "allow_self_declaration": { "type": "boolean" }, "allow_screenshot_proof": { "type": "boolean", "description": "Quando for true, o widget de propriedade da carteira disponibiliza o carregamento de capturas de ecrã como método de prova de propriedade. O padrão é true." }, "auto_wallet_verification": { "type": "boolean" }, "vasp_attribution_enabled": { "type": "boolean" }, "counterparty_screening_enabled": { "type": "boolean", "description": "Triagem opcional de sanções e notícias adversas de VASPs de contraparte, faturada por triagem ao preço da Triagem AML da empresa. Quando ativada, a Didit analisa a contraparte que uma exchange de saída alcança (reutilizando uma triagem com menos de 30 dias) e pode analisar uma com POST /v3/travel-rule/vasps/{vasp_id}/screening/. Predefinição false: nada é analisado ou faturado." }, "sunrise_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "HOLD, REJECT, PROCEED ou vazio para seguir timeout_outcome. Consulte o campo de resposta com o mesmo nome." }, "non_responsive_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "HOLD, REJECT, PROCEED ou vazio para seguir timeout_outcome. Consulte o campo de resposta com o mesmo nome." }, "disabled_networks": { "type": "array", "items": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "description": "Redes que optaram por não aderir à plataforma. Não desativa as suas adesões próprias associadas nem disponibiliza redes indisponíveis.", "default": [] } }, "description": "Todos os campos são opcionais; o PUT aplica uma atualização parcial." }, "WalletAddressEntry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "address": { "type": "string", "description": "O endereço de carteira; `\"\"` para uma entrada importada apenas pelo respetivo hash. Exclusivo por aplicação, cadeia e memo, comparando o endereço sem distinção entre maiúsculas e minúsculas. Depois de eliminar uma entrada, pode registar novamente o mesmo endereço." }, "chain": { "type": "string", "description": "Token de blockchain para o endereço, por exemplo `ETH` ou `BTC`. Quando a Didit encaminha ou regista uma transferência, faz a correspondência das entradas do livro de endereços com o endereço da carteira e, quando a transferência inclui uma blockchain, também com este valor, ignorando maiúsculas/minúsculas. A blockchain de uma transferência é `beneficiary_data.chain`, preenchida a partir da blockchain cripto da transação ou do símbolo da moeda (por exemplo `ETH`) quando não o envia, ou a `chain` de um registo pós-depósito, pelo que deve usar o mesmo token em todo o lado. Uma entrada com uma blockchain vazia corresponde a qualquer blockchain. Um beneficiário Lightning (um ID de nó ou um Lightning Address) registado em bitcoin é armazenado em minúsculas em `LIGHTNING`, onde as transferências Lightning são correspondidas. As blockchains conhecidas são armazenadas sob um único identificador canónico, independentemente da grafia enviada: \"ethereum\", \"Ethereum\" e \"ERC20\" são todas armazenadas como ETH, \"BNB Smart Chain\" e \"BEP20\" como BNB, \"tron\" como TRX. Um nome de blockchain desconhecido é mantido tal como fornecido." }, "holder_vendor_data": { "type": "string", "description": "O seu identificador interno para o titular." }, "holder_name": { "type": "string", "description": "Nome do titular da carteira, utilizado para a correspondência de nome do beneficiário." }, "entity_type": { "type": "string", "description": "Texto livre; por predefinição, é \"individual\"." }, "is_ownership_verified": { "type": "boolean", "description": "Apenas de leitura. Se a propriedade deste endereço foi comprovada." }, "created_at": { "type": "string", "format": "date-time" }, "travel_address": { "type": "string", "description": "O Travel Address do VASP da contraparte para esta carteira, se conhecido. Permite que a Didit encaminhe as transferências deste beneficiário através da via TRP, para os ativos suportados pelo TRP (BTC, ETH e USDC numa rede indicada)." }, "address_hash": { "type": "string", "description": "Apenas de leitura. SHA-256 do endereço em minúsculas, em hexadecimal minúsculo. Uma entrada importada apenas pelo respetivo hash é comparada com este valor." }, "memo": { "type": "string", "description": "A tag ou memo de destino que faz parte da carteira numa rede baseada em memo (XRP, XLM, EOS, ATOM, HBAR); `\"\"` para o endereço completo. Uma entrada com um memo apenas corresponde a transferências que indiquem esse memo; uma entrada sem memo corresponde ao endereço completo." }, "receiving_travel_address": { "type": "string", "readOnly": true, "description": "O seu Travel Address específico por carteira para esta carteira: forneça-o ao VASP remetente para que a respetiva consulta TRP identifique esta carteira. Vazio para uma carteira registada como pertencente a outro VASP, enquanto a Travel Rule estiver desativada e antes de o seu perfil de VASP ser guardado." } } }, "WalletAddressEntryCreate": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "maxLength": 128, "description": "O endereço de carteira. Um endereço X da XRP é guardado como o seu endereço clássico e a respetiva tag, pelo que corresponde a transferências que indiquem qualquer um dos formatos." }, "chain": { "type": "string", "maxLength": 32, "description": "Token da blockchain para o endereço, por exemplo `ETH` ou `BTC`. Quando a Didit encaminha ou regista uma transferência, faz a correspondência das entradas do livro de endereços com base no endereço da carteira e, quando a transferência inclui uma blockchain, também neste valor, ignorando maiúsculas e minúsculas. A blockchain de uma transferência é `beneficiary_data.chain`, preenchida a partir da blockchain de criptoativos ou do símbolo da moeda da transação (por exemplo `ETH`) quando não a enviar, ou o `chain` de um registo pós-depósito, pelo que deve usar o mesmo token em todo o lado. Uma entrada com uma blockchain vazia corresponde a qualquer blockchain. As blockchains conhecidas são armazenadas sob um identificador canónico, independentemente da grafia enviada: \"ethereum\", \"Ethereum\" e \"ERC20\" são todas guardadas como ETH, \"BNB Smart Chain\" e \"BEP20\" como BNB, \"tron\" como TRX. Um nome de blockchain desconhecido é mantido tal como fornecido." }, "holder_vendor_data": { "type": "string", "maxLength": 255 }, "holder_name": { "type": "string", "maxLength": 255 }, "entity_type": { "type": "string", "default": "individual", "maxLength": 16 }, "self_declared": { "type": "boolean", "default": false, "description": "Apenas de escrita. Quando true, a entrada é criada já com a propriedade verificada através de uma prova SELF_DECLARATION. Devolve 400 quando `allow_self_declaration` estiver desativado nas suas definições de Travel Rule." }, "travel_address": { "type": "string", "description": "Opcional. O Travel Address do VASP da contraparte para esta carteira, ativando o encaminhamento TRP para os ativos suportados pelo TRP (BTC, ETH e USDC numa rede designada). Um Travel Address inválido devolve 400.", "maxLength": 512 }, "memo": { "type": "string", "maxLength": 256, "description": "Opcional. A destination tag ou memo que faz parte da carteira. XRP: uma destination tag, um número inteiro de 0 a 4294967295 (é aceite um número JSON). XLM: um memo de texto de até 28 bytes, um id de 64 bits ou um hash de 32 bytes em hexadecimal. EOS: até 256 bytes. ATOM: até 256 carateres. HBAR: até 100 bytes. As carteiras de Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning não aceitam memo: incluir um resulta num `400`. Alias: `destinationTag` ou `destination_tag`." } } }, "WalletAddressEntryUpdate": { "type": "object", "properties": { "holder_name": { "type": "string", "maxLength": 255 }, "holder_vendor_data": { "type": "string", "maxLength": 255 }, "entity_type": { "type": "string", "maxLength": 16 }, "travel_address": { "type": "string", "maxLength": 512 } }, "description": "PATCH é uma atualização parcial; a resposta reflete apenas holder_name, holder_vendor_data, entity_type, travel_address, receiving_travel_address, label e owner_type." }, "TravelRuleTransferDetail": { "type": "object", "description": "Objeto completo de transferência devolvido pelos endpoints de confirmação de propriedade e de finalização/cancelamento. Enquanto a propriedade da carteira de uma transferência recebida não estiver confirmada, os campos `originator_data` e `beneficiary_data` da contraparte são devolvidos mascarados (a primeira letra de cada palavra é mantida; a carteira, a blockchain e o encaminhamento do VASP permanecem legíveis) e `data_masked` é true.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "rail": { "type": "string", "nullable": true, "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP", null ], "description": "O canal através do qual a transferência foi encaminhada, ou null quando nenhum canal foi selecionado (por exemplo, abaixo do limiar, uma carteira de contraparte autocustodiada, um registo pós-depósito, ou nenhuma contraparte alcançável). INTERNAL significa que ambos os lados são aplicações da Didit; EMAIL significa que a contraparte foi alcançada através de uma ligação de recolha enviada por e-mail. TEST_VASP significa que o Didit Test VASP respondeu à transferência em sandbox. Através de GTR, VERIFYVASP e SYGNA, a Didit lê a resposta da contraparte a partir da resposta da rede ou consultando-a a cada 5 minutos. TRUST apenas envia, pelo que uma transferência TRUST permanece AWAITING_COUNTERPARTY até expirar. Um canal de rede só é utilizado quando tiver associado a sua própria adesão a essa rede. É escolhido após o retorno da criação da transação, pelo que é null nessa resposta." }, "protocol": { "type": "string", "nullable": true }, "ivms_version": { "type": "string", "example": "ivms101.2023" }, "required": { "type": "boolean" }, "ownership_confirmed": { "type": "boolean", "nullable": true }, "deadline_at": { "type": "string", "format": "date-time", "nullable": true }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "detail": { "type": "string" }, "name_match": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleNameMatch" } ], "nullable": true, "description": "A comparação de nomes decidida por esta entrada, junto a `detail`. Ausente em entradas que não compararam qualquer nome." }, "reason": { "type": "string", "description": "Presente apenas na entrada de uma transição causada por uma entrega com falha: `email_undeliverable` ou `delivery_failed`, o valor que `reason` da transferência reporta." } } } }, "counterparty_vasp": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "lei": { "type": "string" }, "dd_score": { "type": "integer", "description": "Pontuação de diligência devida de 0 a 100, onde quanto mais alto, melhor. Mesma escala que no diretório VASP." }, "dd_score_breakdown": { "type": "object", "description": "Contribuições por componente para dd_score, um objeto por componente como no diretório VASP (jurisdiction, verification, protocol, lei, history, essentials, responsiveness), cada um com {points, max, reason, detail}. {} até que a contraparte tenha sido avaliada.", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "Pontos atribuídos a este componente." }, "max": { "type": "integer", "description": "Pontos máximos que este componente pode atribuir." }, "reason": { "type": "string", "description": "Código legível por máquina do veredito do componente." }, "detail": { "type": "string", "description": "Motivo legível por humanos para os pontos atribuídos." } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a avaliação de diligência devida foi executada pela última vez. Nulo até que a contraparte tenha sido avaliada." } } }, "originator_data": { "type": "object", "description": "Parte ordenante. Para uma transferência de entrada, os valores da contraparte são ocultados até que a propriedade seja confirmada." }, "beneficiary_data": { "type": "object", "description": "Parte beneficiária. Para uma transferência de entrada, os valores da contraparte são ocultados até que a propriedade seja confirmada." }, "name_match": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleNameMatch" } ], "nullable": true, "description": "A comparação de nomes que decidiu a transferência, ou nulo até que uma seja executada. Enquanto as partes estiverem mascaradas, e na cópia do outro cliente de uma troca INTERNAL, `transfer_name`, `compared_name`, `matched_names` e `mismatched_names` são ocultados. `score` e `matched` podem divergir: `matched` segue o rigor, `score` é a semelhança dos dois nomes completos." }, "data_match": { "$ref": "#/components/schemas/TravelRuleDataMatch" }, "mismatched_fields": { "type": "array", "items": { "type": "string" }, "description": "Atalho para `data_match.mismatched_fields`. Vazio quando nada difere." }, "data_unmasked": { "$ref": "#/components/schemas/TravelRuleDataUnmasked" }, "data_masked": { "type": "boolean", "description": "Verdadeiro enquanto os dados pessoais da contraparte estiverem mascarados nesta resposta." }, "created_at": { "type": "string", "format": "date-time" }, "delivery": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TravelRuleDelivery" } ], "description": "O estado em que se encontra a mensagem mais recente que esta transferência deve à outra parte. Nulo quando a transferência nunca deveu nenhuma (por exemplo, abaixo de `threshold_amount`, uma carteira autocustodiada declarada ou um registo sunrise)." }, "discovery": { "type": "array", "description": "Como a Didit procurou a contraparte, uma entrada por passo executado. Vazio quando não foi executada qualquer deteção, por exemplo, numa transferência recebida.", "items": { "$ref": "#/components/schemas/TravelRuleDiscoveryStep" } }, "reason": { "type": "string", "description": "O motivo pelo qual uma transferência `COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE` está bloqueada; `\"\"` para qualquer outro estado. Uma falha na entrega determina-o primeiro, apenas em `COUNTERPARTY_VASP_NOT_REACHABLE`: `email_undeliverable` (o fornecedor de e-mail recusou o e-mail de conformidade e não resta nenhum endereço para tentar: quando foi enviado, num lembrete ou como uma devolução permanente comunicada posteriormente) ou `delivery_failed` (o canal que estava a efetuar a entrega falhou definitivamente: um canal de rede recusou a mensagem ou esgotou as tentativas, um host de identidade `TRP` não respondeu, ou o host `TRP` da contraparte não aceitou a consulta). Caso contrário, o rastreio de `discovery` determina-o: `awaiting_end_user` (nenhum passo identificou uma contraparte que a Didit consiga contactar), `directory_match_no_route` (um passo identificou um VASP de diretório que não tem rota), `picked_member_without_proven_wallet` (o utilizador final escolheu um cliente Didit que não comprovou o controlo da carteira), ou `no_directory_match` quando o rastreio não fornece outro motivo. Um novo envio faz avançar a transferência, pelo que o motivo é limpo. Consulte [Por que motivo uma transferência está bloqueada](/pt/transaction-monitoring/travel-rule#por-que-motivo-uma-transferência-está-bloqueada)." }, "next_actions": { "type": "array", "description": "O que faz a transferência avançar; `[]` para qualquer estado exceto `COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE`. `email_undeliverable` disponibiliza `update_compliance_email` e, em seguida, `resend`. `delivery_failed` disponibiliza `resend`. Um motivo de descoberta disponibiliza `select_counterparty_vasp`, `declare_self_hosted`, `add_vasp_hint` e `resend`.", "items": { "$ref": "#/components/schemas/TravelRuleNextAction" } }, "chain_details": { "$ref": "#/components/schemas/TravelRuleChainDetails" } } }, "TravelRuleOwnershipConfirmRequest": { "type": "object", "required": [ "confirmed" ], "properties": { "confirmed": { "type": "boolean", "description": "true para confirmar a propriedade, false para a negar." }, "wallet_address": { "type": "string", "default": "", "description": "Transferências TRP de entrada: o endereço de pagamento que a Didit devolve ao VASP de origem quando aprova. O valor predefinido é o endereço da entrada correspondente no livro de endereços, seguido de beneficiary_data.wallet_address. Numa transferência declarada de carteira autocustodiada que não indique uma carteira da contraparte, a carteira cuja propriedade verificou; sem ela, o pedido é rejeitado com 400. Ignorado para outras transferências." } } }, "TravelRuleTransferPatchRequest": { "type": "object", "description": "Forneça exatamente um de: payment_txn_id (finish), action=cancel, action=resend, action=update_compliance_email com compliance_email, action=update_originator_wallet com wallet_address ou action=beneficiary_vasp com beneficiary_vasp.", "properties": { "payment_txn_id": { "type": "string", "description": "O hash da transação on-chain. Exige que a transferência seja uma transferência de saída no estado COMPLETED." }, "action": { "type": "string", "enum": [ "cancel", "resend", "update_compliance_email", "update_originator_wallet", "beneficiary_vasp" ], "description": "\"cancel\" cancela uma transferência não terminal. \"resend\" executa novamente o encaminhamento de uma transferência enviada retida em COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE ou NOT_ENOUGH_COUNTERPARTY_DATA. \"update_compliance_email\" substitui o e-mail de conformidade para o qual o pedido é enviado, numa transferência enviada num desses três estados; envie \"resend\" em seguida. \"update_originator_wallet\" regista a carteira de onde os fundos saíram efetivamente (`wallet_address`, `memo`). \"beneficiary_vasp\" indica manualmente o VASP da contraparte (requer `beneficiary_vasp`) para uma transferência enviada num desses estados: é encaminhada para esse VASP e enviada novamente." }, "compliance_email": { "type": "string", "format": "email", "maxLength": 254, "description": "Obrigatório com `action: update_compliance_email`. Mantido como `beneficiary_data.counterparty_vasp_email` desta transferência: pertence apenas a esta transferência e não é associado a nenhuma entrada do diretório nem a nenhuma lista de contactos." }, "wallet_address": { "type": "string", "maxLength": 128, "description": "Com `action: update_originator_wallet`: a carteira de onde os fundos saíram. Quando as entradas UTXO da transferência são conhecidas, tem de ser uma delas." }, "memo": { "type": "string", "maxLength": 256, "description": "Com `action: update_originator_wallet`: o memo ou etiqueta da carteira numa rede com memo. Opcional." }, "beneficiary_vasp": { "type": "string", "format": "uuid", "description": "Obrigatório com action=beneficiary_vasp: o `id` de um VASP do diretório, de `GET /v3/travel-rule/vasps/`. A sua escolha tem prioridade sobre qualquer passo de deteção automática, que nunca a substitui." } } }, "VaspDirectoryEntry": { "type": "object", "description": "Um VASP do diretório ou um membro da rede Didit, com as rotas que a sua aplicação tem para o mesmo. Um cliente é membro da rede Didit apenas enquanto a sua aplicação estiver em produção, o seu Travel Rule estiver ativado, o seu perfil for detetável, tiver uma denominação social e um e-mail de conformidade confirmado, e a Didit não tiver marcado a aplicação como de teste, demonstração ou interna. Cada linha inclui também a avaliação de diligência devida partilhada (dd_score, risk_level, responsiveness, essential_checks) e a decisão, triagem de entidades e questionários próprios da sua aplicação, que nenhum outro cliente vê.", "properties": { "id": { "type": "string", "format": "uuid", "description": "O id da entrada, para GET /v3/travel-rule/vasps/{vasp_id}/." }, "kind": { "type": "string", "enum": [ "directory", "didit" ], "description": "directory para uma entrada do diretório partilhado; didit para um membro da rede Didit." }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string", "description": "Código de país ISO 3166, tal como fornecido pela fonte." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Os domínios web do VASP. Sempre vazios para membros da rede Didit." }, "reachable": { "type": "boolean", "description": "Se a sua aplicação tem uma rota disponível para este VASP ou para uma das suas entidades de uma marca. Sempre true para um membro da rede Didit, exceto numa aplicação sandbox, onde todas as linhas são false." }, "aliases": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "trading_name", "other_legal_name", "network_name", "attribution", "merged", "staff" ], "description": "trading_name, other_legal_name (do registo global de LEI), network_name (o nome numa rede da Travel Rule), attribution (o nome da entidade que a análise de blockchain atribui às carteiras do VASP), merged (o nome de uma entrada duplicada fundida nesta) ou staff." } } }, "description": "Outros nomes pelos quais o VASP é identificado." }, "networks": { "type": "array", "items": { "type": "object", "description": "Uma listagem atual deste VASP no diretório de membros de uma rede Travel Rule. Uma listagem TRISA indica quem é o VASP na TRISA; a Didit não tem canal TRISA, pelo que nunca é uma rota.", "properties": { "network": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "code": { "type": "string", "description": "O identificador do VASP nessa rede." }, "listed_name": { "type": "string", "description": "O nome sob o qual a rede lista o VASP." }, "country": { "type": "string", "description": "O país indicado pela rede, quando disponibilizado." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a equipa da Didit verificou a listagem. Nulo para listagens lidas a partir de um diretório público." }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a fonte apresentou a listagem pela última vez. Uma listagem que a fonte não tenha apresentado durante três semanas é removida." }, "source": { "type": "string", "enum": [ "trisa_directory", "staff" ], "description": "De onde provém a listagem: do diretório público TRISA ou da equipa da Didit." } } } }, "routes": { "type": "array", "items": { "type": "object", "description": "Uma forma de a sua aplicação entregar dados de Travel Rule a este VASP, pela ordem pela qual o envio os tenta. Uma rota de rede necessita de uma adesão nessa rede: a sua própria (ligada no Marketplace) ou a da Didit assim que a Didit a detenha. Sem ela, a rota é listada como indisponível com o respetivo motivo, nunca como uma forma de contactar o VASP.", "properties": { "rail": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL" ] }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "type": "string", "enum": [ "", "no_membership", "network_switched_off", "sandbox_application" ], "description": "O motivo pelo qual uma rota indisponível não pode ser utilizada: no_membership (nem você nem a Didit possuem adesão nessa rede), network_switched_off (desativou essa rede nas suas definições) ou sandbox_application (uma aplicação de sandbox envia apenas para o Didit Test VASP, pelo que nenhuma rota está disponível para ela). Vazio quando a rota está disponível." }, "via": { "type": "string", "enum": [ "", "own_membership", "didit_membership", "directory", "contact", "didit_network" ], "description": "Como se alcança uma rota disponível: own_membership ou didit_membership para uma via de rede, directory para um endpoint TRP verificado pelo diretório, contact para a via EMAIL, didit_network para um membro da rede Didit. Vazio quando a rota está indisponível." } } } }, "umbrella": { "type": "object", "nullable": true, "description": "A marca da qual esta entrada é uma entidade regulada. Nulo quando não faz parte de nenhuma.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "entities": { "type": "array", "items": { "type": "object", "description": "Uma entidade regulada de uma marca: a entidade legal que recebe uma transferência.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string" }, "reachable": { "type": "boolean", "description": "Se a sua aplicação tem uma rota disponível para o mesmo." } } }, "description": "Para uma marca, as entidades regulamentadas que recebem as suas transferências. Uma transferência que indique a marca segue para a entidade acessível na jurisdição indicada (beneficiary_data.counterparty_vasp_jurisdiction); caso contrário, para a entidade atribuída pela análise de blockchain associada à carteira de destino; caso contrário, para a única entidade acessível quando nenhuma jurisdição for indicada. Nunca se escolhe entre duas entidades igualmente adequadas por suposição." }, "contacts": { "type": "array", "items": { "type": "object", "description": "Um contacto de conformidade para o qual o canal EMAIL pode escrever.", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "staff", "application", "learned" ], "description": "staff: com curadoria da Didit; application: adicionado pela sua aplicação; learned: um endereço que respondeu a um pedido da Travel Rule através da respetiva ligação de resposta." }, "scope": { "type": "string", "enum": [ "platform", "application" ], "description": "os contactos da plataforma são utilizados para as transferências de todos os clientes da Didit; os contactos da aplicação são privados da sua aplicação, que vê apenas os seus próprios." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando alguém neste endereço respondeu a um pedido. Nulo quando ainda não o fez." } } }, "description": "Os contactos da plataforma para este VASP e os da sua própria aplicação." }, "dd_status": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "REJECTED" ], "description": "Estado de verificação da Didit para a entrada, pontuado pela componente de verificação do dd_score. Sempre COMPLETED para um membro da rede Didit." }, "dd_score": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100, "description": "A pontuação partilhada de diligência devida de uma entrada do diretório, de 0 a 100, onde quanto mais alto, mais seguro (consulte dd_score_semantic): a soma dos pontos em dd_score_breakdown. Nulo para um membro da rede Didit, que não é pontuado. Uma entrada ainda não avaliada (dd_assessed_at nulo) apresenta 0 com um risk_level vazio; por isso, consulte risk_level em vez da pontuação bruta." }, "reachable_rails": { "type": "array", "items": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL" ] }, "description": "Vias registadas na entrada. Consulte as rotas para ver o que a sua aplicação pode utilizar hoje." }, "is_didit_customer": { "type": "boolean", "description": "true para um membro da rede Didit (dd_status é sempre COMPLETED, dd_score é null e risk_level fica vazio nestes casos) e para uma entrada do diretório associada a um cliente da Didit." }, "dd_score_breakdown": { "type": "object", "description": "Um objeto por componente de dd_score. Componentes, o respetivo peso (máx.) e os respetivos códigos de motivo: jurisdiction, 25 (jurisdiction_not_high_risk, jurisdiction_high_risk, jurisdiction_unknown); verification, 15 (dd_status_completed, dd_status_in_progress, dd_status_not_started, dd_status_rejected); protocol, 15 (native_rail, email_only, no_rail); lei, 10 (lei_valid, lei_missing); history, 10 (history, no_history); essentials, 15 (essential_checks, no_essential_checks); responsiveness, 10 (responsive, unresponsive, responsiveness_unknown). Vazio para um membro da rede Didit.", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "Pontos com que o componente contribui, arredondados a uma casa decimal." }, "max": { "type": "integer", "description": "O peso do componente: os pontos com que contribui no melhor dos casos." }, "reason": { "type": "string", "description": "Código legível por máquina do veredito do componente." }, "detail": { "type": "string", "description": "Explicação em inglês numa única linha." } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando dd_score, risk_level e responsiveness foram calculados pela última vez: após uma troca com a entrada ser concluída, terminar, expirar, não corresponder ou ser recusada, quando a Didit atualiza ou faz a curadoria da entrada, e na atualização semanal do diretório. Nulo para um membro da rede Didit." }, "dd_score_semantic": { "type": "string", "enum": [ "higher_is_safer" ], "description": "Em que sentido o dd_score aponta: sempre higher_is_safer." }, "risk_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "" ], "description": "A faixa em que dd_score se insere: LOW (70 ou mais), MEDIUM (40 a 69) ou HIGH (abaixo de 40). Vazio para um membro da rede Didit e para uma entrada ainda não avaliada. Filtre por este parâmetro com risk. A sua própria triagem sinalizada nunca altera este valor partilhado: em vez disso, define counterparty_risk_level como HIGH nas suas regras." }, "responsiveness": { "type": "object", "description": "Indica se o VASP responde a pedidos de Travel Rule: a percentagem de pedidos iniciados por clientes Didit em direção a ele nos últimos 90 dias que foram respondidos. Apenas contam os pedidos enviados através de uma via de rede ou protocolo, ou por e-mail para um endereço partilhado (o endereço de conformidade do registo ou um contacto da plataforma); um pedido enviado para um endereço introduzido manualmente por um cliente, ou para o contacto privado de um cliente, nunca conta. Um pedido expirado conta como não respondido; uma troca concluída, uma recusa ou uma divergência de dados contam como resposta; um pedido cancelado ou uma via inacessível não contam como nenhum dos dois. Sempre UNKNOWN com contagens a zero para um membro da rede Didit.", "properties": { "status": { "type": "string", "enum": [ "RESPONSIVE", "UNRESPONSIVE", "UNKNOWN" ], "description": "UNKNOWN com menos de 5 pedidos decididos no intervalo; UNRESPONSIVE quando menos de 10 por cento foram respondidos; RESPONSIVE nos restantes casos." }, "answered": { "type": "integer", "description": "Pedidos decididos na janela, aos quais o VASP respondeu." }, "total": { "type": "integer", "description": "Pedidos decididos na janela: respondidos mais expirados." }, "computed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "essential_checks": { "type": "object", "description": "O relatório de verificações essenciais de uma entrada do diretório, construído exclusivamente a partir de fontes verificadas da plataforma: registo (um registo oficial lista o VASP: o registo provisório do MiCA da UE, o diretório público da TRISA ou o registo global de LEI), licença (uma autorização MiCA está registada e em vigor), domínio (o domínio da entrada corresponde ao respetivo endpoint TRP ou ao website indicado no seu registo) e lei (o respetivo registo LEI está ativo, emitido e consistente com os nomes e o país da entrada). O componente de verificações essenciais do dd_score é a proporção de verificações decididas com resultado positivo. Fica vazio até que a atualização semanal do diretório verifique a entrada pela primeira vez, e está sempre vazio para membros da rede Didit.", "properties": { "level": { "type": "string", "enum": [ "essential" ] }, "checked_at": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "registration", "licence", "domain", "lei" ] }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown" ], "description": "unknown quando nenhuma fonte registada consegue decidir a verificação." }, "reason": { "type": "string", "description": "Código legível por máquina do veredito." }, "detail": { "type": "string", "description": "Explicação em inglês numa única linha." } } } }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "unknown": { "type": "integer" }, "total": { "type": "integer" } } }, "decision": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyDecision" } ], "nullable": true, "description": "A decisão da sua aplicação sobre este VASP ou, para uma entidade sem decisão própria, a da sua marca (inherited_from indica a marca). Nulo quando não existe nenhuma. Privada para a sua aplicação." }, "entity_screening": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } ], "nullable": true, "description": "A triagem mais recente de sanções e notícias adversas da sua aplicação sobre este VASP. Nula se nunca o tiver analisado. Privada para a sua aplicação." }, "questionnaires": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "description": "Os questionários de diligência prévia da sua aplicação com este VASP, os mais recentes primeiro. Privados para a sua aplicação." } }, "example": { "id": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "kind": "directory", "name": "Example Counterparty VASP", "lei": "529900EXAMPLECPTY001", "jurisdiction": "DE", "domains": [ "counterparty.example" ], "reachable": true, "aliases": [ { "name": "Example Counterparty", "kind": "trading_name" } ], "networks": [ { "network": "GTR", "code": "EXAMPLE01", "listed_name": "Example Counterparty VASP", "country": "DE", "verified_at": "2026-10-12T09:30:00Z", "last_seen_at": "2026-10-12T09:30:00Z", "source": "staff" } ], "routes": [ { "rail": "GTR", "status": "unavailable", "reason": "no_membership", "via": "" }, { "rail": "EMAIL", "status": "available", "reason": "", "via": "contact" } ], "umbrella": null, "entities": [], "contacts": [ { "id": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "email": "travelrule@counterparty.example", "name": "Travel Rule desk", "source": "staff", "scope": "platform", "verified_at": null } ], "dd_status": "NOT_STARTED", "dd_score": 62, "dd_score_breakdown": { "jurisdiction": { "points": 25.0, "max": 25, "reason": "jurisdiction_not_high_risk", "detail": "DEU is not on the high-risk jurisdiction list" }, "verification": { "points": 3.8, "max": 15, "reason": "dd_status_not_started", "detail": "due diligence status NOT_STARTED" }, "protocol": { "points": 6.0, "max": 15, "reason": "email_only", "detail": "reachable over the email fallback only" }, "lei": { "points": 10.0, "max": 10, "reason": "lei_valid", "detail": "valid LEI on record" }, "history": { "points": 5.0, "max": 10, "reason": "no_history", "detail": "no exchange history" }, "essentials": { "points": 7.5, "max": 15, "reason": "no_essential_checks", "detail": "no decided essential check yet" }, "responsiveness": { "points": 5.0, "max": 10, "reason": "responsiveness_unknown", "detail": "0 decided recent requests, too few to judge" } }, "dd_assessed_at": "2026-10-12T09:30:00Z", "dd_score_semantic": "higher_is_safer", "risk_level": "MEDIUM", "responsiveness": { "status": "UNKNOWN", "answered": 0, "total": 0, "computed_at": "2026-10-12T09:30:00Z" }, "essential_checks": {}, "reachable_rails": [ "GTR", "EMAIL" ], "is_didit_customer": false, "decision": { "decision": "APPROVED", "reason": "Licensed in DE, questionnaire reviewed", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null }, "entity_screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false }, "questionnaires": [ { "id": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "status": "ANSWERED", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-09-02T08:00:00Z", "expires_at": "2026-10-02T08:00:00Z", "answered_at": "2026-09-04T15:20:00Z", "valid_until": "2027-09-04T15:20:00Z", "current": true, "answers": { "legal_name": "Example Counterparty VASP, incorporated in the example jurisdiction.", "licensing": "Crypto-asset service provider authorised under MiCA by its national regulator, licence active.", "jurisdictions": "EU and EEA. We do not serve the United States.", "aml_program": "Written AML/CFT policy, annual independent review, last completed in March 2026.", "compliance_officer": "Head of Compliance, reachable at compliance@counterparty.example.", "sanctions_screening": "Customers at onboarding and daily; counterparties on every transfer.", "transaction_monitoring": "Rule-based monitoring with analyst review; suspicious activity reports filed with the FIU.", "travel_rule": "TRP and email; we answer requests within one business day.", "custody": "Segregated customer wallets held with a qualified custodian, insured.", "ownership": "No shareholder holds 25 percent or more; parent company Example Holding Group.", "record_keeping": "Five-year record-keeping for Travel Rule and transaction data, as our regulator requires.", "data_protection": "Encrypted at rest and in transit, stored in the EU." } } ] } }, "TravelRuleCounterpartyDecision": { "type": "object", "description": "A decisão da sua aplicação sobre um VASP de contraparte. Privada para a sua aplicação: nunca altera a entrada do diretório partilhado e outro cliente nunca a vê. Atua apenas através das suas regras de transação (o campo de regra counterparty_dd_status e as predefinições travel-rule-counterparty-blocked e travel-rule-counterparty-restricted); nunca altera a forma como uma transferência é encaminhada.", "properties": { "decision": { "type": "string", "enum": [ "APPROVED", "RESTRICTED", "BLOCKED" ], "description": "APPROVED: a sua equipa aprovou a contraparte. RESTRICTED: as transferências para a mesma podem prosseguir após revisão. BLOCKED: a sua equipa recusou-a." }, "reason": { "type": "string", "maxLength": 255, "description": "Motivo em texto livre que indicou, vazio quando não existe nenhum." }, "decided_by": { "type": "string", "description": "O utilizador da consola que tomou ou alterou pela última vez a decisão. Vazio quando tomada através de uma chave de API." }, "updated_at": { "type": "string", "format": "date-time" }, "inherited_from": { "type": "object", "nullable": true, "description": "A marca cuja decisão esta entidade segue porque não tomou nenhuma sobre a própria entidade. Nulo quando a decisão é da própria contraparte.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } }, "TravelRuleCounterpartyDecisionResponse": { "type": "object", "properties": { "decision": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyDecision" } ], "nullable": true, "description": "A decisão aplicável à contraparte para a sua aplicação: a sua própria ou, caso contrário (para uma entidade de uma marca), a da marca. Null quando não existir nenhuma." } } }, "TravelRuleCounterpartyDecisionRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "APPROVED", "RESTRICTED", "BLOCKED" ] }, "reason": { "type": "string", "maxLength": 255, "description": "Opcional. Substitui o motivo anterior; omita-o para limpá-lo." } } }, "TravelRuleCounterpartyScreening": { "type": "object", "description": "Uma triagem de sanções e de notícias adversas da entidade de contraparte, executada para e faturada à sua aplicação. Privada para a sua aplicação: outro cliente nunca a vê.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Aprovada: nenhuma correspondência possível requer atenção. Em análise ou Recusada: uma possível correspondência com sanções ou notícias adversas." }, "total_hits": { "type": "integer", "description": "Quantas correspondências possíveis a triagem devolveu." }, "score": { "type": "number", "nullable": true, "description": "A pontuação de risco mais elevada entre as correspondências possíveis. Nulo quando não houve correspondências." }, "screened_at": { "type": "string", "format": "date-time" }, "fresh": { "type": "boolean", "description": "Se a triagem tem menos de fresh_days (30 dias). Uma triagem recente é reutilizada em vez de ser faturada novamente." }, "flagged": { "type": "boolean", "description": "true enquanto a triagem for recente e o respetivo estado for In Review ou Declined. Enquanto a sua triagem mais recente estiver sinalizada e a triagem de contrapartes permanecer ativa, counterparty_risk_level é HIGH nas suas regras." } } }, "TravelRuleCounterpartyScreeningStatus": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "A sua definição counterparty_screening_enabled de Travel Rule. Desativada por predefinição; nada é analisado nem faturado enquanto estiver desativada." }, "price": { "type": "string", "description": "String decimal, em USD: o custo de uma triagem para a sua organização, o preço de Triagem AML de Empresas." }, "fresh_days": { "type": "integer", "description": "Quantos dias uma triagem permanece recente e é reutilizada." }, "screening": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } ], "nullable": true, "description": "A sua triagem mais recente da contraparte. Nulo se nunca a tiver submetido a triagem." } } }, "TravelRuleCounterpartyScreeningRequest": { "type": "object", "properties": { "refresh": { "type": "boolean", "default": false, "description": "true realiza nova triagem (e fatura novamente) mesmo quando já existe uma triagem recente." } } }, "TravelRuleCounterpartyScreeningResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "screened", "reused" ], "description": "screened: uma nova triagem foi executada e faturada (201). reused: uma triagem recente foi devolvida e nada foi faturado (200)." }, "screening": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } } }, "TravelRuleCounterpartyQuestionnaire": { "type": "object", "description": "Um questionário de diligência devida que a sua aplicação enviou à contraparte: o questionário padrão da Didit, enviado por e-mail para um endereço de conformidade registado com uma ligação de resposta de utilização única. Privado da sua aplicação.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "SENT", "ANSWERED", "EXPIRED" ], "description": "SENT: a aguardar respostas. ANSWERED: a contraparte respondeu a todas as perguntas. EXPIRED: a ligação de resposta expirou sem resposta (o prazo terminou ou foi substituída por um questionário mais recente), ou as respostas ultrapassaram valid_until." }, "form_version": { "type": "string", "description": "Versão do questionário padrão do Didit à qual as respostas pertencem. Atualmente 1." }, "sent_to": { "type": "string", "format": "email" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "O prazo de resposta, 30 dias após o envio. A ligação deixa de funcionar após essa data." }, "answered_at": { "type": "string", "format": "date-time", "nullable": true }, "valid_until": { "type": "string", "format": "date-time", "nullable": true, "description": "Duração da validade das respostas: 365 dias após serem respondidas. Nulo até ser respondido." }, "current": { "type": "boolean", "description": "true enquanto o questionário estiver ANSWERED e valid_until não tiver expirado." }, "answers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "As respostas indexadas pelo id da pergunta: legal_name, licensing, jurisdictions, aml_program, compliance_officer, sanctions_screening, transaction_monitoring, travel_rule, custody, ownership, record_keeping, data_protection. Cada resposta tem até 2.000 carateres. Vazias até serem respondidas." } } }, "TravelRuleCounterpartyQuestionnaireRequest": { "type": "object", "properties": { "sent_to": { "type": "string", "format": "email", "description": "Opcional. Um endereço de conformidade registado para a contraparte: para uma entrada de diretório, o respetivo endereço de conformidade ou um contacto que a sua aplicação vê; para um membro da rede Didit, o respetivo e-mail de conformidade confirmado. Predefinição: o endereço para o qual é enviado um e-mail de Travel Rule para a contraparte (primeiro o seu próprio contacto, depois um contacto da plataforma e, por fim, o endereço de conformidade da entrada)." } } }, "TravelRuleCounterpartyQuestionnaireList": { "type": "object", "properties": { "questionnaires": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "description": "Mais recentes primeiro." } } }, "TravelRulePickupInfo": { "type": "object", "description": "A troca pendente por trás de uma ligação de recolha enviada por e-mail, tal como a página de resposta da contraparte a apresenta.", "properties": { "reference": { "type": "string", "format": "uuid", "description": "O UUID da transferência, tal como apresentado na consola do VASP remetente." }, "requested_at": { "type": "string", "format": "date-time" }, "originator_vasp_name": { "type": "string" }, "originator_vasp_lei": { "type": "string" }, "recipient_vasp_name": { "type": "string", "description": "O VASP da contraparte a quem o pedido é dirigido." }, "language": { "type": "string", "description": "O idioma do e-mail do pedido e da página de resposta, com base na jurisdição da contraparte." }, "amount": { "type": "string" }, "currency": { "type": "string" }, "fiat_amount": { "type": "string", "description": "O valor convertido indicado pelo remetente, ou vazio." }, "fiat_currency": { "type": "string" }, "chain": { "type": "string" }, "beneficiary_wallet": { "type": "string" }, "status": { "type": "string" }, "ivms_version": { "type": "string" }, "deadline_at": { "type": "string", "format": "date-time", "description": "Quando a ligação deixa de responder." }, "reminders_sent": { "type": "integer" }, "contact": { "type": "string", "description": "O valor de `?contact=` da ligação, repetido na resposta; vazio quando a ligação não tem nenhum." }, "decline_reasons": { "type": "array", "items": { "type": "string", "enum": [ "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ] }, "description": "Os valores que `decline_reason` aceita." }, "join_invitation": { "type": "object", "description": "Indica se a contraparte tem um convite ativo para aderir gratuitamente à Didit. A ligação do convite é enviada apenas por e-mail para o endereço convidado, pelo que `url` está vazio aqui.", "properties": { "eligible": { "type": "boolean" }, "url": { "type": "string" } } }, "originator_data": { "type": "object", "description": "Os campos do ordenante partilhados pelo VASP remetente (`data_sharing_fields`). O nome e a carteira estão sempre incluídos." }, "beneficiary_data": { "type": "object" }, "ivms_request": { "type": "object", "description": "O mesmo pedido como um objeto IVMS 101. Omitido enquanto `data_masked` for true." }, "data_masked": { "type": "boolean", "description": "Sempre false neste endpoint: um pedido de e-mail é de saída e o próprio utilizador do remetente nunca é mascarado." } } }, "TravelRulePickupRespondRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "accept", "decline" ] }, "beneficiary_name": { "type": "string", "description": "O nome do beneficiário conforme consta dos seus registos, processado pela regra de nomes do VASP remetente. `ivms_response` tem precedência quando indica o beneficiário.", "maxLength": 255 }, "decline_reason": { "type": "string", "enum": [ "", "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ], "description": "O motivo da sua recusa. Registado na cronologia de transferências do VASP remetente. Vazio (o padrão) quando não indicar nenhum motivo." }, "decline_detail": { "type": "string", "maxLength": 512, "description": "Texto livre; obrigatório quando `decision` é `decline` e `decline_reason` é `other`." }, "ivms_response": { "type": "object", "description": "A sua resposta IVMS 101 completa. O respetivo nome do beneficiário tem precedência sobre `beneficiary_name`." }, "contact": { "type": "string", "format": "uuid", "description": "O contacto para o qual a ligação foi enviada, a partir do valor `?contact=` da ligação. Quando o corpo o omite, é utilizado o parâmetro de consulta `contact`." } } }, "TravelRuleInboundRequest": { "type": "object", "required": [ "chain", "txid", "wallet_address", "amount", "currency" ], "properties": { "chain": { "type": "string", "description": "Blockchain na qual o depósito foi liquidado, por exemplo `ETH`. Armazenada em minúsculas e comparada de forma insensível a maiúsculas/minúsculas com as entradas do seu livro de endereços de carteiras, pelo que deve utilizar o mesmo token de blockchain aí.", "maxLength": 32 }, "txid": { "type": "string", "description": "Hash da transação on-chain. Deduplicado em conjunto com wallet_address.", "maxLength": 128 }, "wallet_address": { "type": "string", "description": "A carteira de destino na qual recebeu o depósito. Um endereço X-address de XRP é dividido no respetivo endereço clássico e tag.", "maxLength": 128 }, "amount": { "type": "string", "description": "Montante do depósito como uma string decimal, igual ou superior a zero, com até 18 casas decimais." }, "currency": { "type": "string", "description": "Ativo do depósito, por exemplo, \"USDC\".", "maxLength": 16 }, "originator_data": { "type": "object", "description": "Dados do ordenante do VASP remetente, se conhecidos, como um objeto simples, tal como `{\"name\": \"...\"}`. A Didit lê name (ou full_name), first_name, last_name e vendor_data a partir dele.", "additionalProperties": true }, "beneficiary_data": { "type": "object", "description": "Detalhes do beneficiário (o seu cliente), como um objeto simples tal como `{\"name\": \"...\"}`. A Didit compara o nome com o holder_name da entrada correspondente do livro de endereços e define wallet_address e chain a partir do pedido.", "additionalProperties": true }, "originating_vasp": { "type": "object", "description": "Descrição opcional do VASP remetente. Permanece apenas nesta transferência (`metadata.originating_vasp`, e o VASP ordenante da transferência em GET /v3/travel-rule/transfers/); nunca cria, edita ou associa uma entrada no diretório partilhado de VASPs.", "properties": { "name": { "type": "string", "maxLength": 255 }, "lei": { "type": "string", "maxLength": 20, "description": "Opcional. Um LEI ISO 17442 válido de 20 carateres, ou vazio." }, "travel_address": { "type": "string", "description": "O Travel Address do remetente, registado nesta transferência.", "maxLength": 512 } } }, "memo": { "type": "string", "maxLength": 256, "description": "Opcional. A tag de destino ou memo do depósito numa rede que utilize memos: num endereço de depósito partilhado, é o que distingue os seus clientes, e é utilizada a entrada do livro de endereços correspondente a esse memo. XRP: uma tag de destino, um número inteiro de 0 a 4294967295 (um número JSON é aceite). XLM: um memo de texto até 28 bytes, um ID de 64 bits ou um hash de 32 bytes em hexadecimal. EOS: até 256 bytes. ATOM: até 256 carateres. HBAR: até 100 bytes. As carteiras Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning não aceitam memo: incluir um devolve `400`. Pseudónimo: `destinationTag` ou `destination_tag`." }, "utxo": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleUtxo" } ], "description": "Opcional, apenas para cadeias UTXO. As entradas e saídas da transação de depósito: a carteira do remetente é o `originator_data.wallet_address` declarado; caso contrário, a maior entrada." } } }, "TravelRuleInboundResponse": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "UUID da transação Didit para o depósito recebido." }, "txn_id": { "type": "string", "description": "txn_id da transação de entrada: gerado pela Didit quando a Didit criou a transação, ou o seu próprio identificador quando um depósito não reclamado foi reutilizado." }, "created": { "type": "boolean", "description": "true quando esta chamada registou a transferência (HTTP 201); false quando já existia uma transferência para o mesmo txid e wallet_address (HTTP 200)." }, "travel_rule": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } }, "TravelRuleTestVaspInboundRequest": { "type": "object", "required": [ "beneficiary_wallet_address" ], "properties": { "beneficiary_wallet_address": { "type": "string", "description": "O endereço de carteira de destino. O VASP de teste da Didit envia para este endereço, correspondendo-o com o seu livro de endereços de carteiras na blockchain do ativo. Uma carteira sem nenhuma entrada correspondente é aceite e a transação de entrada é registada como ON_HOLD." }, "scenario": { "type": "string", "enum": [ "accept", "name_mismatch" ], "default": "accept", "description": "O que a Didit Test VASP declara que o beneficiário é. `accept` declara o próprio nome do titular; `name_mismatch` declara um nome com o qual nenhum titular concorda. A decisão em si é sempre sua." }, "chain": { "type": "string", "default": "ETH", "description": "Blockchain do ativo." }, "amount": { "type": "string", "default": "1", "description": "Montante como uma string decimal." }, "currency": { "type": "string", "default": "ETH", "description": "Código do ativo." }, "reference": { "type": "string", "description": "Chave de idempotência opcional. Uma repetição com o mesmo valor devolve a transferência que a primeira chamada registou." } } }, "TravelRuleTestVaspInboundResponse": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "UUID da transação Didit da transferência recebida." }, "txn_id": { "type": "string", "description": "txn_id gerado pela Didit." }, "scenario": { "type": "string", "description": "O cenário que foi executado." }, "travel_rule_status": { "type": "string", "description": "O estado determinado pela decisão da sua própria aplicação." }, "detail": { "type": "string", "description": "O motivo pelo qual a transferência foi resolvida para esse estado." }, "test_vasp": { "type": "boolean", "description": "Sempre true: o remetente foi o Didit Test VASP." }, "travel_rule": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } }, "TravelRuleWidgetSessionCreate": { "type": "object", "properties": { "wallet_address": { "type": "string", "description": "O endereço de carteira a verificar. Opcional; quando vazio, o endereço deve ser fornecido quando uma prova for iniciada.", "maxLength": 128 }, "chain": { "type": "string", "description": "Token da blockchain para o endereço, por exemplo `ETH`, `BTC` ou `SOL`. Use o mesmo token do seu livro de endereços de carteiras. A assinatura de mensagens e o teste Satoshi são disponibilizados apenas para uma blockchain suportada. A entrada do livro de endereços que a prova verifica armazena-o sob o seu identificador canónico (ETH, BTC, SOL, TRX).", "maxLength": 32 }, "holder_name": { "type": "string", "description": "Nome do titular da carteira, utilizado para a correspondência de nome do beneficiário.", "maxLength": 255 }, "vendor_data": { "type": "string", "description": "O seu identificador interno para o titular, associado à entrada do livro de endereços criada.", "maxLength": 255 }, "transaction_id": { "type": "string", "format": "uuid", "description": "Opcional. UUID da transação Didit de uma transferência Travel Rule a avançar quando a prova for verificada.", "nullable": true }, "satoshi_deposit_address": { "type": "string", "description": "Opcional. Um endereço de depósito que controla; fornecê-lo ativa o método de prova SATOSHI_TEST.", "maxLength": 128 }, "callback_url": { "type": "string", "description": "Opcional. URL absoluto http(s) para onde o widget devolve o cliente após a conclusão.", "maxLength": 512 }, "expires_in_minutes": { "type": "integer", "description": "Opcional. Duração da ligação gerada, em minutos. Automaticamente estendida para cobrir a janela do teste Satoshi quando SATOSHI_TEST é disponibilizado.", "default": 60, "minimum": 5, "maximum": 10080 } } }, "TravelRuleWidgetSessionResponse": { "type": "object", "properties": { "widget_session_id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "Token de sessão opaco incorporado no URL do widget." }, "url": { "type": "string", "description": "O URL do widget alojado de comprovação de propriedade da carteira. Abra-o exatamente como fornecido no navegador do sistema (nunca dentro de uma webview de SDK móvel)." }, "expires_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWidgetContext": { "type": "object", "properties": { "vasp_name": { "type": "string", "description": "Nome legal do seu perfil de VASP, apresentado ao cliente no widget. Vazio quando não existe nenhum perfil." }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "A blockchain com a qual a sessão foi criada, tal como a enviou." }, "chain_family": { "type": "string", "nullable": true, "enum": [ "EVM", "BTC", "SOL", "TRON", null ], "description": "A família de chaves associada à blockchain: EVM (Ethereum, BNB Chain, Polygon, Arbitrum, Base, Optimism, Avalanche, Linea e as restantes blockchains EVM), BTC, SOL ou TRON. Uma chave EVM controla o mesmo endereço em todas as blockchains EVM. Nulo quando nenhuma assinatura pode ser verificada na blockchain." }, "holder_name": { "type": "string" }, "allowed_methods": { "type": "array", "items": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SCREENSHOT", "SATOSHI_TEST", "SELF_DECLARATION" ] }, "description": "Métodos de prova disponíveis para esta sessão. MESSAGE_SIGNING requer uma blockchain com uma chain_family, SATOSHI_TEST requer um satoshi_deposit_address na sessão e uma blockchain cujos depósitos a Didit consiga ler, SCREENSHOT requer a definição allow_screenshot_proof e SELF_DECLARATION requer a definição allow_self_declaration." }, "transfer_status": { "type": "string", "nullable": true, "description": "Estado da transferência Travel Rule associada. Nulo quando a sessão foi criada sem um transaction_id." }, "callback_url": { "type": "string", "description": "Para onde o widget devolve o cliente após a conclusão. Vazio quando não definido." }, "expires_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Não nulo após uma prova ter sido verificada." }, "proofs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } }, "max_attempts": { "type": "integer", "description": "Comprovativos de carteira rejeitados permitidos por esta sessão." }, "attempts_used": { "type": "integer", "description": "Comprovativos rejeitados até ao momento." }, "attempts_remaining": { "type": "integer", "description": "Quando for 0, iniciar outra prova devolve 409 e é gerada uma nova sessão de widget." }, "customization": { "type": "object", "nullable": true, "description": "A personalização de marca branca da aplicação (cores, logótipo, família de tipos de letra) quando a marca branca está ativada - o widget é apresentado com a mesma imagem de marca do fluxo de verificação. Nulo caso contrário." } } }, "TravelRuleWidgetProofSummary": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "description": "PENDING: o utilizador final escolheu este método e a prova ainda não foi decidida. Uma assinatura com falha ou um depósito de teste que ainda não seja legível ou confirmado mantém a prova PENDING com um failure_reason, para que o utilizador final possa tentar novamente; um depósito SATOSHI_TEST submetido é verificado novamente de forma automática até que a respetiva janela termine, e uma SCREENSHOT submetida aguarda a sua revisão. VERIFIED: a propriedade está comprovada. REJECTED: o depósito de teste está comprovadamente incorreto (outro ordenante, valor diferente do esperado para o endereço de depósito, mais antigo do que o desafio ou uma transação que já provou outra carteira) ou o seu revisor rejeitou a captura de ecrã; failure_reason indica o motivo. Uma prova rejeitada é definitiva e consome uma das tentativas da sessão. EXPIRED: a prova já não pode ser decidida (a janela fechou, o utilizador final mudou de método, a sessão do widget expirou ou o titular da carteira mudou); failure_reason indica o motivo." }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "Identificador canónico da blockchain da entrada do livro de endereços a que a prova se refere, por exemplo, ETH, BTC, SOL, TRX." }, "deposit_address": { "type": "string", "nullable": true, "description": "Endereço de depósito para o qual o cliente deve enviar o montante do teste Satoshi. Presente apenas num comprovativo SATOSHI_TEST." }, "expected_amount": { "type": "string", "nullable": true, "description": "Montante exato on-chain, na moeda nativa do depósito, com o qual o depósito de teste Satoshi deve corresponder. Presente apenas num comprovativo SATOSHI_TEST." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Prazo para a janela do teste de Satoshi deste comprovativo. Presente apenas num comprovativo SATOSHI_TEST; o expires_at da própria sessão do widget é prolongado para cobri-lo quando SATOSHI_TEST é disponibilizado." }, "challenge": { "type": "string", "nullable": true, "description": "Mensagem emitida pela Didit que o cliente assina com a sua carteira. Presente apenas num comprovativo MESSAGE_SIGNING." }, "rejection_reason": { "type": "string", "description": "O motivo pelo qual a prova foi recusada, como uma frase em inglês para o utilizador final. Presente apenas quando `status` é REJECTED; vazio quando o seu revisor recusou uma captura de ecrã (a sua nota permanece consigo)." }, "created_at": { "type": "string", "format": "date-time" }, "attempts": { "type": "integer", "description": "Quantas vezes foram submetidas provas para este comprovativo (assinaturas, IDs de transação, carregamentos)." }, "failure_reason": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "O motivo pelo qual a última tentativa falhou ou a prova foi encerrada. Vazio quando nada falhou." } } }, "CaseSubject": { "type": "object", "nullable": true, "description": "O único utilizador ou a única empresa a que o caso está associado.", "properties": { "type": { "type": "string", "enum": [ "user", "business" ] }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "external_id": { "type": "string", "nullable": true, "description": "O vendor_data do sujeito." }, "country": { "type": "string", "nullable": true, "description": "Código de país de três letras do sujeito (ISO 3166-1 alfa-3), ou null quando não for conhecido. Para uma empresa, o respetivo país de constituição. Para uma pessoa, o país emissor de um documento de identificação das suas verificações; uma pessoa com documentos de vários países apresenta um deles, e podem surgir códigos de documentos da ICAO como `XXA`.", "example": "ESP" }, "portrait": { "type": "string", "format": "uri", "nullable": true, "description": "URL assinado de curta duração da imagem de retrato da pessoa. Sempre nulo para uma empresa, e nulo para uma pessoa sem retrato. O URL expira, pelo que deve descarregar a imagem ao consultar o caso em vez de guardar o URL." } } }, "CaseAssignee": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "CaseBlueprintSummary": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 } } }, "CaseContentConfig": { "type": "object", "description": "As seis secções alternáveis que determinam quais os separadores e campos apresentados na página do caso. Secções ou chaves desconhecidas são rejeitadas.", "properties": { "checklist": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "optional": { "type": "boolean", "description": "Quando for true, um caso pode ser resolvido com itens da lista de verificação incompletos." }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "order": { "type": "integer" } } } } } }, "aml_control": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "financial": { "type": "boolean" }, "identity": { "type": "boolean" } } }, "identity": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "personal_information": { "type": "boolean" }, "applicant_tags": { "type": "boolean" }, "contact_information": { "type": "boolean" }, "risk_overview": { "type": "boolean" }, "poi_documents": { "type": "boolean" }, "poa_documents": { "type": "boolean" } } }, "verifications": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "summary": { "type": "boolean" } } }, "reporting": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fiu_reports": { "type": "boolean" } } }, "financial": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "payment_methods": { "type": "boolean" }, "transactions": { "type": "boolean" } } } } }, "CaseNote": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "comment": { "type": "string" }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "is_internal": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "s3_key": { "type": "string" }, "filename": { "type": "string" }, "file_size": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseEvent": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "enum": [ "CREATED", "STATUS_CHANGED", "ASSIGNED", "UNASSIGNED", "RESOLVED", "REOPENED", "LINK_ADDED", "LINK_REMOVED", "NOTE_ADDED", "NOTE_PINNED", "NOTE_UNPINNED", "PRIORITY_CHANGED", "DUE_DATE_CHANGED", "TAG_ADDED", "TAG_REMOVED", "ESCALATED", "TRANSFERRED", "CHECKLIST_COMPLETED", "REPORT_CREATED", "REPORT_FINALIZED", "SUBMITTED_FOR_APPROVAL", "APPROVAL_GRANTED", "APPROVAL_REJECTED", "ENTITY_ACTION", "APPROVAL_INVALIDATED", "CUSTOMER_REQUEST", "STAGE_CHANGED", "TEAM_CHANGED", "CHECKER_ASSIGNED", "CHECKER_UNASSIGNED" ] }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "previous_status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "nullable": true }, "new_status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "nullable": true }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseLink": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "linked_entity_type": { "type": "string", "enum": [ "session", "business_session", "transaction" ], "nullable": true }, "linked_entity_uuid": { "type": "string", "format": "uuid", "nullable": true }, "linked_entity_summary": { "type": "object", "nullable": true, "description": "session_id/session_number/status para ligações de sessão e business_session; uuid/txn_id/status para ligações de transação." }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseChecklistItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "maxLength": 255 }, "is_completed": { "type": "boolean" }, "completed_by": { "type": "string", "format": "email", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "order": { "type": "integer" } } }, "CaseBlueprintListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "max_active_cases": { "type": "integer", "nullable": true }, "escalation_enabled": { "type": "boolean" }, "transfer_enabled": { "type": "boolean" }, "require_resolution_note": { "type": "boolean" }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "readOnly": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760 } } }, "CaseBlueprintDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "max_active_cases": { "type": "integer", "nullable": true }, "escalation_enabled": { "type": "boolean" }, "transfer_enabled": { "type": "boolean" }, "require_resolution_note": { "type": "boolean" }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "escalation_blueprint_name": { "type": "string", "nullable": true }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "four_eyes_checker_blueprint_name": { "type": "string", "nullable": true }, "content_config": { "type": "object", "description": "As seis secções alternáveis que determinam quais os separadores e campos apresentados na página do caso. Secções ou chaves desconhecidas são rejeitadas.", "properties": { "checklist": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "optional": { "type": "boolean", "description": "Quando for true, um caso pode ser resolvido com itens da lista de verificação incompletos." }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "order": { "type": "integer" } } } } } }, "aml_control": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "financial": { "type": "boolean" }, "identity": { "type": "boolean" } } }, "identity": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "personal_information": { "type": "boolean" }, "applicant_tags": { "type": "boolean" }, "contact_information": { "type": "boolean" }, "risk_overview": { "type": "boolean" }, "poi_documents": { "type": "boolean" }, "poa_documents": { "type": "boolean" } } }, "verifications": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "summary": { "type": "boolean" } } }, "reporting": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fiu_reports": { "type": "boolean" } } }, "financial": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "payment_methods": { "type": "boolean" }, "transactions": { "type": "boolean" } } } } }, "creation_sources": { "type": "array", "description": "Conetores que atualmente encaminham novos casos para este modelo.", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "aml", "rule", "workflow" ] }, "id": { "type": "string" }, "name": { "type": "string" } } } }, "receives_escalation_from": { "type": "array", "description": "Outros esquemas cujo destino de escalamento aponta para este.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "readOnly": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760 } } }, "CaseListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true, "description": "Atribuído automaticamente, ex.: CS-0001." }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "nullable": true }, "pending_resolution": { "type": "object", "nullable": true, "description": "Definido apenas enquanto uma resolução 4-eyes estiver preparada no blueprint do verificador, a aguardar aprovação ou rejeição.", "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "resolution_notes": { "type": "string", "nullable": true }, "maker_email": { "type": "string", "format": "email", "nullable": true, "description": "E-mail do responsável que submeteu a resolução. Null quando submetida por uma chave de API: essa resolução não tem criador registado, pelo que aprovar e rejeitar aprovação devolvem 403 para qualquer chamador." }, "maker_name": { "type": "string", "nullable": true }, "maker_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID de utilizador do membro que submeteu a resolução. Null quando foi submetido por uma chave de API. Esse membro não pode ser indicado como `checker`." }, "maker_blueprint_id": { "type": "string", "format": "uuid" }, "staged_at": { "type": "string", "format": "date-time" } } }, "checker": { "$ref": "#/components/schemas/CaseChecker" }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "$ref": "#/components/schemas/CaseSubject" }, "assigned_to": { "$ref": "#/components/schemas/CaseAssignee" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true }, "team": { "$ref": "#/components/schemas/CaseTeamSummary" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by_email": { "type": "string", "nullable": true }, "created_by_name": { "type": "string", "nullable": true }, "blueprint": { "$ref": "#/components/schemas/CaseBlueprintSummary" }, "links_count": { "type": "integer" }, "notes_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "application_id": { "type": "string", "format": "uuid" }, "application_name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" } } }, "CaseDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "nullable": true }, "resolution_notes": { "type": "string", "nullable": true }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "$ref": "#/components/schemas/CaseSubject" }, "assigned_to": { "$ref": "#/components/schemas/CaseAssignee" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true }, "team": { "$ref": "#/components/schemas/CaseTeamSummary" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_by_email": { "type": "string", "nullable": true }, "pending_resolution": { "type": "object", "nullable": true, "description": "Definido apenas enquanto uma resolução 4-eyes estiver preparada no blueprint do verificador, a aguardar aprovação ou rejeição.", "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "resolution_notes": { "type": "string", "nullable": true }, "maker_email": { "type": "string", "format": "email", "nullable": true, "description": "E-mail do responsável que submeteu a resolução. Null quando submetida por uma chave de API: essa resolução não tem criador registado, pelo que aprovar e rejeitar aprovação devolvem 403 para qualquer chamador." }, "maker_name": { "type": "string", "nullable": true }, "maker_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID de utilizador do membro que submeteu a resolução. Null quando foi submetido por uma chave de API. Esse membro não pode ser indicado como `checker`." }, "maker_blueprint_id": { "type": "string", "format": "uuid" }, "staged_at": { "type": "string", "format": "date-time" } } }, "checker": { "$ref": "#/components/schemas/CaseChecker" }, "metadata": { "type": "object" }, "blueprint": { "$ref": "#/components/schemas/CaseBlueprintDetail" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/CaseNote" }, "description": "As 50 notas mais recentes." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CaseEvent" }, "description": "Os 100 eventos mais recentes." }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/CaseLink" } }, "links_count": { "type": "integer" }, "notes_count": { "type": "integer" }, "checklist_items": { "type": "array", "items": { "$ref": "#/components/schemas/CaseChecklistItem" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ReportTemplateDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Código de país ISO 3166-1 alpha-2." }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "report_type_display": { "type": "string" }, "field_config": { "type": "object", "description": "Predefinições de cabeçalho goAML reutilizáveis. Campos obrigatórios ao nível do modelo: rentity_id, submission_code e currency_code_local (3 letras). Opcional: enabled_fields (que blocos de relatório opcionais incluir) mais predefinições de reporting_person, location, reason e action. Os campos de cabeçalho por submissão (action, submission_date, transactions, jurisdiction) são obrigatórios quando o relatório é validado ou finalizado, não no modelo." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RegulatoryReportDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "report_type_display": { "type": "string" }, "report_code": { "type": "string", "description": "Código de relatório goAML derivado de report_type, por ex., STR, CTR, BCR." }, "report_number": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "status_display": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2 }, "rentity_id": { "type": "string", "nullable": true, "description": "ID da entidade reportante emitido pela UIF." }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ] }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "description": "Secções narrativas dos Cinco Ws.", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "validation_errors": { "type": "array", "description": "Resultado da validação mais recente; cada entrada é um objeto {field, message}.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } }, "validated_at": { "type": "string", "format": "date-time", "nullable": true }, "finalized_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by_email": { "type": "string", "nullable": true }, "created_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TransactionRuleCondition": { "type": "object", "required": [ "field", "operator" ], "properties": { "field": { "type": "string", "description": "Caminho do campo da transação a avaliar. Campos principais: amount, currency, direction, action_type, score, severity, transaction_type, payment_details, preferred_currency_amount (recorre a amount_in_default_currency), default_currency_code, subject_country, counterparty_country, subject_vendor_data, counterparty_vendor_data, subject_device_fingerprint, counterparty_device_fingerprint, subject_browser_family, subject_browser_version, subject_platform, subject_accept_language, subject_session_age_ms, subject_ip_country, counterparty_ip_country, subject_ip_address, counterparty_ip_address, subject_payment_method_type, subject_payment_method_country, subject_payment_method_fingerprint, subject_payment_method_account_id (e os equivalentes counterparty_payment_method_*), travel_rule_status, travel_rule_required, travel_rule_obligations_count, counterparty_dd_status (a sua decisão sobre a contraparte da Travel Rule: APPROVED, RESTRICTED ou BLOCKED, seguindo a entidade da respetiva marca), counterparty_risk_level (LOW, MEDIUM ou HIGH; HIGH enquanto a sua própria triagem da contraparte estiver sinalizada), counterparty_jurisdiction (o país do VASP da contraparte), counterparty_responsiveness (RESPONSIVE, UNRESPONSIVE ou UNKNOWN), subject_days_since_previous_transaction, tags e custom_values. para qualquer chave enviada em custom_properties na criação da transação. Os campos de código de país aceitam ISO-2 ou ISO-3; ambos os lados são normalizados para ISO-3 antes da comparação." }, "operator": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte", "in", "not_in", "contains", "not_contains", "contains_any", "regex", "fuzzy_match", "exists", "is_not_empty", "is_not_null", "not_exists", "is_empty", "is_null" ], "description": "Operador de comparação. in/not_in testam a pertença (o valor pode ser uma lista ou um escalar individual). contains/not_contains são verificações de substring que não diferenciam maiúsculas de minúsculas face a um valor de texto. contains_any aceita uma lista de strings e obtém correspondência se alguma for uma substring (insensível a maiúsculas e minúsculas) do valor do campo. regex compara o padrão do valor com o campo. fuzzy_match compara com a string do valor com o limiar de `score` exigido (0-100). gt/gte/lt/lte nunca encontram correspondência se qualquer um dos lados estiver em falta. exists/is_not_empty/is_not_null (aliases) e not_exists/is_empty/is_null (aliases) são verificações de presença que ignoram `value`." }, "value": { "description": "Valor de comparação. O seu formato depende do operador e de value_type; omita-o para os operadores de verificação de presença. Todos os outros operadores requerem um valor que não seja `null` nem uma lista vazia, caso contrário a regra é rejeitada com `400`. `contains_any` requer uma lista de strings, e `contains`, `not_contains` e `regex` requerem uma única string." }, "value_type": { "type": "string", "enum": [ "list", "field", "relative_date" ], "description": "Interpretação de valor opcional. `list`: o valor é um UUID de Lista e as entradas da lista tornam-se o valor de comparação. `field`: o valor é outro caminho de campo, comparado campo a campo. `relative_date`: o valor é um objeto de data relativa, por ex., {\"direction\": \"past\", \"unit\": \"days\", \"amount\": 30}." }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Obrigatório quando o operador for fuzzy_match: o limiar de semelhança de 0-100." }, "group_index": { "type": "integer", "description": "Lógica agrupada opcional. Quando qualquer condição inclui group_index, as condições que partilham um índice formam um grupo e a avaliação agrupada substitui evaluation_mode." }, "group_logic": { "type": "string", "enum": [ "AND", "OR" ], "default": "AND", "description": "Como as condições se combinam DENTRO de um grupo." }, "groups_logic": { "type": "string", "enum": [ "AND", "OR" ], "default": "OR", "description": "Como os resultados dos grupos se combinam ENTRE grupos. Lido a partir da primeira condição." } }, "description": "Uma condição lê apenas a transação a ser avaliada - nunca filtra a janela de agregação." }, "TransactionRuleAggregation": { "type": "object", "required": [ "value" ], "properties": { "metric": { "type": "string", "enum": [ "count", "sum", "max", "min", "avg", "distinct_count" ], "default": "count", "description": "Como as transações históricas correspondentes são agregadas. unique_count é aceite como um alias de distinct_count." }, "field": { "type": "string", "default": "amount", "description": "Campo agregado por sum/max/min/avg/distinct_count. Ignorado para count." }, "operator": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ], "default": "eq", "description": "Comparação aplicada à métrica calculada." }, "value": { "type": "number", "description": "Limiar com o qual a métrica calculada é comparada." }, "window": { "type": "string", "pattern": "^\\d+(m|h|d)$", "default": "1d", "description": "Janela de retrospetiva que termina na txn_date da transação: m (MINUTOS, não meses), h (horas) ou d (dias), por exemplo 30m, 24h, 7d, 30d." }, "filters": { "type": "object", "additionalProperties": true, "description": "Restringe quais transações históricas são agregadas. As chaves são caminhos de campos do catálogo de campos de condição; um valor de \"__current__\" resolve para o valor do mesmo campo na transação que está a ser avaliada (por ex., {\"subject_vendor_data\": \"__current__\"} restringe a janela ao mesmo sujeito), e um valor de lista significa pertença. Registos sem o valor agrupado nunca são agrupados: quando a transação que está a ser avaliada não tem valor para um campo \"__current__\" (sem contraparte, sem impressão digital do dispositivo), a agregação não corresponde, qualquer que seja o seu operador. Os filtros comparam APENAS por igualdade ou pertença - não existe filtro lt/gte, pelo que um intervalo como \"transações históricas inferiores a 10 000\" não pode ser expresso aqui. Em vez disso, coloque o intervalo na métrica (uma métrica max com operador lt mantém todas as transações na janela abaixo do limiar)." } }, "description": "Verificação de velocidade sobre as transações históricas da aplicação dentro da janela. Cada entrada de agregação tem de corresponder para que a regra corresponda, independentemente do evaluation_mode. Uma agregação restringe apenas a janela; a transação avaliada é restringida pelo âmbito e pelas condições, por isso repita direction, currency ou transaction_type em ambas as metades quando a regra os prevê." }, "TransactionRuleScope": { "type": "object", "properties": { "transaction_types": { "type": "array", "items": { "type": "string" }, "description": "Restringir a tipos de transação, p. ex., finance, kyc, travel_rule, user_event. Vazio ou em falta = sem restrição." }, "directions": { "type": "array", "items": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "description": "Restringir a direções de transação (não sensível a maiúsculas/minúsculas na escrita)." }, "action_types": { "type": "array", "items": { "type": "string" }, "description": "Restringir aos seus valores de action_type, p. ex., withdrawal, deposit." } }, "description": "A que transações a regra se aplica. Apenas estas três chaves são aceites." }, "TransactionRuleAction": { "oneOf": [ { "$ref": "#/components/schemas/TransactionRuleActionAddScore" }, { "$ref": "#/components/schemas/TransactionRuleActionChangeStatus" }, { "$ref": "#/components/schemas/TransactionRuleActionAddTags" }, { "$ref": "#/components/schemas/TransactionRuleActionAddNote" }, { "$ref": "#/components/schemas/TransactionRuleActionAddToList" }, { "$ref": "#/components/schemas/TransactionRuleActionOpenCase" } ], "discriminator": { "propertyName": "type", "mapping": { "add_score": "#/components/schemas/TransactionRuleActionAddScore", "change_status": "#/components/schemas/TransactionRuleActionChangeStatus", "add_tags": "#/components/schemas/TransactionRuleActionAddTags", "add_note": "#/components/schemas/TransactionRuleActionAddNote", "add_to_list": "#/components/schemas/TransactionRuleActionAddToList", "open_case": "#/components/schemas/TransactionRuleActionOpenCase" } }, "description": "Uma ação de regra. Uma regra pode conter várias; todas são aplicadas em conjunto quando houver correspondência. As regras no modo TEST registam o que teriam feito sem aplicar qualquer ação." }, "TransactionRuleCreateRequest": { "type": "object", "required": [ "title", "category", "mode" ], "properties": { "title": { "type": "string", "description": "Nome da regra. Exclusivo por aplicação entre regras não eliminadas; duplicados devolvem 400." }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "Tema de risco utilizado para agrupamento e relatórios, por exemplo finance, aml_ctf, anomaly_detection, fatf, device_intelligence, crypto_monitoring, travel_rule, responsible_gaming, e_commerce." }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE avalia em produção. TEST avalia e regista as execuções das regras, mas nunca altera a pontuação ou o estado - o modo inicial recomendado. DISABLED é ignorado." }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "Se todas as condições têm de corresponder (ALL) ou pelo menos uma (ANY). Ignorado quando as condições utilizam group_index." }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "Metadados de formato livre armazenados na regra." } }, "description": "Cria uma regra CUSTOM. As regras no modo ACTIVE entram em vigor imediatamente para novas transações - crie no modo TEST e faça um teste retrospetivo primeiro." }, "TransactionRuleUpdateRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "Nome da regra. Exclusivo por aplicação entre regras não eliminadas; duplicados devolvem 400." }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "Tema de risco utilizado para agrupamento e relatórios, por exemplo finance, aml_ctf, anomaly_detection, fatf, device_intelligence, crypto_monitoring, travel_rule, responsible_gaming, e_commerce." }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE avalia em produção. TEST avalia e regista as execuções das regras, mas nunca altera a pontuação ou o estado - o modo inicial recomendado. DISABLED é ignorado." }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "Se todas as condições têm de corresponder (ALL) ou pelo menos uma (ANY). Ignorado quando as condições utilizam group_index." }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "Metadados de formato livre armazenados na regra." } }, "description": "Atualização parcial. Regras personalizadas aceitam todos os campos; regras da biblioteca (PRESET) aceitam apenas mode - qualquer outra coisa devolve 400." }, "TransactionRuleDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "description": "Nome da regra. Exclusivo por aplicação entre regras não eliminadas; duplicados devolvem 400." }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "Tema de risco utilizado para agrupamento e relatórios, por exemplo finance, aml_ctf, anomaly_detection, fatf, device_intelligence, crypto_monitoring, travel_rule, responsible_gaming, e_commerce." }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE avalia em produção. TEST avalia e regista as execuções das regras, mas nunca altera a pontuação ou o estado - o modo inicial recomendado. DISABLED é ignorado." }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "Se todas as condições têm de corresponder (ALL) ou pelo menos uma (ANY). Ignorado quando as condições utilizam group_index." }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "Metadados de formato livre armazenados na regra." }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "nullable": true, "description": "Nível de gravidade informativo definido pelas regras da biblioteca; não configurável em regras personalizadas." }, "source": { "type": "string", "enum": [ "PRESET", "CUSTOM" ], "description": "As regras PRESET vêm da biblioteca (instalar/desinstalar, edições apenas de modo); as regras CUSTOM são inteiramente suas." }, "library_key": { "type": "string", "nullable": true, "description": "Identificador estável da biblioteca; null para regras personalizadas." }, "latest_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "run_count": { "type": "integer", "description": "Quantas transações corresponderam a esta regra." }, "approved_count": { "type": "integer" }, "reviewed_count": { "type": "integer" }, "declined_count": { "type": "integer" }, "awaiting_user_count": { "type": "integer" }, "approved_pct": { "type": "number" }, "reviewed_pct": { "type": "number" }, "declined_pct": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TransactionRuleBacktestRequest": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" }, "default": [] }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" }, "default": [] }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL" }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "period_days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "description": "Configuração de regra hipotética a avaliar contra transações recentes. Só de leitura e gratuita: nada é criado ou modificado. Envie as mesmas condições, agregação, evaluation_mode E scope da regra que pretende ativar. Condições, agregação e scope omitidos não adicionam restrições próprias; remover o scope pode incluir direções ou tipos de transação que a regra guardada ignora. evaluation_mode omitido assume ALL por predefinição (o que pode reduzir correspondências para uma regra ANY), e period_days omitido assume 90 dias por predefinição, não histórico ilimitado." }, "TransactionRuleBacktestResult": { "type": "object", "properties": { "evaluated": { "type": "integer", "description": "Transações avaliadas (mais recentes primeiro, com limite)." }, "matched": { "type": "integer", "description": "Transações que a configuração teria correspondido." }, "affected_entities": { "type": "integer", "description": "Sujeitos distintos (por vendor_data) entre as correspondências." }, "period_days": { "type": "integer" } } }, "TransactionRuleLibraryEntry": { "type": "object", "properties": { "library_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string" }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ] }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object" }, "bundle": { "type": "string", "nullable": true, "description": "Família funcional, por exemplo finance, aml_ctf, crypto_monitoring, travel_rule, responsible_gaming." }, "tags": { "type": "array", "items": { "type": "string" } }, "industries": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "is_installed": { "type": "boolean", "description": "Se esta predefinição está atualmente instalada na aplicação." } } }, "TransactionRuleInstallRequest": { "type": "object", "properties": { "library_keys": { "type": "array", "items": { "type": "string" }, "description": "Predefinições específicas a instalar ou desinstalar." }, "bundle": { "type": "string", "description": "Em alternativa, instale ou desinstale todas as predefinições deste pacote." } }, "description": "Forneça library_keys OU bundle." }, "TransactionRuleInstallResult": { "type": "object", "properties": { "installed_library_keys": { "type": "array", "items": { "type": "string" }, "description": "Apenas POST (instalação): predefinições instaladas por esta chamada." }, "installed_count": { "type": "integer", "description": "Apenas POST (instalação)." }, "uninstalled_count": { "type": "integer", "description": "Apenas DELETE (desinstalação): predefinições removidas por esta chamada." } } }, "WalletScreeningResult": { "type": "object", "properties": { "provider": { "type": "string", "description": "Fornecedor que realizou a triagem (por exemplo, `merklescience`, `crystal`)." }, "screening_type": { "type": "string", "enum": [ "WALLET_SCREENING" ], "description": "Sempre `WALLET_SCREENING` para este endpoint." }, "risk_score": { "type": "integer", "description": "Pontuação de risco normalizada de 0-100. Um valor mais alto significa maior exposição a entidades de risco. A Merkle Science classifica um endereço de 0 a 5, o que mapeia para 0, 15, 35, 55, 75 ou 95." }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Intervalo de risco derivado de `risk_score`: `0-9` UNKNOWN, `10-39` LOW, `40-69` MEDIUM, `70-89` HIGH, `90-100` CRITICAL. `UNKNOWN` é a faixa mais baixa, não um estado separado sem dados: um `risk_score` de 0 (o caso comum de endereço limpo) significa que não há avaliação adversa, enquanto uma pontuação diferente de zero no intervalo de 1 a 9 é um sinal real, mas abaixo de LOW - leia o `risk_score`, não apenas a faixa. Nunca trate `UNKNOWN` como uma classificação afirmativa de baixo risco ou limpa; não a apresente como aprovação." }, "status": { "type": "string", "enum": [ "SCREENED", "PENDING", "ERROR" ], "description": "Estado do resultado da triagem." }, "summary": { "type": "string", "description": "Resumo legível por humanos do resultado da triagem." }, "wallet_address": { "type": "string", "description": "O endereço submetido a triagem, devolvido tal como foi recebido." }, "transaction_hash": { "type": "string", "nullable": true, "description": "Campo de triagem de transações, partilhado com o formato do resultado. É sempre `null` num resultado de triagem de carteiras." }, "blockchain": { "type": "string", "description": "A blockchain que foi analisada." }, "block_timestamp": { "type": "string", "nullable": true, "description": "Campo de triagem de transações, partilhado com o formato do resultado. É sempre `null` num resultado de triagem de carteiras." }, "total_value_usd": { "type": "number", "nullable": true, "description": "Campo de triagem de transações, partilhado com o formato do resultado. É sempre `null` num resultado de triagem de carteiras." }, "fee_usd": { "type": "number", "nullable": true, "description": "Campo de triagem de transações, partilhado com o formato do resultado. É sempre `null` num resultado de triagem de carteiras." }, "sender_rows": { "type": "array", "items": { "type": "object" }, "description": "Campo de triagem de transações, partilhado com o formato do resultado. Está sempre vazio num resultado de triagem de carteiras." }, "receiver_rows": { "type": "array", "items": { "type": "object" }, "description": "Campo de triagem de transações, partilhado com o formato do resultado. Está sempre vazio num resultado de triagem de carteiras." }, "transaction_flows": { "type": "array", "items": { "type": "object" }, "description": "Campo de triagem de transações, partilhado com o formato do resultado. Está sempre vazio num resultado de triagem de carteiras." }, "transaction_flows_status": { "type": "string", "nullable": true, "description": "Campo de triagem de transações, partilhado com o formato do resultado. É sempre `null` num resultado de triagem de carteiras." }, "transaction_flows_error": { "type": "string", "nullable": true, "description": "Campo de triagem de transações, partilhado com o formato do resultado. É sempre `null` num resultado de triagem de carteiras." }, "source_of_funds": { "type": "array", "description": "De onde o endereço recebeu fundos, atribuídos por entidade. Cada entrada é um detalhe de exposição.", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Categoria de risco normalizada, por exemplo, `exchange_licensed`, `dex`, `defi`, `payment_processor`, `mixer`, `darknet_market`, `sanctioned`, `stolen_funds`, `high_risk_exchange`." }, "percentage": { "type": "number", "description": "Percentagem da exposição total da direção, 0-100." }, "amount_usd": { "type": "number", "nullable": true, "description": "Valor em USD atribuído a esta entidade." }, "entity_name": { "type": "string", "nullable": true, "description": "Nome da entidade atribuída, por exemplo uma exchange, um misturador ou um grupo sancionado." }, "entity_type": { "type": "string", "nullable": true, "description": "Tipo de entidade do fornecedor (por exemplo, `Exchange`, `DeFi`, `Sanctions`, `Theft`)." }, "entity_subtype": { "type": "string", "nullable": true, "description": "Subtipo mais granular (p. ex., `Mandatory KYC and AML`, `OFAC`, `Yield Aggregator`)." }, "hops": { "type": "integer", "nullable": true, "description": "Número de saltos até à entidade (1 para uma contraparte direta), quando o fornecedor indicar um. Sempre `null` para a Merkle Science, que apenas indica se a exposição é direta ou indireta: utilize `exposure_type`." }, "description": { "type": "string", "nullable": true, "description": "`entity_type / entity_subtype`, tal como o fornecedor rotula a entidade." }, "is_direct": { "type": "boolean", "description": "True quando `exposure_type` é `direct`." }, "exposure_direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected" ], "description": "Indica se os fundos provieram (`incoming`) ou foram enviados para (`outgoing`) esta entidade." }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect" ], "description": "Exposição `direct` (1 salto) ou `indirect` (múltiplos saltos)." }, "provider_entity_id": { "type": "string", "nullable": true, "description": "O identificador próprio do fornecedor para a entidade." }, "provider_entity_type_id": { "type": "string", "nullable": true, "description": "O identificador próprio do fornecedor para `entity_type`." }, "provider_entity_subtype_id": { "type": "string", "nullable": true, "description": "O identificador próprio do fornecedor para `entity_subtype`." }, "country": { "type": "string", "nullable": true, "description": "País principal da entidade, segundo a norma ISO 3166-1 alpha-2. Vazio ou `null` quando o fornecedor não o conhece." }, "raw_amount": { "type": "number", "nullable": true, "description": "Montante na própria unidade do ativo, quando o fornecedor o reporta." }, "raw_currency": { "type": "string", "nullable": true, "description": "Unidade de `raw_amount`, quando o fornecedor a comunica." } } } }, "destination_of_funds": { "type": "array", "description": "Para onde o endereço enviou fundos, atribuídos por entidade. Mesma estrutura de itens que `source_of_funds` com `exposure_direction` = `outgoing`.", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Categoria de risco normalizada, por exemplo, `exchange_licensed`, `dex`, `defi`, `payment_processor`, `mixer`, `darknet_market`, `sanctioned`, `stolen_funds`, `high_risk_exchange`." }, "percentage": { "type": "number", "description": "Percentagem da exposição total da direção, 0-100." }, "amount_usd": { "type": "number", "nullable": true, "description": "Valor em USD atribuído a esta entidade." }, "entity_name": { "type": "string", "nullable": true, "description": "Nome da entidade atribuída, por exemplo uma exchange, um misturador ou um grupo sancionado." }, "entity_type": { "type": "string", "nullable": true, "description": "Tipo de entidade do fornecedor (por exemplo, `Exchange`, `DeFi`, `Sanctions`, `Theft`)." }, "entity_subtype": { "type": "string", "nullable": true, "description": "Subtipo mais granular (p. ex., `Mandatory KYC and AML`, `OFAC`, `Yield Aggregator`)." }, "hops": { "type": "integer", "nullable": true, "description": "Número de saltos até à entidade (1 para uma contraparte direta), quando o fornecedor indicar um. Sempre `null` para a Merkle Science, que apenas indica se a exposição é direta ou indireta: utilize `exposure_type`." }, "description": { "type": "string", "nullable": true, "description": "`entity_type / entity_subtype`, tal como o fornecedor rotula a entidade." }, "is_direct": { "type": "boolean", "description": "True quando `exposure_type` é `direct`." }, "exposure_direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected" ], "description": "Indica se os fundos provieram (`incoming`) ou foram enviados para (`outgoing`) esta entidade." }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect" ], "description": "Exposição `direct` (1 salto) ou `indirect` (múltiplos saltos)." }, "provider_entity_id": { "type": "string", "nullable": true, "description": "O identificador próprio do fornecedor para a entidade." }, "provider_entity_type_id": { "type": "string", "nullable": true, "description": "O identificador próprio do fornecedor para `entity_type`." }, "provider_entity_subtype_id": { "type": "string", "nullable": true, "description": "O identificador próprio do fornecedor para `entity_subtype`." }, "country": { "type": "string", "nullable": true, "description": "País principal da entidade, segundo a norma ISO 3166-1 alpha-2. Vazio ou `null` quando o fornecedor não o conhece." }, "raw_amount": { "type": "number", "nullable": true, "description": "Montante na própria unidade do ativo, quando o fornecedor o reporta." }, "raw_currency": { "type": "string", "nullable": true, "description": "Unidade de `raw_amount`, quando o fornecedor a comunica." } } } }, "counterparty_connections": { "type": "array", "description": "Entidades às quais o fornecedor atribui o endereço submetido a triagem. Para a Merkle Science, estas provêm das etiquetas de proprietário e utilizador do próprio endereço, pelo que a mesma entidade pode surgir duas vezes, e não transportam fluxos de fundos: `received_usd`, `sent_usd`, `received_hops` e `sent_hops` são `null` e `percentage` é 0. Não efetue o encaminhamento com base em `risk_level` ou `is_direct` aqui: utilize `sanctions_hit`, `dominant_risk_category` e `risk_factors[].is_high_risk` para o veredito, e `exposure_type` em `source_of_funds`/`destination_of_funds` para aferir a ligação direta.", "items": { "type": "object", "properties": { "entity_name": { "type": "string", "nullable": true, "description": "Nome da entidade atribuída." }, "entity_type": { "type": "string", "nullable": true, "description": "Tipo de entidade do fornecedor." }, "entity_subtype": { "type": "string", "nullable": true, "description": "Subtipo de entidade do fornecedor." }, "risk_level": { "type": "string", "description": "Em minúsculas e dependente do fornecedor. Para a Merkle Science, é o próprio grau de risco de 0 a 5 do endereço (`no_risk`, `low`, `medium_low`, `medium`, `high`, `critical`), elevado para `high` quando a categoria da entidade é de alto risco; não é um grau separado da entidade." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Categorias de risco normalizadas da entidade." }, "received_usd": { "type": "number", "nullable": true, "description": "USD recebidos da entidade, quando comunicado pelo fornecedor." }, "sent_usd": { "type": "number", "nullable": true, "description": "USD enviados para a entidade, quando comunicado pelo fornecedor." }, "received_hops": { "type": "integer", "nullable": true, "description": "Saltos até à entidade no lado recetor, quando o fornecedor os comunica." }, "sent_hops": { "type": "integer", "nullable": true, "description": "Saltos até à entidade no lado emissor, quando o fornecedor os comunica." }, "percentage": { "type": "number", "description": "Percentagem de exposição do endereço, quando comunicada pelo fornecedor; caso contrário, 0." }, "is_direct": { "type": "boolean", "description": "Sempre `true` para a Merkle Science, cujas ligações são atribuições em vez de contrapartes." }, "country": { "type": "string", "nullable": true, "description": "País da entidade, quando conhecido." }, "provider_entity_id": { "type": "string", "nullable": true, "description": "O identificador próprio do fornecedor para a entidade." } } } }, "network_nodes": { "type": "array", "items": { "type": "object" }, "description": "Nós do grafo de exposição para triagem de transações. Vazio no resultado de uma triagem de carteiras." }, "network_edges": { "type": "array", "items": { "type": "object" }, "description": "Arestas do grafo de exposição para triagem de transações. Vazio no resultado de uma triagem de carteiras." }, "sanctions_hit": { "type": "boolean", "description": "True se o endereço tiver exposição direta ou indireta a sanções." }, "pep_counterparty": { "type": "boolean", "description": "Exposição como pessoa politicamente exposta. `null` quando não há qualquer conclusão de PEP disponível, o que corresponde a todos os resultados atualmente porque nenhum fornecedor o comunica; `false` apenas para um resultado de triagem explicitamente negativo. Não interprete `null` como uma verificação de PEP concluída.", "nullable": true }, "dominant_risk_category": { "type": "string", "nullable": true, "description": "Categoria de alto risco com maior peso, ou `null` quando nenhuma é dominante (ex.: `sanctioned`, `mixer`, `stolen_funds`)." }, "risk_factors": { "type": "array", "description": "Explicação classificada de `risk_score`: o que produziu este veredito. Os fornecedores avaliam um endereço no seu próprio modelo e devolvem apenas um veredito (a Merkle Science devolve um número inteiro de 0 a 5), pelo que a pontuação por si só não é acionável. Com os elementos de maior risco primeiro e, depois, ordenada pelo valor movimentado através de cada fator, limitada aos cinco mais fortes; `source_of_funds` e `destination_of_funds` incluem sempre o detalhe completo. Um `risk_score` elevado sem nenhuma entrada `is_high_risk` significa que o fornecedor não reportou sanções nem qualquer correspondência com entidades atribuídas e avaliou o endereço puramente no seu próprio modelo de exposição - o `summary` indica isto explicitamente.", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "attribution", "exposure" ], "description": "`attribution` é o que o fornecedor indica que o próprio endereço é (a sua própria etiqueta ou cluster); `exposure` é para onde os respetivos fundos foram efetivamente movimentados." }, "category": { "type": "string", "description": "Categoria de risco normalizada, o mesmo vocabulário da desagregação de exposição." }, "label": { "type": "string", "description": "A redação própria do fornecedor para o fator (por ex. `Gambling / Crypto only`), que é também o que veria na consola do fornecedor." }, "entity_name": { "type": "string", "nullable": true, "description": "Entidade atribuída por trás do motor, por exemplo, um site de apostas ou uma exchange." }, "direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected", "unknown", "attribution" ], "description": "Direção do fluxo de fundos, `attribution` quando o fator determinante é a própria etiqueta do endereço, ou `unknown` quando o fornecedor não comunicou uma direção." }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect", "unknown", "attribution" ], "description": "`direct` (1 salto) ou `indirect` (múltiplos saltos), `attribution` para a própria etiqueta do endereço, ou `unknown` quando o fornecedor não indicou a quantos saltos de distância está a contraparte. Trate `unknown` como não classificado, e não como `direct`." }, "amount_usd": { "type": "number", "format": "float", "nullable": true, "description": "Valor em USD atribuído a este fator." }, "percentage": { "type": "number", "format": "float", "description": "Percentagem do volume TOTAL analisado do endereço, combinando ambas as direções - ao contrário de `percentage` dentro de `source_of_funds`/`destination_of_funds`, que é normalizado por direção. Comparável e somável em toda a lista." }, "is_high_risk": { "type": "boolean", "description": "Indica se a categoria é considerada de alto risco pela Didit (`sanctioned`, `mixer`, `stolen_funds`, `ransomware`, `scam`, `darknet_market`, `terrorist_financing`, `child_exploitation`, `hacked_exchange`, `high_risk_exchange`, `seized_funds`)." }, "description": { "type": "string", "description": "Apresentação numa única linha do fator determinante, p. ex., `9.01% indirect outgoing exposure to Gambling / Crypto only (Example Gambling)`." } } } }, "raw_response": { "type": "object", "additionalProperties": true, "description": "O payload próprio do fornecedor. O seu formato é específico do fornecedor e pode mudar sem aviso prévio: leia os campos normalizados em vez de o analisar diretamente." }, "report_signature": { "type": "string", "description": "Assinatura HMAC-SHA256 opaca sobre este resultado exato, com âmbito restrito à sua aplicação. Não tem significado por si só — reenvie o corpo completo da resposta, sem modificações e incluindo este campo, para `POST /v3/wallet-screening/pdf/` para o renderizar como um PDF. O endpoint de PDF rejeita o pedido com `400` se `report_signature` estiver em falta ou se qualquer campo assinado (por exemplo, `risk_score`, `severity`, `sanctions_hit`) tiver sido editado antes do reenvio." } }, "required": [ "provider", "screening_type", "risk_score", "severity", "status", "summary", "wallet_address", "blockchain", "sanctions_hit", "dominant_risk_category", "source_of_funds", "destination_of_funds", "counterparty_connections", "report_signature" ] }, "NetworkRiskDisplay": { "type": "object", "properties": { "score": { "type": "integer", "description": "Pontuação de risco, 0-100." }, "band": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Faixa em que a pontuação é apresentada. high >= 70, medium >= 40, caso contrário low." }, "bar": { "type": "number", "format": "float", "description": "Valor normalizado de 0-1 para renderizar uma barra de risco." } } }, "NetworkNodeTag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true, "description": "Nulo para etiquetas de proteção, cujo token de cor pertence ao renderizador." }, "source": { "type": "string", "enum": [ "subject_tag", "session_tag", "transaction_tag", "signal_guard" ], "description": "De onde a etiqueta proveio: uma etiqueta no utilizador/empresa, uma etiqueta numa sessão nesta rede, uma etiqueta numa transação à qual uma parte pertence ou uma condição de proteção de sinais (por exemplo, hub, IP de centro de dados)." }, "category": { "type": "string", "enum": [ "customer", "quality" ], "nullable": true, "description": "customer para etiquetas definidas pelo cliente, quality para etiquetas de proteção da qualidade do sinal. Null quando não aplicável." } } }, "NetworkListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "network_id": { "type": "string", "description": "ID sequencial legível por humanos por organização, ex.: N-0001." }, "name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "in_review", "resolved", "dismissed" ], "description": "Estado do ciclo de vida da rede. Distinto do outcome_status por requerente dentro de uma rede (approved/in_review/declined/not_completed)." }, "risk": { "$ref": "#/components/schemas/NetworkRiskDisplay" }, "pattern_types": { "type": "array", "items": { "type": "string", "enum": [ "exact_same_device", "similar_device", "same_ip_address", "same_address", "similar_selfie_backgrounds", "similar_poa_documents", "same_document_number", "same_phone_number", "same_email" ] }, "description": "Os padrões de agrupamento detetados nesta rede." }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "description": "Os tipos de sinal distintos presentes nesta rede." }, "member_counts": { "type": "object", "description": "Contagens de membros por categoria (por ex., total, por outcome_status)." }, "member_status": { "type": "object", "description": "Distribuição de membros por outcome_status." }, "signal_coverage": { "type": "object", "description": "Cobertura dos membros desta rede por signal_type." }, "first_activity_at": { "type": "string", "format": "date-time", "nullable": true }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkDetail": { "allOf": [ { "$ref": "#/components/schemas/NetworkListItem" }, { "type": "object", "properties": { "stats": { "type": "object", "description": "Estatísticas agregadas para a rede (por exemplo, totais de membros)." }, "fraud_tags": { "type": "array", "items": { "type": "object" }, "description": "Etiquetas de padrões de fraude identificadas na rede." }, "risk_signals": { "type": "object", "description": "Resumos de sinais de risco: residential_proxy_reuse, email_intelligence, phone_intelligence." }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_by": { "type": "string", "nullable": true }, "review_reason": { "type": "string", "nullable": true } } } ], "properties": { "notes_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "Número de notas privadas do analista nesta investigação." } } }, "NetworkGraphNode": { "type": "object", "description": "Um nó de sujeito ou um nó de sinal, distinguido pelo tipo. Os nós de sujeito (kind: vendor_user | vendor_business | transaction_party) contêm id, kind, subject, node_status (approved | in_review | declined | not_completed) e tags. Os nós de sinal (kind: signal) contêm id, kind, uuid, signal_type, subject_count, coverage, is_hub, is_datacenter_ip, is_high_collision_device, node_status (signal_active | signal_guarded), tags, risk_evidence, first_seen_at e last_seen_at.", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party", "signal" ] } } }, "NetworkGraphEdge": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "description": "ID do nó do sujeito." }, "target": { "type": "string", "description": "ID do nó de sinal." }, "subject_kind": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party" ] }, "signal_type": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "confidence": { "type": "number", "format": "float", "description": "1.0 para uma correspondência exata." }, "observation_count": { "type": "integer" }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkGraph": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkDetail" }, "depth": { "type": "integer", "nullable": true, "description": "Profundidade efetiva aplicada, ou null quando ilimitada (depth=all)." }, "truncated": { "type": "boolean", "description": "True se a vizinhança foi limitada pela profundidade." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkGraphNode" } }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkGraphEdge" } }, "metrics": { "type": "object", "properties": { "node_count": { "type": "integer" }, "edge_count": { "type": "integer" }, "hub_signal_count": { "type": "integer" } } } } }, "NetworkMember": { "type": "object", "properties": { "subject": { "type": "object", "description": "O vendor_user, vendor_business ou transaction_party que este membro representa." }, "outcome_status": { "type": "string", "description": "O resultado da verificação/decisão do sujeito." }, "node_status": { "type": "string", "enum": [ "approved", "in_review", "declined", "not_completed", "signal_active", "signal_guarded" ], "description": "Para uma linha de membro, este valor é sempre um dos resultados do sujeito: approved, in_review, declined ou not_completed." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNodeTag" } }, "risk": { "$ref": "#/components/schemas/NetworkRiskDisplay" }, "signal_coverage": { "type": "object" }, "shared_infrastructure": { "type": "object" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "provenance": { "type": "object", "properties": { "session_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "business_session_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "transaction_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } }, "NetworkSignal": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "signal_type": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "subject_count": { "type": "integer" }, "coverage": { "type": "number", "format": "float" }, "is_hub": { "type": "boolean", "description": "Verdadeiro quando este sinal associa um número invulgarmente elevado de sujeitos." }, "is_datacenter_ip": { "type": "boolean" }, "is_high_collision_device": { "type": "boolean" }, "node_status": { "type": "string", "enum": [ "signal_active", "signal_guarded" ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNodeTag" } }, "risk_evidence": { "type": "object" }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkTimelineEvent": { "type": "object", "properties": { "event_type": { "type": "string", "description": "por ex., network_detected, signal_observed, network_in_review, network_resolved, network_dismissed." }, "occurred_at": { "type": "string", "format": "date-time", "nullable": true }, "label": { "type": "string" }, "metadata": { "type": "object" } } }, "NetworkMap": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkDetail" }, "convergence_count": { "type": "integer", "description": "Número de pontos de morada/localização distintos para onde os membros convergem." }, "countries": { "type": "array", "items": { "type": "string" } }, "points": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "country": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "float", "nullable": true }, "longitude": { "type": "number", "format": "float", "nullable": true }, "observed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "EntityNetworkMembership": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkListItem" }, "subject": { "type": "object" }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] } }, "signal_count": { "type": "integer" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RiskSignals": { "type": "object", "description": "Contexto opcional de dispositivo e rede observado pela sua aplicação. Todos os campos são opcionais. Passá-los alimenta a deteção de correspondências entre sessões em Redes.", "properties": { "ip": { "type": "string", "format": "ip", "description": "Endereço IPv4 ou IPv6 observado para o utilizador final.", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "Identificador de dispositivo estável recolhido pela sua aplicação (Android `ANDROID_ID`, iOS `identifierForVendor`)." }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "Plataforma do dispositivo do utilizador final." }, "device_model": { "type": "string", "maxLength": 255, "description": "Modelo do dispositivo comunicado pela sua aplicação." }, "os_version": { "type": "string", "maxLength": 64, "description": "Versão do sistema operativo." }, "app_version": { "type": "string", "maxLength": 64, "description": "Versão da sua aplicação." }, "user_agent": { "type": "string", "maxLength": 512, "description": "Agente do utilizador do navegador ou da aplicação." } } }, "PhoneRiskRequest": { "type": "object", "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "Número de telefone ao qual atribuir pontuação. É validado e normalizado para E.164.", "example": "+14155552671" }, "country_code": { "type": "string", "maxLength": 3, "description": "Sugestão opcional de país ISO 3166-1 alpha-2 ou alpha-3 para cobertura de inteligência.", "example": "US" }, "signals": { "$ref": "#/components/schemas/RiskSignals" }, "vendor_data": { "type": "string", "description": "A sua referência estável para este pedido. Armazenada na sessão da API e refletida na resposta." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Os seus metadados JSON não sensíveis. Armazenados na sessão da API e devolvidos na resposta." }, "enable_social": { "type": "boolean", "default": false, "description": "Quando for true, consulta também a pegada social do número: as plataformas de mensagens, redes sociais, de comércio eletrónico e profissionais nas quais está registado. Faturado como uma unidade `phone_social` por pedido, além do preço do próprio endpoint.", "example": true } } }, "EmailRiskRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Endereço de e-mail a avaliar.", "example": "alice@example.com" }, "country_code": { "type": "string", "maxLength": 3, "description": "Sugestão opcional de país ISO 3166-1 alpha-2 ou alpha-3 para cobertura de inteligência.", "example": "US" }, "signals": { "$ref": "#/components/schemas/RiskSignals" }, "vendor_data": { "type": "string", "description": "A sua referência estável para este pedido. Armazenada na sessão da API e refletida na resposta." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Os seus metadados JSON não sensíveis. Armazenados na sessão da API e devolvidos na resposta." }, "enable_social": { "type": "boolean", "default": false, "description": "Quando for true, consulta também a pegada social do endereço: as plataformas de e-mail, redes sociais, profissionais, de comércio eletrónico e de entretenimento nas quais está registado. Faturado como uma unidade `email_social` por pedido, além do preço do próprio endpoint.", "example": true } } }, "IPRiskRequest": { "type": "object", "required": [ "ip_address" ], "properties": { "ip_address": { "type": "string", "format": "ip", "description": "Endereço IPv4 ou IPv6 a pontuar.", "example": "8.8.8.8" }, "claimed_country": { "type": "string", "maxLength": 3, "description": "País ISO 3166-1 alpha-2 ou alpha-3 opcional declarado pelo utilizador ou pela sessão. Utilizado para calcular `country_mismatch`.", "example": "ESP" }, "user_agent": { "type": "string", "maxLength": 512, "description": "Agente do utilizador observado pelo seu back-end. Armazenado como contexto do pedido; não fornece a impressão digital do dispositivo." }, "vendor_data": { "type": "string", "description": "A sua referência estável para este pedido. Armazenada na sessão da API e refletida na resposta." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Os seus metadados JSON não sensíveis. Armazenados na sessão da API e devolvidos na resposta." } } }, "RiskWarning": { "type": "object", "required": [ "feature", "risk", "log_type", "short_description", "long_description" ], "properties": { "feature": { "type": "string", "description": "Funcionalidade que gerou o aviso." }, "risk": { "type": "string", "description": "Código de risco legível por máquina. Podem ser adicionados novos valores ao longo do tempo." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contexto específico do risco, ou `null`." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravidade utilizada pelas regras de decisão." }, "short_description": { "type": "string", "description": "Resumo de uma linha legível por humanos." }, "long_description": { "type": "string", "description": "Explicação legível." } } }, "RiskLifecycleEvent": { "type": "object", "required": [ "type", "timestamp", "details", "fee" ], "properties": { "type": { "type": "string", "description": "Tipo de evento legível por máquina. Podem ser adicionados novos valores ao longo do tempo." }, "timestamp": { "type": "string", "format": "date-time", "description": "Quando o evento aconteceu." }, "details": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Payload específico do evento, ou `null`." }, "fee": { "type": "number", "description": "Montante em USD faturado por este evento." } } }, "PhoneMatchItem": { "type": "object", "description": "Outra sessão da sua aplicação que utilizou o mesmo número de telefone com um `vendor_data` diferente.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID de sessão da outra verificação que utilizou este número de telefone." }, "session_number": { "type": "integer", "description": "Número sequencial legível da sessão." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` dessa sessão." }, "verification_date": { "type": "string", "description": "Quando essa sessão foi criada (`YYYY-MM-DDTHH:MM:SSZ`)." }, "phone_number": { "type": "string", "description": "O número de telefone correspondido." }, "status": { "type": "string", "description": "Estado dessa sessão (por exemplo, `Approved`, `Declined`, `In Progress`)." }, "is_blocklisted": { "type": "boolean", "description": "Se o número de telefone está na lista de bloqueio da sua aplicação." }, "api_service": { "type": "string", "nullable": true, "description": "Para sessões do tipo API, a API autónoma que a criou; `null` para sessões de verificação normais." }, "source": { "type": "string", "description": "Onde a correspondência foi encontrada. Habitualmente `session`; uma ocorrência na lista de bloqueio através de uma entrada de lista da organização utiliza `list_entry`." } } }, "EmailMatchItem": { "type": "object", "description": "Outra sessão da sua aplicação que utilizou o mesmo endereço de e-mail com um `vendor_data` diferente.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID de sessão da outra verificação que utilizou este endereço de e-mail." }, "session_number": { "type": "integer", "description": "Número sequencial legível da sessão." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` dessa sessão." }, "verification_date": { "type": "string", "description": "Quando essa sessão foi criada (`YYYY-MM-DDTHH:MM:SSZ`)." }, "email": { "type": "string", "description": "O endereço de e-mail correspondido." }, "status": { "type": "string", "description": "Estado dessa sessão (por exemplo, `Approved`, `Declined`, `In Progress`)." }, "is_blocklisted": { "type": "boolean", "description": "Indica se o endereço de e-mail está na lista de bloqueio da sua aplicação." }, "api_service": { "type": "string", "nullable": true, "description": "Para sessões do tipo API, a API autónoma que a criou; `null` para sessões de verificação normais." }, "source": { "type": "string", "description": "Onde a correspondência foi encontrada. Habitualmente `session`; uma ocorrência na lista de bloqueio através de uma entrada de lista da organização utiliza `list_entry`." } } }, "PhoneIntelligence": { "type": "object", "description": "Bloco de inteligência de telefone normalizado. Presente apenas quando o suplemento de inteligência foi executado para esta consulta; quando presente, também é exposto sob o alias `enrichment` com valores idênticos.", "properties": { "score": { "type": "number", "nullable": true, "description": "Pontuação de risco normalizada de 0-100. Mais alto é mais arriscado." }, "phone_type_risk": { "type": "string", "nullable": true, "description": "`Low`, `Medium` ou `High`, derivado da pontuação." }, "phone_trust_index": { "type": "number", "nullable": true, "description": "Inverso da pontuação, para painéis que preferem que quanto maior, melhor." }, "network_stability_index": { "type": "number", "nullable": true, "description": "Estabilidade da rede associada à linha." }, "is_disposable": { "type": "boolean", "nullable": true, "description": "`true` quando o número parece descartável ou virtual." }, "is_ported": { "type": "boolean", "nullable": true, "description": "`true` quando o número mudou de operadora." }, "is_recently_ported": { "type": "boolean", "nullable": true, "description": "`true` quando a portabilidade ocorreu recentemente." }, "carrier_type": { "type": "string", "nullable": true, "description": "Classificação da linha comunicada pela consulta (por exemplo, `mobile`)." }, "reason_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Identificador Didit estável do sinal, por exemplo `IR-5AC67A32`. Opaco: agrupe e filtre por ele, não tente analisá-lo." }, "value": { "nullable": true, "description": "Para um sinalizador de risco (por exemplo, `voip`, `leaked`, `disposable`, `spam_trap`), o respetivo valor: um booleano, um nível ou uma data. Nulo para um código de motivo com pontuação." }, "direction": { "type": "string", "enum": [ "risk", "trust" ], "description": "Se o sinal aumentou o risco ou adicionou confiança." }, "message": { "type": "string", "description": "Explicação legível do sinal, em inglês." }, "impact_level": { "type": "string", "nullable": true, "description": "Com que intensidade o sinal influenciou a pontuação, por exemplo `low`, `medium` ou `high`." } } }, "description": "Sinais que explicam a pontuação, cada um com um código Didit estável, uma direção, uma mensagem e um nível de impacto. Podem surgir novos códigos ao longo do tempo, pelo que não deve rejeitar códigos desconhecidos." } } }, "EmailIntelligence": { "type": "object", "description": "Bloco de inteligência de e-mail normalizado. Presente apenas quando o suplemento de inteligência foi executado para este e-mail; quando presente, também é exposto como o alias `enrichment` com valores idênticos.", "properties": { "score": { "type": "number", "nullable": true, "description": "Pontuação de risco normalizada de 0-100. Mais alto é mais arriscado." }, "deliverable": { "type": "string", "nullable": true, "description": "Faixa de capacidade de entrega (por exemplo, `high`)." }, "breach_risk_level": { "type": "string", "nullable": true, "description": "`Low`, `Medium` ou `High`." }, "breach_risk_index": { "type": "number", "nullable": true, "description": "Índice numérico de risco de violação." }, "is_recent_breach": { "type": "boolean", "nullable": true, "description": "`true` quando o endereço surge numa violação recente." }, "is_frequent_breached": { "type": "boolean", "nullable": true, "description": "`true` quando o endereço surge em muitas violações." }, "is_disposable": { "type": "boolean", "nullable": true, "description": "`true` quando o domínio é de um fornecedor descartável." }, "is_free_domain": { "type": "boolean", "nullable": true, "description": "`true` quando o domínio é de um fornecedor de e-mail gratuito." }, "is_breached": { "type": "boolean", "nullable": true, "description": "`true` quando o endereço surge em violações conhecidas." }, "no_of_breaches": { "type": "number", "nullable": true, "description": "Número de violações de dados conhecidas que contêm o endereço." }, "reason_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Identificador Didit estável do sinal, por exemplo `IR-5AC67A32`. Opaco: agrupe e filtre por ele, não tente analisá-lo." }, "value": { "nullable": true, "description": "Para um sinalizador de risco (por exemplo, `voip`, `leaked`, `disposable`, `spam_trap`), o respetivo valor: um booleano, um nível ou uma data. Nulo para um código de motivo com pontuação." }, "direction": { "type": "string", "enum": [ "risk", "trust" ], "description": "Se o sinal aumentou o risco ou adicionou confiança." }, "message": { "type": "string", "description": "Explicação legível do sinal, em inglês." }, "impact_level": { "type": "string", "nullable": true, "description": "Com que intensidade o sinal influenciou a pontuação, por exemplo `low`, `medium` ou `high`." } } }, "description": "Sinais que explicam a pontuação, cada um com um código Didit estável, uma direção, uma mensagem e um nível de impacto. Podem surgir novos códigos ao longo do tempo, pelo que não deve rejeitar códigos desconhecidos." } } }, "IPRiskResult": { "type": "object", "description": "Resultado de risco de IP. Os campos individuais de enriquecimento podem ser `null` quando a consulta não retornou dados utilizáveis.", "required": [ "status", "threat" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "`In Review` quando o país resolvido entrar em conflito com `claimed_country`, ou quando o endereço estiver associado a infraestruturas de VPN, Tor ou centro de dados. Caso contrário, `Approved`." }, "ip_address": { "type": "string", "nullable": true, "description": "O endereço avaliado. `null` quando nenhuma fonte de enriquecimento devolveu dados utilizáveis." }, "ip_country": { "type": "string", "nullable": true, "description": "Nome do país resolvido." }, "ip_country_code": { "type": "string", "nullable": true, "description": "Código do país resolvido. Compare países através de `country_mismatch` em vez de comparar diretamente as strings brutas dos países." }, "ip_state": { "type": "string", "nullable": true, "description": "Estado ou região resolvidos." }, "ip_city": { "type": "string", "nullable": true, "description": "Cidade resolvida." }, "latitude": { "type": "number", "nullable": true, "description": "Geolocalização de rede aproximada, não uma localização precisa do dispositivo." }, "longitude": { "type": "number", "nullable": true, "description": "Geolocalização de rede aproximada, não uma localização precisa do dispositivo." }, "isp": { "type": "string", "nullable": true, "description": "Fornecedor de serviços de Internet que presta serviço ao endereço." }, "organization": { "type": "string", "nullable": true, "description": "Organização proprietária do bloco de endereços." }, "is_vpn_or_tor": { "type": "boolean", "nullable": true, "description": "`true` quando o endereço está associado a infraestrutura de VPN ou Tor." }, "is_data_center": { "type": "boolean", "nullable": true, "description": "`true` quando o endereço pertence a uma rede de alojamento ou centro de dados." }, "time_zone": { "type": "string", "nullable": true, "description": "Fuso horário da localização resolvida." }, "time_zone_offset": { "type": "string", "nullable": true, "description": "Desfasamento UTC da localização determinada." }, "asn_number": { "type": "number", "nullable": true, "description": "Número de sistema autónomo." }, "asn_organization": { "type": "string", "nullable": true, "description": "Organização que opera o sistema autónomo." }, "connection_type": { "type": "string", "nullable": true, "description": "Classificação da ligação (por exemplo, `cellular`, `hosting`)." }, "carrier": { "type": "string", "nullable": true, "description": "Operadora móvel quando o endereço se encontra numa rede móvel." }, "proxy_type": { "type": "string", "nullable": true, "description": "Classificação de proxy quando o endereço está atrás de um proxy." }, "claimed_country": { "type": "string", "nullable": true, "description": "Eco do `claimed_country` que enviou." }, "country_mismatch": { "type": "boolean", "nullable": true, "description": "`true` quando o país apurado difere de `claimed_country`. `null` quando não estão disponíveis dados de enriquecimento ou país declarado." }, "threat": { "type": "object", "additionalProperties": true, "description": "Evidência de ameaças de rede em formato livre a partir da fonte de enriquecimento (por exemplo, `is_proxy`, `is_tor`). Objeto vazio quando não existem dados de enriquecimento disponíveis. Considere-o como um detalhe de diagnóstico, não como um contrato estável." } } }, "PhoneRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão de API criada para este pedido. Guarde-o com `vendor_data` se precisar de correlacionar o resultado com webhooks posteriores ou atividade na consola." }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Decisão final para esta sessão de API. Normalmente `Approved`; a avaliação de risco pode produzir `In Review` ou `Declined`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, `null` se não tiver enviado nenhum." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, `null` se não tiver enviado nenhum." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora desta resposta." }, "phone": { "type": "object", "description": "Relatório de telefone normalizado, o mesmo bloco utilizado pelas respostas da Verificação de telefone.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Decisão para este número de telefone. Reflete o `status` de nível superior." }, "phone_number_prefix": { "type": "string", "description": "Indicativo telefónico do país com `+` inicial (ex.: `+1`).", "example": "+1" }, "phone_number": { "type": "string", "description": "Número nacional sem o indicativo do país.", "example": "4155552671" }, "full_number": { "type": "string", "description": "Número completo no formato E.164.", "example": "+14155552671" }, "country_code": { "type": "string", "nullable": true, "description": "País ISO 3166-1 alfa-2 do número.", "example": "US" }, "country_name": { "type": "string", "description": "Nome completo do país derivado de `country_code`.", "example": "United States" }, "carrier": { "type": "object", "nullable": true, "description": "Rede atual que serve o número. `null` quando a consulta não conseguiu determinar uma operadora.", "properties": { "name": { "type": "string", "description": "Nome da operadora. Cadeia vazia quando a pesquisa não a conseguiu identificar." }, "type": { "type": "string", "description": "Tipo de linha comunicado pela consulta: `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate` ou semelhante." } } }, "is_disposable": { "type": "boolean", "description": "`true` quando o número pertence a um serviço de números temporários ou descartáveis." }, "is_virtual": { "type": "boolean", "description": "`true` quando o tipo de linha é virtual (`voip`, `isp` ou `vpn`)." }, "verification_method": { "type": "string", "nullable": true, "description": "Canal OTP da verificação subjacente. `null` para consultas de risco, que nunca enviam um código." }, "verification_attempts": { "type": "integer", "description": "Envios de OTP para este número. `0` para pesquisas de risco." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o número foi verificado pela última vez por um OTP. `null` para consultas de risco." }, "warnings": { "type": "array", "description": "Avisos de risco registados para este pedido. Array vazio quando não existirem.", "items": { "$ref": "#/components/schemas/RiskWarning" } }, "lifecycle": { "type": "array", "description": "Registo de auditoria cronológico do pedido. Array vazio para consultas de risco sem eventos de envio.", "items": { "$ref": "#/components/schemas/RiskLifecycleEvent" } }, "matches": { "type": "array", "description": "Outras sessões da sua aplicação onde o mesmo número de telefone foi utilizado por um utilizador diferente (`vendor_data` diferente). Até 5 entradas. Array vazio quando não existirem correspondências.", "items": { "$ref": "#/components/schemas/PhoneMatchItem" } }, "phone_intelligence": { "$ref": "#/components/schemas/PhoneIntelligence" }, "enrichment": { "$ref": "#/components/schemas/PhoneIntelligence" }, "phone_social": { "$ref": "#/components/schemas/PhoneSocialFootprint" } } } } }, "EmailRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão de API criada para este pedido. Guarde-o com `vendor_data` se precisar de correlacionar o resultado com webhooks posteriores ou atividade na consola." }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Decisão final para esta sessão de API. Normalmente `Approved`; a avaliação de risco pode produzir `In Review` ou `Declined`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, `null` se não tiver enviado nenhum." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, `null` se não tiver enviado nenhum." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora desta resposta." }, "email": { "type": "object", "description": "Relatório de e-mail normalizado, o mesmo bloco utilizado pelas respostas da Verificação de e-mail.", "required": [ "status", "email", "is_breached", "breaches", "is_disposable", "is_undeliverable" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Decisão para este endereço de e-mail. Reflete o `status` de nível superior." }, "email": { "type": "string", "description": "O endereço avaliado.", "example": "alice@example.com" }, "is_breached": { "type": "boolean", "description": "Indica se o endereço surge numa violação de credenciais conhecida." }, "breaches": { "type": "array", "description": "Até 5 violações conhecidas mais recentes que contêm este endereço. Array vazio quando `is_breached` for `false`.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Identificador da violação." }, "domain": { "type": "string", "description": "Domínio do serviço afetado pela violação." }, "breach_date": { "type": "string", "format": "date", "description": "Data em que a violação ocorreu." }, "breach_emails_count": { "type": "integer", "description": "Número total de contas expostas na violação de dados." }, "description": { "type": "string", "description": "Descrição legível da violação (pode conter marcação HTML)." }, "logo_path": { "type": "string", "description": "URL do logótipo do serviço comprometido." }, "data_classes": { "type": "array", "items": { "type": "string" }, "description": "Categorias de dados expostos, em snake_case (por ex., `email_addresses`, `passwords`)." }, "is_verified": { "type": "boolean", "description": "Indica se a violação foi verificada como legítima." } } } }, "is_disposable": { "type": "boolean", "description": "Indica se o domínio pertence a um fornecedor de endereços descartáveis." }, "is_undeliverable": { "type": "boolean", "description": "Indica se o endereço foi considerado não entregável." }, "verification_attempts": { "type": "integer", "description": "Envios de OTP para este endereço. `0` para pesquisas de risco." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o endereço foi verificado pela última vez por um OTP. `null` para consultas de risco." }, "warnings": { "type": "array", "description": "Avisos de risco registados para este pedido. Array vazio quando não existirem.", "items": { "$ref": "#/components/schemas/RiskWarning" } }, "lifecycle": { "type": "array", "description": "Registo de auditoria cronológico do pedido. Array vazio para consultas de risco sem envios.", "items": { "$ref": "#/components/schemas/RiskLifecycleEvent" } }, "matches": { "type": "array", "description": "Outras sessões da sua aplicação onde o mesmo endereço de e-mail foi utilizado por um utilizador diferente (`vendor_data` diferente). Até 5 entradas. Array vazio quando não existirem correspondências.", "items": { "$ref": "#/components/schemas/EmailMatchItem" } }, "email_intelligence": { "$ref": "#/components/schemas/EmailIntelligence" }, "enrichment": { "$ref": "#/components/schemas/EmailIntelligence" }, "email_social": { "$ref": "#/components/schemas/EmailSocialFootprint" } } } } }, "IPRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID da sessão de API criada para este pedido. Guarde-o com `vendor_data` se precisar de correlacionar o resultado com webhooks posteriores ou atividade na consola." }, "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "Decisão para esta sessão de API: `In Review` em caso de risco de rede ou discrepância de país, caso contrário `Approved`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou, `null` se não tiver enviado nenhum." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou, `null` se não tiver enviado nenhum." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora desta resposta." }, "ip": { "type": "object", "description": "Resultado de risco de IP. Os campos individuais de enriquecimento podem ser `null` quando a consulta não retornou dados utilizáveis.", "required": [ "status", "threat" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "`In Review` quando o país resolvido entrar em conflito com `claimed_country`, ou quando o endereço estiver associado a infraestruturas de VPN, Tor ou centro de dados. Caso contrário, `Approved`." }, "ip_address": { "type": "string", "nullable": true, "description": "O endereço avaliado. `null` quando nenhuma fonte de enriquecimento devolveu dados utilizáveis." }, "ip_country": { "type": "string", "nullable": true, "description": "Nome do país resolvido." }, "ip_country_code": { "type": "string", "nullable": true, "description": "Código do país resolvido. Compare países através de `country_mismatch` em vez de comparar diretamente as strings brutas dos países." }, "ip_state": { "type": "string", "nullable": true, "description": "Estado ou região resolvidos." }, "ip_city": { "type": "string", "nullable": true, "description": "Cidade resolvida." }, "latitude": { "type": "number", "nullable": true, "description": "Geolocalização de rede aproximada, não uma localização precisa do dispositivo." }, "longitude": { "type": "number", "nullable": true, "description": "Geolocalização de rede aproximada, não uma localização precisa do dispositivo." }, "isp": { "type": "string", "nullable": true, "description": "Fornecedor de serviços de Internet que presta serviço ao endereço." }, "organization": { "type": "string", "nullable": true, "description": "Organização proprietária do bloco de endereços." }, "is_vpn_or_tor": { "type": "boolean", "nullable": true, "description": "`true` quando o endereço está associado a infraestrutura de VPN ou Tor." }, "is_data_center": { "type": "boolean", "nullable": true, "description": "`true` quando o endereço pertence a uma rede de alojamento ou centro de dados." }, "time_zone": { "type": "string", "nullable": true, "description": "Fuso horário da localização resolvida." }, "time_zone_offset": { "type": "string", "nullable": true, "description": "Desfasamento UTC da localização determinada." }, "asn_number": { "type": "number", "nullable": true, "description": "Número de sistema autónomo." }, "asn_organization": { "type": "string", "nullable": true, "description": "Organização que opera o sistema autónomo." }, "connection_type": { "type": "string", "nullable": true, "description": "Classificação da ligação (por exemplo, `cellular`, `hosting`)." }, "carrier": { "type": "string", "nullable": true, "description": "Operadora móvel quando o endereço se encontra numa rede móvel." }, "proxy_type": { "type": "string", "nullable": true, "description": "Classificação de proxy quando o endereço está atrás de um proxy." }, "claimed_country": { "type": "string", "nullable": true, "description": "Eco do `claimed_country` que enviou." }, "country_mismatch": { "type": "boolean", "nullable": true, "description": "`true` quando o país apurado difere de `claimed_country`. `null` quando não estão disponíveis dados de enriquecimento ou país declarado." }, "threat": { "type": "object", "additionalProperties": true, "description": "Evidência de ameaças de rede em formato livre a partir da fonte de enriquecimento (por exemplo, `is_proxy`, `is_tor`). Objeto vazio quando não existem dados de enriquecimento disponíveis. Considere-o como um detalhe de diagnóstico, não como um contrato estável." } } } } }, "SocialFootprintPlatform": { "type": "object", "properties": { "platform": { "type": "string", "description": "Identificador da plataforma.", "example": "whatsapp" }, "category": { "type": "string", "description": "Categoria da plataforma, por exemplo, MESSAGING, SOCIAL_MEDIA, ECOMMERCE, PROFESSIONAL, EMAIL_PROVIDER.", "example": "MESSAGING" }, "scope": { "type": "string", "enum": [ "global", "local" ], "description": "`global` para plataformas mundiais, `local` para plataformas específicas de uma região.", "example": "global" } } }, "SocialFootprintCategorySummary": { "type": "object", "properties": { "registered": { "type": "integer", "nullable": true, "description": "Plataformas nesta categoria onde o registo está confirmado.", "example": 2 }, "ratio": { "type": "number", "format": "float", "nullable": true, "description": "Percentagem de plataformas verificadas da categoria com registo, 0.0-1.0.", "example": 0.6667 } } }, "SocialFootprintProfile": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Nome do perfil, quando a plataforma o disponibiliza." }, "photo": { "type": "string", "nullable": true, "description": "URL da fotografia de perfil, quando a plataforma o disponibiliza." }, "about": { "type": "string", "nullable": true, "description": "Texto de biografia/apresentação do perfil, quando a plataforma o disponibiliza." }, "privacy_status": { "type": "string", "nullable": true, "enum": [ "PUBLIC", "PRIVATE", null ], "description": "Visibilidade do perfil, quando a plataforma a disponibiliza." }, "business_account": { "type": "boolean", "nullable": true, "description": "Se o perfil é uma conta empresarial, quando a plataforma o disponibiliza." } } }, "PhoneSocialFootprint": { "type": "object", "nullable": true, "description": "Presença social (social footprint) do número de telefone: as plataformas online em que está registado. Presente apenas quando `enable_social` foi definido e a verificação foi concluída. Cada contagem pode ser nula quando não foram devolvidos dados para ela. `profiles_registered: 0` significa que as plataformas foram verificadas e o número de telefone não foi encontrado em nenhuma delas - uma resposta válida, faturável e um sinal comum de identidade sintética.", "properties": { "profiles_registered": { "type": "integer", "nullable": true, "description": "Plataformas onde o número de telefone está confirmado como registado.", "example": 5 }, "profiles_checked": { "type": "integer", "nullable": true, "description": "Plataformas avaliadas quanto ao registo.", "example": 14 }, "names_found": { "type": "integer", "nullable": true, "description": "Plataformas que devolveram um nome associado.", "example": 0 }, "photos_found": { "type": "integer", "nullable": true, "description": "Plataformas que devolveram uma fotografia de perfil.", "example": 0 }, "communication_breadth": { "type": "integer", "nullable": true, "description": "Plataformas de comunicação com presença detetada.", "example": 2 }, "digital_footprint_diversity": { "type": "integer", "nullable": true, "description": "Categorias de plataforma distintas com presença detetada.", "example": 5 }, "digital_sophistication_index": { "type": "integer", "nullable": true, "description": "Indicador composto de maturidade digital, 0-10.", "example": 5 }, "engagement_depth_index": { "type": "integer", "nullable": true, "description": "Indicador do nível de detalhe do perfil, 0-10.", "example": 3 }, "subscription_affordability_index": { "type": "integer", "nullable": true, "description": "Distribuição da plataforma gratuita vs paga, 0-10.", "example": 2 }, "free_platforms": { "type": "integer", "nullable": true, "description": "Registos em plataformas gratuitas.", "example": 4 }, "full_paid_platforms": { "type": "integer", "nullable": true, "description": "Registos em plataformas totalmente pagas.", "example": 0 }, "partial_paid_platforms": { "type": "integer", "nullable": true, "description": "Registos em plataformas freemium.", "example": 1 }, "whatsapp_profile_completeness": { "type": "string", "nullable": true, "enum": [ "Basic", "Partial", "Complete", "Not Present", null ], "description": "Grau de preenchimento do perfil do WhatsApp. Apenas para telefone; nulo para e-mail.", "example": "Partial" }, "registered_platforms": { "type": "array", "description": "Plataformas onde o registo está confirmado.", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "not_registered_platforms": { "type": "array", "description": "Plataformas verificadas com resultado negativo.", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "categories": { "type": "object", "description": "Contagem e proporção de registos por categoria de plataforma.", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintCategorySummary" } }, "profiles": { "type": "object", "description": "Detalhes de perfil por plataforma, indexados por plataforma, quando a plataforma os disponibiliza.", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintProfile" } } } }, "EmailSocialFootprint": { "type": "object", "nullable": true, "description": "Presença social do endereço de e-mail: as plataformas online em que está registado. Presente apenas quando `enable_social` foi definido e a verificação foi concluída. Cada contagem pode ser nula quando não foram devolvidos dados para ela. `profiles_registered: 0` significa que as plataformas foram verificadas e o endereço de e-mail não foi encontrado em nenhuma delas - uma resposta válida, faturável e um sinal comum de identidade sintética.", "properties": { "profiles_registered": { "type": "integer", "nullable": true, "description": "Plataformas onde o endereço de e-mail está confirmado como registado.", "example": 5 }, "profiles_checked": { "type": "integer", "nullable": true, "description": "Plataformas avaliadas quanto ao registo.", "example": 14 }, "names_found": { "type": "integer", "nullable": true, "description": "Plataformas que devolveram um nome associado.", "example": 0 }, "photos_found": { "type": "integer", "nullable": true, "description": "Plataformas que devolveram uma fotografia de perfil.", "example": 0 }, "communication_breadth": { "type": "integer", "nullable": true, "description": "Plataformas de comunicação com presença detetada.", "example": 2 }, "digital_footprint_diversity": { "type": "integer", "nullable": true, "description": "Categorias de plataforma distintas com presença detetada.", "example": 5 }, "digital_sophistication_index": { "type": "integer", "nullable": true, "description": "Indicador composto de maturidade digital, 0-10.", "example": 5 }, "engagement_depth_index": { "type": "integer", "nullable": true, "description": "Indicador do nível de detalhe do perfil, 0-10.", "example": 3 }, "subscription_affordability_index": { "type": "integer", "nullable": true, "description": "Distribuição da plataforma gratuita vs paga, 0-10.", "example": 2 }, "free_platforms": { "type": "integer", "nullable": true, "description": "Registos em plataformas gratuitas.", "example": 4 }, "full_paid_platforms": { "type": "integer", "nullable": true, "description": "Registos em plataformas totalmente pagas.", "example": 0 }, "partial_paid_platforms": { "type": "integer", "nullable": true, "description": "Registos em plataformas freemium.", "example": 1 }, "whatsapp_profile_completeness": { "type": "string", "nullable": true, "enum": [ "Basic", "Partial", "Complete", "Not Present", null ], "description": "Grau de preenchimento do perfil do WhatsApp. Apenas para telefone; nulo para e-mail.", "example": "Partial" }, "registered_platforms": { "type": "array", "description": "Plataformas onde o registo está confirmado.", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "not_registered_platforms": { "type": "array", "description": "Plataformas verificadas com resultado negativo.", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "categories": { "type": "object", "description": "Contagem e proporção de registos por categoria de plataforma.", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintCategorySummary" } }, "profiles": { "type": "object", "description": "Detalhes de perfil por plataforma, indexados por plataforma, quando a plataforma os disponibiliza.", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintProfile" } } } }, "KYBRegistryAddress": { "type": "object", "description": "Uma morada indicada pelo registo, com o mesmo formato para todos os países e fontes de registo. Todas as chaves estão sempre presentes; uma parte que o registo não publique é null.", "properties": { "type": { "type": "string", "nullable": true, "description": "Tipo de morada em minúsculas: `registered` para a sede social; outros tipos conforme designados pelo registo (por exemplo, `postal`, `office`). `null` quando o registo não indica o tipo de morada." }, "address": { "type": "string", "description": "A morada completa numa linha. Sempre presente em todas as moradas." }, "street": { "type": "string", "nullable": true, "description": "Rua e número." }, "city": { "type": "string", "nullable": true, "description": "Cidade ou localidade." }, "postal_code": { "type": "string", "nullable": true, "description": "Código postal." }, "region": { "type": "string", "nullable": true, "description": "Região, estado ou província." }, "country_code": { "type": "string", "nullable": true, "description": "Código de país ISO 3166-1 alpha-2." }, "description": { "type": "string", "nullable": true, "description": "A etiqueta própria do registo para a morada, quando este a fornece." } }, "required": [ "type", "address", "street", "city", "postal_code", "region", "country_code", "description" ] }, "KYBRegistryIndustry": { "type": "object", "description": "Uma atividade na qual o registo classifica a empresa, com o mesmo formato para todos os países e fontes de registo.", "properties": { "code": { "type": "string", "nullable": true, "description": "Código de atividade conforme consta do registo (por exemplo `73110`)." }, "description": { "type": "string", "nullable": true, "description": "Rótulo da atividade, quando o registo publica um." }, "scheme": { "type": "string", "nullable": true, "description": "Sistema de classificação, um nome por sistema independentemente da fonte que o comunicou: `UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`; outros sistemas nacionais mantêm o nome original do registo. Nulo quando o registo não especifica o sistema." }, "is_primary": { "type": "boolean", "description": "True para a atividade principal da empresa. Exatamente uma entrada é principal quando a lista não está vazia." } }, "required": [ "code", "description", "scheme", "is_primary" ] }, "KYBRegistryShareholding": { "type": "object", "nullable": true, "description": "O que um proprietário detém, no mesmo formato para todos os países e fontes de registo. Nulo quando o registo não indicar qualquer participação. Um intervalo (por exemplo, os 25-50% de um PSC do Reino Unido) não é uma participação: `percentage` é nulo e o intervalo permanece em `ownership_min_shares` / `ownership_max_shares`.", "properties": { "share_class": { "type": "string", "nullable": true, "description": "Classe ou tipo de ação conforme designado no registo." }, "number_of_shares": { "type": "number", "nullable": true, "description": "Número de ações detidas." }, "currency": { "type": "string", "nullable": true, "description": "Moeda ISO 4217 dos valores abaixo." }, "nominal_value": { "type": "number", "nullable": true, "description": "Valor nominal por ação." }, "total_value": { "type": "number", "nullable": true, "description": "Valor total da posição detida." }, "percentage": { "type": "number", "nullable": true, "description": "Participação exata em percentagem, até quatro casas decimais." } }, "required": [ "share_class", "number_of_shares", "currency", "nominal_value", "total_value", "percentage" ] }, "KYBRegistryOwnership": { "type": "object", "description": "O resultado do nível de propriedade (Acionistas / UBO), no mesmo formato para todos os países e fontes de registo.", "properties": { "status": { "type": "string", "nullable": true, "enum": [ "not_requested", "pending", "delivered", "not_held", "unavailable", null ], "description": "`delivered` quando o registo disponibilizou os dados de propriedade; `not_held` quando o registo de propriedade respondeu e não lista de todo a empresa (consulte `unavailable_reason`); `unavailable` quando não disponibilizou os dados de propriedade por qualquer outro motivo (consulte `unavailable_reason`); `pending` enquanto o registo ainda os estiver a obter; `not_requested` para o nível Basic." }, "tier_requested": { "type": "string", "nullable": true, "enum": [ "basic", "shareholders", "ubo", null ], "description": "O nível encomendado pelo fluxo." }, "tier_delivered": { "type": "string", "nullable": true, "enum": [ "basic", "shareholders", "ubo", null ], "description": "O nível entregue pelo registo (e que é faturado). Um pedido de UBO respondido apenas com acionistas diretos é `shareholders`." }, "unavailable_reason": { "type": "string", "nullable": true, "enum": [ "no_owners_on_record", "no_natural_person_owner", "ownership_section_unavailable", "company_not_found", "ambiguous_company_match", "missing_registration_number", "entity_type_not_covered", "provider_unavailable", "other", null ], "description": "O motivo pelo qual um nível de propriedade solicitado não foi fornecido. Nulo, exceto se `status` for `unavailable` ou `pending`." }, "direct_ownership_complete": { "type": "boolean", "nullable": true, "description": "True quando as participações declaradas dos acionistas diretos perfazem 100% (dentro de uma margem de arredondamento de um ponto percentual); false quando não perfazem; null quando a propriedade não foi fornecida ou uma participação não está declarada." }, "unresolved": { "type": "array", "description": "Partes da cadeia de propriedade que o registo não conseguiu resolver, por exemplo, a ausência de registo da estrutura do grupo acima dos proprietários diretos.", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "section": { "type": "string", "nullable": true } } } } }, "required": [ "status", "tier_requested", "tier_delivered", "unavailable_reason", "direct_ownership_complete", "unresolved" ] }, "KYBRegistryData": { "type": "object", "nullable": true, "description": "Detalhe de registo normalizado da Didit para a empresa: o resultado da propriedade (`ownership_error`, `section_errors`, `ubo_resolution`, `lite_enrichment`), as correções feitas com update-data e factos de registo que não têm um campo próprio. Nunca transporta o registo próprio da fonte de registo. Todas as chaves são opcionais e estão presentes apenas quando a empresa tem um valor para as mesmas; podem ser adicionadas novas chaves. Leia os campos canónicos (`addresses`, `industries`, `ownership`, `beneficial_owners[].shareholding`) para tudo o que abrangem.", "properties": { "company_name": { "type": "string", "description": "Nome da empresa conforme corrigido na consola." }, "registration_number": { "type": "string", "description": "Número de registo conforme indicado pelo registo de empresas ou por uma correção na consola." }, "country_code": { "type": "string", "description": "País do registo conforme indicado pelo registo de empresas ou por uma correção na consola." }, "region": { "type": "string", "description": "Região ou estado do registo." }, "incorporation_date": { "type": "string", "description": "Data de constituição (ISO 8601)." }, "registration_date": { "type": "string", "description": "Data de registo (ISO 8601) quando o registo de empresas indica uma diferente da data de constituição." }, "dissolution_date": { "type": "string", "description": "Data de dissolução (ISO 8601) quando o registo a indicar." }, "tax_number": { "type": "string", "description": "Número de identificação fiscal." }, "vat_number": { "type": "string", "description": "Número de IVA (NIF)." }, "legal_address": { "type": "string", "description": "Sede social conforme corrigida na consola." }, "registered_address": { "type": "string", "description": "Morada registada conforme indicada no registo." }, "company_type": { "type": "string", "description": "Forma jurídica." }, "registry_status": { "type": "string", "description": "Estado da empresa no registo de empresas." }, "verification_status": { "type": "string", "description": "Estado da verificação." }, "alternative_names": { "type": "string", "description": "Outros nomes com os quais a empresa opera ou operou." }, "nature_of_business": { "type": "string", "description": "Descrição da atividade." }, "registered_capital": { "type": "string", "description": "Capital social registado conforme impresso." }, "registered_capital_amount": { "type": "string", "description": "Montante do capital social registado, como cadeia de caracteres decimal." }, "registered_capital_currency": { "type": "string", "description": "Moeda do capital social registado (ISO 4217)." }, "website": { "type": "string", "description": "Website." }, "email": { "type": "string", "description": "E-mail de contacto." }, "phone": { "type": "string", "description": "Telefone de contacto." }, "legal_entity_identifier": { "type": "string", "description": "Identificador de Entidade Jurídica (LEI)." }, "location_of_registration": { "type": "string", "description": "Local de registo." }, "control_scheme": { "type": "string", "description": "Regime de governação quando o registo o disponibiliza." }, "ownership_error": { "type": "string", "enum": [ "no_owners_on_record", "no_natural_person_owner", "ownership_section_unavailable", "company_not_found", "ambiguous_company_match", "missing_registration_number", "entity_type_not_covered", "provider_unavailable", "other" ], "description": "O motivo pelo qual um nível de propriedade solicitado não foi fornecido, nos mesmos códigos que `ownership.unavailable_reason`. `no_owners_on_record` (o registo respondeu e não indica nenhum proprietário) e `ownership_section_unavailable` (o registo não devolveu a secção de propriedade) são conclusões diferentes." }, "section_errors": { "type": "object", "description": "Secções que o registo não devolveu, indexadas por secção (`officers`, `shareholders`, `group_structure`). Uma secção listada aqui nunca foi entregue: uma lista vazia ao lado não diz nada sobre a empresa.", "additionalProperties": { "$ref": "#/components/schemas/KYBRegistrySectionError" } }, "ubo_resolution": { "$ref": "#/components/schemas/KYBRegistryUboResolution" }, "lite_enrichment": { "$ref": "#/components/schemas/KYBRegistryLiteEnrichment" }, "registry_metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Os campos próprios do registo para a empresa, indexados tal como o registo os nomeia, como valores simples (registos legados). Apenas estão incluídos os campos revistos como factos do registo." }, "registry_sources": { "type": "array", "description": "Os registos oficiais a partir dos quais o registo foi lido (registos legados). Outras fontes não são indicadas.", "items": { "$ref": "#/components/schemas/KYBRegistrySource" } }, "previous_names": { "type": "array", "items": { "type": "string" }, "description": "Nomes sob os quais a empresa esteve registada anteriormente (registos históricos)." }, "parent_companies": { "type": "array", "items": { "type": "string" }, "description": "Empresas-mãe identificadas pelo registo (registos legados)." }, "documents_available": { "type": "integer", "description": "Quantos registos o registo disponibiliza para a empresa (registos legados)." } } }, "KYBRegistryGroupCompany": { "type": "object", "description": "Uma empresa do grupo empresarial, pela sua identidade de registo.", "properties": { "name": { "type": "string", "nullable": true, "description": "Nome da empresa." }, "country_code": { "type": "string", "nullable": true, "description": "País de registo." }, "registration_number": { "type": "string", "nullable": true, "description": "Número de registo." } }, "required": [ "name", "country_code", "registration_number" ] }, "KYBRegistryUboResolution": { "type": "object", "description": "Como o nível de UBO percorreu a cadeia de propriedade acima da empresa.", "properties": { "parent_chain": { "type": "array", "description": "Empresas-mãe desde a entidade-mãe final até à empresa.", "items": { "$ref": "#/components/schemas/KYBRegistryGroupCompany" } }, "subsidiaries": { "type": "array", "description": "Empresas diretamente abaixo da empresa no seu grupo empresarial.", "items": { "$ref": "#/components/schemas/KYBRegistryGroupCompany" } }, "unresolved": { "type": "array", "description": "Partes da cadeia que o registo não conseguiu resolver (as mesmas entradas que `ownership.unresolved`).", "items": { "type": "object", "properties": { "reason": { "type": "string", "description": "O motivo, por exemplo `no_group_structure_on_record`, `selected_company_not_in_group_structure` ou `section_error`." }, "section": { "type": "string", "nullable": true, "description": "A secção em causa, por exemplo `group_structure`." } }, "required": [ "reason", "section" ] } } }, "required": [ "parent_chain", "subsidiaries", "unresolved" ] }, "KYBRegistrySectionError": { "type": "object", "description": "Uma secção que o registo não devolveu.", "properties": { "status_code": { "type": "integer", "nullable": true, "description": "O estado retornado pelo registo para a secção." } }, "required": [ "status_code" ] }, "KYBRegistryLiteEnrichment": { "type": "object", "description": "Campos vazios do perfil Lite que outra das fontes de registo do país preencheu. A fonte não é indicada.", "properties": { "fields": { "type": "array", "items": { "type": "string" }, "description": "Os campos da empresa que foram preenchidos." }, "people_added": { "type": "integer", "description": "Quantos administradores ou proprietários foram adicionados." } }, "required": [ "fields", "people_added" ] }, "KYBRegistrySource": { "type": "object", "description": "Um registo oficial a partir do qual os dados foram obtidos. Apenas são nomeados registos governamentais oficiais, reguladores e o sistema oficial de identificadores; qualquer outra fonte é omitida.", "properties": { "name": { "type": "string", "description": "Nome do registo, por exemplo `UK Companies House`." }, "source_type": { "type": "string", "enum": [ "official" ], "description": "Sempre `official`." } }, "required": [ "name", "source_type" ] }, "KYBOwnershipStructure": { "type": "object", "nullable": true, "description": "A tabela de capitalização comprovada pelo registo, tal como constava quando o nível de propriedade foi entregue: `shareholders` e `beneficial_owners` diretos. Nulo quando o registo não comprovou qualquer propriedade. Nunca contém as próprias linhas da fonte de registo; consulte `company.beneficial_owners` e `company.ownership` para o registo atual.", "properties": { "shareholders": { "type": "array", "items": { "$ref": "#/components/schemas/KYBOwnershipStructureOwner" } }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/KYBOwnershipStructureOwner" } } }, "required": [ "shareholders", "beneficial_owners" ] }, "KYBOwnershipStructureOwner": { "type": "object", "description": "Um proprietário do instantâneo da propriedade: a mesma identidade de registo e participação que `company.beneficial_owners[]`, e a respetiva `shareholding` canónica.", "properties": { "name": { "type": "string", "nullable": true, "description": "Nome do proprietário conforme indicado no registo." }, "first_name": { "type": "string", "nullable": true, "description": "Nome próprio, para uma pessoa singular, quando o registo o indicar." }, "last_name": { "type": "string", "nullable": true, "description": "Apelido, para uma pessoa singular, quando o registo o indica." }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento (ISO 8601) quando o registo a publica." }, "country_of_birth": { "type": "string", "nullable": true, "description": "País de nascimento quando o registo o publica." }, "company_name": { "type": "string", "nullable": true, "description": "Nome da empresa, para um proprietário empresarial." }, "registration_number": { "type": "string", "nullable": true, "description": "Número de registo, para um proprietário societário." }, "entity_type": { "type": "string", "nullable": true, "enum": [ "person", "company", null ], "description": "Se o proprietário é uma pessoa singular ou uma empresa." }, "nationality": { "type": "string", "nullable": true, "description": "Nacionalidade quando o registo a indicar." }, "designation": { "type": "string", "nullable": true, "description": "O cargo ou a função do titular tal como consta no registo." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "`shareholder` para um titular direto, `ubo` para um beneficiário efetivo." }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferior da participação, em percentagem (igual ao limite superior no caso de uma participação exata)." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superior da participação, em percentagem." }, "voting_min_shares": { "type": "string", "nullable": true, "description": "Limite inferior dos direitos de voto, em percentagem." }, "voting_max_shares": { "type": "string", "nullable": true, "description": "Limite superior dos direitos de voto, em percentagem." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data em que o cargo ou a nomeação teve início (ISO 8601)." }, "is_active": { "type": "boolean", "nullable": true, "description": "Falso para um antigo proprietário." }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } }, "required": [ "name", "first_name", "last_name", "date_of_birth", "country_of_birth", "company_name", "registration_number", "entity_type", "nationality", "designation", "roles", "ownership_min_shares", "ownership_max_shares", "voting_min_shares", "voting_max_shares", "appointment_date", "is_active", "shareholding" ] }, "DigitalIdWalletApiWalletVerificationError": { "type": "object", "properties": { "error": { "type": "string", "description": "Código legível por máquina estável, por exemplo, wallet_unavailable." }, "detail": { "type": "string" } }, "required": [ "detail", "error" ] }, "DigitalIdWalletApiWalletVerificationStartForbidden": { "oneOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" }, { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } ] }, "DigitalIdWalletApiClientCredentialsForbiddenErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Forbidden - User doesn't have permission" } } }, "DigitalIdWalletApiWalletVerificationStartBadRequest": { "oneOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" }, { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationFieldErrors" } ] }, "DigitalIdWalletApiWalletVerificationFieldErrors": { "type": "object", "description": "Erros de validação do pedido: cada campo rejeitado com as respetivas mensagens.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "DigitalIdWalletApiWalletVerificationResponse": { "type": "object", "description": "Uma verificação de carteira autónoma, tal como é devolvida por todos os endpoints de carteira.", "properties": { "request_id": { "type": "string", "format": "uuid" }, "wallet_verification": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResult" }, "vendor_data": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "O objeto de metadados enviado no início, ou nulo." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "created_at", "metadata", "request_id", "vendor_data", "wallet_verification" ] }, "DigitalIdWalletApiWalletVerificationResult": { "type": "object", "properties": { "wallet": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWallet" } ], "readOnly": true }, "country": { "type": "string" }, "status": { "type": "string", "description": "Não terminada enquanto pendente, depois Aprovada (verificada) ou Recusada." }, "outcome": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResultOutcomeEnum" }, "error": { "type": "string", "nullable": true, "readOnly": true }, "interaction": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiInteractionEnum" } ], "readOnly": true }, "simulated": { "type": "boolean", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time" }, "next_action": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletNextAction" } ], "nullable": true, "readOnly": true }, "identity": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletIdentity" } ], "nullable": true, "readOnly": true }, "attributes": { "type": "object", "additionalProperties": {}, "nullable": true, "readOnly": true }, "level_of_assurance": { "type": "string", "nullable": true }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "signature_valid": { "type": "boolean", "nullable": true, "description": "True após a assinatura da credencial ter sido verificada; null para uma credencial simulada." }, "credential_type": { "type": "string", "nullable": true } }, "required": [ "attributes", "country", "credential_type", "error", "expires_at", "identity", "interaction", "level_of_assurance", "next_action", "outcome", "signature_valid", "simulated", "status", "verified_at", "wallet" ] }, "DigitalIdWalletApiWalletIdentity": { "type": "object", "properties": { "full_name": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "nationality": { "type": "string", "nullable": true, "description": "Nacionalidade ISO3, apenas quando a carteira afirmar uma (nunca deduzida)." }, "issuing_state": { "type": "string", "description": "País ISO3 cujo esquema emitiu a identidade." } }, "required": [ "date_of_birth", "first_name", "full_name", "issuing_state", "last_name", "nationality" ] }, "DigitalIdWalletApiWalletNextAction": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletNextActionTypeEnum" } ], "description": "redirect: envie o navegador do utilizador para url. confirm_in_app: mostre verification_code ao utilizador, que verifica se coincide com o código na respetiva aplicação de carteira e confirma aí; depois, faça polling. request_digital_credential: num gesto do utilizador na origem em que iniciou o processo, solicite à carteira com digital_credentials.request e, em seguida, envie o que ela devolver para POST .../verifications/{request_id}/response/.\n\n* `redirect` - redirect\n* `confirm_in_app` - confirm_in_app\n* `request_digital_credential` - request_digital_credential" }, "url": { "type": "string", "format": "uri", "description": "apenas redirect: onde o utilizador inicia sessão com a carteira." }, "digital_credentials": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialsRequest" } ], "description": "apenas request_digital_credential: o pedido a entregar à carteira." }, "verification_code": { "type": "string", "description": "Apenas confirm_in_app: o código de comparação de 4 dígitos que a aplicação de carteira também apresenta." }, "poll_interval_seconds": { "type": "integer", "description": "Apenas confirm_in_app: com que frequência chamar POST .../verifications/{request_id}/poll/ para obter feedback imediato. O Didit também consulta inícios de sessão pendentes em segundo plano, pelo que o webhook comunica o resultado mesmo que não efetue consultas." } }, "required": [ "type" ] }, "DigitalIdWalletApiWalletNextActionTypeEnum": { "enum": [ "redirect", "confirm_in_app", "request_digital_credential" ], "type": "string", "description": "* `redirect` - redirect\n* `confirm_in_app` - confirm_in_app\n* `request_digital_credential` - request_digital_credential" }, "DigitalIdWalletApiInteractionEnum": { "enum": [ "redirect", "in_app", "digital_credentials" ], "type": "string", "description": "* `redirect` - redirect\n* `in_app` - in_app\n* `digital_credentials` - digital_credentials" }, "DigitalIdWalletApiWalletVerificationResultOutcomeEnum": { "enum": [ "pending", "verified", "cancelled", "timeout", "failed" ], "type": "string", "description": "* `pending` - Pendente\n* `verified` - Verificado\n* `cancelled` - Cancelado pelo utilizador\n* `timeout` - Tempo limite excedido\n* `failed` - Falhou" }, "DigitalIdWalletApiWallet": { "type": "object", "properties": { "id": { "type": "string", "description": "ID de catálogo da carteira, por ex. bankid_se." }, "name": { "type": "string" }, "issuing_authority": { "type": "string", "nullable": true } }, "required": [ "id", "issuing_authority", "name" ] }, "DigitalIdWalletApiEudiWalletVerificationStartRequest": { "type": "object", "description": "Inicie uma verificação EUDI Wallet (AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE, ISL, LIE, NOR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartCountryEnum" } ], "description": "País ISO 3166-1 alfa-3 da identidade EUDI Wallet.\n\n* `AUT` - AUT\n* `BEL` - BEL\n* `BGR` - BGR\n* `HRV` - HRV\n* `CYP` - CYP\n* `CZE` - CZE\n* `DNK` - DNK\n* `EST` - EST\n* `FIN` - FIN\n* `FRA` - FRA\n* `DEU` - DEU\n* `GRC` - GRC\n* `HUN` - HUN\n* `IRL` - IRL\n* `ITA` - ITA\n* `LVA` - LVA\n* `LTU` - LTU\n* `LUX` - LUX\n* `MLT` - MLT\n* `NLD` - NLD\n* `POL` - POL\n* `PRT` - PRT\n* `ROU` - ROU\n* `SVK` - SVK\n* `SVN` - SVN\n* `ESP` - ESP\n* `SWE` - SWE\n* `ISL` - ISL\n* `LIE` - LIE\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "country", "return_url" ] }, "DigitalIdWalletApiDeviceEnum": { "enum": [ "same_device", "cross_device" ], "type": "string", "description": "* `same_device` - same_device\n* `cross_device` - cross_device" }, "DigitalIdWalletApiEudiWalletVerificationStartCountryEnum": { "enum": [ "AUT", "BEL", "BGR", "HRV", "CYP", "CZE", "DNK", "EST", "FIN", "FRA", "DEU", "GRC", "HUN", "IRL", "ITA", "LVA", "LTU", "LUX", "MLT", "NLD", "POL", "PRT", "ROU", "SVK", "SVN", "ESP", "SWE", "ISL", "LIE", "NOR" ], "type": "string", "description": "* `AUT` - AUT\n* `BEL` - BEL\n* `BGR` - BGR\n* `HRV` - HRV\n* `CYP` - CYP\n* `CZE` - CZE\n* `DNK` - DNK\n* `EST` - EST\n* `FIN` - FIN\n* `FRA` - FRA\n* `DEU` - DEU\n* `GRC` - GRC\n* `HUN` - HUN\n* `IRL` - IRL\n* `ITA` - ITA\n* `LVA` - LVA\n* `LTU` - LTU\n* `LUX` - LUX\n* `MLT` - MLT\n* `NLD` - NLD\n* `POL` - POL\n* `PRT` - PRT\n* `ROU` - ROU\n* `SVK` - SVK\n* `SVN` - SVN\n* `ESP` - ESP\n* `SWE` - SWE\n* `ISL` - ISL\n* `LIE` - LIE\n* `NOR` - NOR" }, "DigitalIdWalletApiConnectidWalletVerificationStartRequest": { "type": "object", "description": "Inicie uma verificação ConnectID (AUS).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum" } ], "default": "AUS", "description": "País ISO 3166-1 alfa-3 da identidade ConnectID. A predefinição é AUS, o único país a que presta serviço.\n\n* `AUS` - AUS" }, "authorisation_server_id": { "type": "string", "minLength": 1, "description": "ID do servidor de autorização selecionado através do seletor bancário do ConnectID. O sandbox utiliza por predefinição o Mock Bank A.", "maxLength": 36 }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum": { "enum": [ "AUS" ], "type": "string", "description": "* `AUS` - AUS" }, "DigitalIdWalletApiAudkenniWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação Auðkenni (ISL).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum" } ], "default": "ISL", "description": "País ISO 3166-1 alfa-3 da identidade Auðkenni. A predefinição é ISL, o único país a que presta serviço.\n\n* `ISL` - ISL" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum": { "enum": [ "ISL" ], "type": "string", "description": "* `ISL` - ISL" }, "DigitalIdWalletApiFranceconnectWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com FranceConnect (FRA).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum" } ], "default": "FRA", "description": "País ISO 3166-1 alfa-3 da identidade FranceConnect. A predefinição é FRA, o único país a que presta serviço.\n\n* `FRA` - FRA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum": { "enum": [ "FRA" ], "type": "string", "description": "* `FRA` - FRA" }, "DigitalIdWalletApiDiiaWalletVerificationStartRequest": { "type": "object", "description": "Inicie uma verificação Diia (UKR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum" } ], "default": "UKR", "description": "País ISO 3166-1 alfa-3 da identidade Diia. A predefinição é UKR, o único país a que presta serviço.\n\n* `UKR` - UKR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum": { "enum": [ "UKR" ], "type": "string", "description": "* `UKR` - UKR" }, "DigitalIdWalletApiMojeidWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com o MojeID (CZE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryE2dEnum" } ], "default": "CZE", "description": "País ISO 3166-1 alfa-3 da identidade MojeID. A predefinição é CZE, o único país a que presta serviço.\n\n* `CZE` - CZE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryE2dEnum": { "enum": [ "CZE" ], "type": "string", "description": "* `CZE` - CZE" }, "DigitalIdWalletApiBankidCzWalletVerificationStartRequest": { "type": "object", "description": "Inicie uma verificação Bank iD (CZE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryE2dEnum" } ], "default": "CZE", "description": "País ISO 3166-1 alfa-3 da identidade Bank iD. A predefinição é CZE, o único país a que presta serviço.\n\n* `CZE` - CZE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com o eParaksts mobile (LVA).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum" } ], "default": "LVA", "description": "País ISO 3166-1 alfa-3 da identidade eParaksts mobile. A predefinição é LVA, o único país a que presta serviço.\n\n* `LVA` - LVA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum": { "enum": [ "LVA" ], "type": "string", "description": "* `LVA` - LVA" }, "DigitalIdWalletApiIdcardEeWalletVerificationStartRequest": { "type": "object", "description": "Inicie uma verificação Estonian ID-card (EST).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum" } ], "default": "EST", "description": "País ISO 3166-1 alfa-3 da identidade do cartão de identificação estónio (ID-card). A predefinição é EST, o único país a que presta serviço.\n\n* `EST` - EST" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum": { "enum": [ "EST" ], "type": "string", "description": "* `EST` - EST" }, "DigitalIdWalletApiMobileIdWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com Mobile-ID (EST, LTU).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum" } ], "description": "País ISO 3166-1 alfa-3 da identidade Mobile-ID.\n\n* `EST` - EST\n* `LTU` - LTU" }, "personal_code": { "type": "string", "minLength": 1, "description": "O código de identificação pessoal nacional do utilizador. Direciona para a aplicação Mobile-ID do utilizador; o utilizador confirma o código de comparação e introduz o respetivo PIN na aplicação. Nunca recolha o PIN.", "pattern": "^[0-9-]{6,20}$" }, "phone_number": { "type": "string", "minLength": 1, "description": "O número de telefone Mobile-ID no formato E.164 (+372... ou +370...).", "maxLength": 16 } }, "required": [ "country", "personal_code", "phone_number" ] }, "DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum": { "enum": [ "EST", "LTU" ], "type": "string", "description": "* `EST` - EST\n* `LTU` - LTU" }, "DigitalIdWalletApiSmartIdWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com o Smart-ID (EST, LVA, LTU, BEL).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum" } ], "description": "País ISO 3166-1 alfa-3 da identidade Smart-ID.\n\n* `EST` - EST\n* `LVA` - LVA\n* `LTU` - LTU\n* `BEL` - BEL" }, "personal_code": { "type": "string", "minLength": 1, "description": "O código de identificação pessoal nacional do utilizador. Direciona para a aplicação Smart-ID do utilizador; o utilizador confirma o código de comparação e introduz o respetivo PIN na aplicação. Nunca recolha o PIN.", "pattern": "^[0-9-]{6,20}$" } }, "required": [ "country", "personal_code" ] }, "DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum": { "enum": [ "EST", "LVA", "LTU", "BEL" ], "type": "string", "description": "* `EST` - EST\n* `LVA` - LVA\n* `LTU` - LTU\n* `BEL` - BEL" }, "DigitalIdWalletApiGovukWalletWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com GOV.UK Wallet (GBR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountry520Enum" } ], "default": "GBR", "description": "País ISO 3166-1 alfa-3 da identidade GOV.UK Wallet. A predefinição é GBR, o único país a que presta serviço.\n\n* `GBR` - GBR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountry520Enum": { "enum": [ "GBR" ], "type": "string", "description": "* `GBR` - GBR" }, "DigitalIdWalletApiOneidWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com o OneID (GBR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountry520Enum" } ], "default": "GBR", "description": "País ISO 3166-1 alfa-3 da identidade OneID. A predefinição é GBR, o único país a que presta serviço.\n\n* `GBR` - GBR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiGovbrWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação gov.br (BRA).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum" } ], "default": "BRA", "description": "País ISO 3166-1 alfa-3 da identidade gov.br. A predefinição é BRA, o único país a que presta serviço.\n\n* `BRA` - BRA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum": { "enum": [ "BRA" ], "type": "string", "description": "* `BRA` - BRA" }, "DigitalIdWalletApiUaePassWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com o UAE PASS (ARE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum" } ], "default": "ARE", "description": "País ISO 3166-1 alfa-3 da identidade UAE PASS. A predefinição é ARE, o único país a que presta serviço.\n\n* `ARE` - ARE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum": { "enum": [ "ARE" ], "type": "string", "description": "* `ARE` - ARE" }, "DigitalIdWalletApiFrejaidWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com Freja eID (SWE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryEe9Enum" } ], "default": "SWE", "description": "País ISO 3166-1 alfa-3 da identidade Freja eID. A predefinição é SWE, o único país a que presta serviço.\n\n* `SWE` - SWE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryEe9Enum": { "enum": [ "SWE" ], "type": "string", "description": "* `SWE` - SWE" }, "DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com o Personalausweis (DEU).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum" } ], "default": "DEU", "description": "País ISO 3166-1 alfa-3 da identidade Personalausweis. A predefinição é DEU, o único país a que presta serviço.\n\n* `DEU` - DEU" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum": { "enum": [ "DEU" ], "type": "string", "description": "* `DEU` - DEU" }, "DigitalIdWalletApiFtnWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com Finnish Trust Network (FIN).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartCountryEnum" } ], "default": "FIN", "description": "País ISO 3166-1 alfa-3 da identidade Finnish Trust Network. A predefinição é FIN, o único país a que presta serviço.\n\n* `FIN` - FIN" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiFtnWalletVerificationStartCountryEnum": { "enum": [ "FIN" ], "type": "string", "description": "* `FIN` - FIN" }, "DigitalIdWalletApiIdinWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação iDIN (NLD).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartCountryEnum" } ], "default": "NLD", "description": "País ISO 3166-1 alfa-3 da identidade iDIN. A predefinição é NLD, o único país a que presta serviço.\n\n* `NLD` - NLD" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiIdinWalletVerificationStartCountryEnum": { "enum": [ "NLD" ], "type": "string", "description": "* `NLD` - NLD" }, "DigitalIdWalletApiItsmeWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação itsme (BEL, LUX, NLD).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum" } ], "description": "País ISO 3166-1 alfa-3 da identidade itsme.\n\n* `BEL` - BEL\n* `LUX` - LUX\n* `NLD` - NLD" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "country", "return_url" ] }, "DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum": { "enum": [ "BEL", "LUX", "NLD" ], "type": "string", "description": "* `BEL` - BEL\n* `LUX` - LUX\n* `NLD` - NLD" }, "DigitalIdWalletApiBuypassWalletVerificationStartRequest": { "type": "object", "description": "Inicie uma verificação Buypass ID (NOR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "País ISO 3166-1 alfa-3 da identidade Buypass ID. A predefinição é NOR, o único país a que presta serviço.\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryAfcEnum": { "enum": [ "NOR" ], "type": "string", "description": "* `NOR` - NOR" }, "DigitalIdWalletApiVippsWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com o Vipps (NOR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "País ISO 3166-1 alfa-3 da identidade Vipps. A predefinição é NOR, o único país a que presta serviço.\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiBankidNoWalletVerificationStartRequest": { "type": "object", "description": "Inicie uma verificação BankID (NOR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "País ISO 3166-1 alfa-3 da identidade BankID. A predefinição é NOR, o único país a que presta serviço.\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiBankidSeWalletVerificationStartRequest": { "type": "object", "description": "Inicie uma verificação BankID (SWE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryEe9Enum" } ], "default": "SWE", "description": "País ISO 3166-1 alfa-3 da identidade BankID. A predefinição é SWE, o único país a que presta serviço.\n\n* `SWE` - SWE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiMitidWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com MitID (DNK).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartCountryEnum" } ], "default": "DNK", "description": "País ISO 3166-1 alfa-3 da identidade MitID. A predefinição é DNK, o único país a que presta serviço.\n\n* `DNK` - DNK" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https para o qual o navegador do utilizador regressa após a carteira, com request_id e result anexados. O seu anfitrião tem de estar registado nos allowed_return_hosts da aplicação (ou ser o seu domínio de marca branca). Nunca confie em result por si só: leia o resultado com GET .../verifications/{request_id}/ ou o webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando o utilizador inicia sessão no dispositivo que mostra a sua página, cross_device quando utiliza outro (por exemplo, o código QR do BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiMitidWalletVerificationStartCountryEnum": { "enum": [ "DNK" ], "type": "string", "description": "* `DNK` - DNK" }, "DigitalIdWalletApiWalletCatalogResponse": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletCatalogEntry" } } }, "required": [ "wallets" ] }, "DigitalIdWalletApiWalletCatalogEntry": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string", "description": "O endpoint de início da própria carteira." }, "countries": { "type": "array", "items": { "type": "string" } }, "issuing_authority": { "type": "string" }, "level_of_assurance": { "type": "string", "nullable": true }, "interaction": { "$ref": "#/components/schemas/DigitalIdWalletApiInteractionEnum" }, "required_fields": { "type": "array", "items": { "type": "string" } }, "available": { "type": "boolean", "description": "Se esta aplicação pode iniciá-lo neste ambiente agora. Estar listado não significa estar em produção." } }, "required": [ "available", "countries", "id", "interaction", "issuing_authority", "level_of_assurance", "name", "path", "required_fields" ] }, "CaseDuplicateCaseDuplicate": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "case_number": { "type": "string", "nullable": true, "maxLength": 32 }, "title": { "type": "string", "maxLength": 255 }, "status": { "$ref": "#/components/schemas/CaseDuplicateStatusEnum" }, "priority": { "$ref": "#/components/schemas/CaseDuplicatePriorityEnum" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "title", "uuid" ] }, "CaseDuplicateCaseDuplicatePage": { "type": "object", "properties": { "count": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicate" } } }, "required": [ "count", "next_offset", "results" ] }, "RoutingPublicationPolicyDraftResponse": { "type": "object", "properties": { "draft": { "allOf": [ { "$ref": "#/components/schemas/RoutingPublicationPolicyDraft" } ], "nullable": true } }, "required": [ "draft" ] }, "RoutingPublicationPolicyDraftWriteRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true }, "changes": { "type": "object", "additionalProperties": {} } }, "required": [ "changes", "expected_revision", "expected_version" ] }, "CasePublicationPolicyDraft": { "type": "object", "properties": { "revision": { "type": "string", "format": "uuid" }, "base_version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "changes": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "base_version", "updated_at" ] }, "CasePublicationPolicyDraftPreconditionRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "expected_revision", "expected_version" ] }, "CaseCollaborationCaseNote": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "comment": { "type": "string" }, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "actor_name": { "type": "string", "nullable": true, "maxLength": 255 }, "mentioned_emails": {}, "is_internal": { "type": "boolean" }, "attachments": {}, "tags": {}, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "reply_to": { "allOf": [ { "$ref": "#/components/schemas/CaseCollaborationCaseNoteReply" } ], "nullable": true, "readOnly": true }, "is_pinned": { "type": "boolean" }, "client_reference": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "comment", "created_at", "reply_to", "uuid" ] }, "CustomerMessagingPaginatedCaseRequestList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } } }, "FraudCheckResponse": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid", "description": "Sessão de verificação nativa criada para esta verificação." }, "client_reference": { "type": "string", "nullable": true }, "processing_status": { "$ref": "#/components/schemas/FraudProcessingStatusEnum" }, "profile_id": { "type": "string" }, "profile_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckInput" } }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckModuleReport" } }, "attribute_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "compound_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "risk": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckRisk" } }, "network": { "type": "object", "additionalProperties": {} }, "enrichment": { "type": "object", "additionalProperties": {} }, "identity_relationship": { "allOf": [ { "$ref": "#/components/schemas/FraudCheckIdentityRelationship" } ], "nullable": true }, "recommendation": { "$ref": "#/components/schemas/FraudRecommendationEnum" }, "next_action": { "$ref": "#/components/schemas/FraudNextActionEnum" }, "decision_reasons": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "object", "additionalProperties": {} }, "usage": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "vendor_data": { "type": "string", "nullable": true }, "metadata": { "nullable": true } }, "required": [ "attribute_evidence", "check_id", "client_reference", "completed_at", "compound_evidence", "coverage", "created_at", "decision_reasons", "inputs", "modules", "network", "next_action", "processing_status", "profile_id", "profile_version", "recommendation", "risk", "usage" ] }, "CaseReviewTeam": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" }, "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "CaseActionCaseEntityActionRequest": { "type": "object", "properties": { "client_reference": { "type": "string", "format": "uuid" }, "retry": { "type": "boolean", "default": false }, "action": { "$ref": "#/components/schemas/CaseActionActionEnum" }, "status": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "note": { "type": "string", "nullable": true } }, "required": [ "action" ] }, "RoutingPublicationPaginatedPolicyRevisionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPublicationPolicyRevision" } } } }, "FraudRecommendationEnum": { "enum": [ "approve", "review", "reject" ], "type": "string", "description": "* `approve` - Aprovar\n* `review` - Rever\n* `reject` - Rejeitar" }, "CustomerMessagingCaseRequestPreviewResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "recipient": { "type": "string", "format": "email" }, "sender": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string" }, "requires_user_action": { "type": "boolean" }, "preview_token": { "type": "string" } }, "required": [ "expires_at", "html", "preview_token", "recipient", "request_id", "requires_user_action", "sender", "subject" ] }, "CustomerMessagingCaseCustomerResponseRequest": { "type": "object", "properties": { "full_name": { "type": "string", "minLength": 1, "maxLength": 512 }, "date_of_birth": { "type": "string", "format": "date" }, "file": { "type": "string", "format": "binary", "writeOnly": true } } }, "CaseCollaborationCaseNoteReply": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "actor_name": { "type": "string", "nullable": true }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "comment": { "type": "string", "maxLength": 300 } }, "required": [ "actor_email", "actor_name", "comment", "uuid" ] }, "FraudCheckModuleReport": { "type": "object", "properties": { "module": { "$ref": "#/components/schemas/FraudExcludeEnum" }, "status": { "$ref": "#/components/schemas/FraudStatusEnum" }, "reason": { "type": "string", "nullable": true }, "latency_ms": { "type": "integer" }, "freshness": { "type": "string", "nullable": true }, "billable_units": { "type": "integer" } }, "required": [ "billable_units", "freshness", "latency_ms", "module", "reason", "status" ] }, "CaseDuplicateEntityTypeEnum": { "enum": [ "session", "business_session", "transaction" ], "type": "string", "description": "* `session` - Sessão\n* `business_session` - Sessão de empresa\n* `transaction` - Transação" }, "FraudClientCredentialsErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Authentication failed: Invalid client access token." } } }, "FraudAvailabilityEnum": { "enum": [ "available", "not_requested", "no_reference", "insufficient_history", "unsupported_region", "source_unavailable" ], "type": "string", "description": "* `available` - Disponível\n* `not_requested` - Não solicitado\n* `no_reference` - Sem referência\n* `insufficient_history` - Histórico insuficiente\n* `unsupported_region` - Região não suportada\n* `source_unavailable` - Origem indisponível" }, "CasePublicationPolicyDraftResponse": { "type": "object", "properties": { "draft": { "allOf": [ { "$ref": "#/components/schemas/CasePublicationPolicyDraft" } ], "nullable": true } }, "required": [ "draft" ] }, "FraudCheckAttributesRequest": { "type": "object", "description": "Atributos corroborantes. Todos opcionais; alargam a cobertura do módulo.", "properties": { "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "full_name": { "type": "string", "maxLength": 256 }, "date_of_birth": { "type": "string", "format": "date" }, "nationality": { "type": "string", "maxLength": 3 }, "gender": { "type": "string", "maxLength": 16 }, "address": { "type": "string", "maxLength": 512 }, "city": { "type": "string", "maxLength": 128 }, "state": { "type": "string", "maxLength": 128 }, "postal_code": { "type": "string", "maxLength": 32 } } }, "NetworkNote": { "type": "object", "required": [ "uuid", "actor_email", "comment", "client_reference", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "actor_email": { "type": "string", "format": "email", "readOnly": true, "description": "Autor autenticado, atribuído pelo servidor." }, "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "client_reference": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "CaseActionEntityTypeEnum": { "enum": [ "user", "business" ], "type": "string", "description": "* `user` - user\n* `business` - business" }, "CaseRoutingCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "source", "priority", "tags" ] }, "operator": { "type": "string", "enum": [ "equals", "in", "contains" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "field", "operator", "value" ], "description": "Source e priority suportam equals ou in com valores suportados. Tags suporta contains com uma etiqueta não vazia." }, "RoutingPublicationPolicyRevision": { "type": "object", "properties": { "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "snapshot": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "published_at", "snapshot", "version" ] }, "CasePublicationPolicyRevision": { "type": "object", "properties": { "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "snapshot": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "published_at", "snapshot", "version" ] }, "FraudCheckIdentityRelationship": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/FraudResultEnum" }, "reference_type": { "type": "string" }, "country": { "type": "string" }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" }, "reason_codes": { "type": "array", "items": { "type": "string" } } }, "required": [ "availability", "country", "reason_codes", "reference_type", "result" ] }, "CasePublicationPaginatedPolicyRevisionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CasePublicationPolicyRevision" } } } }, "CaseDuplicateBlankEnum": { "enum": [ "" ] }, "FraudCheckPlan": { "type": "object", "properties": { "profile_id": { "type": "string" }, "profile_version": { "type": "string" }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckPlannedModule" } }, "estimated_price": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "is_sandbox": { "type": "boolean" }, "can_afford": { "type": "boolean" } }, "required": [ "can_afford", "currency", "estimated_price", "is_sandbox", "modules", "profile_id", "profile_version" ] }, "CaseReviewTeamUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" } } }, "RoutingPublicationPolicyDraft": { "type": "object", "properties": { "revision": { "type": "string", "format": "uuid" }, "base_version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "changes": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "base_version", "updated_at" ] }, "FraudCheckRequestRequest": { "type": "object", "properties": { "client_reference": { "type": "string", "minLength": 1, "description": "A sua própria referência para esta verificação. Funciona também como a chave de idempotência: reutilizá-la com o mesmo corpo devolve a verificação original sem executar ou faturar os módulos novamente; reutilizá-la com um corpo diferente devolve 409.", "maxLength": 255 }, "profile": { "type": "string", "minLength": 1, "default": "standard", "description": "ID do perfil de orquestração. O valor predefinido é o perfil `standard` da Didit.", "maxLength": 64 }, "profile_version": { "type": "string", "minLength": 1, "description": "Fixar uma versão congelada do perfil. Assume por predefinição a versão atual do perfil.", "maxLength": 32 }, "subject": { "$ref": "#/components/schemas/FraudCheckSubjectRequest" }, "context": { "$ref": "#/components/schemas/FraudCheckContextRequest" }, "checks": { "$ref": "#/components/schemas/FraudCheckModuleSelectionRequest" }, "vendor_data": { "type": "string", "maxLength": 1000 }, "metadata": {} }, "required": [ "subject" ] }, "CaseDuplicateCaseSubjectInputRequest": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CaseDuplicateTypeEnum" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "type", "uuid" ] }, "CaseReviewTeamMember": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "availability": { "type": "string", "enum": [ "available", "unavailable" ], "default": "available" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "available_from": { "type": "string", "format": "date-time", "nullable": true }, "available_until": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "user_id" ] }, "CaseRoutingPreviewRequest": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "MEDIUM" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 }, "rule_uuid": { "type": "string", "format": "uuid" }, "draft": { "$ref": "#/components/schemas/CaseRoutingRuleCreate" } }, "required": [ "source" ] }, "FraudExcludeEnum": { "enum": [ "normalization", "email_risk", "email_social", "phone_social", "phone_risk", "ip_risk", "database_validation", "networks_same_org", "networks_cross_org", "biometric_identity" ], "type": "string", "description": "* `normalization` - Normalização\n* `email_risk` - Risco de e-mail\n* `email_social` - Redes sociais do e-mail\n* `phone_social` - Redes sociais do telefone\n* `phone_risk` - Risco do telefone\n* `ip_risk` - Risco de IP\n* `database_validation` - Validação de base de dados\n* `networks_same_org` - Redes da mesma organização\n* `networks_cross_org` - Redes entre organizações\n* `biometric_identity` - Identidade biométrica" }, "CaseDuplicateCaseLinkCreateRequest": { "type": "object", "properties": { "entity_type": { "$ref": "#/components/schemas/CaseDuplicateEntityTypeEnum" }, "entity_uuid": { "type": "string", "format": "uuid" } }, "required": [ "entity_type", "entity_uuid" ] }, "CaseDuplicateStatusEnum": { "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "type": "string", "description": "* `OPEN` - Aberto\n* `AWAITING_USER` - A aguardar utilizador\n* `RESOLVED` - Resolvido" }, "FraudBandEnum": { "enum": [ "low", "medium", "high", "unknown" ], "type": "string", "description": "* `low` - Baixo\n* `medium` - Médio\n* `high` - Alto\n* `unknown` - Desconhecido" }, "CaseDuplicatePriorityEnum": { "enum": [ "LOW", "MEDIUM", "HIGH" ], "type": "string", "description": "* `LOW` - Baixo\n* `MEDIUM` - Médio\n* `HIGH` - Alto" }, "FraudStatusEnum": { "enum": [ "planned", "completed", "skipped", "failed" ], "type": "string", "description": "* `planned` - Planeado\n* `completed` - Concluído\n* `skipped` - Ignorado\n* `failed` - Falhou" }, "FraudCheckInput": { "type": "object", "properties": { "reference": { "type": "string", "description": "Nome de utilizador ocultado para o identificador submetido." }, "type": { "$ref": "#/components/schemas/FraudTypeEnum" }, "namespace": { "type": "object", "additionalProperties": {} }, "quality": { "type": "string" }, "normalization": { "type": "object", "additionalProperties": {} }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" } }, "required": [ "availability", "namespace", "normalization", "quality", "reference", "type" ] }, "CustomerMessagingPurposesEnum": { "enum": [ "identity_document", "proof_of_address", "business_document", "confirm_details", "review_in_progress" ], "type": "string", "description": "* `identity_document` - identity_document\n* `proof_of_address` - proof_of_address\n* `business_document` - business_document\n* `confirm_details` - confirm_details\n* `review_in_progress` - review_in_progress" }, "FraudTypeEnum": { "enum": [ "email", "phone", "national_id", "tax_number", "passport_number", "driving_licence_number", "residence_permit_number", "voter_id", "external_id" ], "type": "string", "description": "* `email` - E-mail\n* `phone` - Telefone\n* `national_id` - Documento de identificação nacional\n* `tax_number` - Número de identificação fiscal\n* `passport_number` - Número de passaporte\n* `driving_licence_number` - Número da carta de condução\n* `residence_permit_number` - Número do título de residência\n* `voter_id` - Cartão de eleitor\n* `external_id` - ID externo" }, "CaseDuplicateCaseSubjectInput": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CaseDuplicateTypeEnum" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "type", "uuid" ] }, "CaseReviewTeamCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" } }, "required": [ "name", "members" ] }, "CaseDuplicateCaseDuplicateQueryRequest": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/CaseDuplicateCaseSubjectInputRequest" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/CaseDuplicateCaseLinkCreateRequest" } }, "offset": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0 } } }, "CaseDuplicateResolutionEnum": { "enum": [ "FALSE_POSITIVE", "VALID_THREAT" ], "type": "string", "description": "* `FALSE_POSITIVE` - Falso positivo\n* `VALID_THREAT` - Ameaça válida" }, "CasePublicationPolicyDraftWriteRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true }, "changes": { "type": "object", "additionalProperties": {} } }, "required": [ "changes", "expected_revision", "expected_version" ] }, "FraudCheckSubjectRequest": { "type": "object", "properties": { "selfie": { "type": "string", "minLength": 1, "description": "Selfie em JPEG, PNG ou WebP em Base64, até 6 MB. Sem imagem de referência nem URL.", "maxLength": 8388672 }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckIdentifierRequest" }, "description": "Um ou mais identificadores com tipo. Um é suficiente.", "maxItems": 10, "minItems": 1 }, "attributes": { "$ref": "#/components/schemas/FraudCheckAttributesRequest" } }, "required": [ "identifiers" ] }, "RoutingPublicationRoutingCondition": { "type": "object", "properties": { "field": { "$ref": "#/components/schemas/RoutingPublicationFieldEnum" }, "operator": { "$ref": "#/components/schemas/RoutingPublicationOperatorEnum" }, "value": {} }, "required": [ "field", "operator", "value" ] }, "CaseActionCaseActionReceipt": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "client_reference": { "type": "string", "format": "uuid" }, "action": { "type": "string", "maxLength": 32 }, "status": { "$ref": "#/components/schemas/CaseActionStatusEnum" }, "result": {}, "error": { "type": "string", "maxLength": 255 }, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "attempts": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "action", "client_reference", "created_at", "status", "updated_at", "uuid" ] }, "FraudCheckContextRequest": { "type": "object", "properties": { "ip_address": { "type": "string", "minLength": 1 }, "user_agent": { "type": "string", "maxLength": 512 }, "country": { "type": "string", "description": "País onde o titular alega estar. Apenas contextual - nunca prova de titularidade da identidade.", "maxLength": 3 }, "purpose": { "type": "string", "maxLength": 128 }, "consent_obtained": { "type": "boolean" } } }, "CustomerMessagingCaseCustomerResponseResult": { "type": "object", "properties": { "responded_at": { "type": "string", "format": "date-time" } }, "required": [ "responded_at" ] }, "CustomerMessagingCaseRequestContact": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "verified_at": { "type": "string", "format": "date-time" } }, "required": [ "email", "uuid", "verified_at" ] }, "FraudClientCredentialsForbiddenErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Forbidden - User doesn't have permission" } } }, "CasePublicationAssignmentMethodEnum": { "enum": [ "MANUAL", "AUTOMATIC" ], "type": "string", "description": "* `MANUAL` - Manual\n* `AUTOMATIC` - Automático" }, "CaseDuplicateNullEnum": { "enum": [ null ] }, "CustomerMessagingLanguageEnum": { "enum": [ "en", "es", "pt" ], "type": "string", "description": "* `en` - en\n* `es` - es\n* `pt` - pt" }, "CaseDuplicateCaseFraudSourceContextRequest": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "source_section": { "type": "string", "minLength": 1, "pattern": "^[A-Z][A-Z0-9_:-]{0,63}$" } }, "required": [ "check_id", "request_id", "source_section" ] }, "FraudCheckPlannedModule": { "type": "object", "properties": { "module": { "$ref": "#/components/schemas/FraudExcludeEnum" }, "available": { "type": "boolean" }, "availability_reason": { "type": "string", "nullable": true }, "will_run": { "type": "boolean" }, "selection_reason": { "type": "string", "nullable": true }, "estimated_price": { "type": "string", "nullable": true } }, "required": [ "availability_reason", "available", "estimated_price", "module", "selection_reason", "will_run" ] }, "CustomerMessagingCaseRequestOptions": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestContact" } }, "purposes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingPurposesEnum" } }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingLanguagesEnum" } } }, "required": [ "contacts", "languages", "purposes" ] }, "CaseCollaborationPaginatedCaseNoteList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } } }, "FraudProcessingStatusEnum": { "enum": [ "pending", "running", "completed", "failed" ], "type": "string", "description": "* `pending` - Pendente\n* `running` - Em execução\n* `completed` - Concluído\n* `failed` - Falhado" }, "CasePublicationCaseBlueprint": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "$ref": "#/components/schemas/CasePublicationAssignmentMethodEnum" }, "assignee_pool": {}, "max_active_cases": { "type": "integer", "maximum": 2147483647, "minimum": 0, "nullable": true }, "escalation_enabled": { "type": "boolean" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "escalation_blueprint_name": { "type": "string", "readOnly": true }, "transfer_enabled": { "type": "boolean" }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "four_eyes_checker_blueprint_name": { "type": "string", "readOnly": true }, "require_resolution_note": { "type": "boolean" }, "content_config": {}, "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "default_deadline_hours": { "type": "integer", "maximum": 2147483647, "minimum": 0, "nullable": true }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true, "maxLength": 64 }, "creation_sources": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "readOnly": true }, "receives_escalation_from": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "creation_sources", "escalation_blueprint_name", "four_eyes_checker_blueprint_name", "name", "receives_escalation_from", "updated_at", "uuid" ] }, "CaseRoutingRuleUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "expected_version": { "type": "integer", "minimum": 1, "writeOnly": true, "description": "Versão aberta pelo editor. Quando fornecida, escritas obsoletas devolvem 409 sem alterar a regra." } } }, "CustomerMessagingCaseRequestPreviewRequest": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "allOf": [ { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" } ], "default": "en" } }, "required": [ "contact_id", "purpose" ] }, "CaseDuplicateCaseFraudSourceContext": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "source_section": { "type": "string", "pattern": "^[A-Z][A-Z0-9_:-]{0,63}$" } }, "required": [ "check_id", "request_id", "source_section" ] }, "RoutingPublicationOperatorEnum": { "enum": [ "equals", "in", "contains" ], "type": "string", "description": "* `equals` - igual a\n* `in` - em\n* `contains` - contém" }, "CaseRoutingPreview": { "type": "object", "properties": { "rule_uuid": { "type": "string", "format": "uuid", "nullable": true }, "rule_name": { "type": "string", "nullable": true }, "rule_version": { "type": "integer", "nullable": true }, "blueprint_uuid": { "type": "string", "format": "uuid", "nullable": true }, "team_uuid": { "type": "string", "format": "uuid", "nullable": true }, "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true }, "reason": { "type": "string" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "eligible": { "type": "boolean" }, "active_cases": { "type": "integer", "nullable": true }, "reason": { "type": "string", "nullable": true } } } }, "matched_rules": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "priority": { "type": "integer" } } } } } }, "FraudDimensionEnum": { "enum": [ "identity", "contact", "device_network", "behavioral", "fraud_network" ], "type": "string", "description": "* `identity` - Identidade\n* `contact` - Contacto\n* `device_network` - Rede do dispositivo\n* `behavioral` - Comportamental\n* `fraud_network` - Rede de fraude" }, "FraudBadRequestErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Bad Request - Invalid request data" } } }, "FraudNextActionEnum": { "enum": [ "none", "manual_review", "step_up", "resubmit_capture" ], "type": "string", "description": "* `none` - Nenhum\n* `manual_review` - Revisão manual\n* `step_up` - Escalonamento\n* `resubmit_capture` - Reenviar captura" }, "RoutingPublicationPolicyDraftPreconditionRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "expected_revision", "expected_version" ] }, "FraudCheckRisk": { "type": "object", "properties": { "dimension": { "$ref": "#/components/schemas/FraudDimensionEnum" }, "score": { "type": "integer", "nullable": true }, "band": { "$ref": "#/components/schemas/FraudBandEnum" }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" }, "requested_but_unavailable": { "type": "boolean", "description": "True quando o pedido forneceu tudo o que esta dimensão necessitava e a plataforma mesmo assim não conseguiu responder. Uma verificação deste tipo nunca é recomendada para aprovação com base apenas nas dimensões que responderam." }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "evidence_indexes": { "type": "array", "items": { "type": "integer" } } }, "required": [ "availability", "band", "dimension", "evidence_indexes", "reason_codes", "requested_but_unavailable", "score" ] }, "CaseDuplicateSourceEnum": { "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ], "type": "string", "description": "* `MANUAL` - Manual\n* `AML_SCREENING` - Triagem AML\n* `TRANSACTION_RULE` - Regra de transação\n* `WORKFLOW_BUILDER` - Construtor de fluxos" }, "CaseCollaborationPatchedCaseNoteUpdateRequest": { "type": "object", "properties": { "is_pinned": { "type": "boolean" } } }, "CustomerMessagingPurposeEnum": { "enum": [ "identity_document", "proof_of_address", "business_document", "confirm_details", "review_in_progress" ], "type": "string", "description": "* `identity_document` - identity_document\n* `proof_of_address` - proof_of_address\n* `business_document` - business_document\n* `confirm_details` - confirm_details\n* `review_in_progress` - review_in_progress" }, "CaseDuplicateTypeEnum": { "enum": [ "user", "business" ], "type": "string", "description": "* `user` - user\n* `business` - business" }, "CaseCollaborationCaseNoteCreateRequest": { "type": "object", "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "reply_to": { "type": "string", "format": "uuid", "nullable": true }, "client_reference": { "type": "string", "format": "uuid", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email", "minLength": 1 } }, "is_internal": { "type": "boolean", "default": false }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "comment" ] }, "CustomerMessagingLanguagesEnum": { "enum": [ "en", "es", "pt" ], "type": "string", "description": "* `en` - en\n* `es` - es\n* `pt` - pt" }, "CustomerMessagingCaseRequestConfirmRequest": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "allOf": [ { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" } ], "default": "en" }, "request_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "preview_token": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "contact_id", "expires_at", "preview_token", "purpose", "request_id" ] }, "CaseRoutingRule": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "readOnly": true }, "blueprint_name": { "type": "string", "readOnly": true }, "team_name": { "type": "string", "nullable": true, "readOnly": true } } }, "FraudResultEnum": { "enum": [ "match", "mismatch", "inconclusive", "no_reference" ], "type": "string", "description": "* `match` - Correspondência\n* `mismatch` - Não correspondência\n* `inconclusive` - Inconclusivo\n* `no_reference` - Sem referência" }, "CaseRoutingRuleCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "publish": { "type": "boolean", "writeOnly": true, "description": "Defina como false para guardar um rascunho nunca publicado. O registo permanece inativo na versão 0 até que o rascunho seja explicitamente publicado. Omitir este campo preserva a criação imediata para integrações existentes." } }, "required": [ "name", "conditions", "blueprint" ] }, "FraudCheckIdentifierRequest": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/FraudTypeEnum" } ], "description": "Tipo de identificador. Determina quais os campos do namespace que são obrigatórios.\n\n* `email` - E-mail\n* `phone` - Telefone\n* `national_id` - ID Nacional\n* `tax_number` - Número de Identificação Fiscal\n* `passport_number` - Número de Passaporte\n* `driving_licence_number` - Número da Carta de Condução\n* `residence_permit_number` - Número da Autorização de Residência\n* `voter_id` - Título de Eleitor\n* `external_id` - ID Externo" }, "value": { "type": "string", "minLength": 1, "description": "O valor do identificador, em qualquer formato habitual.", "maxLength": 255 }, "country": { "type": "string", "description": "País emissor ISO-3166 alfa-2 ou alfa-3. Obrigatório para tipos de identificadores governamentais: os mesmos dígitos representam pessoas diferentes em países diferentes.", "maxLength": 3 }, "issuer": { "type": "string", "description": "Autoridade emissora ou emissor subnacional opcional, quando o país, por si só, não for único.", "maxLength": 128 } }, "required": [ "type", "value" ] }, "CaseActionActionEnum": { "enum": [ "set_status", "add_tags", "add_note", "add_to_blocklist" ], "type": "string", "description": "* `set_status` - set_status\n* `add_tags` - add_tags\n* `add_note` - add_note\n* `add_to_blocklist` - add_to_blocklist" }, "CaseActionCaseActionReceiptPage": { "type": "object", "properties": { "count": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" } } }, "required": [ "count", "next_offset", "results" ] }, "CaseActionCaseEntityActionResult": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" }, "entity_type": { "$ref": "#/components/schemas/CaseActionEntityTypeEnum" }, "entity_uuid": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "previous_status": { "type": "string" }, "new_status": { "type": "string" }, "tags_added": { "type": "array", "items": { "type": "string" } }, "comment_uuid": { "type": "string", "format": "uuid" }, "blocklisted": { "type": "array", "items": { "type": "string" } } } }, "CustomerMessagingCaseRequest": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "purpose": { "type": "string", "readOnly": true }, "language": { "type": "string", "readOnly": true }, "recipient": { "type": "string", "format": "email", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time", "readOnly": true }, "actor_email": { "type": "string", "format": "email", "readOnly": true, "nullable": true }, "delivery_status": { "type": "string", "readOnly": true }, "delivered_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "responded_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "response": { "readOnly": true, "nullable": true }, "has_attachment": { "type": "boolean", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "actor_email", "cancelled_at", "created_at", "delivered_at", "delivery_status", "expires_at", "has_attachment", "language", "purpose", "recipient", "responded_at", "response", "uuid" ] }, "CustomerMessagingCaseRequestPublic": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" }, "expires_at": { "type": "string", "format": "date-time" }, "responded_at": { "type": "string", "format": "date-time", "nullable": true }, "copy": { "type": "object", "additionalProperties": {} }, "organization_name": { "type": "string" }, "is_white_label": { "type": "boolean" }, "customization": { "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "copy", "customization", "expires_at", "is_white_label", "language", "organization_name", "purpose", "request_id", "responded_at" ] }, "RoutingPublicationFieldEnum": { "enum": [ "source", "priority", "tags" ], "type": "string", "description": "* `source` - source\n* `priority` - priority\n* `tags` - tags" }, "RoutingPublicationCaseRoutingRule": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPublicationRoutingCondition" } }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "blueprint_name": { "type": "string", "readOnly": true }, "team": { "type": "string", "format": "uuid", "nullable": true }, "team_name": { "type": "string", "readOnly": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "blueprint", "blueprint_name", "conditions", "created_at", "name", "team_name", "updated_at", "uuid", "version" ] }, "CaseActionStatusEnum": { "enum": [ "APPLIED", "FAILED" ], "type": "string", "description": "* `APPLIED` - Aplicado\n* `FAILED` - Falhado" }, "FraudCheckModuleSelectionRequest": { "type": "object", "properties": { "include": { "type": "array", "items": { "$ref": "#/components/schemas/FraudExcludeEnum" } }, "exclude": { "type": "array", "items": { "$ref": "#/components/schemas/FraudExcludeEnum" } } } }, "SignatureField": { "type": "object", "description": "Um campo a colocar num documento de sessão: qual o signatário que o preenche, como e onde. Indique uma posição (`page`, `x`, `y`, `width` e `height`) ou um `anchor`. As posições são frações da página conforme é apresentada, a partir do seu canto superior esquerdo, arredondadas a 4 casas decimais, e o campo deve caber dentro da página. Um documento aceita até 200 campos e um signatário até 500, e cada função com campos num documento necessita de um campo `signature` ou `initials` no mesmo. Consulte [Campos no documento](/pt/core-technology/electronic-signature/overview#campos-no-documento).", "required": [ "key", "type" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "Dá nome ao campo nos resultados e em `sign.field_values`. Único dentro do documento." }, "type": { "type": "string", "enum": [ "signature", "initials", "full_name", "date_signed", "text", "checkbox", "email", "data" ], "description": "O que o campo contém. O signatário aplica a `signature` e as `initials` que adotou, introduz `text`, marca uma `checkbox` e introduz um `email` quando a sessão não tem um e-mail verificado. O Didit preenche `full_name` (o nome verificado), `date_signed` (a data de assinatura, no fuso horário do signatário), `data` (a partir de `prefill`) e um `email` verificado, apresentando-os apenas para leitura. Não existe um tipo de seletor de data: utilize `text`." }, "role": { "type": "string", "enum": [ "verified_person", "legal_representative", "key_people" ], "description": "Quem preenche o campo, com os valores de `signature_signer`. Um passo preenche e carimba apenas os campos do seu próprio signatário. A predefinição é o signatário do passo." }, "page": { "type": "integer", "minimum": 1, "description": "Número da página, de 1 até ao número total de páginas do documento. Para um documento Word, uma página do PDF convertido." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Margem esquerda, como fração da largura da página." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Limite superior, como uma fração da altura da página." }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "Largura, como uma fração da largura da página. Uma assinatura tem pelo menos `0.12` de largura." }, "height": { "type": "number", "minimum": 0.012, "maximum": 1, "description": "Altura, como fração da altura da página. Uma assinatura tem pelo menos `0.035` de altura." }, "anchor": { "$ref": "#/components/schemas/SignatureFieldAnchor" }, "required": { "type": "boolean", "description": "`signature` and `initials` are required unless you set `false`. `full_name`, `date_signed` and `data` are always required. The signer can't finish a document until its required fields have a value, and a required checkbox must be ticked." }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Apresentado ao signatário e nos resultados. Predefinido com base no tipo." }, "placeholder": { "type": "string", "nullable": true, "maxLength": 80, "description": "apenas `text` e `email`." }, "validation": { "$ref": "#/components/schemas/SignatureFieldValidation" }, "prefill": { "type": "string", "nullable": true, "description": "De onde o valor provém: `identity.full_name`, `identity.first_name`, `identity.last_name`, `identity.date_of_birth` (`DD/MM/YYYY`), `identity.nationality`, `identity.document_number`, `identity.document_type`, `identity.issuing_country`, `identity.address`, `contact.email`, `contact.phone`, `company.name`, `company.registration_number`, `company.address`, `company.country` (KYB), `session.vendor_data`, `metadata.` (uma chave dos `metadata` da sessão) ou `api.` (uma chave de `sign.field_values`). Obrigatório para `data`. `full_name` utiliza sempre `identity.full_name` e `email` utiliza `contact.email`. Os valores dos campos `data`, `full_name` e `email` verificado são fixados quando o signatário inicia a assinatura." }, "editable_when_prefilled": { "type": "boolean", "default": false, "description": "apenas `text` e `email`: o signatário pode alterar um valor pré-preenchido." }, "checked_by_default": { "type": "boolean", "default": false, "description": "Apenas `checkbox`: a caixa começa assinalada." }, "date_format": { "type": "string", "enum": [ "DD/MM/YYYY", "MM/DD/YYYY", "YYYY-MM-DD", "D MMMM YYYY" ], "default": "DD/MM/YYYY", "description": "`date_signed` apenas." } } }, "SessionSignDocument": { "type": "object", "required": [ "file_name", "content_base64" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Título apresentado ao signatário. O valor predefinido é `file_name`." }, "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Nome do ficheiro, a terminar em `.pdf` ou `.docx`." }, "content_base64": { "type": "string", "format": "byte", "description": "O ficheiro, codificado em base64. Um PDF pode ter até 20 MB e 100 páginas, sem palavra-passe, scripts ou ficheiros anexados. Um ficheiro Word (`.docx`) pode ter até 20 MB e é convertido para PDF durante a execução do pedido, em no máximo 25 segundos; o PDF fica então com os mesmos limites. Até 5 ficheiros Word por sessão. Um ficheiro Word com macros, alterações registadas, ligações para conteúdo externo ou objetos incorporados é recusado com `signature_document_not_supported`, e um que não possa ser convertido devolve `signature_document_conversion_failed`, cada um com um `reason`." }, "fields": { "type": "array", "description": "Campos opcionais a colocar neste documento, até 200. As páginas e posições referem-se ao PDF, ou ao PDF convertido no caso de um ficheiro Word. Sem campos, o signatário lê o documento e aceita-o.", "items": { "$ref": "#/components/schemas/SignatureField" }, "maxItems": 200 } } }, "SignatureResult": { "type": "object", "description": "O resultado de um signatário para um passo de Assinatura eletrónica. Consulte o [relatório de Assinatura eletrónica](/pt/core-technology/electronic-signature/report-electronic-signature).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Passe como `signature_id` para descarregar o comprovativo deste signatário ou validar a respetiva assinatura." }, "node_id": { "type": "string", "description": "O passo do fluxo que o produziu." }, "status": { "type": "string", "enum": [ "intro", "review", "code", "signing", "signed", "declined" ], "description": "O ponto em que o signatário se encontra no passo. Apenas `signed` significa que os documentos estão assinados." }, "verdict": { "type": "string", "enum": [ "Not Finished", "Approved", "In Review", "Declined" ], "description": "O resultado do passo. Um aviso define-o através da sua regra; as regras de estado personalizadas aplicam-se depois." }, "level": { "type": "string", "enum": [ "simple", "aes", "qes" ], "description": "`simple` (predefinição) ou `aes`. `qes` (Assinatura Eletrónica Qualificada, QES) é um suplemento que ainda não se encontra disponível." }, "format": { "type": "string", "enum": [ "pdf", "pades" ], "description": "`pdf` para uma assinatura Simple, `pades` para Advanced (AES)." }, "profile": { "type": "string", "nullable": true, "description": "`PAdES-B-LT` assim que uma assinatura avançada (AES) for assinada; caso contrário, null." }, "signer": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "O nome do signatário. Verificado (a partir da verificação de identidade aprovada ou da sessão), exceto no nível Simple sem um nome de sessão verificado, onde corresponde ao nome que o signatário introduziu e não é verificado." }, "capacity": { "type": "string", "enum": [ "self", "company" ] }, "company": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true, "description": "O cargo da pessoa-chave, conforme declarado." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "As funções estruturadas da pessoa-chave, conforme declaradas para a empresa." }, "identity_session_id": { "type": "string", "format": "uuid", "description": "A sessão de KYC que verificou o signatário." } } }, "identity_used": { "type": "object", "description": "A identidade verificada na qual a assinatura se baseia. Vazio para uma assinatura Simples sem identidade verificada.", "properties": { "session_id": { "type": "string", "format": "uuid" }, "kyc_id": { "type": "string", "format": "uuid", "nullable": true }, "verified": { "type": "boolean" }, "expected_name": { "type": "string", "nullable": true, "description": "O nome com o qual o signatário tinha de corresponder." } } }, "certificate": { "type": "object", "nullable": true, "description": "O certificado com o qual os documentos foram assinados. `null` até à assinatura e sempre `null` para uma assinatura Simple.", "properties": { "issuer": { "type": "string" }, "issued_to": { "type": "string" }, "serial": { "type": "string", "description": "Número de série, hexadecimal." }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" } } }, "confirmation": { "type": "object", "properties": { "channel": { "type": "string", "nullable": true, "enum": [ "email", "sms" ], "description": "`null` para uma assinatura Simple, que não tem código." }, "destination": { "type": "string", "nullable": true, "description": "O contacto mascarado para o qual o código foi enviado." }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "attempts": { "type": "integer", "description": "Códigos introduzidos, incluindo o correto." } } }, "timestamp": { "type": "object", "nullable": true, "description": "O carimbo de data/hora RFC 3161 na assinatura, emitido pela Didit. `null` até ser assinado e sempre `null` para uma assinatura Simples.", "properties": { "time": { "type": "string", "format": "date-time" }, "qualified": { "type": "boolean", "description": "Sempre `false` para AES." }, "valid": { "type": "boolean" } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "O documento na cópia deste signatário. Utilize-o para descarregar o ficheiro assinado." }, "uuid": { "type": "string", "format": "uuid", "description": "Igual a `id`." }, "title": { "type": "string" }, "file_name": { "type": "string" }, "pages": { "type": "integer", "description": "Páginas do documento assinado. Para Word, do PDF convertido." }, "size_bytes": { "type": "integer" }, "sha256_original": { "type": "string", "description": "SHA-256 do documento tal como foi apresentado ao signatário." }, "sha256_signed": { "type": "string", "nullable": true, "description": "SHA-256 do PDF assinado, após a assinatura." }, "status": { "type": "string", "enum": [ "signed", "declined", "not_signed", "not_reached" ], "description": "`not_signed`: aberto mas não assinado. `not_reached`: nunca foi aberto." }, "opened_at": { "type": "string", "format": "date-time", "nullable": true }, "read_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o signatário chegou ao fim de um documento sem campos, quando o passo o exige." }, "read_to_end": { "type": "boolean" }, "consented_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o signatário concordou com um documento sem campos ou preencheu os campos de um documento com campos." }, "consent": { "type": "boolean" }, "signed_file": { "type": "string", "nullable": true, "description": "Caminho do PDF assinado, assim que estiver assinado. Consulte [Transferir um documento assinado](/pt/sessions-api/electronic-signature/download-signed-document)." }, "mode": { "type": "string", "enum": [ "fields", "read_and_agree" ], "description": "`fields` para um documento com campos, `read_and_agree` para um documento sem campos." }, "source_format": { "type": "string", "enum": [ "pdf", "docx" ], "description": "`pdf`, ou `docx` para um documento Word convertido para PDF pela Didit." }, "conversion": { "type": "object", "nullable": true, "description": "`null` para um PDF. Para um documento Word, o ficheiro original e a conversão.", "properties": { "from": { "type": "string", "enum": [ "docx" ] }, "file_name": { "type": "string", "description": "O nome original do seu ficheiro Word." }, "sha256": { "type": "string", "description": "SHA-256 do seu ficheiro Word original." }, "size_bytes": { "type": "integer", "description": "Tamanho do seu ficheiro Word original." }, "converter": { "type": "string", "description": "Versão do conversor que gerou o PDF." } } }, "fields": { "type": "array", "description": "Campos no documento, com os respetivos valores. Vazio para um documento sem campos.", "items": { "$ref": "#/components/schemas/SignatureFieldResult" } } } } }, "adopted_signature": { "type": "object", "nullable": true, "description": "A assinatura e as iniciais que o signatário adotou para os campos de assinatura e iniciais. `null` até que o signatário adote uma.", "properties": { "method": { "type": "string", "enum": [ "typed", "drawn" ], "description": "`typed`: o nome verificado num estilo de caligrafia. `drawn`: desenhado com o dedo ou com o rato." }, "font": { "type": "string", "nullable": true, "description": "O estilo caligráfico de uma assinatura digitada. `null` quando desenhada à mão." }, "adopted_at": { "type": "string", "format": "date-time" } } }, "electronic_signature_consent_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o signatário concordou, no ecrã de revisão, em assinar eletronicamente os documentos. Definido quando qualquer documento tiver campos." }, "evidence_file": { "type": "string", "nullable": true, "description": "Caminho do PDF de evidências, depois de assinado. Consulte [Descarregar as evidências da assinatura](/pt/sessions-api/electronic-signature/download-evidence)." }, "warnings": { "type": "array", "description": "Avisos gerados para este signatário. Consulte os [Avisos de assinatura eletrónica](/pt/core-technology/electronic-signature/warnings-electronic-signature).", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SIGNATURE_DECLINED", "SIGNATURE_OTP_FAILED", "SIGNATURE_NAME_MISMATCH", "SIGNATURE_IDENTITY_NOT_VERIFIED", "SIGNATURE_DOCUMENT_CHANGED", "SIGNATURE_FIELD_DATA_MISSING" ] }, "node_id": { "type": "string" } } } }, "validation": { "type": "object", "nullable": true, "description": "A última verificação criptográfica dos documentos assinados. `null` até que os documentos sejam assinados. Se a Didit não conseguir confirmar o resultado da assinatura, o valor será `{\"valid\": null, \"reason\": \"signature_provider_outcome_unknown\", \"checked_at\": ...}` e o `status` permanecerá `signing`: trate-o como não assinado.", "properties": { "valid": { "type": "boolean", "nullable": true, "description": "`true` quando todos os documentos são válidos. `null` quando o resultado da assinatura não pôde ser confirmado." }, "reason": { "type": "string", "description": "Definido quando `valid` é `null`: `signature_provider_outcome_unknown`." }, "checked_at": { "type": "string", "format": "date-time" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "checked_at": { "type": "string", "format": "date-time" }, "valid": { "type": "boolean", "description": "`true` quando a assinatura e o carimbo de data/hora são ambos válidos e fidedignos." }, "integrity": { "type": "boolean", "description": "`true` quando o documento não foi alterado desde a assinatura." }, "trusted": { "type": "boolean", "description": "`true` quando a cadeia do certificado de assinatura liga a uma raiz fidedigna." }, "revoked": { "type": "boolean" }, "trusted_list": { "type": "object", "description": "Verificação da Lista Confiável da UE. Para AES: `{\"status\": \"not_applicable\", \"reason\": \"aes_not_qualified\"}`.", "properties": { "status": { "type": "string" }, "reason": { "type": "string" } } }, "certificate": { "type": "object", "nullable": true, "description": "O certificado com o qual os documentos foram assinados. `null` até à assinatura e sempre `null` para uma assinatura Simple.", "properties": { "issuer": { "type": "string" }, "issued_to": { "type": "string" }, "serial": { "type": "string", "description": "Número de série, hexadecimal." }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" } } }, "timestamp": { "type": "object", "nullable": true, "description": "O carimbo de data/hora RFC 3161 na assinatura, emitido pela Didit. `null` até ser assinado e sempre `null` para uma assinatura Simples.", "properties": { "time": { "type": "string", "format": "date-time" }, "qualified": { "type": "boolean", "description": "Sempre `false` para AES." }, "valid": { "type": "boolean" } } } } } } } }, "declined_at": { "type": "string", "format": "date-time", "nullable": true }, "declined_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ] }, "signed_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando a ligação de assinatura deixa de funcionar." }, "email_sent_at": { "type": "string", "format": "date-time", "nullable": true }, "email_unavailable_reason": { "type": "string", "nullable": true }, "ip_address": { "type": "string", "nullable": true, "description": "O endereço IP do signatário quando pediu o seu código." }, "place": { "type": "string", "nullable": true, "description": "Não recolhido: sempre `null`." }, "place_unavailable_reason": { "type": "string", "nullable": true, "enum": [ "not_collected" ] } } }, "SignatureFieldValidation": { "type": "object", "nullable": true, "description": "Regras para o valor de um campo `text`. A pré-visualização da consola, o fluxo de assinatura e a API aplicam as mesmas regras.", "properties": { "kind": { "type": "string", "enum": [ "any", "letters", "number", "email", "pattern" ], "description": "`letters`: letras em qualquer sistema de escrita, espaços, hífenes e apóstrofos. `number`: dígitos com um separador decimal opcional. `pattern`: o valor tem de corresponder a `pattern`." }, "min_length": { "type": "integer", "minimum": 0, "maximum": 500, "description": "De `0` até `max_length`." }, "max_length": { "type": "integer", "minimum": 1, "maximum": 500, "default": 120 }, "pattern": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 200, "description": "Obrigatório com `kind: \"pattern\"`. Uma expressão regular à qual o valor completo deve corresponder. Asserções de contexto e retroreferências não são suportadas." }, "message": { "type": "string", "nullable": true, "maxLength": 120, "description": "Apresentado ao signatário em vez do erro predefinido." } } }, "SignatureFieldAnchor": { "type": "object", "description": "Posiciona um campo com base num excerto de texto no documento em vez de uma posição. O Didit não remove o texto do PDF, pelo que deve escrevê-lo com a mesma cor do fundo da página. Quando o texto não é encontrado, a chamada devolve `400` com `field_anchor_not_found`. Consulte [Posicionar campos por texto-âncora](/pt/sessions-api/create-session#colocar-campos-por-texto-de-âncora).", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Texto pesquisado no documento. No caso de um ficheiro Word, no PDF convertido." }, "occurrence": { "type": "string", "enum": [ "first", "all" ], "default": "first", "description": "`all` coloca um campo por correspondência; as chaves a seguir à primeira recebem `_2`, `_3` e assim sucessivamente." }, "offset_x": { "type": "number", "description": "Adicionado à margem esquerda do texto, como fração da largura da página." }, "offset_y": { "type": "number", "description": "Adicionado à margem superior do texto, como fração da altura da página." }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "Largura do campo, como uma fração da largura da página." }, "height": { "type": "number", "minimum": 0.012, "maximum": 1, "description": "Altura do campo, como fração da altura da página." } } }, "SignatureFieldResult": { "type": "object", "description": "Um campo de um documento assinado, com o respetivo valor na cópia deste signatário. Consulte [Campos](/pt/core-technology/electronic-signature/report-electronic-signature#campos).", "properties": { "key": { "type": "string", "description": "A chave do campo, conforme utilizada em `sign.field_values`." }, "type": { "type": "string", "enum": [ "signature", "initials", "full_name", "date_signed", "text", "checkbox", "email", "data" ] }, "role": { "type": "string", "enum": [ "verified_person", "legal_representative", "key_people" ] }, "label": { "type": "string" }, "page": { "type": "integer", "description": "Número da página, a começar em 1. Para um documento Word, uma página do PDF convertido." }, "x": { "type": "number", "description": "Margem esquerda, como fração da largura da página." }, "y": { "type": "number", "description": "Limite superior, como uma fração da altura da página." }, "width": { "type": "number", "description": "Largura, como uma fração da largura da página." }, "height": { "type": "number", "description": "Altura, como fração da altura da página." }, "required": { "type": "boolean" }, "value": { "nullable": true, "description": "Uma cadeia de carateres para `text`, `email`, `full_name`, `date_signed` e `data`, um booleano para uma `checkbox`, e `true` para uma assinatura ou iniciais aplicadas. `null` quando vazio." }, "display_value": { "type": "string", "nullable": true, "description": "O valor tal como estampado na página: datas no `date_format` do campo, `Yes` ou `No` para uma caixa de seleção, `Signed` para uma assinatura ou rubrica." }, "value_source": { "type": "string", "nullable": true, "enum": [ "signer", "identity", "contact", "company", "session", "metadata", "api", "signing_time", null ], "description": "De onde o valor proveio: `signer` (introduzido, assinalado ou aplicado pelo signatário), `identity` (a identificação verificada), `contact` (o e-mail ou telefone verificado), `company` (a empresa verificada), `session` (`vendor_data`), `metadata`, `api` (`sign.field_values`) ou `signing_time` (a data de assinatura)." }, "filled_at": { "type": "string", "format": "date-time", "nullable": true }, "image_url": { "type": "string", "nullable": true, "description": "Apenas assinatura e rubricas: o caminho da imagem aplicada. Consulte [Descarregar uma imagem de assinatura](/pt/sessions-api/electronic-signature/download-field-image)." }, "value_unavailable_reason": { "type": "string", "nullable": true, "enum": [ "source_empty", null ], "description": "`source_empty` quando um campo pré-preenchido não tinha qualquer valor na sessão e `signature_field_data_missing_action` permitiu que o signatário assinasse mesmo assim." } } }, "VaspDirectoryWidgetEntry": { "type": "object", "description": "O que o seletor de VASP do utilizador final apresenta: quem é a VASP e se é possível contactá-la.", "properties": { "id": { "type": "string", "format": "uuid", "description": "O id da entrada, para GET /v3/travel-rule/vasps/{vasp_id}/." }, "kind": { "type": "string", "enum": [ "directory", "didit" ], "description": "directory para uma entrada do diretório partilhado; didit para um membro da rede Didit." }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string", "description": "Código de país ISO 3166, tal como fornecido pela fonte." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Os domínios web do VASP. Sempre vazios para membros da rede Didit." }, "reachable": { "type": "boolean", "description": "Se a sua aplicação tem uma rota disponível para este VASP ou para uma das suas entidades de uma marca. Sempre true para um membro da rede Didit." } } }, "TravelRuleDataSharingFields": { "type": "object", "description": "Os campos que a Didit envia para o VASP contraparte sobre os seus próprios utilizadores, por tipo de entidade. O `name` e o `wallet_address` são sempre enviados, independentemente do que a lista indicar. Um tipo de entidade que nunca escolheu partilha todos os campos. Uma lista vazia também é uma escolha: partilha apenas o nome e a carteira.", "properties": { "individual": { "type": "array", "items": { "type": "string", "enum": [ "name", "wallet_address", "address", "national_id", "customer_identification", "date_of_birth", "place_of_birth" ] }, "description": "Campos partilhados relativos a uma pessoa singular." }, "company": { "type": "array", "items": { "type": "string", "enum": [ "name", "wallet_address", "address", "national_id", "customer_identification" ] }, "description": "Campos partilhados relativos a uma pessoa coletiva." } } }, "TravelRuleMatchingRules": { "type": "object", "description": "Com que rigor cada campo dos dados da contraparte é comparado com o que possui, por tipo de entidade. Um campo omitido mantém a sua predefinição. `NONE` ignora a comparação, `STRICT` exige exatamente as mesmas palavras, `CONTAINS` aceita um valor cujas palavras apareçam todas no outro, `DEFAULT` é a correspondência de subconjunto padrão e `FUZZY` aceita grafias aproximadas (e, para datas de nascimento, dia e mês trocados).", "properties": { "individual": { "type": "object", "description": "Regras para uma pessoa singular.", "properties": { "name": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Predefinição: segue `name_matching_strictness`." }, "date_of_birth": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Predefinição `NONE`." }, "address": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Predefinição `NONE`." }, "account": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "A carteira através da qual a exchange foi encaminhada. Predefinição `STRICT`." } } }, "company": { "type": "object", "description": "Regras para uma pessoa coletiva.", "properties": { "name": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Predefinição: segue `name_matching_strictness`." }, "address": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Predefinição `NONE`." }, "account": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "A carteira através da qual a exchange foi encaminhada. Predefinição `STRICT`." } } } } }, "TravelRuleDataMatch": { "type": "object", "nullable": true, "description": "Comparação campo a campo dos dados das partes da transferência com o que a outra parte sabe sobre o titular da carteira. Indica campos e resultados, nunca valores, para que permaneça legível enquanto os dados da contraparte estiverem mascarados. Null até que uma comparação tenha sido executada.", "properties": { "matched": { "type": "boolean", "description": "True quando nenhum campo comparado difere." }, "mismatched_fields": { "type": "array", "items": { "type": "string", "enum": [ "name", "date_of_birth", "address", "account" ] }, "description": "Os campos que diferem." }, "fields": { "type": "object", "description": "Uma entrada por campo comparado para o tipo de entidade da parte (`name`, `date_of_birth`, `address`, `account`; uma empresa não tem `date_of_birth`).", "additionalProperties": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "matched", "mismatched", "not_compared" ], "description": "`not_compared` quando a regra é `NONE` ou um dos lados não tem valor para o campo." }, "strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ] } } } } } }, "TravelRuleDataUnmasked": { "type": "object", "nullable": true, "description": "Registo de auditoria do momento em que os dados da contraparte foram desmascarados. Nulo enquanto os dados ainda estiverem mascarados e para transferências de saída.", "properties": { "at": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "enum": [ "ownership_confirmed", "wallet_proof", "address_book_match", "own_verified_wallet", "inquiry_approved", "known_payment_method", "travel_address" ], "description": "O que confirmou a propriedade: ownership_confirmed (a sua confirmação através da consola ou da API), wallet_proof (uma prova de carteira no widget, ou uma transferência de entrada INTERNAL, definida quando é criada), address_book_match (uma carteira verificada do livro de endereços), own_verified_wallet (a carteira própria verificada do seu utilizador), inquiry_approved (a sua aprovação de um pedido TRP de entrada ou de uma mensagem GTR ou Sygna), known_payment_method (uma carteira com a qual o seu utilizador já pagou) ou travel_address (o Travel Address por carteira que nomeou a carteira)." }, "actor": { "type": "string", "description": "Quem o confirmou: o e-mail do utilizador da consola ou a etiqueta da chave de API. Em branco para uma decisão automática." } } }, "TravelRuleMessageAttachment": { "type": "object", "nullable": true, "description": "O documento anexado a uma mensagem, armazenado como qualquer outro documento de transação.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "uploaded_by": { "type": "string", "nullable": true, "description": "Quem o anexou. No portal de recolha, um ficheiro enviado por si mostra o nome do seu VASP, nunca a pessoa ou a chave de API associada." }, "created_at": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_url": { "type": "string", "nullable": true, "description": "URL de transferência com limite temporal." }, "original_filename": { "type": "string" }, "file_size": { "type": "integer" } } } } } }, "TravelRuleMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "MESSAGE", "DOCUMENT_REQUEST" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "`OUTBOUND` é o que o próprio lado do leitor enviou. No portal de recolha, a direção é definida a partir do lado da contraparte." }, "author": { "type": "string", "description": "Quem o escreveu do seu próprio lado: o e-mail de um utilizador da consola ou uma etiqueta de chave de API, ou o nome do outro VASP." }, "body": { "type": "string" }, "requested_documents": { "type": "array", "items": { "type": "string" }, "description": "O que um DOCUMENT_REQUEST solicita, pelas palavras do requerente." }, "reply_to": { "type": "string", "format": "uuid", "nullable": true }, "fulfilled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Definido num DOCUMENT_REQUEST assim que uma resposta ao mesmo incluir um documento." }, "attachment": { "$ref": "#/components/schemas/TravelRuleMessageAttachment" }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleMessageCreateRequest": { "type": "object", "description": "Envie como JSON, ou como multipart/form-data com os anexos em `files`.", "properties": { "kind": { "type": "string", "enum": [ "MESSAGE", "DOCUMENT_REQUEST" ], "default": "MESSAGE" }, "body": { "type": "string", "maxLength": 5000, "description": "Obrigatório para uma MESSAGE, a menos que um ficheiro esteja anexado." }, "requested_documents": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 10, "description": "Obrigatório (pelo menos um) para um DOCUMENT_REQUEST, e só é permitido nesse caso." }, "reply_to": { "type": "string", "format": "uuid", "nullable": true, "description": "Uma mensagem da mesma transferência. Uma resposta que inclua um documento satisfaz o pedido de documento a que responde." }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 5, "description": "Apenas multipart. Até 5 ficheiros de 10 MB cada." } } }, "SessionDeletionJob": { "type": "object", "description": "Uma eliminação em lote de sessões em execução em segundo plano: progresso e contagens por resultado, nunca quais sessões foram eliminadas.", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Faça polling de `GET /v3/sessions/delete/{job_id}/` com este id." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ], "description": "`PENDING`: aceite, ainda não iniciado. `PROCESSING`: a eliminar; `processed` e `outcomes` estão a ser atualizados. `COMPLETED`: todas as sessões selecionadas foram contabilizadas. `FAILED`: a tarefa parou prematuramente; consulte `error`." }, "total": { "type": "integer", "description": "Sessões selecionadas quando a eliminação foi pedida." }, "processed": { "type": "integer", "description": "Sessões que a tarefa concluiu até ao momento." }, "outcomes": { "type": "object", "description": "Quantas sessões terminaram em cada resultado. Todas as chaves estão sempre presentes.", "properties": { "deleted": { "type": "integer", "description": "Sessões eliminadas juntamente com o seu embedding facial." }, "none": { "type": "integer", "description": "Sessões eliminadas que não tinham embedding facial." }, "retained_with_user": { "type": "integer", "description": "Sessões eliminadas enquanto um template biométrico sem imagem foi retido para o respetivo utilizador, a pedido ou de acordo com a política da aplicação." }, "ineligible_no_vendor_user": { "type": "integer", "description": "Sessões eliminadas, com o seu embedding facial, porque a conservação de dados foi solicitada mas não tinham um utilizador associado." }, "failed_retryable": { "type": "integer", "description": "Sessões reportadas como não eliminadas. Uma tarefa tenta novamente um grupo que não conseguiu eliminar por si própria em vez de o contabilizar aqui." }, "already_deleted": { "type": "integer", "description": "Sessões selecionadas que já tinham sido eliminadas, por exemplo por outro pedido, quando a tarefa as alcançou." } } }, "deleted_child_verifications": { "type": "integer", "description": "Verificações criadas pelas verificações de empresas eliminadas, eliminadas em conjunto com as mesmas. É sempre `0` para uma tarefa iniciada por `POST /v3/sessions/delete/`, que elimina apenas sessões de KYC." }, "error": { "type": "string", "nullable": true, "description": "`null` a menos que `status` seja `FAILED`; nesse caso, o motivo pelo qual a eliminação parou. As sessões que a tarefa ainda não tinha alcançado permanecem intactas: repita o pedido para as eliminar." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a eliminação foi pedida." }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o trabalho terminou; `null` enquanto estiver em execução." } } }, "EntityStatusUpdateRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Novo estado do ciclo de vida. `BLOCKED` também adiciona o `vendor_data` à lista de bloqueio do sistema." } } }, "AMLMonitoringToggleResult": { "oneOf": [ { "type": "object", "required": [ "users_total", "already_enabled", "with_existing_aml", "needing_screening", "skipped_no_identity_data", "skipped_blocked", "estimated_screening_cost_usd", "estimated_annual_monitoring_cost_usd", "balance_sufficient", "unmatched" ], "description": "Pré-visualização do custo. Devolvida diretamente quando estimate_only é true (nada é gravado).", "properties": { "users_total": { "type": "integer", "description": "Perfis correspondidos pela seleção." }, "already_enabled": { "type": "integer", "description": "Perfis já monitorizados (nada a fazer ao ativar; são estes que a desativação desliga)." }, "with_existing_aml": { "type": "integer", "description": "Perfis cuja triagem AML existente será alterada para monitorizada (sem nova triagem)." }, "needing_screening": { "type": "integer", "description": "Perfis sem qualquer triagem AML que serão submetidos a triagem primeiro (faturada como uma triagem AML normal)." }, "skipped_no_identity_data": { "type": "integer", "description": "Perfis que não podem ser submetidos a triagem porque faltam dados de identidade." }, "skipped_blocked": { "type": "integer", "description": "Utilizadores bloqueados que serão ignorados (sempre 0 para empresas)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Custo único das novas triagens." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Custo anual de monitorização dos perfis que passarão a ser monitorizados." }, "balance_sufficient": { "type": "boolean", "description": "Se o saldo da organização cobre a triagem mais o primeiro ano de monitorização." }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "Identificadores do pedido que não corresponderam a nenhum perfil nesta aplicação, exatamente como foram enviados." } } }, { "type": "object", "required": [ "job_id", "status", "is_enabled", "target_type", "total", "processed", "outcomes", "results", "error", "created_at", "completed_at", "estimate", "unmatched" ], "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "true quando o trabalho ativa a monitorização, false quando a desativa." }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "Qual a família de perfis que a tarefa ativa/desativa." }, "total": { "type": "integer", "description": "Perfis que a tarefa processa." }, "processed": { "type": "integer", "description": "Perfis processados até ao momento." }, "outcomes": { "type": "object", "description": "Contadores de resultados por registo. Cada perfil selecionado corresponde exatamente a um contador; nada é ignorado silenciosamente.", "properties": { "enabled": { "type": "integer", "description": "Monitorização ativada numa triagem AML existente." }, "screened_and_enabled": { "type": "integer", "description": "Foi criada uma nova triagem AML (faturada) e ativada a monitorização na mesma." }, "already_enabled": { "type": "integer", "description": "A monitorização já se encontrava ativa; nada foi alterado e nada foi faturado." }, "disabled": { "type": "integer", "description": "Monitorização desativada em todas as triagens AML do perfil." }, "skipped_no_identity_data": { "type": "integer", "description": "Ignorado: o perfil não tem o nome completo, a data de nascimento e o país (utilizadores) ou um nome (empresas) necessários para a triagem." }, "skipped_blocked": { "type": "integer", "description": "Ignorado: o utilizador está bloqueado." }, "skipped_sandbox": { "type": "integer", "description": "Ignorado: aplicação em sandbox, nenhuma triagem é criada." }, "failed_provider": { "type": "integer", "description": "Não foi possível concluir a triagem; tente novamente mais tarde." }, "failed_insufficient_balance": { "type": "integer", "description": "O saldo esgotou-se enquanto a tarefa estava em execução." } } }, "results": { "type": "array", "description": "Uma entrada por perfil processado, pela ordem de processamento. Aumenta enquanto a tarefa é executada; completa assim que o estado for COMPLETED. Registada para tarefas iniciadas através da API.", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "ID interno da Didit do perfil." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu próprio identificador para o perfil." }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "Mensagem genérica de falha quando o estado é FAILED; a causa detalhada é mantida do lado da plataforma." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "estimate": { "type": "object", "description": "Pré-visualização do custo. Devolvida diretamente quando estimate_only é true (nada é gravado).", "properties": { "users_total": { "type": "integer", "description": "Perfis correspondidos pela seleção." }, "already_enabled": { "type": "integer", "description": "Perfis já monitorizados (nada a fazer ao ativar; são estes que a desativação desliga)." }, "with_existing_aml": { "type": "integer", "description": "Perfis cuja triagem AML existente será alterada para monitorizada (sem nova triagem)." }, "needing_screening": { "type": "integer", "description": "Perfis sem qualquer triagem AML que serão submetidos a triagem primeiro (faturada como uma triagem AML normal)." }, "skipped_no_identity_data": { "type": "integer", "description": "Perfis que não podem ser submetidos a triagem porque faltam dados de identidade." }, "skipped_blocked": { "type": "integer", "description": "Utilizadores bloqueados que serão ignorados (sempre 0 para empresas)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Custo único das novas triagens." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Custo anual de monitorização dos perfis que passarão a ser monitorizados." }, "balance_sufficient": { "type": "boolean", "description": "Se o saldo da organização cobre a triagem mais o primeiro ano de monitorização." } } }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "Identificadores do pedido que não corresponderam a nenhum perfil nesta aplicação, exatamente como foram enviados. Não fazem parte da tarefa." } } } ] }, "AMLMonitoringJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "true quando o trabalho ativa a monitorização, false quando a desativa." }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "Qual a família de perfis que a tarefa ativa/desativa." }, "total": { "type": "integer", "description": "Perfis que a tarefa processa." }, "processed": { "type": "integer", "description": "Perfis processados até ao momento." }, "outcomes": { "type": "object", "description": "Contadores de resultados por registo. Cada perfil selecionado corresponde exatamente a um contador; nada é ignorado silenciosamente.", "properties": { "enabled": { "type": "integer", "description": "Monitorização ativada numa triagem AML existente." }, "screened_and_enabled": { "type": "integer", "description": "Foi criada uma nova triagem AML (faturada) e ativada a monitorização na mesma." }, "already_enabled": { "type": "integer", "description": "A monitorização já se encontrava ativa; nada foi alterado e nada foi faturado." }, "disabled": { "type": "integer", "description": "Monitorização desativada em todas as triagens AML do perfil." }, "skipped_no_identity_data": { "type": "integer", "description": "Ignorado: o perfil não tem o nome completo, a data de nascimento e o país (utilizadores) ou um nome (empresas) necessários para a triagem." }, "skipped_blocked": { "type": "integer", "description": "Ignorado: o utilizador está bloqueado." }, "skipped_sandbox": { "type": "integer", "description": "Ignorado: aplicação em sandbox, nenhuma triagem é criada." }, "failed_provider": { "type": "integer", "description": "Não foi possível concluir a triagem; tente novamente mais tarde." }, "failed_insufficient_balance": { "type": "integer", "description": "O saldo esgotou-se enquanto a tarefa estava em execução." } } }, "results": { "type": "array", "description": "Uma entrada por perfil processado, pela ordem de processamento. Aumenta enquanto a tarefa é executada; completa assim que o estado for COMPLETED. Registada para tarefas iniciadas através da API.", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "ID interno da Didit do perfil." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu próprio identificador para o perfil." }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "Mensagem genérica de falha quando o estado é FAILED; a causa detalhada é mantida do lado da plataforma." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "estimate": { "type": "object", "description": "Pré-visualização do custo. Devolvida diretamente quando estimate_only é true (nada é gravado).", "properties": { "users_total": { "type": "integer", "description": "Perfis correspondidos pela seleção." }, "already_enabled": { "type": "integer", "description": "Perfis já monitorizados (nada a fazer ao ativar; são estes que a desativação desliga)." }, "with_existing_aml": { "type": "integer", "description": "Perfis cuja triagem AML existente será alterada para monitorizada (sem nova triagem)." }, "needing_screening": { "type": "integer", "description": "Perfis sem qualquer triagem AML que serão submetidos a triagem primeiro (faturada como uma triagem AML normal)." }, "skipped_no_identity_data": { "type": "integer", "description": "Perfis que não podem ser submetidos a triagem porque faltam dados de identidade." }, "skipped_blocked": { "type": "integer", "description": "Utilizadores bloqueados que serão ignorados (sempre 0 para empresas)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Custo único das novas triagens." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Custo anual de monitorização dos perfis que passarão a ser monitorizados." }, "balance_sufficient": { "type": "boolean", "description": "Se o saldo da organização cobre a triagem mais o primeiro ano de monitorização." } } }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "Identificadores do pedido que não corresponderam a nenhum perfil nesta aplicação, exatamente como foram enviados. Não fazem parte da tarefa." } } }, "OngoingMonitoringToggleRequest": { "type": "object", "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean", "description": "true para ativar a monitorização, false para a desativar." }, "estimate_only": { "type": "boolean", "default": false, "description": "Quando for true, devolve a estimativa de custos e não realiza gravações." }, "update_all": { "type": "boolean", "default": false, "description": "Aplicar a todas as entidades da aplicação (delimitado pelos parâmetros filter_* quando presentes)." }, "filter_search": { "type": "string" }, "filter_status": { "type": "array", "items": { "type": "string" } }, "filter_country": { "type": "string" }, "filter_date_from": { "type": "string", "format": "date" }, "filter_date_to": { "type": "string", "format": "date" }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Entidades a alternar. Obrigatório, exceto se update_all for verdadeiro." } } }, "OngoingMonitoringJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean" }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "outcomes": { "type": "object", "description": "Contadores de resultados por entidade. Nada é ignorado silenciosamente: cada entidade solicitada corresponde exatamente a um contador.", "properties": { "enabled": { "type": "integer", "description": "Monitorização ativada numa triagem AML existente." }, "screened_and_enabled": { "type": "integer", "description": "Foi criada uma nova triagem AML (faturada) e ativada a monitorização." }, "already_enabled": { "type": "integer", "description": "A monitorização já se encontrava ativa (as linhas duplicadas legadas são consolidadas)." }, "disabled": { "type": "integer", "description": "Monitorização desativada em todas as linhas de AML da entidade." }, "skipped_no_identity_data": { "type": "integer", "description": "Ignorado: não há nome completo + data de nascimento + país disponíveis para triagem." }, "skipped_blocked": { "type": "integer", "description": "Ignorado: o utilizador está bloqueado." }, "skipped_sandbox": { "type": "integer", "description": "Ignorado: aplicação em sandbox." }, "failed_provider": { "type": "integer", "description": "A chamada ao fornecedor de triagem falhou." }, "failed_insufficient_balance": { "type": "integer", "description": "O saldo esgotou-se a meio da tarefa." } } }, "error": { "type": "string", "nullable": true }, "estimate": { "type": "object", "description": "Pré-visualização do custo. Devolvida diretamente quando estimate_only é true (nenhuma escrita é efetuada).", "properties": { "users_total": { "type": "integer", "description": "Entidades na seleção." }, "already_enabled": { "type": "integer" }, "with_existing_aml": { "type": "integer", "description": "Entidades cuja triagem AML existente passará a ser monitorizada." }, "needing_screening": { "type": "integer", "description": "Entidades sem qualquer triagem AML que serão submetidas a triagem primeiro (faturadas)." }, "skipped_no_identity_data": { "type": "integer" }, "skipped_blocked": { "type": "integer" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2 }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07 }, "balance_sufficient": { "type": "boolean" } } } } }, "OngoingMonitoringToggleResult": { "oneOf": [ { "type": "object", "description": "Pré-visualização do custo. Devolvida diretamente quando estimate_only é true (nenhuma escrita é efetuada).", "properties": { "users_total": { "type": "integer", "description": "Entidades na seleção." }, "already_enabled": { "type": "integer" }, "with_existing_aml": { "type": "integer", "description": "Entidades cuja triagem AML existente passará a ser monitorizada." }, "needing_screening": { "type": "integer", "description": "Entidades sem qualquer triagem AML que serão submetidas a triagem primeiro (faturadas)." }, "skipped_no_identity_data": { "type": "integer" }, "skipped_blocked": { "type": "integer" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2 }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07 }, "balance_sufficient": { "type": "boolean" } } }, { "$ref": "#/components/schemas/OngoingMonitoringJob" } ] }, "CaseBlueprintPresetInstallResult": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "string" } } } }, "CaseBulkUpdateResult": { "type": "object", "properties": { "updated": { "type": "integer" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "case_uuid": { "type": "string", "format": "uuid" }, "detail": { "type": "string" } } } } } }, "RegulatoryReportList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Número de linhas correspondentes, limitado a 100 por motivos de desempenho." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "EntityNetworkMembershipList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntityNetworkMembership" } } } }, "SessionDecision": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "O identificador único da sessão." }, "session_kind": { "type": "string", "enum": [ "user", "business" ], "description": "Discriminador que indica se esta é uma sessão de Verificação de utilizadores (KYC) ou de Verificação de empresas (KYB). Quando for `user`, aplicam-se os arrays de funcionalidades de KYC (`id_verifications`, `nfc_verifications`, `liveness_checks`, `face_matches`, `poa_verifications`, `document_ai_documents`, `database_validations`, ...) e os arrays da empresa estão ausentes. Quando for `business`, o payload inclui `registry_checks`, `document_verifications`, `key_people_checks`, além dos arrays partilhados (`aml_screenings`, `phone_verifications`, `email_verifications`, `ip_analyses`, `questionnaire_responses`). **Omitido quando `include=events` é transmitido** — a estrutura de eventos apenas existe para sessões de utilizador, pelo que o discriminador é removido nessa variante." }, "shared_from_session": { "type": "string", "format": "uuid", "nullable": true, "description": "Para uma sessão clonada com `POST /v3/session/import-shared/`: o `session_id` da sessão original na aplicação de origem. `null` para qualquer outra sessão. Omitido quando `include=events` é especificado." }, "shared_from_session_number": { "type": "integer", "nullable": true, "description": "`session_number` da sessão de origem quando esta sessão foi importada de outra aplicação da sua organização. Caso contrário, `null`." }, "session_number": { "type": "integer", "description": "O número da sessão.", "nullable": true }, "session_url": { "type": "string", "format": "uri", "description": "O URL da sessão.", "nullable": true }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Awaiting User", "In Review", "Approved", "Declined", "Resubmitted", "Expired", "Kyc Expired", "Abandoned" ], "description": "Estado global do ciclo de vida da sessão — o resultado agregado do fluxo. Os valores finais são `Approved`, `Declined`, `In Review`, `Expired`, `Kyc Expired` e `Abandoned`; `Not Started`, `In Progress`, `Awaiting User` e `Resubmitted` indicam que a sessão ainda está a avançar no fluxo." }, "status_override": { "type": "object", "nullable": true, "description": "Presente quando um revisor definiu `status` manualmente. `null` quando o estado é automático. Utilize-o para distinguir uma aprovação manual de uma automática.", "properties": { "overridden_at": { "type": "string", "format": "date-time", "nullable": true }, "automatic_status": { "type": "string", "nullable": true, "description": "O estado determinado pelas próprias verificações da plataforma." } } }, "decision_trace": { "type": "object", "description": "Como o estado foi alcançado: quem o definiu e que avisos o originaram.", "properties": { "status": { "type": "string", "description": "O estado da sessão." }, "decided_by": { "type": "string", "nullable": true, "enum": [ "manual", "automatic", "investigator", null ], "description": "Quem definiu o estado. `null` enquanto a sessão não estiver decidida." }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "automatic_status": { "type": "string", "nullable": true, "description": "O que as próprias verificações da plataforma concluem, o que difere de `status` após uma decisão manual." }, "terminal_node_id": { "type": "string", "nullable": true, "description": "O nó de estado do fluxo que terminou a sessão, quando um deles tiver terminado a sessão." }, "actor": { "type": "object", "nullable": true, "description": "O revisor responsável por uma decisão manual.", "properties": { "user": { "type": "string", "nullable": true }, "actor_type": { "type": "string", "nullable": true } } }, "warning_counts": { "type": "object", "description": "Avisos por `log_type` (`error`, `warning`, `information`) e `total`.", "additionalProperties": { "type": "integer" } }, "status_warnings": { "type": "array", "description": "Os avisos que definem o estado `Declined` ou `In Review`.", "items": { "type": "object", "properties": { "risk": { "type": "string" }, "feature": { "type": "string", "nullable": true }, "node_id": { "type": "string", "nullable": true }, "log_type": { "type": "string", "nullable": true }, "check_status": { "type": "string", "nullable": true }, "source": { "type": "string", "description": "A lista do payload de onde o aviso teve origem, por exemplo `id_verifications`." }, "short_description": { "type": "string", "nullable": true } } } } } }, "linked_records": { "type": "object", "nullable": true, "description": "Um resumo de outros registos associados à sessão. `null` quando não há nada a apresentar e para fluxos que declarem um padrão de garantia de idade.", "properties": { "same_face": { "type": "object", "nullable": true, "description": "Outras pessoas cuja face coincidiu com uma das pesquisas faciais desta sessão.", "properties": { "count": { "type": "integer" }, "best_match": { "type": "object", "nullable": true, "properties": { "session_id": { "type": "string", "format": "uuid", "nullable": true }, "session_number": { "type": "integer", "nullable": true }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true }, "similarity_percentage": { "type": "number", "nullable": true } } } } }, "earlier_verifications": { "type": "object", "nullable": true, "properties": { "count": { "type": "integer" }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true } } }, "networks": { "type": "object", "nullable": true, "properties": { "count": { "type": "integer" }, "open": { "type": "integer" }, "dismissed": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "network_id": { "type": "string", "format": "uuid" }, "display_number": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "status": { "type": "string" }, "risk_score": { "type": "number", "nullable": true } } } } } } } }, "workflow_id": { "type": "string", "format": "uuid", "description": "Identificador estável do grupo de fluxos que gerou esta sessão. Os fluxos são versionados — este valor identifica o fluxo em si, e não a versão específica.", "nullable": true }, "features": { "type": "array", "items": { "type": "string", "description": "A funcionalidade da sessão." }, "description": "Lista de funcionalidades de verificação configuradas para esta sessão, como nomes de apresentação: `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACE_MATCH`, `POA`, `PHONE`, `EMAIL_VERIFICATION`, `AML`, `IP_ANALYSIS`, `DATABASE_VALIDATION`, `QUESTIONNAIRE`, `AGE_ESTIMATION`, `FACE_SEARCH`, `GEOLOCATION` (verificação de localização) (as sessões de Verificação de empresas (KYB) utilizam o conjunto de funcionalidades de KYB: `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`, `AML`, `PHONE`, `EMAIL_VERIFICATION`, `IP_ANALYSIS`, `QUESTIONNAIRE`). Com `include=events`, cada entrada torna-se um objeto `{feature, node_id}` em vez de uma string simples, e a funcionalidade de e-mail é renomeada: aparece como `EMAIL` no modo de eventos em vez do `EMAIL_VERIFICATION` aqui utilizado." }, "vendor_data": { "type": "string", "description": "Os dados de fornecedor da sessão.", "nullable": true }, "metadata": { "type": "object", "description": "Os metadados da sessão.", "nullable": true }, "expected_details": { "type": "object", "description": "Dados esperados fornecidos na criação da sessão — utilizados para validação cruzada com os dados extraídos (KYC) ou para pré-preencher a pesquisa no registo de empresas (KYB). Devolve exatamente as mesmas chaves que foram fornecidas; `null` quando nenhum dado foi fornecido. As sessões de KYC contêm os campos da pessoa; as sessões de empresas (KYB) contêm `company_name`, `registry_country` e `registration_number`.", "properties": { "first_name": { "type": "string", "description": "Primeiro nome do utilizador. Por exemplo, `John`." }, "last_name": { "type": "string", "description": "Apelido do utilizador. Por exemplo, `Doe`." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data de nascimento do utilizador no formato: YYYY-MM-DD. Por exemplo, `1990-05-15`." }, "gender": { "type": "string", "nullable": true, "enum": [ "M", "F" ], "default": null, "description": "Género do utilizador. Deve ser 'M', 'F' ou null." }, "nationality": { "type": "string", "description": "Código de país ISO 3166-1 alfa-3 que representa o país de origem do requerente. Por exemplo, `USA`." }, "country": { "type": "string", "description": "Código de país ISO 3166-1 alfa-3 que representa o país do documento de Comprovativo de morada, ou o país do documento de identificação do requerente, que pode diferir da nacionalidade. Por exemplo, `GBR`." }, "address": { "type": "string", "description": "A morada num formato legível por humanos, incluindo o máximo de informação possível. Por exemplo, `123 Main St, San Francisco, CA 94105, USA`." }, "identification_number": { "type": "string", "description": "O número de documento, número de identificação pessoal ou número de identificação fiscal do utilizador. Por exemplo, `123456789`." }, "ip_address": { "type": "string", "format": "ipv4", "description": "Endereço IP previsto para a sessão. Se o endereço IP real diferir deste valor, será registado um aviso. Por exemplo, `192.168.1.100`." }, "expected_document_types": { "type": "array", "description": "Tipos de documento aos quais o passo de verificação de identidade foi restrito na criação da sessão. Vazio/não definido significa sem restrição. Códigos: `P` (passaporte), `ID` (documento de identificação nacional), `DL` (carta de condução), `RP` (autorização de residência), `HIC` (cartão de seguro de saúde), `TC` (cartão fiscal), `SSC` (cartão de segurança social).", "items": { "type": "string", "enum": [ "P", "ID", "DL", "RP", "HIC", "TC", "SSC" ] } }, "id_country": { "type": "string", "nullable": true, "description": "País emissor previsto para o documento de identificação (ISO 3166-1 alfa-3), quando restrito no momento da criação.", "example": "ESP" }, "poa_country": { "type": "string", "nullable": true, "description": "País previsto do documento de Comprovativo de morada (ISO 3166-1 alfa-3), quando restrito no momento da criação.", "example": "ESP" }, "company_name": { "type": "string", "description": "Nome legal esperado da empresa. Apenas para sessões de empresas (KYB)." }, "registry_country": { "type": "string", "description": "País do registo esperado como `XX` ou `XX-YY` (ISO 3166-1 alfa-2, opcionalmente com uma subdivisão ISO 3166-2 para registos a nível estadual, por exemplo, `US-CA`). Apenas para sessões de Business (KYB)." }, "registration_number": { "type": "string", "description": "Número de registo da empresa previsto. Apenas sessões de empresas (KYB)." } }, "nullable": true }, "contact_details": { "type": "object", "description": "Detalhes de contacto fornecidos quando a sessão foi criada (utilizados para e-mails de notificação, verificação pré-preenchida de telefone/e-mail e idioma de comunicação). `null` quando não foi fornecido nem um e-mail nem um número de telefone.", "properties": { "email": { "type": "string", "description": "Endereço de e-mail do utilizador (ex.: \"john.doe@example.com\") que será utilizado durante o passo de Verificação de e-mail. Se não for fornecido, o utilizador terá de o indicar durante o fluxo de verificação." }, "email_lang": { "type": "string", "description": "Código de idioma (ISO 639-1) para notificações por e-mail. Controla o idioma de todas as comunicações por e-mail (por exemplo, \"en\", \"es\", \"fr\")." }, "send_notification_emails": { "type": "boolean", "default": false, "description": "Se for true e for fornecido um e-mail, a Didit envia o e-mail inicial \"Verifique a sua identidade\" de forma assíncrona quando a sessão de Verificação de utilizadores (KYC) ou de Verificação de empresas (KYB) é criada. A Didit também envia notificações de estado da verificação para sessões que exijam revisão manual para o endereço de e-mail fornecido." }, "phone": { "type": "string", "nullable": true, "description": "Número de telefone do utilizador no formato E.164, se disponível (por exemplo, +14155552671). `null` quando apenas um e-mail foi fornecido na criação da sessão. Nota: Este campo devolve o número de telefone original fornecido durante a criação da sessão. Se o número for inválido, pode não estar no formato E.164." } }, "nullable": true }, "callback": { "type": "string", "format": "uri", "description": "O URL de retorno da sessão.", "nullable": true }, "id_verifications": { "type": "array", "nullable": true, "description": "**Array de relatórios de verificação de identidade (OCR)** produzidos por passos de documento de identificação no grafo do fluxo. Sempre um array JSON — leia `id_verifications[0]` e itere se o seu fluxo puder executar mais do que uma verificação de identificação (por exemplo, uma verificação principal mais uma verificação adicional). `null` até que pelo menos um passo de identificação tenha produzido dados. Cada item é o relatório completo, incluindo `node_id`, `status` ao nível da funcionalidade, campos do documento extraídos, URLs de imagens, pontuações de qualidade, MRZ, análise da morada, correspondências entre sessões e `warnings[]`.", "items": { "type": "object", "description": "Um relatório de Verificação de identidade - o relatório completo de um único passo de Verificação de identidade. `verification_method` indica qual dos três métodos o gerou (captura de documento, consulta sem documento ou início de sessão com carteira) e o bloco de evidências específico do método é preenchido em conformidade.", "properties": { "node_id": { "type": "string", "description": "ID do nó do grafo do fluxo do passo de OCR que gerou este relatório." }, "verification_method": { "type": "string", "enum": [ "document", "id_lookup", "wallet" ], "description": "Qual o método de Verificação de identidade que gerou este relatório. `document` - o utilizador fotografou um documento de identificação físico (a predefinição e o valor em todas as sessões criadas antes da existência dos outros métodos). `id_lookup` - o utilizador introduziu o seu número de identificação nacional e este foi verificado num registo governamental ou noutra fonte oficial desse país (`id_lookup.source` indica qual). `wallet` - o utilizador iniciou sessão com uma identidade digital governamental ou bancária." }, "assurance": { "type": "string", "enum": [ "documentary", "data_match", "cryptographic" ], "description": "Nível de garantia derivado de `verification_method`: `documentary` para um documento que foi capturado e verificado, `data_match` para detalhes que corresponderam a um registo mantido pela fonte consultada, `cryptographic` para atributos autenticados e assinados por um fornecedor de identidade." }, "wallet_provider": { "type": "string", "nullable": true, "description": "ID de catálogo da carteira quando `verification_method` é `wallet` (`mitid`, `bankid_se`, `itsme`, ...). Caso contrário, `null`." }, "fallback_from": { "type": "object", "nullable": true, "description": "O motivo pelo qual um método não documental não concluiu o passo de identificação. Definido quando uma consulta ou um início de sessão com carteira falhou: na verificação de documentos com a qual o utilizador continuou quando a opção de recurso do país era `fallback_to_document` (`action` é `fallback_to_document`), ou no relatório recusado quando era `decline`. `null` nos restantes casos.", "properties": { "method": { "type": "string", "enum": [ "id_lookup", "wallet" ], "description": "O método que falhou." }, "reason": { "type": "string", "description": "O resultado que determinou o seu fim, por exemplo, `no_match`, `provider_error`, `cancelled`, `timeout`." }, "action": { "type": "string", "enum": [ "fallback_to_document", "decline" ], "description": "A ação configurada que foi executada: `fallback_to_document` ou `decline`." } } }, "id_lookup": { "type": "object", "nullable": true, "description": "Comprovativo do registo de empresas. Presente apenas quando `verification_method` é `id_lookup`; `null` caso contrário.", "properties": { "source": { "type": "string", "description": "Nome visível ao cliente da fonte consultada, por exemplo, `Department of Home Affairs` (um registo governamental) ou `UK credit bureau and financial services records` (não é um registo governamental). Esta é a única declaração de proveniência para a consulta; não assuma uma fonte governamental." }, "checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o registo respondeu." }, "attempts": { "type": "integer", "description": "Número da tentativa, indexado a partir de 1, que deu origem a este relatório." }, "max_attempts": { "type": "integer", "description": "Orçamento de tentativas configurado para o país (1 a 5, predefinição 1)." }, "outcome": { "type": "string", "enum": [ "match", "partial_match", "no_match", "provider_error", "format_rejected" ], "nullable": true, "description": "O que o registo respondeu. Apenas `match`, `partial_match` e `no_match` contam para o orçamento de tentativas e a faturação." }, "comparison": { "type": "array", "description": "Uma linha por campo comparável ao qual a fonte respondeu, mais uma linha por erro da fonte. As linhas de comparação utilizam os nomes de campo normalizados abaixo em vez das chaves dos campos de pedido específicas do país, porque vários campos do pedido (primeiro e último nome, ou qualquer um dos aliases de identificador) colapsam numa única comparação. Uma fonte que tenha falhado anexa uma linha com `field: \"provider\"` e `result: \"error\"`, pelo que deve consultar `result` antes de tratar uma linha como um veredito do campo.", "items": { "type": "object", "required": [ "field", "label", "provided", "record", "result" ], "properties": { "field": { "type": "string", "enum": [ "identification_number", "full_name", "date_of_birth", "address", "provider" ], "description": "Campo de comparação normalizado. `provider` não é um campo de utilizador: marca uma linha de erro de origem." }, "label": { "type": "string", "description": "Etiqueta visível da linha, por exemplo `ID number`, `Full name`, `Provider`." }, "provided": { "type": "string", "nullable": true, "description": "O que o utilizador introduziu. `null` numa linha de erro de `provider`." }, "record": { "type": "string", "nullable": true, "description": "O que a fonte continha. Numa linha de erro de `provider`, este campo contém a mensagem de erro." }, "result": { "type": "string", "enum": [ "match", "partial", "no_match", "error" ], "description": "Resultado de comparação por campo. `error` surge apenas numa linha `provider` e significa que essa fonte não respondeu; trate-o como uma evidência sobre o pedido, nunca como uma divergência de campo." } } } }, "registry_portrait": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinado de curta duração para o retrato devolvido pela fonte. Apenas para os quatro registos governamentais que devolvem um (África do Sul, Nigéria, Argentina, Panamá)." }, "face_match_score": { "type": "number", "nullable": true, "description": "Selfie em comparação com o retrato do registo, 0-100. Apenas quando o registo devolve um retrato." } } }, "wallet_verification": { "type": "object", "nullable": true, "description": "Evidência da credencial. Presente apenas quando `verification_method` é `wallet`; `null` caso contrário.", "properties": { "provider": { "type": "string", "description": "ID de catálogo da carteira, por ex. `mitid`." }, "provider_name": { "type": "string", "nullable": true, "description": "Nome da carteira tal como o utilizador final a conhece, por ex. `MitID`." }, "issuing_authority": { "type": "string", "nullable": true, "description": "A autoridade responsável pela carteira, por exemplo `Danish Agency for Digital Government`." }, "issuing_country": { "type": "string", "description": "País ISO 3166-1 alfa-3 no qual a carteira foi disponibilizada." }, "credential_type": { "type": "string", "nullable": true, "description": "Credencial apresentada pela carteira, ex.: `person_identification`." }, "level_of_assurance": { "type": "string", "enum": [ "low", "substantial", "high" ], "nullable": true, "description": "O nível de garantia que a carteira declarou. Um início de sessão que declare menos do que o nível pedido falha em vez de reduzir o nível." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "O instante de autenticação da carteira." }, "signature_valid": { "type": "boolean", "nullable": true, "description": "Se a asserção assinada devolvida pela carteira foi validada." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Os atributos partilhados pela carteira, com as chaves indicadas na entrada correspondente do catálogo da carteira." }, "portrait": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinado de curta duração para o retrato partilhado pela carteira, quando esta partilhar algum." }, "face_match_score": { "type": "number", "nullable": true, "description": "Selfie em comparação com o retrato da carteira, 0-100, quando a carteira partilha um retrato." } } }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Expired" ], "description": "Estado ao nível da funcionalidade deste passo de verificação de identidade. Independente do `status` da sessão de nível superior — uma sessão pode alcançar a sua decisão global enquanto uma funcionalidade individual permanece `In Review`." }, "document_type": { "type": "string", "description": "Tipo de documento de identificação" }, "document_subtype": { "type": "string", "nullable": true, "description": "Código de subtipo de documento aceite das definições de documentos do fluxo, incluindo a região do documento quando aplicável. Exemplos: `ID_CARD_GENERIC`, `QUEENSLAND_DRIVER_LICENSE_GENERIC`." }, "document_number": { "type": "string", "description": "Número de identificação do documento" }, "personal_number": { "type": "string", "description": "Número de identificação pessoal" }, "portrait_image": { "type": "string", "format": "uri", "description": "URL da imagem de retrato" }, "front_image": { "type": "string", "format": "uri", "description": "URL da imagem da frente do documento" }, "front_video": { "type": "string", "format": "uri", "description": "URL do vídeo da frente do documento" }, "back_image": { "type": "string", "format": "uri", "description": "URL da imagem do verso do documento" }, "back_video": { "type": "string", "format": "uri", "description": "URL do vídeo do verso do documento" }, "full_front_image": { "type": "string", "format": "uri", "description": "URL da imagem completa da frente do documento" }, "full_back_image": { "type": "string", "format": "uri", "description": "URL da imagem completa do verso do documento" }, "front_image_camera_front": { "type": "string", "format": "uri", "description": "URL da imagem da frente do documento capturada a partir da câmara frontal" }, "back_image_camera_front": { "type": "string", "format": "uri", "description": "URL da imagem do verso do documento capturada a partir da câmara frontal" }, "date_of_birth": { "type": "string", "format": "date", "description": "Data de nascimento do documento" }, "age": { "type": "integer", "description": "Idade calculada a partir da data de nascimento" }, "expiration_date": { "type": "string", "format": "date", "description": "Data de validade do documento" }, "date_of_issue": { "type": "string", "format": "date", "description": "Data de emissão do documento" }, "issuing_state": { "type": "string", "description": "Código ISO do estado emissor" }, "issuing_state_name": { "type": "string", "description": "Nome completo do estado emissor" }, "first_name": { "type": "string", "description": "Primeiro nome do documento" }, "last_name": { "type": "string", "description": "Apelido extraído do documento" }, "full_name": { "type": "string", "description": "Nome completo constante do documento" }, "gender": { "type": "string", "description": "Género constante do documento" }, "address": { "type": "string", "description": "Morada em bruto do documento" }, "formatted_address": { "type": "string", "description": "Morada completa formatada" }, "place_of_birth": { "type": "string", "description": "Local de nascimento a partir do documento" }, "marital_status": { "type": "string", "description": "Estado civil a partir do documento" }, "nationality": { "type": "string", "description": "Código ISO de nacionalidade" }, "extra_fields": { "type": "object", "description": "Campos adicionais do documento. Inclui atributos específicos do documento (por exemplo, `dl_categories`, `blood_group`, `sponsor`, `employer`, `dl_class_code_b_from`, `dl_class_code_b_to`). As datas de validade das categorias da carta de condução são devolvidas como `dl_class_code__from` e `dl_class_code__to`, e os códigos de restrição/informação por categoria (por exemplo, coluna 12 das cartas do Reino Unido) como `dl_class_code__notes`. Quando o documento contém nomes, morada ou local de nascimento em múltiplos sistemas de escrita, este objeto também inclui versões desses campos nos sistemas de escrita alternativos. A definição de fluxo `preferred_characters` (`latin` ou `non_latin`) controla qual o sistema de escrita que preenche os campos de nível superior (`first_name`, `last_name`, `full_name`, `address`, `place_of_birth`); o sistema de escrita oposto aparece aqui como `first_name_non_latin` / `last_name_non_latin` / `full_name_non_latin` / `middle_name_non_latin` / `address_non_latin` / `place_of_birth_non_latin` (quando `preferred_characters` é `latin`) ou com o sufixo `_latin` (quando `preferred_characters` é `non_latin`). As chaves surgem apenas quando o OCR extrai efetivamente um valor real no sistema de escrita alternativo — um campo cujo valor alternativo esteja no mesmo sistema de escrita do conjunto preferencial (por exemplo, um campo com rótulo em cirílico cujo valor de OCR tenha retornado em homóglifos latinos) é ignorado. Quando `preferred_characters` é `latin` mas o documento apenas contém texto não latino, a Didit translitera os valores extraídos e disponibiliza `first_name_latin` / `last_name_latin` / etc. como recurso de contingência.", "additionalProperties": true, "properties": { "dl_categories": { "type": "array", "items": { "type": "string" } }, "blood_group": { "type": "string", "nullable": true }, "first_name_non_latin": { "type": "string", "description": "Primeiro nome no sistema de escrita não latino quando `preferred_characters=latin` e uma versão não latina está presente no documento (ex.: `Айна` para uma identificação do Quirguistão)." }, "last_name_non_latin": { "type": "string", "description": "Apelido no sistema de escrita não latino quando `preferred_characters=latin` e uma versão não latina estiver presente no documento." }, "middle_name_non_latin": { "type": "string", "description": "Segundo nome / patronímico no sistema de escrita não latino quando `preferred_characters=latin` e uma versão não latina está presente no documento." }, "full_name_non_latin": { "type": "string", "description": "Nome completo composto no sistema de escrita não latino. Reconstruído a partir dos componentes individuais quando o nome próprio e os apelidos estão disponíveis." }, "address_non_latin": { "type": "string", "description": "Morada no sistema de escrita não latino quando `preferred_characters=latin` e uma versão não latina está presente no documento." }, "place_of_birth_non_latin": { "type": "string", "description": "Local de nascimento no sistema de escrita não latino quando `preferred_characters=latin` e uma versão não latina estiver presente no documento." }, "first_name_latin": { "type": "string", "description": "Primeiro nome em sistema de escrita latino. Preenchido quando `preferred_characters=non_latin` e uma versão em carateres latinos está presente no documento, ou — como alternativa de transliteração — quando `preferred_characters=latin` mas o documento apenas contém texto não latino." }, "last_name_latin": { "type": "string", "description": "Apelido no sistema de escrita latino. As mesmas regras que `first_name_latin`." }, "middle_name_latin": { "type": "string", "description": "Segundo nome / patronímico em sistema de escrita latino. Aplicam-se as mesmas regras que a `first_name_latin`." }, "full_name_latin": { "type": "string", "description": "Nome completo composto em sistema de escrita latino. Sempre reconstruído a partir dos componentes individuais quando o nome próprio e os apelidos estão disponíveis." }, "address_latin": { "type": "string", "description": "Morada em sistema de escrita latino. Aplicam-se as mesmas regras que a `first_name_latin`." }, "place_of_birth_latin": { "type": "string", "description": "Local de nascimento em sistema de escrita latino. As mesmas regras que para `first_name_latin`." } } }, "mrz": { "type": "object", "nullable": true, "description": "Campos analisados da Zona de Leitura Ótica (MRZ) extraídos do documento. `null` se nenhuma MRZ foi detetada.", "properties": { "surname": { "type": "string", "example": "MARTINEZ_families` / `very_high_similarity_plus__families`. Presente apenas quando `match_source` é `recovered_high`." } } } }, "browser_version": { "type": "string", "nullable": true }, "os_version": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true, "description": "A string de user agent do navegador." }, "accept_language": { "type": "string", "nullable": true, "description": "O cabeçalho `Accept-Language` enviado pelo navegador." }, "session_identifier": { "type": "string", "nullable": true, "description": "Identificador da sessão de navegação na qual a verificação foi executada." }, "session_age_ms": { "type": "integer", "nullable": true, "description": "Idade dessa sessão de navegação em milissegundos quando o passo foi executado." }, "coords_accuracy": { "type": "number", "nullable": true, "description": "Raio de precisão, em metros, das coordenadas comunicadas pelo dispositivo." }, "raw_device_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Sinais do dispositivo em bruto recolhidos para o passo." } } } }, "geolocation_checks": { "type": "array", "nullable": true, "description": "**Array de resultados de verificação de localização**, um por passo de verificação de localização: a tentativa aceite desse passo. `null` até que um passo de verificação de localização tenha produzido dados. As tentativas anteriores do mesmo passo estão em `geolocation_attempts`.", "items": { "$ref": "#/components/schemas/GeolocationCheck" } }, "geolocation_attempts": { "type": "array", "nullable": true, "description": "Cada tentativa de cada passo de verificação de Localização desta sessão, da mais antiga para a mais recente. As tentativas substituídas por um novo envio são excluídas. Um fluxo que omita `geolocation_checks` através dos respetivos atributos de resposta também omite esta lista.", "items": { "$ref": "#/components/schemas/GeolocationAttempt" } }, "database_validations": { "type": "array", "nullable": true, "description": "**Array de relatórios de Validação de base de dados** — sempre um array JSON, nunca um objeto `database_validation` singular. `null` até que pelo menos um passo de validação de base de dados tenha gerado dados. Cada item é o relatório completo, incluindo `node_id`, o `status` ao nível da funcionalidade, `screened_data`, as `validations[]` por serviço (cada uma com o seu `source_data` do registo) e `warnings[]`. Os campos `screened_data` e `source_data` variam por país:\n\n**ARG (Argentina)**: screened_data: {document_number, selfie, gender, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, date_of_death, tax_id, tax_id_type, face_match_score, sit_1_since, banks, last_position, highest_position, rejected_checks}. Utiliza a validação biométrica de correspondência facial do RENAPER. O género é inferido automaticamente a partir da análise facial ou do nome próprio quando não se encontra presente no documento (por exemplo, em cartas de condução)\n\n**BOL (Bolívia)**: screened_data: {document_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender}\n\n**BRA (Brasil)**: screened_data: {tax_number, first_name, last_name, date_of_birth}. source_data inclui sempre {identification_number, first_name, last_name, date_of_birth, lgpd_minor, minor_under_18, minor_under_16} para correspondências bem-sucedidas de CPF. Consultas de adultos bem-sucedidas definem esses sinalizadores como false. O serviço Consulta CPF da Receita Federal pode devolver HTTP 422 (menor de 18 anos) ou 451 (menor de 16 anos) com dados retidos pela LGPD; nesses casos, source_data define os sinalizadores de menor como true conforme apropriado, inclui o código de estado HTTP do serviço a montante e a validação ao nível do campo é no_match. Consulte a secção do Brasil da referência de Códigos de Resultado de Validação de base de dados para a lista completa de códigos.\n\n**CHL (Chile)**: screened_data: {personal_number, first_name, last_name, date_of_birth}. source_data: {identification_number, first_name, last_name, date_of_birth, gender}\n\n**COL (Colômbia)**: screened_data: {document_number, document_type, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, document_type}\n\n**CRI (Costa Rica)**: screened_data: {personal_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**DOM (República Dominicana)**: screened_data: {personal_number}. source_data: {identification_number} (devolve apenas valid/invalid)\n\n**ECU (Equador)**: screened_data: {personal_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, street, formatted_address, gender, nationality, education, marital_status, spouse, mother_name, father_name, profession}\n\n**ESP (Espanha)**: screened_data: {personal_number, document_type, expiration_date, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, document_type, expiration_date}\n\n**GTM (Guatemala)**: screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**HND (Honduras)**: screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**MEX (México)**: screened_data: {personal_number (CURP), first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender, nationality, curp_status, state_of_birth, doc_probatorio, registration_year, registration_state, registration_municipality, num_acta, crip, issuing_state_code, foreign_registry_number, folio_carta, folio_certificado}. Utiliza o registo civil do RENAPO. Está também disponível um serviço independente de verificação de validade do INE para o MEX como uma validação adicional individual.\n\n**PAN (Panamá)**: screened_data: {personal_number, selfie}. source_data: {identification_number}. Utiliza a validação biométrica do SIB\n\n**PER (Peru)**: screened_data: {personal_number (DNI), first_name, last_name}. source_data: {identification_number, first_name, last_name, paternal_name, maternal_name, verification_number, verification_letter}\n\n**PRY (Paraguai)**: screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**SLV (El Salvador)**: screened_data: {document_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**URY (Uruguai)**: screened_data: {personal_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**VEN (Venezuela)**: screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, gender, date_of_birth, document_type}", "items": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Identificador único para este passo de validação de base de dados no grafo do fluxo." }, "issuing_state": { "type": "string", "description": "Código ISO 3166-1 alfa-3 do país cujas fontes governamentais/de registo foram consultadas (por exemplo, `BRA`, `MEX`, `ESP`, `NGA`, `IDN`). A Validação de base de dados abrange 60+ países nas Américas, Europa, África, Médio Oriente e Ásia-Pacífico, além de fontes globais multipaís — a cobertura expande-se regularmente, pelo que deve tratar o valor como um conjunto aberto e não como um enum fixo." }, "validation_type": { "type": "string", "enum": [ "one_by_one", "two_by_two", "not_enabled" ], "description": "Como o resultado foi corroborado: `one_by_one` (resultado de serviço único), `two_by_two` (dois ou mais serviços distintos estabeleceram correspondência total com o número de identificação de forma independente) ou `not_enabled` (persistido quando nenhum serviço produziu uma correspondência utilizável). O valor nunca é `null`. Modos de validação biométrica 2x2 dedicados estão atualmente disponíveis para `ECU` e `PER`." }, "screened_data": { "type": "object", "description": "Os dados de entrada utilizados para validação. Os campos variam consoante o país — consulte a documentação de Validação de base de dados (`/core-technology/database-validation/overview`) para obter os formatos específicos de cada país.", "properties": { "last_name": { "type": "string" }, "first_name": { "type": "string" }, "tax_number": { "type": "string", "description": "Brasil: CPF (11 dígitos)" }, "personal_number": { "type": "string", "description": "Chile: RUT, DOM: Cédula (11 dígitos), ECU: Cédula (10 dígitos), ESP: DNI/NIE, MEX: CURP (18 carateres), PER: DNI (8 dígitos), URY: CI" }, "document_number": { "type": "string", "description": "ARG: DNI, BOL: CI, COL: Cédula, GTM: DPI, HND: DNI, PAN: Cédula, PRY: CI, SLV: DUI, VEN: Cédula" }, "date_of_birth": { "type": "string", "format": "date" }, "document_type": { "type": "string", "description": "COL: CC/CE/TI/NIT, ESP: ID/PASSPORT" }, "expiration_date": { "type": "string", "format": "date", "description": "Obrigatório para ESP" } } }, "validations": { "type": "array", "description": "Uma entrada por serviço de registo que devolveu um payload de validação. Cada entrada identifica o serviço (`service_id`, `service_name`) e inclui a comparação de `validation` por campo, o `outcome_code` / `outcome_detail` do serviço quando reportado e o registo normalizado do serviço de registo em `source_data`.", "items": { "type": "object", "properties": { "service_id": { "type": "string", "description": "Identificador do serviço de registo que produziu este resultado de validação.", "example": "bra_cpf" }, "service_name": { "type": "string", "description": "Nome legível do serviço de registo.", "example": "Brazil - CPF status check" }, "validation": { "type": "object", "description": "Os resultados das validações dos campos.", "properties": { "full_name": { "type": "string", "description": "Resultado da correspondência para o nome completo (ex.: 'full_match', 'partial_match', 'no_match')." }, "date_of_birth": { "type": "string", "description": "Resultado da correspondência para a data de nascimento." }, "identification_number": { "type": "string", "description": "Resultado da correspondência para o número de identificação." } } }, "outcome_code": { "type": "string", "nullable": true, "description": "Resultado legível por máquina da consulta ao registo (por exemplo, `MATCH`, `NO_MATCH`, `PARTIAL_MATCH`, `INCONCLUSIVE`, códigos específicos da fonte). Presente quando o serviço reporta um." }, "outcome_detail": { "type": "string", "nullable": true, "description": "Explicação legível de `outcome_code`, quando fornecida pelo serviço." }, "source_data": { "type": "object", "description": "Os dados devolvidos pela base de dados governamental. Campos comuns: identification_number, first_name, last_name, full_name, date_of_birth, gender. Campos adicionais por país: BRA inclui sempre lgpd_minor, minor_under_18 e minor_under_16 em correspondências de CPF bem-sucedidas; também inclui o código de estado HTTP a montante quando os dados do CPF são retidos ao abrigo da LGPD (HTTP 422/451). ECU adiciona street, formatted_address, nationality, education, marital_status, spouse, mother_name, father_name, profession. PER adiciona paternal_name, maternal_name, verification_number, verification_letter. ESP adiciona document_type, expiration_date. VEN/COL adicionam document_type.", "additionalProperties": true } } } }, "errors": { "type": "array", "description": "Erros devolvidos pelos serviços de registo durante a validação, cada um etiquetado com o `service_id` que o gerou. **Esta chave é totalmente omitida quando não existem erros.**", "items": { "type": "object", "description": "O objeto de erro do serviço a montante expandido tal como está — as respetivas chaves variam consoante o serviço (habitualmente uma mensagem/código e quaisquer detalhes específicos do fornecedor) — além de `service_id`, que identifica o serviço com erro.", "properties": { "service_id": { "type": "string", "nullable": true, "description": "Identificador do serviço de registo que gerou o erro." } }, "additionalProperties": true } }, "match_type": { "type": "string", "enum": [ "no_match", "partial_match", "full_match" ], "nullable": true, "description": "O resultado de correspondência agregado entre os serviços consultados. `null` até que a validação tenha sido avaliada." }, "status": { "type": "string", "description": "Estado ao nível da funcionalidade desta validação de base de dados. Independente do `status` da sessão de nível superior — uma sessão pode alcançar a sua decisão global enquanto uma funcionalidade individual permanece `In Review`.", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "A funcionalidade que gerou este aviso. O valor identifica o bloco de funcionalidade a que o aviso pertence. O array de avisos de cada módulo utiliza tipicamente o valor correspondente ao seu módulo (por exemplo, `PHONE` dentro de `phone_verifications[].warnings`), mas o enum acima é a referência autoritativa para todos os avisos de funcionalidades no payload da decisão." }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "O ID do nó do grafo do fluxo que gerou este aviso" } } }, "description": "Avisos relacionados com a validação de base de dados." } } } }, "database_validation_not_performed_reason": { "type": "object", "nullable": true, "additionalProperties": true, "description": "O motivo pelo qual uma validação de base de dados configurada não produziu nenhum resultado, como `{code, message}` mais campos de contexto. Presente apenas quando `database_validations` é `null` num fluxo que tem o passo, para que possa distinguir \"o registo concordou\" de \"nada foi executado\". `null` nos restantes casos.", "properties": { "code": { "type": "string", "description": "Motivo legível por máquina estável." }, "message": { "type": "string", "description": "Explicação legível." } } }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string", "description": "Quem realizou a revisão. Normalmente o identificador do revisor na consola (o respetivo e-mail), mas o valor é `\"API Client\"` para atualizações de estado feitas com uma chave de API e `\"Unknown\"` quando não foi possível resolver nenhum interveniente — portanto, não processe este campo como um endereço de e-mail." }, "new_status": { "type": "string" }, "comment": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "assignee": { "type": "object", "nullable": true, "description": "O revisor da consola ao qual a sessão está atribuída, ou `null` quando não está atribuída a ninguém.", "properties": { "email": { "type": "string", "format": "email" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true } } }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a sessão começou a aguardar revisão. `null` a menos que a sessão esteja `In Review` e a sua aplicação defina um prazo de revisão." }, "sla_due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a revisão deve ser concluída. `null` a menos que a sessão esteja `In Review` e a sua aplicação defina um prazo de revisão." }, "created_at": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora em que a sessão foi criada (ISO 8601, UTC)." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora em que esta sessão está agendada para expirar. Definido em sessões de Verificação de utilizadores (KYC) quando foi configurada uma expiração no momento da criação (ou assim que o estado `Approved` acionar o cálculo de expiração do KYC). `null` para sessões sem uma expiração configurada e para tipos que não utilizam expiração (por exemplo, sessões de Verificação de empresas (KYB) que nunca receberam um `expires_at`)." }, "registry_checks": { "type": "array", "nullable": true, "description": "Verificações no registo de empresas. Presente apenas quando `session_kind = business`. Cada item contém o payload completo do registo de empresas.", "items": { "type": "object", "description": "Uma verificação de registo de empresas — o payload completo de registo de empresas enriquecido com a estrutura de propriedade e avisos. Presente apenas quando `session_kind = business`.", "properties": { "status": { "type": "string", "description": "Estado do ciclo de vida da funcionalidade." }, "node_id": { "type": "string", "nullable": true }, "data_resolved": { "type": "boolean" }, "company": { "type": "object", "description": "Payload completo do registo de empresas para a empresa (registo de empresas combinado com quaisquer dados fornecidos pelo utilizador ou editados na consola).", "properties": { "uuid": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "registry_status": { "type": "string", "nullable": true }, "data_resolved": { "type": "boolean" }, "company_name": { "type": "string" }, "registration_number": { "type": "string", "nullable": true }, "country_code": { "type": "string", "description": "País de constituição (ISO 3166-1 alpha-2, por ex., `GB`, `DE`, `US`)." }, "region": { "type": "string", "nullable": true, "description": "Código de subdivisão ISO 3166-2 quando aplicável (por exemplo, `CA`, `NY` para estados dos EUA)." }, "company_type": { "type": "string", "nullable": true }, "incorporation_date": { "type": "string", "format": "date", "nullable": true }, "registered_address": { "type": "string", "nullable": true }, "tax_number": { "type": "string", "nullable": true }, "risk_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "nullable": true }, "verification_status": { "type": "string", "nullable": true }, "is_from_registry": { "type": "boolean" }, "fetch_status": { "type": "string", "nullable": true }, "alternative_names": { "type": "string", "nullable": true, "description": "Nomes alternativos, comerciais, anteriores ou no idioma original da empresa em texto, quando comunicados." }, "nature_of_business": { "type": "string", "nullable": true }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "format": "decimal", "nullable": true, "description": "Montante do capital registado/capital social como string decimal (ex.: `\"100.00\"`), analisado a partir do registo de empresas. `null` quando não disponível." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Código de moeda ISO 4217 de `registered_capital_amount` (por exemplo, `\"GBP\"`). `null` quando não estiver disponível." }, "website": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "legal_entity_identifier": { "type": "string", "nullable": true }, "location_of_registration": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true, "description": "Número de IVA da UE, quando recolhido durante o passo de registo alojado ou editado posteriormente." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Resultado da validação do número de IVA ou, quando inexistente, do `tax_number`, no envio do registo. `valid` / `invalid`: decidido pelo registo oficial do país (VIES da UE, Noruega, Suíça, Brasil, Colômbia, Costa Rica, Equador, Paraguai; Polónia também pelo seu registo doméstico de IVA). `format_valid` / `invalid_format`: decidido pelas regras de formato e de dígito de controlo do país quando nenhum registo pode ser consultado. `could_not_validate`: o registo estava indisponível. `not_applicable`: sem número, um país sem registo ou regras, ou uma sessão de sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "O número que foi verificado, tal como a fonte o conhece (por exemplo, o número de IVA derivado de um SIREN francês ou de um RSIN neerlandês). `null` quando nenhuma verificação foi executada." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "A origem que determinou o `vat_validation_status`: um registo oficial ou `format_rules`. `null` quando nenhuma verificação foi executada." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registado na fonte que validou o número, quando esta o divulga. Apenas definido quando o estado for `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Morada registada junto da fonte que validou o número, quando esta a divulga. Apenas definida quando o estado é `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Carimbo de data/hora da verificação. `null` quando nenhuma verificação foi executada." }, "financial_summary": { "type": "object", "nullable": true }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "designation": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "enum": [ "Approved", "Declined", "Pending" ], "nullable": true }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "first_name": { "type": "string", "nullable": true, "description": "Nome próprio quando explicitamente indicado pelo registo; não deduzido a partir do nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Apelido quando explicitamente comunicado pelo registo." }, "address": { "type": "string", "nullable": true, "description": "Morada do administrador indicada pelo registo." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data em que o administrador foi nomeado.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data em que a nomeação terminou, quando reportada.", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa comunicada pelo registo de empresas. Nulo quando apenas o ano ou mês de nascimento é conhecido.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Ano de nascimento reportado pelo registo de empresas, incluindo quando a data completa não está disponível." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mês de nascimento reportado pelo registo de empresas. Nulo quando apenas o ano é conhecido." } } } }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "roles": { "type": "array", "items": { "type": "string" } }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferior da percentagem de propriedade conforme reportada pelo registo. String de formato livre (por exemplo, `\"25.00\"`, `\"50\"`); utilize `effective_ownership_percent` para um valor numérico processado." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superior da percentagem de propriedade conforme comunicada pelo registo. String de formato livre; utilize `effective_ownership_percent` para um valor numérico processado." }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "enum": [ "Approved", "Declined", "Pending" ], "nullable": true }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa quando comunicada.", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "Data de nomeação quando comunicada.", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } } }, "addresses": { "type": "array", "nullable": true, "description": "Todas as moradas indicadas pelo registo, num formato canónico. Nulo quando este não indicar nenhuma.", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "As atividades sob as quais o registo classifica a empresa, num formato canónico. Null quando não indica nenhuma.", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Datas de submissão no registo de empresas, quando disponíveis. As declarações anuais e assembleias gerais utilizam last_annual_return_date e last_agm_date; são distintas das contas financeiras." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "description": "Dados confirmados ou editados pelo utilizador final." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true }, "is_editable": { "type": "boolean" }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "O nível de registo encomendado pelo fluxo: `basic`, `shareholders` ou `ubo`. Também em `ownership.tier_requested`." }, "registry_tier_delivered": { "type": "string", "nullable": true, "description": "O nível entregue pelo registo e que é faturado. Também em `ownership.tier_delivered`." }, "registry_ownership_status": { "type": "string", "nullable": true, "description": "`not_requested`, `pending`, `delivered`, `not_held` ou `unavailable`. Também em `ownership.status`." }, "registry_monitoring": { "type": "object", "nullable": true, "description": "A monitorização mais recente do registo para a empresa, ou `null` quando não existir nenhuma.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "Os campos da empresa que o monitor acompanha." } } } } }, "ownership_structure": { "$ref": "#/components/schemas/KYBOwnershipStructure" }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "key_people_checks": { "type": "array", "nullable": true, "description": "Verificações agregadas de pessoas-chave. Presente apenas quando `session_kind = business`. Cada item usa o formato de dois contentores (`registry`, `submitted`, `ubo_kyc_summary`).", "items": { "type": "object", "description": "Verificação agregada sobre os responsáveis + UBOs da empresa. Usa o formato `registry` / `submitted`. Presente apenas quando session_kind = business.", "properties": { "status": { "type": "string" }, "node_id": { "type": "string", "nullable": true }, "registry": { "type": "object", "description": "Partes identificadas através da verificação do registo.", "properties": { "officers": { "type": "array", "description": "Administradores identificados através da verificação no registo, cada um enriquecido com o estado de qualquer sessão de KYC filha e triagem AML criadas para eles.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Nome completo do administrador conforme consta no registo." }, "designation": { "type": "string", "nullable": true, "description": "Designação em texto livre do registo (por exemplo, `Director`, `Company Secretary`)." }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Função de dirigente normalizada." }, "nationality": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true, "description": "Data em que o administrador foi nomeado.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data em que a nomeação terminou, quando reportada.", "format": "date" }, "is_active": { "type": "boolean" }, "address": { "type": "string", "nullable": true, "description": "Morada do administrador indicada pelo registo." }, "aml_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "nullable": true, "description": "Estado da triagem AML executada para este administrador. `null` quando nenhuma triagem AML tiver sido executada." }, "kyc_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "Estado do ciclo de vida em bruto da sessão secundária de KYC gerada para este responsável da empresa. Este é o enum de estado completo da sessão (e não um conjunto reduzido Approved/Declined/Pending). `null` quando não existe uma sessão secundária de KYC." }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL partilhável da sessão filha de KYC. `null` quando não existe qualquer sessão filha." }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID de sessão da sessão KYC subordinada. Transmita-o a este mesmo endpoint de decisão para obter o relatório KYC completo da pessoa. `null` quando não existe nenhuma sessão subordinada." }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "Tipo de fluxo base do fluxo da sessão filha (por exemplo, `kyc`). `null` para fluxos baseados em grafos ou quando não existe nenhuma sessão filha." }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID do fluxo utilizado pela sessão subordinada. `null` quando não existe sessão subordinada." }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "Rótulo legível do fluxo da sessão dependente. `null` quando não definido." }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "Progresso por funcionalidade da sessão de verificação filha, por exemplo, `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`. `null` quando a sessão filha não tem uma lista de funcionalidades que possa ser resolvida.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Nome de apresentação da funcionalidade (por exemplo, `ID_VERIFICATION`, `LIVENESS`, `AML`)." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado ao nível da funcionalidade dentro da sessão filha." } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "Identificador interno estável do indivíduo verificado subjacente à sessão subordinada — útil para a ligação entre sessões. `null` quando não existe sessão subordinada ou o utilizador ainda não foi resolvido." }, "kyc_document_type": { "type": "string", "nullable": true, "description": "Tipo de documento apresentado na sessão KYC subordinada (por exemplo, `P`, `ID`, `DL`). `null` até a sessão subordinada ter um resultado de verificação de identidade." }, "kyc_nationality": { "type": "string", "nullable": true, "description": "Nacionalidade extraída do documento na sessão KYC filha. `null` até estar disponível." }, "kyc_liveness_passed": { "type": "boolean", "nullable": true, "description": "Indica se a verificação de prova de vida da sessão de KYC secundária foi aprovada. `null` quando nenhuma prova de vida tiver sido executada." }, "kyc_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a sessão de KYC subordinada atingiu `Approved`. `null` enquanto a sessão subordinada tiver qualquer outro estado." }, "kyc_aml_categories": { "type": "object", "nullable": true, "description": "Resumo por categoria derivado das correspondências de AML da pessoa. `null` quando não existem correspondências.", "properties": { "sanctions": { "type": "string", "enum": [ "match", "clear" ] }, "pep": { "type": "string", "enum": [ "match", "clear" ] }, "adverse_media": { "type": "string", "enum": [ "match", "clear" ] }, "warnings": { "type": "string", "enum": [ "match", "clear" ] } } }, "kyc_notification_sent_at": { "type": "string", "nullable": true, "description": "Carimbo de data/hora ISO 8601 da última notificação de convite de verificação enviada para a sessão dependente desta pessoa. `null` quando nenhuma tiver sido enviada." }, "first_name": { "type": "string", "nullable": true, "description": "Nome próprio quando explicitamente indicado pelo registo; não deduzido a partir do nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Apelido quando explicitamente comunicado pelo registo." }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa comunicada pelo registo de empresas. Nulo quando apenas o ano ou mês de nascimento é conhecido.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Ano de nascimento reportado pelo registo de empresas, incluindo quando a data completa não está disponível." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mês de nascimento reportado pelo registo de empresas. Nulo quando apenas o ano é conhecido." } } } }, "beneficial_owners": { "type": "array", "description": "Beneficiários efetivos descobertos através da verificação no registo, cada um enriquecido com o estado de qualquer sessão de KYC dependente e triagem AML iniciada para eles.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Nome completo do beneficiário efetivo (ou nome da empresa para UBOs empresariais)." }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data de nascimento completa quando comunicada.", "format": "date" }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "roles": { "type": "array", "description": "Nomes das funções desempenhadas por este proprietário, por exemplo `[\"ubo\", \"shareholder\"]`.", "items": { "type": "string" } }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferior da percentagem de propriedade conforme reportada pelo registo. String de formato livre (por exemplo, `\"25\"`, `\"25-50%\"`); utilize `effective_ownership_percent` para um valor numérico processado." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superior da percentagem de propriedade conforme comunicada pelo registo. String de formato livre; utilize `effective_ownership_percent` para um valor numérico processado." }, "is_active": { "type": "boolean" }, "aml_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "nullable": true, "description": "Estado da triagem AML executada para este beneficiário efetivo. `null` quando nenhuma triagem AML tiver sido executada." }, "kyc_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "Estado do ciclo de vida em bruto da sessão secundária de KYC gerada para este beneficiário efetivo. Este é o enum de estado completo da sessão (e não um conjunto reduzido Approved/Declined/Pending). `null` quando não existe uma sessão secundária de KYC." }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL partilhável da sessão filha de KYC. `null` quando não existe qualquer sessão filha." }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID de sessão da sessão KYC subordinada. Transmita-o a este mesmo endpoint de decisão para obter o relatório KYC completo da pessoa. `null` quando não existe nenhuma sessão subordinada." }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "Tipo de fluxo base do fluxo da sessão filha (por exemplo, `kyc`). `null` para fluxos baseados em grafos ou quando não existe nenhuma sessão filha." }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID do fluxo utilizado pela sessão subordinada. `null` quando não existe sessão subordinada." }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "Rótulo legível do fluxo da sessão dependente. `null` quando não definido." }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "Progresso por funcionalidade da sessão de verificação filha, por exemplo, `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`. `null` quando a sessão filha não tem uma lista de funcionalidades que possa ser resolvida.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Nome de apresentação da funcionalidade (por exemplo, `ID_VERIFICATION`, `LIVENESS`, `AML`)." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado ao nível da funcionalidade dentro da sessão filha." } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "Identificador interno estável do indivíduo verificado subjacente à sessão subordinada — útil para a ligação entre sessões. `null` quando não existe sessão subordinada ou o utilizador ainda não foi resolvido." }, "kyc_document_type": { "type": "string", "nullable": true, "description": "Tipo de documento apresentado na sessão KYC subordinada (por exemplo, `P`, `ID`, `DL`). `null` até a sessão subordinada ter um resultado de verificação de identidade." }, "kyc_nationality": { "type": "string", "nullable": true, "description": "Nacionalidade extraída do documento na sessão KYC filha. `null` até estar disponível." }, "kyc_liveness_passed": { "type": "boolean", "nullable": true, "description": "Indica se a verificação de prova de vida da sessão de KYC secundária foi aprovada. `null` quando nenhuma prova de vida tiver sido executada." }, "kyc_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a sessão de KYC subordinada atingiu `Approved`. `null` enquanto a sessão subordinada tiver qualquer outro estado." }, "kyc_aml_categories": { "type": "object", "nullable": true, "description": "Resumo por categoria derivado das correspondências de AML da pessoa. `null` quando não existem correspondências.", "properties": { "sanctions": { "type": "string", "enum": [ "match", "clear" ] }, "pep": { "type": "string", "enum": [ "match", "clear" ] }, "adverse_media": { "type": "string", "enum": [ "match", "clear" ] }, "warnings": { "type": "string", "enum": [ "match", "clear" ] } } }, "kyc_notification_sent_at": { "type": "string", "nullable": true, "description": "Carimbo de data/hora ISO 8601 da última notificação de convite de verificação enviada para a sessão dependente desta pessoa. `null` quando nenhuma tiver sido enviada." }, "child_beneficial_owners": { "type": "array", "description": "Para UBOs corporativos: os próprios beneficiários efetivos da entidade proprietária, como objetos em bruto extraídos do registo. Array vazio quando não for aplicável.", "items": { "type": "object" } }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem de propriedade numérica analisada — o limite máximo quando disponível, caso contrário o limite mínimo. `null` quando nenhum dos limites pôde ser analisado." }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true, "description": "Data de nomeação quando comunicada.", "format": "date" } } } } } }, "submitted": { "type": "object", "description": "Partes submetidas pelo administrador da empresa durante o fluxo de Pessoas-chave (linhas BusinessParty onde source=USER).", "properties": { "parties": { "type": "array", "items": { "type": "object", "description": "Parte submetida pelo administrador da empresa através do fluxo de Pessoas-chave (source=USER).", "properties": { "uuid": { "type": "string", "format": "uuid" }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "source": { "type": "string", "enum": [ "USER" ], "description": "Sempre `USER` aqui — esta categoria contém apenas partes introduzidas ou confirmadas pelo utilizador final no fluxo de pessoas-chave (as pessoas descobertas no registo aparecem sob `registry`)." }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "nationality": { "type": "string", "nullable": true, "description": "Nacionalidade para pessoas singulares; país de constituição para partes empresariais." }, "phone_number": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "position": { "type": "string", "nullable": true, "description": "Cargo/posição em texto livre (apenas pessoas singulares)." }, "custom_fields": { "type": "object", "description": "Campos personalizados definidos pelo fluxo recolhidos para esta parte; as chaves são definidas pelos descritores de campos de pessoas-chave do fluxo." }, "is_active": { "type": "boolean" }, "is_skipped": { "type": "boolean", "description": "True quando o utilizador final ignorou a verificação para esta parte (apenas possível quando a função permite ignorar)." }, "requires_verification": { "type": "boolean", "description": "True quando é necessária uma subsessão secundária de KYC / KYB para esta parte, com base nas definições de funções e limiares de propriedade." }, "roles": { "type": "array", "description": "Todas as funções desempenhadas por esta parte, cada uma com as suas próprias percentagens de propriedade e de voto. Não existe um campo escalar `role`/`ownership_percent` na própria parte.", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "ownership_percent": { "type": "number", "nullable": true }, "voting_percent": { "type": "number", "nullable": true } } } }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID da sessão KYC dependente para partes individuais que requerem verificação. `null` caso contrário." }, "kyc_session_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "Estado do ciclo de vida da sessão-filha de KYC. `null` quando não existe nenhuma sessão-filha de KYC." }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "kyb_sub_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID da subsessão KYB dependente para partes empresariais que requerem verificação. `null` caso contrário." }, "kyb_sub_session_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "Estado do ciclo de vida da subsessão-filha de KYB. `null` quando não existe nenhuma subsessão." }, "kyb_sub_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL partilhável da subsessão filha de KYB. `null` quando não existe qualquer subsessão." }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "Tipo de fluxo base do fluxo da sessão filha (sessão de KYC preferencial, recorrendo à subsessão de KYB como alternativa). `null` para fluxos baseados em grafos ou quando não existe nenhuma sessão filha." }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID do fluxo utilizado pela sessão subordinada. `null` quando não existe sessão subordinada." }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "Rótulo legível do fluxo da sessão dependente. `null` quando não definido." }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "Progresso por funcionalidade da sessão de verificação filha, por exemplo, `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`. `null` quando a sessão filha não tem uma lista de funcionalidades que possa ser resolvida.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Nome de apresentação da funcionalidade (por exemplo, `ID_VERIFICATION`, `LIVENESS`, `AML`)." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado ao nível da funcionalidade dentro da sessão filha." } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "Identificador interno estável do indivíduo verificado subjacente à sessão subordinada. `null` quando não resolvido." } } } } } }, "ubo_kyc_summary": { "type": "object", "nullable": true, "description": "Progresso agregado de KYC de UBOs, ou null quando nenhum UBO tem uma sessão de KYC associada.", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "flagged": { "type": "integer", "description": "UBOs cujo KYC se encontra recusada ou em análise." }, "pending": { "type": "integer" } } }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "document_verifications": { "type": "array", "nullable": true, "description": "Verificações de documentos agrupadas por nó do fluxo. Presente apenas quando `session_kind = business`.", "items": { "type": "object", "description": "Documentos agrupados por nó do fluxo. Presente apenas quando session_kind = business.", "properties": { "status": { "type": "string" }, "node_id": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "document_type": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION", "OTHER" ], "nullable": true, "description": "Grupo de documentos de KYB de alto nível no qual o ficheiro foi classificado. `null` enquanto não estiver classificado." }, "document_subtype": { "type": "string", "nullable": true, "description": "Subtipo específico detetado pelo OCR (por exemplo, `CERTIFICATE_OF_INCORPORATION`, `SHAREHOLDER_REGISTRY`); `UNKNOWN` quando o OCR não conseguiu classificar o documento com confiança." }, "document_group": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION", "OTHER" ], "nullable": true, "description": "Alias de `document_type` — o nome do grupo usado por `groups` e `required_groups`." }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "Ligação pré-assinada de curta duração para o ficheiro carregado. `null` para marcadores de posição de pedidos de documentos criados por analistas (`is_requested = true`) que ainda não tenham sido cumpridos." }, "original_filename": { "type": "string", "nullable": true, "description": "Nome do ficheiro tal como carregado pelo utilizador ou analista." }, "file_size": { "type": "integer", "nullable": true, "description": "Tamanho do ficheiro em bytes." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado da verificação por documento." }, "created_at": { "type": "string", "format": "date-time" }, "cross_check_result": { "type": "object", "nullable": true, "description": "Referência cruzada dos campos do documento extraídos por OCR com o perfil da empresa no registo. Um objeto com as secções `critical`, `non_critical` e `people`, cada uma das quais mapeia o nome de um campo (ex.: `company_name`, `registration_number`, `incorporation_date`, `registered_address`) para um registo de comparação como `{\"document\": \"...\", \"registry\": \"...\", \"match\": true, \"score\": 0.97}`. `null` quando o documento não continha dados de OCR ou não existia nenhuma empresa no registo para comparar." }, "document_metadata": { "type": "object", "nullable": true, "description": "Metadados extraídos do documento empresarial carregado. Quando a extração de metadados for bem-sucedida, todas as 16 chaves estão sempre presentes (os valores individuais são `null` quando não aplicáveis ao tipo de ficheiro); o objeto completo é `null` quando nada pôde ser extraído. Para ficheiros PDF, `overlay_manipulation` contém a análise forense de texto sobreposto.", "properties": { "file_size": { "type": "integer", "nullable": true, "description": "Tamanho do documento." }, "content_type": { "type": "string", "nullable": true, "description": "Tipo de conteúdo do documento." }, "creation_date": { "type": "string", "nullable": true, "description": "Data em que o documento foi criado." }, "modified_date": { "type": "string", "nullable": true, "description": "Data em que o documento foi modificado." }, "creator": { "type": "string", "nullable": true, "description": "Ferramenta ou utilizador de autoria registado nos metadados do ficheiro (`Creator` do PDF)." }, "producer": { "type": "string", "nullable": true, "description": "Software que gerou o ficheiro (PDF `Producer`)." }, "software": { "type": "string", "nullable": true, "description": "Software de edição registado nos metadados do ficheiro." }, "encryption": { "type": "string", "nullable": true, "description": "Esquema de encriptação do ficheiro, quando encriptado." }, "is_signed": { "type": "boolean", "nullable": true, "description": "Indica se o documento contém uma assinatura digital." }, "is_tampered": { "type": "boolean", "nullable": true, "description": "Indica se a assinatura digital falhou a validação (modificação após assinatura)." }, "signature_info": { "type": "object", "nullable": true, "description": "Detalhes da(s) assinatura(s) digital(ais), quando presentes." }, "exif_original_date": { "type": "string", "nullable": true, "description": "Data de captura original EXIF, para carregamentos de imagens." }, "exif_digitized_date": { "type": "string", "nullable": true, "description": "Data de digitalização EXIF, para carregamentos de imagens." }, "processed_by_known_editor": { "type": "boolean", "nullable": true, "description": "Se os metadados indicam que o ficheiro passou por um editor de imagem/PDF conhecido." }, "has_different_creation_mod_date": { "type": "boolean", "nullable": true, "description": "Se as datas de criação e modificação diferem — um possível sinal (mas não conclusivo) de edição." }, "overlay_manipulation": { "type": "object", "nullable": true, "description": "Análise forense de PDF para suspeita de manipulação de texto sobreposto. Nulo quando não forem encontradas evidências de manipulação de texto sobreposto ou o documento não for um PDF.", "properties": { "detected": { "type": "boolean", "description": "Se foram detetadas evidências de manipulação de texto sobreposto." }, "analyzed": { "type": "boolean", "description": "Indica se foi possível analisar o PDF." }, "analysis_incomplete": { "type": "boolean", "description": "Presente e verdadeiro apenas quando o ficheiro não pôde ser verificado na íntegra. O que foi verificado mantém as suas conclusões sempre que possível, e o documento apresenta o aviso de substituição de texto não comprovada." }, "signals": { "type": "array", "items": { "type": "string" }, "description": "Sinais forenses detetados, tais como duplicate_font_subset ou glyph_fragmentation." }, "manipulated_regions": { "type": "array", "description": "Áreas com suspeita de manipulação nas coordenadas da página do PDF.", "items": { "type": "object", "properties": { "page": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "page_width": { "type": "number" }, "page_height": { "type": "number" } } } } } } } }, "description": { "type": "string", "nullable": true, "description": "Rótulo ou motivo fornecido pelo analista para um pedido de documento. `null` para carregamentos normais." }, "is_requested": { "type": "boolean", "description": "True para marcadores de posição de pedidos de documentos criados por analistas a aguardar um carregamento." }, "ocr_data": { "type": "object", "nullable": true }, "is_console_upload": { "type": "boolean", "description": "True para documentos carregados a partir da consola em vez do fluxo do utilizador final. Os carregamentos pela consola nunca alteram o estado agregado ao nível da funcionalidade." }, "is_confirmed": { "type": "boolean", "description": "Os carregamentos através da consola começam como `false` e passam a `true` assim que o administrador os confirmar; os carregamentos do utilizador final são sempre `true`." } } } }, "groups": { "type": "object", "description": "Contadores de progresso por grupo indexados pelo nome do grupo (por exemplo, legal_presence, ownership_structure).", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "pending": { "type": "integer" }, "declined": { "type": "integer" }, "in_review": { "type": "integer" }, "other": { "type": "integer" }, "missing": { "type": "integer", "description": "Marcadores de posição pedidos sem qualquer ficheiro carregado até ao momento." } } } }, "required_groups": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Se a sessão foi criada por uma aplicação em produção (`live`) ou por uma aplicação sandbox (`sandbox`). As sessões sandbox são gratuitas, totalmente simuladas e nunca consomem créditos." }, "sandbox_scenario": { "type": "string", "nullable": true, "description": "O cenário de sandbox com o qual a sessão foi criada. `null` para sessões de produção e para sessões de sandbox criadas sem nenhum." }, "resubmissions": { "type": "array", "description": "Retornado apenas com `include=resubmissions`, para sessões de utilizador e de empresa. Uma entrada por pedido de nova submissão, da mais antiga para a mais recente. Cada entrada contém os resultados que os passos ressubmetidos retornaram antes do pedido, para que as submissões anteriores permaneçam legíveis. A eliminação da sessão elimina todas as submissões.", "items": { "type": "object", "properties": { "number": { "type": "integer", "description": "1 para a primeira nova submissão da sessão, 2 para a segunda e assim sucessivamente." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a resubmissão foi solicitada." }, "previous_status": { "type": "string", "description": "O estado da sessão imediatamente antes do pedido." }, "nodes": { "type": "array", "description": "Os passos do fluxo enviados de volta ao utilizador.", "items": { "type": "object", "properties": { "node_id": { "type": "string" }, "feature": { "type": "string" } } } }, "reasons": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "O motivo indicado para cada passo, indexado por `node_id`." }, "requested_by": { "type": "object", "nullable": true, "description": "Quem solicitou o novo envio.", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "type": { "type": "string" } } }, "results": { "type": "object", "additionalProperties": true, "description": "O que os passos reenviados devolveram antes do pedido, sob as mesmas chaves e com a mesma estrutura que os resultados atuais desta resposta (`id_verifications`, `nfc_verifications`, `liveness_checks`, `face_matches`, `poa_verifications`, `phone_verifications`, `email_verifications`, `aml_screenings`, `ip_analyses`, `database_validations`, `questionnaire_responses`, `document_ai_documents`, `geolocation_checks`; para sessões de empresas também `document_verifications`). Apenas surgem as chaves dos passos que foram reenviados." } } } }, "biometric_consent": { "type": "object", "nullable": true, "description": "Se a sessão exigiu consentimento biométrico explícito antes de uma captura facial, o motivo e a evidência da resposta. Apenas sessões de Verificação de utilizadores (KYC); o mesmo objeto está na `decision` dos webhooks da sessão. `null` quando a sessão nunca foi avaliada, por exemplo, num fluxo sem captura facial. Campos sem valor registado são `null`. Um SDK nativo anterior à versão 4.10.0, ou um que não reporte a sua versão, não consegue apresentar o passo de consentimento: as respetivas capturas faciais são executadas como anteriormente, e uma sessão que tenha exigido consentimento reporta `status: \"pending\"` com `reason: \"BIOMETRIC_CONSENT_UNSUPPORTED_SDK\"`. Consulte [Consentimento biométrico](/pt/getting-started/biometric-consent).", "properties": { "required": { "type": "boolean", "description": "Whether the session must collect explicit biometric consent. Never goes back to `false`." }, "trigger": { "type": "string", "nullable": true, "enum": [ "declared_state", "ip_state", "ip_unknown", "document_issuer", "forced", "customer_collected" ], "description": "O motivo pelo qual o consentimento é obrigatório, ou como foi satisfeito. `declared_state`: declarou um estado abrangido (`user_state`, ou uma morada nos EUA em `expected_details`). `ip_state`: o IP da pessoa está num estado abrangido (Illinois, Texas, Colorado). `ip_unknown`: as evidências colocam a pessoa nos EUA, mas o estado não pode ser determinado (o IP está nos EUA sem indicação de estado, ou não pode ser localizado enquanto os seus dados ou o documento colocam a pessoa nos EUA). `document_issuer`: o documento de identidade foi emitido por um estado abrangido. `forced`: o modo da aplicação é Always. `customer_collected`: enviou `biometric_consent` ao criar a sessão. `null` enquanto não for obrigatório." }, "status": { "type": "string", "enum": [ "not_required", "pending", "given", "declined" ], "description": "`not_required`; `pending` (obrigatório e não fornecido: a pessoa ainda não respondeu, ou `reason` indica por que não foi recolhido); `given`; `declined` (foi registada uma recusa e a sessão terminou como `Declined`; nenhum ecrã da Didit disponibiliza atualmente uma opção de recusa)." }, "given_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o consentimento foi fornecido. Para `customer_collected`, o `given_at` que enviou." }, "declined_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando uma recusa foi registada." }, "text_version": { "type": "string", "nullable": true, "description": "ID da versão do texto de consentimento ao qual a pessoa respondeu, ou o que enviou." }, "text_hash": { "type": "string", "nullable": true, "description": "SHA-256 (hex) do texto de consentimento exato apresentado, no idioma em que foi apresentado." }, "locale": { "type": "string", "nullable": true, "description": "Idioma no qual o texto de consentimento foi apresentado." }, "policy_url": { "type": "string", "format": "uri", "nullable": true, "description": "A política de dados biométricos ligada pelo passo de consentimento." }, "step": { "type": "string", "nullable": true, "description": "Passo do fluxo em que a sessão se encontrava quando a pessoa respondeu, por exemplo `LIVENESS`." }, "node_id": { "type": "string", "nullable": true, "description": "Nó do grafo do fluxo em que a sessão se encontrava quando a pessoa respondeu." }, "ip_address": { "type": "string", "nullable": true, "description": "IP de onde veio a resposta." }, "ip_country_code": { "type": "string", "nullable": true, "description": "País ISO 3166-1 alfa-2 do IP da resposta." }, "ip_state": { "type": "string", "nullable": true, "description": "Subdivisão ISO 3166-2 do IP da resposta, por exemplo `US-IL`." }, "ip_city": { "type": "string", "nullable": true, "description": "Cidade do IP da resposta." }, "user_agent": { "type": "string", "nullable": true, "description": "Agente do utilizador do pedido da resposta." }, "detected_ip_address": { "type": "string", "nullable": true, "description": "O IP da pessoa a partir do qual o requisito foi avaliado pela última vez. Pode ser diferente de `ip_address` quando a pessoa respondeu noutro dispositivo." }, "detected_country_code": { "type": "string", "nullable": true, "description": "País ISO 3166-1 alfa-2 do IP detetado." }, "detected_state": { "type": "string", "nullable": true, "description": "Subdivisão ISO 3166-2 do IP detetado." }, "detected_city": { "type": "string", "nullable": true, "description": "Cidade do IP detetado." }, "declared_state": { "type": "string", "nullable": true, "description": "Subdivisão ISO 3166-2 declarada por si: `user_state`, ou o estado de uma morada dos EUA em `expected_details`." }, "document_state": { "type": "string", "nullable": true, "description": "Subdivisão ISO 3166-2 que emitiu o documento de identidade, lida na captura do documento de identificação." }, "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "Estados dos EUA (códigos USPS, por exemplo `IL`) cuja legislação biométrica abrange a pessoa. `US` quando os dados comprovativos situam a pessoa nos EUA mas nenhum estado é conhecido. Vazio quando nenhum se aplica." }, "retention_months": { "type": "integer", "nullable": true, "description": "O limite de conservação biométrica mais curto, em meses, entre as `jurisdictions`. `null` quando nenhum se aplica." }, "reason": { "type": "string", "nullable": true, "enum": [ "BIOMETRIC_CONSENT_UNSUPPORTED_SDK", "BIOMETRIC_CONSENT_DECLINED" ], "description": "`BIOMETRIC_CONSENT_UNSUPPORTED_SDK`: o consentimento era obrigatório e um SDK nativo anterior a 4.10.0, ou que não comunicou a sua versão, capturou um rosto sem o passo de consentimento; `status` permanece `pending`, ou `given` se a pessoa tiver concordado posteriormente no fluxo alojado. `BIOMETRIC_CONSENT_DECLINED`: foi registada uma recusa (substitui o motivo do SDK). Caso contrário, `null`, e sempre `null` quando a sessão não exigiu consentimento." }, "decline_reason": { "type": "string", "nullable": true, "enum": [ "BIOMETRIC_CONSENT_DECLINED" ], "description": "`BIOMETRIC_CONSENT_DECLINED` quando uma recusa registada encerrou a sessão; caso contrário, `null`." }, "face_data_deleted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a recusa eliminou as imagens faciais, vídeos e templates biométricos da sessão. `null` a menos que tenha sido registada uma recusa." } } }, "investigator": { "$ref": "#/components/schemas/InvestigatorBlock" }, "biometric_retention": { "$ref": "#/components/schemas/BiometricRetention" }, "fraud_check": { "type": "object", "nullable": true, "additionalProperties": true, "description": "O resultado de uma chamada à API Fraud Check. `null` para qualquer outra sessão." }, "full_session_video": { "type": "string", "format": "uri", "nullable": true, "description": "URL temporário da gravação completa da sessão. Devolvido apenas quando a sua organização grava vídeo da sessão completa." }, "full_session_video_recorded_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a gravação de sessão completa foi feita. Devolvido apenas quando a sua organização grava vídeo de sessão completa." } } }, "WorkflowDetail": { "type": "object", "description": "Os campos abaixo são tipados; o objeto também contém todas as outras colunas da configuração do fluxo (comutadores de funcionalidades, limiares, ações de aviso, documentos permitidos, callbacks) como propriedades adicionais. Os campos que não se aplicam ao `workflow_type` são `null`.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador por versão (`settings_uuid`). Cada versão de um fluxo tem o seu próprio." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Identificador estável partilhado por todas as versões do fluxo. As sessões criadas com ele utilizam a versão publicada mais recente." }, "workflow_label": { "type": "string", "description": "Nome de apresentação do fluxo." }, "workflow_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", "adaptive_age_verification", "biometric_authentication", "address_verification", "questionnaire_verification", "email_verification", "phone_verification", null ], "description": "Modelo de fluxo. `null` para fluxos em grafo criados sem um modelo." }, "is_default": { "type": "boolean", "description": "Se este é o fluxo predefinido da aplicação." }, "is_archived": { "type": "boolean", "description": "Os fluxos arquivados não podem iniciar novas sessões." }, "version": { "type": "integer", "description": "Número da versão dentro do fluxo." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "As versões de rascunho são editáveis; as versões publicadas são imutáveis e utilizadas para novas sessões." }, "published_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando esta versão foi publicada. `null` para rascunhos." }, "is_simple_workflow": { "type": "boolean", "description": "`true` quando o fluxo não tem um `workflow_graph` personalizado." }, "is_editable": { "type": "boolean", "description": "`true` apenas para versões `draft`." }, "workflow_url": { "type": "string", "format": "uri", "description": "URL público que inicia uma sessão com este fluxo." }, "workflow_graph": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Estrutura em grafo do fluxo (nós e arestas). `null` para fluxos simples." }, "features": { "type": "string", "description": "Funcionalidades ativadas unidas por `\" + \"`, por exemplo `\"OCR + LIVENESS\"`." }, "total_price": { "type": "number", "nullable": true, "description": "Preço por sessão; para fluxos em grafo, o caminho mais caro." }, "min_price": { "type": "number", "nullable": true, "description": "Preço do caminho mais económico ao longo do fluxo." }, "max_price": { "type": "number", "nullable": true, "description": "Preço do caminho mais caro ao longo do fluxo." }, "special_add_on_prices": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Preços de suplementos específicos da organização, ou `null` quando nenhum estiver definido." }, "max_retry_attempts": { "type": "integer", "description": "Tentativas permitidas após uma verificação recusada." }, "retry_window_days": { "type": "integer", "nullable": true, "description": "Dias durante os quais as tentativas adicionais são permitidas." }, "session_expiration_time": { "type": "integer", "description": "Segundos até uma sessão inacabada expirar." }, "questionnaire": { "type": "object", "nullable": true, "additionalProperties": true, "description": "O questionário associado ao fluxo, ou `null`." }, "kyb_role_settings": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Definições de verificação por função para pessoas-chave de KYB." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "signature_availability": { "type": "object", "description": "Quais os níveis de Assinatura eletrónica que podem assinar neste momento. Verifique antes de definir `signature_level`. Devolvido em fluxos de `kyc`, `kyb` e de grafo.", "properties": { "simple": { "type": "boolean", "description": "Simple está sempre disponível." }, "aes": { "type": "boolean", "description": "Se o nível Avançado (AES) pode assinar agora. Enquanto for `false`, guardar um novo passo com `signature_level: \"aes\"` é recusado com `aes_not_available`." }, "qes": { "type": "boolean", "description": "Se o nível Qualificado (QES) pode assinar agora. É `false` até que um fornecedor qualificado esteja associado." } } }, "is_bank_verification_enabled": { "type": "boolean", "description": "Se um fluxo simples de KYC ou KYB executa a verificação bancária. É executada após os passos de contacto (e a verificação de localização) e antes da validação de base de dados, AML e análise de IP. A verificação bancária ainda não está disponível de forma geral: a sua ativação é recusada onde não estiver ativada." }, "bank_verification_config": { "type": "object", "additionalProperties": true, "description": "Definições de verificação bancária de um fluxo simples, com as mesmas chaves que um nó `BANK_VERIFICATION` aceita (por exemplo, `bank_countries` e `bank_method_order`). Chaves desconhecidas são ignoradas. Todas as chaves são opcionais e uma chave ausente mantém o seu valor predefinido, pelo que `{}` significa todas as predefinições. Consulte [Definições de verificação bancária](/pt/management-api/workflows/feature-configs#verificação-bancária).", "example": {} }, "is_geolocation_enabled": { "type": "boolean", "description": "Se um fluxo simples de KYC executa a verificação de localização. É executada após os passos de contacto e antes da verificação bancária e da validação de base de dados. Os fluxos de empresas (KYB) não a podem executar." }, "geolocation_config": { "type": "object", "additionalProperties": true, "description": "Definições de verificação de localização de um fluxo simples, com as mesmas chaves que um nó `GEOLOCATION` aceita (por exemplo `is_geolocation_geofencing_enabled` e `geolocation_max_attempts`). As chaves desconhecidas são ignoradas. Todas as chaves são opcionais e uma chave ausente mantém o seu valor padrão, pelo que `{}` significa todos os valores padrão.", "example": {} } }, "additionalProperties": true }, "UserSessionListItem": { "title": "KYC session row (session_kind: user)", "type": "object", "description": "Linha de resumo para uma sessão de Verificação de utilizadores (KYC). Os campos de identidade (`full_name`, `country`, `document_type`, `portrait_image`, campos de contacto) são preenchidos progressivamente à medida que o utilizador conclui os passos de verificação, ficando com valor `null` até à conclusão do passo relevante. Os campos restringidos pela configuração de response-attributes do fluxo também são devolvidos como `null`.", "required": [ "session_id", "session_kind", "session_number", "session_url", "portrait_image", "document_type", "full_name", "country", "status", "vendor_data", "didit_internal_id", "created_at", "features", "phone_number", "email_address", "additional_details" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Identificador único da sessão de verificação. Utilize-o com `GET /v3/session/{sessionId}/decision/` para obter o payload de decisão completo.", "example": "5b3720ed-d429-42ef-b67f-37ea805f48ee" }, "session_kind": { "type": "string", "enum": [ "user" ], "description": "Discriminador de linha. Sempre `\"user\"` para linhas de KYC; as linhas de Verificação de empresas (KYB) têm `\"business\"` e uma estrutura diferente.", "example": "user" }, "session_number": { "type": "integer", "description": "Número sequencial legível da sessão dentro da sua aplicação. Também utilizado pelo parâmetro `search` para fazer correspondências.", "example": 720 }, "session_url": { "type": "string", "nullable": true, "description": "URL de verificação alojado que o utilizador final abre para concluir o fluxo. `null` quando a sessão não tem URL alojado.", "example": "https://verify.didit.me/session/CuXoBYCYVO5Y" }, "portrait_image": { "type": "string", "nullable": true, "description": "URL temporário (pré-assinado) do melhor retrato disponível: a fotografia do chip NFC quando disponível, caso contrário o retrato do documento de identificação, caso contrário a imagem de referência da prova de vida. `null` até que um deles exista. Transfira prontamente; a ligação expira.", "example": "https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=..." }, "document_type": { "type": "string", "nullable": true, "enum": [ "Passport", "Identity Card", "Driver's License", "Residence Permit", "Health Insurance Card", "Tax Card" ], "description": "Tipo legível por humanos do documento de identificação verificado. `null` antes da conclusão da verificação do documento, e também `null` após a conclusão quando o código verificado não tem mapeamento de apresentação (`SSC`, `WP`, `VISA`, `PSC`, `BC`, `OTHER`). Nota: o parâmetro de consulta `document_type` filtra por códigos curtos (`P`, `ID`, `DL`, `RP`, ...), não por estes valores de apresentação.", "example": "Passport" }, "full_name": { "type": "string", "nullable": true, "description": "Melhor nome completo disponível para a sessão, resolvido pela ordem: OCR do documento de identificação, dados analisados na triagem AML, dados analisados na validação de base de dados, documento de comprovativo de morada e, em seguida, os detalhes esperados fornecidos na criação da sessão. `null` quando nenhum estiver ainda disponível.", "example": "Jane Marie Doe" }, "country": { "type": "string", "nullable": true, "description": "País ISO 3166-1 alfa-3 associado à sessão, resolvido por ordem: estado emissor do documento de identificação, estado emissor da validação de base de dados, estado emissor do comprovativo de morada, detalhes esperados e, por fim, o país do telefone verificado. Pode diferir da nacionalidade.", "example": "ESP" }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Estado global da sessão. Consulte a página [Estados de verificação](/pt/integration/verification-statuses) para o ciclo de vida.", "example": "Approved" }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu próprio identificador para o utilizador final, devolvido exatamente como foi enviado na criação da sessão.", "example": "your-user-id-123" }, "didit_internal_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Identificador interno da Didit para o perfil de utilizador verificado associado a esta sessão. Estável entre múltiplas sessões do mesmo utilizador; filtrável através do parâmetro de consulta `didit_internal_id`.", "example": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147" }, "created_at": { "type": "string", "format": "date-time", "description": "Marca temporal UTC da criação da sessão.", "example": "2026-06-09T12:26:54.328364Z" }, "features": { "type": "array", "description": "Estado por funcionalidade para cada passo de verificação configurado no fluxo da sessão, pela ordem do fluxo.", "items": { "type": "object", "required": [ "feature", "status" ], "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACE_MATCH", "POA", "QUESTIONNAIRE", "EMAIL_VERIFICATION", "PHONE", "AML", "IP_ANALYSIS", "AGE_ESTIMATION", "DATABASE_VALIDATION", "GEOLOCATION" ], "description": "Identificador da funcionalidade de verificação.", "example": "ID_VERIFICATION" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado desta funcionalidade. `Not Finished` até o passo estar concluído.", "example": "Approved" } } } }, "phone_number": { "type": "object", "nullable": true, "description": "Telefone associado à sessão: o telefone verificado quando a verificação de telefone foi executada; caso contrário, o telefone de contacto fornecido na criação da sessão. `null` quando nenhum existir.", "required": [ "number", "is_verified" ], "properties": { "number": { "type": "string", "description": "Número de telefone no formato E.164.", "example": "+14155552671" }, "is_verified": { "type": "boolean", "description": "`true` apenas quando a funcionalidade de verificação de telefone tiver aprovado este número.", "example": true } } }, "email_address": { "type": "object", "nullable": true, "description": "E-mail associado à sessão: o e-mail verificado quando a verificação de e-mail foi executada; caso contrário, o e-mail de contacto fornecido na criação da sessão. `null` quando nenhum existe.", "required": [ "email", "is_verified" ], "properties": { "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "is_verified": { "type": "boolean", "description": "`true` apenas quando a funcionalidade de verificação de e-mail tiver aprovado este endereço.", "example": true } } }, "additional_details": { "type": "object", "nullable": true, "description": "Dados adicionais compactos por funcionalidade. Apenas as funcionalidades que produziram dados aparecem como chaves; `null` quando nenhuma funcionalidade produziu dados adicionais. Os campos excluídos pela configuração dos atributos da resposta do fluxo são omitidos.", "properties": { "aml": { "type": "object", "description": "Presente quando a Triagem AML foi executada.", "properties": { "total_hits": { "type": "integer", "description": "Número de correspondências de triagem AML.", "example": 0 }, "entity_type": { "type": "string", "description": "Tipo de entidade submetida a triagem.", "example": "person" }, "is_adverse_media_fetched": { "type": "boolean", "example": false }, "screened_data": { "type": "object", "description": "Subconjunto dos dados analisados. Apenas são incluídas chaves não vazias.", "properties": { "nationality": { "type": "string", "example": "ESP" }, "document_number": { "type": "string", "example": "XX1234567" }, "date_of_birth": { "type": "string", "example": "1990-05-21" } } } } }, "database_validation": { "type": "object", "description": "Presente quando a validação de base de dados foi executada.", "properties": { "validation_type": { "type": "string", "example": "DOCUMENT_VALIDATION" }, "match_type": { "type": "string", "example": "FULL_MATCH" }, "identification_number": { "type": "string", "description": "Número fiscal, pessoal ou do documento que foi validado (primeiro disponível).", "example": "12345678Z" } } }, "poa": { "type": "object", "description": "Presente quando foi efetuada a verificação do comprovativo de morada.", "properties": { "document_type": { "type": "string", "example": "UTILITY_BILL" }, "issuer": { "type": "string", "example": "Energy Co" }, "address": { "type": "string", "example": "Calle Mayor 1, 28013 Madrid" }, "name_on_document": { "type": "string", "example": "Jane Marie Doe" } } }, "liveness": { "type": "object", "description": "Presente quando uma verificação de prova de vida foi executada.", "properties": { "method": { "type": "string", "example": "PASSIVE" }, "score": { "type": "number", "description": "Pontuação de confiança da prova de vida, arredondada a 2 casas decimais.", "example": 0.98 } } }, "face_match": { "type": "object", "description": "Presente quando a correspondência facial foi executada.", "properties": { "score": { "type": "number", "description": "Pontuação de semelhança da correspondência facial, arredondada a 2 casas decimais.", "example": 0.95 }, "source_image": { "type": "string", "description": "URL temporário (pré-assinado) da imagem facial de origem.", "example": "https:///faces/source.jpg?X-Amz-Expires=3600&..." }, "target_image": { "type": "string", "description": "URL temporário (pré-assinado) da imagem facial de destino.", "example": "https:///faces/target.jpg?X-Amz-Expires=3600&..." } } }, "phone_verification": { "type": "object", "description": "Presente quando a verificação de telefone foi executada.", "properties": { "country_code": { "type": "string", "description": "País ISO 3166-1 alfa-2 do número de telefone.", "example": "US" }, "is_temporary": { "type": "boolean", "example": false }, "is_ported": { "type": "boolean", "example": false }, "is_blocked": { "type": "boolean", "example": false } } }, "email_verification": { "type": "object", "description": "Presente quando a verificação de e-mail foi executada.", "properties": { "is_breached": { "type": "boolean", "example": false }, "is_disposable": { "type": "boolean", "example": false }, "is_undeliverable": { "type": "boolean", "example": false }, "is_blocklisted": { "type": "boolean", "example": false } } } } }, "assignee": { "type": "object", "nullable": true, "description": "O revisor da consola ao qual a sessão está atribuída, ou `null` quando não está atribuída a ninguém.", "properties": { "email": { "type": "string", "format": "email" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true } } }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a sessão começou a aguardar revisão. `null` a menos que a sessão esteja `In Review`." }, "sla_due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a revisão deve ser concluída, a partir do prazo de revisão definido para a sua aplicação na Console. `null` a menos que a sessão esteja `In Review` e um prazo esteja definido." }, "top_warnings": { "type": "array", "description": "Até alguns dos avisos mais importantes da sessão, para uma vista rápida de triagem. A lista completa está na decisão.", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "Código de aviso, por exemplo `FACE_MATCH_LOW_SIMILARITY`." }, "feature": { "type": "string", "description": "A funcionalidade que o gerou." }, "log_type": { "type": "string", "nullable": true, "description": "`error` ou `warning`; `null` para uma entrada legada." }, "short_description": { "type": "string" } } } }, "warnings_count": { "type": "integer", "description": "Número de avisos na sessão." } } }, "BusinessSessionListItem": { "title": "KYB session row (session_kind: business)", "type": "object", "description": "Linha de resumo para uma sessão de Verificação de empresas (KYB). Devolvida apenas quando `session_kind` for `business` ou `all`.", "required": [ "session_id", "session_kind", "session_number", "status", "vendor_data", "created_at", "workflow_id", "workflow_type", "workflow_label", "company_name", "registration_number", "country" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Identificador único da sessão de Verificação de empresas (KYB).", "example": "8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52" }, "session_kind": { "type": "string", "enum": [ "business" ], "description": "Discriminador de linha. Sempre `\"business\"` para linhas de KYB.", "example": "business" }, "session_number": { "type": "integer", "description": "Número sequencial legível da sessão de empresa dentro da sua aplicação. Numerado de forma independente das sessões de KYC.", "example": 42 }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Estado global da sessão. Consulte a página [Estados de verificação](/pt/integration/verification-statuses).", "example": "Approved" }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu próprio identificador para a empresa, devolvido exatamente como foi enviado na criação da sessão.", "example": "your-company-id-77" }, "created_at": { "type": "string", "format": "date-time", "description": "Marca temporal UTC da criação da sessão.", "example": "2026-06-08T09:14:02.118450Z" }, "workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Identificador do fluxo com o qual esta sessão foi criada.", "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, "workflow_type": { "type": "string", "nullable": true, "description": "Tipo de fluxo. `kyb` para fluxos de empresas.", "example": "kyb" }, "workflow_label": { "type": "string", "nullable": true, "description": "Nome de apresentação do fluxo.", "example": "Standard KYB" }, "company_name": { "type": "string", "nullable": true, "description": "Nome da empresa que está a ser verificada, proveniente da empresa do registo associada à sessão. `null` até que uma empresa seja selecionada.", "example": "Acme Holdings S.L." }, "registration_number": { "type": "string", "nullable": true, "description": "Número de registo da empresa do registo associada à sessão.", "example": "B12345678" }, "country": { "type": "string", "nullable": true, "description": "Código de país da empresa do registo associada à sessão.", "example": "ES" } } }, "TransactionVerificationSessionAction": { "title": "Verification session", "type": "object", "properties": { "type": { "type": "string", "enum": [ "verification_session" ] }, "url": { "type": "string", "format": "uri", "description": "URL de verificação alojado a abrir para o utilizador final." }, "session_id": { "type": "string", "format": "uuid", "description": "ID da sessão de verificação." }, "session_token": { "type": "string", "description": "Token de sessão, utilizado pelos SDKs móveis para iniciar o fluxo nativamente." }, "status": { "type": "string", "description": "Estado da sessão de verificação." } }, "required": [ "type", "url" ] }, "TransactionWalletOwnershipAction": { "title": "Wallet ownership", "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet_ownership" ] }, "url": { "type": "string", "format": "uri", "description": "URL do widget alojado de propriedade de carteira. Abra-o num navegador real - em dispositivos móveis, utilize SFSafariViewController ou um Chrome Custom Tab, nunca uma webview incorporada." }, "widget_session_id": { "type": "string", "format": "uuid", "description": "ID de sessão do widget de propriedade da carteira." }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando a sessão do widget expira." } }, "required": [ "type", "url" ] }, "TransactionRuleActionAddScore": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "add_score" ] }, "value": { "type": "integer", "description": "Pontos adicionados à pontuação de risco da transação. Podem ser negativos." } }, "description": "Adicione pontos à pontuação de risco cumulativa da transação; o total decide o estado através dos limiares de revisão/recusa da aplicação." }, "TransactionRuleActionChangeStatus": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "change_status" ] }, "value": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Estado a definir imediatamente, independentemente da pontuação. Chave de alias: status." }, "workflow_id": { "type": "string", "format": "uuid", "description": "OBRIGATÓRIO quando o valor é AWAITING_USER: o fluxo de verificação que o sujeito deve concluir. Chave alternativa: remediation_workflow_id. A Didit cria uma sessão de remediação alojada para o sujeito quando a regra é acionada." } }, "description": "Definir diretamente o estado da transação. DECLINED tem sempre prioridade entre as regras correspondentes." }, "TransactionRuleActionAddTags": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "add_tags" ] }, "tag_uuid": { "type": "string", "format": "uuid", "description": "Etiqueta da aplicação existente a associar." }, "tag_name": { "type": "string", "description": "Nome da etiqueta a associar; criada na primeira utilização (guardada em maiúsculas). Forneça tag_uuid ou tag_name." }, "tag_color": { "type": "string", "description": "Cor hexadecimal utilizada quando tag_name cria uma nova etiqueta, ex.: #007AFE." } }, "description": "Anexar uma etiqueta da aplicação à transação correspondida." }, "TransactionRuleActionAddNote": { "type": "object", "required": [ "type", "note" ], "properties": { "type": { "type": "string", "enum": [ "add_note" ] }, "note": { "type": "string", "description": "Texto da nota anexado à transação (autor: Rule Engine). Chave do alias: valor." } }, "description": "Anexar uma nota de analista automatizada à transação correspondida." }, "TransactionRuleActionAddToList": { "type": "object", "required": [ "type", "list_id" ], "properties": { "type": { "type": "string", "enum": [ "add_to_list" ] }, "list_id": { "type": "string", "format": "uuid", "description": "Lista à qual adicionar os vendor_data do sujeito." } }, "description": "Adicione o vendor_data do sujeito a uma lista de bloqueio, lista de permissões ou lista personalizada." }, "TransactionRuleActionOpenCase": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "open_case" ] }, "blueprint": { "type": "string", "format": "uuid", "description": "UUID do blueprint do caso; assume por predefinição o blueprint predefinido da aplicação." }, "grouping": { "type": "string", "enum": [ "by_applicant", "by_rule_and_applicant" ], "description": "Se as correspondências repetidas são agrupadas num único caso por requerente ou um por regra+requerente." }, "attach_matched_transaction": { "type": "boolean", "description": "Anexar a transação correspondida ao caso." } }, "description": "Abrir um caso de investigação (ou adicionar a um caso existente). Apenas a primeira ação open_case numa regra é aplicada." }, "KYBRegistrySearchResults": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "kyb_response_id": { "type": "string", "nullable": true, "description": "Identificador para este candidato — passe-o para `POST /v3/kyb/select/` para obter o perfil completo. Efémero e limitado a esta pesquisa: não o guarde a longo prazo; pesquise novamente para obter um novo.", "example": "69aeeb95febb0f1704042259" }, "name": { "type": "string", "nullable": true, "description": "Nome registado da empresa.", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "description": "Número de registo.", "example": "00445790" }, "status": { "type": "string", "nullable": true, "description": "Estado normalizado da empresa no registo de empresas (por exemplo, `active`, `dissolved`, `inactive`, `struck off`).", "example": "active" }, "type": { "type": "string", "nullable": true, "description": "Forma jurídica comunicada pelo registo.", "example": "Public Limited Company" }, "registered_address": { "type": "string", "nullable": true, "description": "Morada registada do candidato, quando o registo devolve uma. Utilize-a, juntamente com o número de registo, para distinguir empresas com o mesmo nome: nos Estados Unidos, um candidato pode constar sob o estado onde a empresa opera em vez do estado que pesquisou.", "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA" }, "risk_level": { "type": "string", "nullable": true, "description": "Nível de risco reportado pelo registo de empresas, quando disponível. Geralmente `null` no momento da pesquisa." }, "fetch_status": { "type": "string", "nullable": true, "description": "Sempre `pending` para candidatos de pesquisa — o perfil completo da empresa só é obtido (e faturado) quando seleciona o candidato.", "example": "pending" } } }, "description": "Lista desduplicada de candidatos. Vazia enquanto `search_resolved=false` (modo webhook) ou quando não houver correspondências." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Número de candidatos devolvidos." }, "page": { "type": "integer" }, "per_page": { "type": "integer", "example": 25 } } }, "search_status": { "type": "string", "nullable": true, "enum": [ "pending", "resolved" ], "description": "Estado do ciclo de vida da pesquisa no registo de empresas." }, "search_resolved": { "type": "boolean", "description": "`true` assim que a lista de candidatos for final." } } }, "KYBRegistryCandidateRequest": { "type": "object", "required": [ "kyb_response_id" ], "properties": { "kyb_response_id": { "type": "string", "maxLength": 1024, "description": "Identificador de candidato de `POST /v3/kyb/search/` (`kyb_registry.companies[].kyb_response_id`). Efémero: utilize-o pouco depois da pesquisa que o gerou. Os identificadores podem ser longos, pelo que deve armazenar e enviar o valor exatamente como devolvido, sem remover espaços em branco nem assumir um comprimento.", "example": "69aeeb95febb0f1704042259" }, "vendor_data": { "type": "string", "description": "O seu identificador para esta empresa; devolvido e armazenado com a sessão da empresa." }, "metadata": { "type": "object", "nullable": true, "description": "JSON de formato livre armazenado com a sessão de empresa e devolvido na resposta." }, "save_api_request": { "type": "boolean", "default": true, "description": "Tem de ser `true` (o valor predefinido). As seleções de registo KYB são sempre persistidas para que a faturação e a recuperação possam ser monitorizadas; `false` devolve `400`." } } }, "WebhookEventEnvelope": { "type": "object", "description": "Campos que a Didit adiciona a cada entrega de webhook assinada, qualquer que seja o tipo de evento. Leia `webhook_type` para saber qual payload recebeu.", "required": [ "event_id", "webhook_type", "timestamp", "created_at", "application_id", "environment" ], "properties": { "event_id": { "type": "string", "format": "uuid", "description": "Identificador do evento. Todos os destinos recebem o mesmo valor e um reenvio mantém-no, pelo que deve usá-lo para desduplicação." }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "timestamp": { "type": "integer", "description": "Hora Unix em segundos na qual esta entrega foi assinada. Igual ao cabeçalho `X-Timestamp`; uma nova entrega inclui um novo valor." }, "created_at": { "type": "integer", "description": "Hora Unix em segundos da alteração que produziu o evento." }, "application_id": { "type": "string", "format": "uuid", "description": "A aplicação à qual o evento pertence." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "`sandbox` para sessões de sandbox e aplicações de sandbox; caso contrário, `live`." } } }, "SessionWebhookEventData": { "type": "object", "description": "Campos da sessão de `status.updated` e `data.updated`. Os campos opcionais são omitidos, nunca enviados como `null`, quando não se aplicam. As sessões empresariais (KYB) adicionam `business_session_id`, `session_kind` e `vendor_business_id`.", "required": [ "session_id", "status", "sandbox_scenario" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "A sessão de verificação." }, "business_session_id": { "type": "string", "format": "uuid", "description": "Apenas sessões de empresa (KYB): o mesmo valor que `session_id`." }, "session_kind": { "type": "string", "enum": [ "business" ], "description": "Apenas sessões de empresa (KYB). Os eventos de sessão de utilizador (KYC) não contêm `session_kind` de nível superior; leia `decision.session_kind` em alternativa." }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Estado da sessão após a alteração." }, "trigger": { "type": "string", "description": "Presente quando o evento não foi produzido pelo próprio fluxo de verificação, por exemplo `manual_review`, `manual_step_update`, `ongoing_monitoring`, `webhook_reconciliation` (um `status.updated` reenviado porque o primeiro webhook terminal nunca foi criado, pelo que poderá receber um segundo evento para uma decisão que já obteve: desduplique por `session_id` e `status`), `manual_webhook_recovery`, `kyb_registry_change`, `biometric_retention` (um `data.updated` enviado quando os dados biométricos ativos da sessão são eliminados conforme programado) ou uma edição `console_*` como `console_registry_edit`, `console_key_people_skip` ou `console_key_people_regenerate`." }, "workflow_id": { "type": "string", "format": "uuid", "description": "O fluxo da sessão. Omitido quando a sessão não tem nenhum." }, "workflow_version": { "type": "integer", "description": "Versão do fluxo que a sessão executou. Enviada juntamente com `workflow_id`." }, "vendor_data": { "type": "string", "description": "O seu `vendor_data` para a sessão. Omitido quando vazio." }, "vendor_business_id": { "type": "string", "description": "Apenas sessões de empresa (KYB): a empresa à qual a sessão pertence. Omitido quando não existe." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Os `metadata` da sua sessão. Omitido quando vazio." }, "decision": { "$ref": "#/components/schemas/SessionDecision" }, "resubmit_info": { "type": "object", "description": "Apenas quando `status` é `Resubmitted`: os passos que o utilizador tem de refazer e o respetivo motivo.", "required": [ "nodes_to_resubmit", "reasons" ], "properties": { "nodes_to_resubmit": { "type": "array", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "Identificador do nó tal como aparece na definição do fluxo da sessão (por exemplo `feature_ocr`, `feature_liveness`).", "example": "feature_poa" }, "feature": { "type": "string", "description": "Tipo de funcionalidade do nó, por exemplo `OCR`, `LIVENESS` ou `PROOF_OF_ADDRESS`.", "example": "PROOF_OF_ADDRESS" } } }, "description": "Passos do fluxo que o utilizador deve repetir. As mesmas entradas `{node_id, feature}` de `nodes_to_resubmit` em [Atualizar estado](#patch-/v3/session/-sessionId-/update-status/)." }, "reasons": { "type": "object", "additionalProperties": true, "description": "Motivo por `node_id` em `nodes_to_resubmit`." } } }, "sandbox_scenario": { "type": "string", "nullable": true, "description": "O resultado simulado preparado numa sessão em sandbox, ou `null`. Sempre `null` para sessões de produção." } } }, "SessionStatusUpdatedEvent": { "description": "Uma sessão de verificação mudou de estado. `decision` só é enviado para `Approved`, `Declined`, `In Review` e `Abandoned`; tem o formato de `GET /v3/session/{sessionId}/decision/` para destinos na versão 3 de webhooks (a predefinida), e o formato reduzido anterior para destinos nas versões 1 ou 2. As sessões de empresas recebem sempre a decisão de empresa da versão 3.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "$ref": "#/components/schemas/SessionWebhookEventData" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "status.updated" ], "description": "Sempre `status.updated`." } }, "required": [ "webhook_type" ] } ] }, "SessionDataUpdatedEvent": { "description": "Os dados de uma sessão de verificação foram alterados sem alteração de estado, por exemplo, após a edição de uma revisão manual, uma substituição de passo ou uma nova triagem de monitorização contínua. `decision` é enviado apenas para `Approved`, `Declined`, `In Review` e `Abandoned`; tem o formato de `GET /v3/session/{sessionId}/decision/` para destinos na versão 3 de webhook (a predefinição), e o formato reduzido anterior para destinos nas versões 1 ou 2. As sessões de empresas recebem sempre a decisão de empresa na versão 3.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "$ref": "#/components/schemas/SessionWebhookEventData" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "data.updated" ], "description": "Sempre `data.updated`." } }, "required": [ "webhook_type" ] } ] }, "UserStatusUpdatedEvent": { "description": "Um utilizador mudou de estado. Não é enviado quando o utilizador é criado.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "user.status.updated" ], "description": "Sempre `user.status.updated`." }, "vendor_user_id": { "type": "string", "format": "uuid", "description": "O utilizador a quem o evento diz respeito." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu `vendor_data` para o utilizador, ou `null`." }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Estado do utilizador após a alteração." }, "previous_status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Estado antes da alteração." } }, "required": [ "webhook_type", "vendor_user_id", "vendor_data", "status", "previous_status" ] } ] }, "UserDataUpdatedEvent": { "description": "Campos de um utilizador alterados. Não é enviado quando o utilizador é criado. Uma única gravação pode produzir tanto um evento de estado como de dados.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "user.data.updated" ], "description": "Sempre `user.data.updated`." }, "vendor_user_id": { "type": "string", "format": "uuid", "description": "O utilizador a quem o evento diz respeito." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu `vendor_data` para o utilizador, ou `null`." }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Estado do utilizador após a alteração." }, "changed_fields": { "type": "array", "items": { "type": "string", "enum": [ "vendor_data", "display_name", "full_name", "date_of_birth", "metadata", "portrait_image", "issuing_states", "approved_emails", "approved_phones", "features", "session_count", "approved_count", "declined_count", "in_review_count", "first_session_at", "last_session_at" ] }, "description": "Nomes dos campos que foram alterados." }, "changes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "previous": { "nullable": true, "description": "Valor antes da alteração. As datas são strings ISO 8601." }, "current": { "nullable": true, "description": "Valor após a alteração. As datas são strings ISO 8601." } } }, "description": "Valor anterior e atual de cada campo alterado, indexado pelo nome do campo. Os valores podem ser dados pessoais (nomes, datas de nascimento, ligações de retratos, e-mails, números de telefone); processe-os em conformidade." } }, "required": [ "webhook_type", "vendor_user_id", "vendor_data", "status", "changed_fields", "changes" ] } ] }, "BusinessStatusUpdatedEvent": { "description": "Uma empresa mudou de estado. Não é enviado quando a empresa é criada.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "business.status.updated" ], "description": "Sempre `business.status.updated`." }, "vendor_business_id": { "type": "string", "format": "uuid", "description": "A empresa à qual o evento diz respeito." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu `vendor_data` para a empresa, ou `null`." }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Estado da empresa após a alteração." }, "previous_status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Estado antes da alteração." } }, "required": [ "webhook_type", "vendor_business_id", "vendor_data", "status", "previous_status" ] } ] }, "BusinessDataUpdatedEvent": { "description": "Campos de uma empresa alterados. Não é enviado quando a empresa é criada. Uma única gravação pode produzir tanto um evento de estado como de dados.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "business.data.updated" ], "description": "Sempre `business.data.updated`." }, "vendor_business_id": { "type": "string", "format": "uuid", "description": "A empresa à qual o evento diz respeito." }, "vendor_data": { "type": "string", "nullable": true, "description": "O seu `vendor_data` para a empresa, ou `null`." }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Estado da empresa após a alteração." }, "changed_fields": { "type": "array", "items": { "type": "string", "enum": [ "vendor_data", "display_name", "metadata", "legal_name", "registration_number", "country_code", "session_count", "approved_count", "declined_count", "in_review_count", "features", "first_session_at", "last_session_at" ] }, "description": "Nomes dos campos que foram alterados." }, "changes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "previous": { "nullable": true, "description": "Valor antes da alteração. As datas são strings ISO 8601." }, "current": { "nullable": true, "description": "Valor após a alteração. As datas são strings ISO 8601." } } }, "description": "Valor anterior e atual de cada campo alterado, indexado pelo nome do campo." } }, "required": [ "webhook_type", "vendor_business_id", "vendor_data", "status", "changed_fields", "changes" ] } ] }, "TransactionCreatedEvent": { "description": "Uma transação foi criada e analisada. Enviado apenas para aplicações em produção.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction.created" ], "description": "Sempre `transaction.created`." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Identificador da transação da Didit." }, "txn_id": { "type": "string", "nullable": true, "description": "O `transaction_id` que indicou no momento da criação, ou `null`." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Estado da monitorização após a alteração." }, "score": { "type": "integer", "description": "Pontuação de risco acumulada por regras." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "Gravidade do risco, ou `null` até que uma regra ou fornecedor a defina." }, "amount": { "type": "string", "description": "Montante da transação como uma string decimal. Ao contrário da API, não é normalizado, pelo que pode conter zeros à direita (até 18 casas decimais)." }, "currency": { "type": "string", "description": "Código de moeda ou símbolo de ativo criptográfico de `amount`." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direção em relação ao sujeito." }, "action_required": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } }, "description": "Ação pendente do utilizador final, ou `null`. O mesmo objeto que `action_required` na transação; `session_token` é uma credencial, pelo que nunca a deve registar em logs." } }, "required": [ "webhook_type", "transaction_id", "txn_id", "status", "score", "severity", "amount", "currency", "direction", "action_required" ] } ] }, "TransactionStatusUpdatedEvent": { "description": "Uma transação mudou de estado, a partir de uma regra, de uma revisão ou de uma ação do utilizador final. Enviado apenas para aplicações em produção.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction.status.updated" ], "description": "Sempre `transaction.status.updated`." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Identificador da transação da Didit." }, "txn_id": { "type": "string", "nullable": true, "description": "O `transaction_id` que indicou no momento da criação, ou `null`." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Estado da monitorização após a alteração." }, "score": { "type": "integer", "description": "Pontuação de risco acumulada por regras." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "Gravidade do risco, ou `null` até que uma regra ou fornecedor a defina." }, "amount": { "type": "string", "description": "Montante da transação como uma string decimal. Ao contrário da API, não é normalizado, pelo que pode conter zeros à direita (até 18 casas decimais)." }, "currency": { "type": "string", "description": "Código de moeda ou símbolo de ativo criptográfico de `amount`." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direção em relação ao sujeito." }, "action_required": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } }, "description": "Ação pendente do utilizador final, ou `null`. O mesmo objeto que `action_required` na transação; `session_token` é uma credencial, pelo que nunca a deve registar em logs." } }, "required": [ "webhook_type", "transaction_id", "txn_id", "status", "score", "severity", "amount", "currency", "direction", "action_required" ] } ] }, "TravelRuleStatusUpdatedEvent": { "description": "Uma troca de Travel Rule mudou de estado. É enviado em cada transição até `FINISHED`, `CANCELLED` ou `EXPIRED`, inclusive, e nunca depois. Enviado para aplicações de produção e, no caso de trocas de Travel Rule, também para aplicações sandbox (`environment: sandbox`). Não existe nenhum `status` de nível superior.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "travel_rule.status.updated" ], "description": "Sempre `travel_rule.status.updated`." }, "transaction_id": { "type": "string", "format": "uuid", "description": "A transação à qual a troca pertence." }, "txn_id": { "type": "string", "nullable": true, "description": "O `transaction_id` que indicou no momento da criação, ou `null`." }, "travel_rule_status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ], "description": "Estado da troca após a alteração." }, "rail": { "type": "string", "enum": [ "", "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP" ], "description": "Rede em que a exchange opera, ou uma string vazia quando nenhuma pôde ser resolvida. `TEST_VASP` é uma transferência de sandbox à qual o Didit Test VASP respondeu." }, "test_vasp": { "type": "boolean", "description": "Presente e `true` apenas numa transferência de sandbox à qual o VASP de teste da Didit respondeu." }, "test_vasp_scenario": { "type": "string", "description": "Presente apenas com `test_vasp`: o cenário de sandbox que decidiu o resultado, ou uma cadeia vazia." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direção da transferência." } }, "required": [ "webhook_type", "transaction_id", "txn_id", "travel_rule_status", "rail", "direction" ] } ] }, "WorkflowComplianceChangedEvent": { "description": "O estado de conformidade de um fluxo publicado mudou após uma reavaliação. Um evento por fluxo. Não existe um `status` de nível superior.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "workflow.compliance_changed" ], "description": "Sempre `workflow.compliance_changed`." }, "workflow_id": { "type": "string", "format": "uuid", "description": "O fluxo que foi alterado." }, "workflow_version": { "type": "integer", "description": "Versão que foi avaliada." }, "workflow_label": { "type": "string", "nullable": true, "description": "Nome de apresentação do fluxo." }, "transition": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "enum": [ "compliant", "gaps_detected", "pending_change", "unknown_coverage", "not_evaluated" ], "description": "Estado antes da reavaliação." }, "to": { "type": "string", "enum": [ "compliant", "gaps_detected", "pending_change", "unknown_coverage", "not_evaluated" ], "description": "Estado após a reavaliação." } } }, "severity": { "type": "string", "enum": [ "actionable", "indicative", "informative" ], "description": "`actionable` quando foram detetadas lacunas, `indicative` para uma alteração pendente, `informative` quando as lacunas foram resolvidas." }, "kb_version": { "type": "string", "description": "Versão da base de conhecimento regulamentar utilizada." } }, "required": [ "webhook_type", "workflow_id", "workflow_version", "workflow_label", "transition", "severity", "kb_version" ] } ] }, "WebhookEventPayload": { "description": "Corpo de uma entrega de webhook assinada, distinguido por `webhook_type`. `activity.created` pode ser subscrito, mas atualmente não é enviado. Trate qualquer outro `webhook_type` como um novo tipo de evento e mantenha o corpo em bruto.", "oneOf": [ { "$ref": "#/components/schemas/SessionStatusUpdatedEvent" }, { "$ref": "#/components/schemas/SessionDataUpdatedEvent" }, { "$ref": "#/components/schemas/UserStatusUpdatedEvent" }, { "$ref": "#/components/schemas/UserDataUpdatedEvent" }, { "$ref": "#/components/schemas/BusinessStatusUpdatedEvent" }, { "$ref": "#/components/schemas/BusinessDataUpdatedEvent" }, { "$ref": "#/components/schemas/TransactionCreatedEvent" }, { "$ref": "#/components/schemas/TransactionStatusUpdatedEvent" }, { "$ref": "#/components/schemas/TravelRuleStatusUpdatedEvent" }, { "$ref": "#/components/schemas/WorkflowComplianceChangedEvent" }, { "$ref": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } ], "discriminator": { "propertyName": "webhook_type", "mapping": { "status.updated": "#/components/schemas/SessionStatusUpdatedEvent", "data.updated": "#/components/schemas/SessionDataUpdatedEvent", "user.status.updated": "#/components/schemas/UserStatusUpdatedEvent", "user.data.updated": "#/components/schemas/UserDataUpdatedEvent", "business.status.updated": "#/components/schemas/BusinessStatusUpdatedEvent", "business.data.updated": "#/components/schemas/BusinessDataUpdatedEvent", "transaction.created": "#/components/schemas/TransactionCreatedEvent", "transaction.status.updated": "#/components/schemas/TransactionStatusUpdatedEvent", "travel_rule.status.updated": "#/components/schemas/TravelRuleStatusUpdatedEvent", "workflow.compliance_changed": "#/components/schemas/WorkflowComplianceChangedEvent", "transaction_rule_suggestions.created": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } } }, "KYBRegistrySearchResolvedCallback": { "type": "object", "description": "Corpo do retorno de chamada enviado para o `webhook_url` de `POST /v3/kyb/search/` assim que a pesquisa no registo for resolvida. Não é assinado: o pedido inclui `X-Didit-Unsigned-Callback: true` e nenhum dos cabeçalhos de assinatura; portanto, confirme-o comparando o `request_id` com o de uma pesquisa que iniciou. Utiliza `event_type`, e não `webhook_type`.", "required": [ "event_id", "event_type", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at" ], "properties": { "event_id": { "type": "string", "format": "uuid", "description": "Identificador do callback." }, "event_type": { "type": "string", "enum": [ "kyb.registry_search.resolved" ], "description": "Sempre `kyb.registry_search.resolved`." }, "request_id": { "type": "string", "format": "uuid", "description": "O `request_id` devolvido por `POST /v3/kyb/search/`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco do `vendor_data` que enviou." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco do objeto `metadata` que enviou." }, "search_status": { "type": "string", "description": "Sempre `resolved` atualmente." }, "search_resolved": { "type": "boolean", "description": "`true` quando `search_status` é `resolved`." }, "kyb_registry": { "$ref": "#/components/schemas/KYBRegistrySearchResults" }, "timestamp": { "type": "integer", "description": "Hora Unix em segundos na qual o retorno foi colocado na fila." }, "created_at": { "type": "integer", "description": "Hora Unix em segundos na qual o retorno foi colocado na fila." } } }, "AMLScreening": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Identificador exclusivo para este passo de AML no grafo do fluxo." }, "status": { "type": "string", "description": "Estado ao nível da funcionalidade desta triagem AML. Independente do `status` da sessão de nível superior — uma sessão pode alcançar a sua decisão global enquanto uma funcionalidade individual permanece `In Review`.", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ] }, "total_hits": { "type": "integer", "description": "Número total de correspondências encontradas" }, "entity_type": { "type": "string", "description": "Tipo de entidade analisada: pessoa ou empresa" }, "hits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador estável da Didit para o resultado (hit): `hit_` seguido de 24 carateres hexadecimais. A mesma entidade correspondente mantém o mesmo `id` quando o sujeito é novamente analisado. Transmita-o como `hit_id` para os endpoints de revisão de resultados AML." }, "url": { "type": "string", "format": "uri", "description": "URL de origem para a correspondência" }, "match": { "type": "boolean", "description": "Se esta é uma correspondência confirmada" }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 1, "description": "Pontuação de correspondência ponderada descontinuada no intervalo 0-1 (por exemplo, `0.73`). Utilize `match_score` (0-100) em alternativa.", "deprecated": true }, "target": { "type": "boolean", "nullable": true, "description": "Indica se a entidade correspondente é o alvo direto da listagem (em oposição a uma parte relacionada). `null` quando a fonte não o especificar." }, "caption": { "type": "string", "description": "Legenda ou título da correspondência" }, "datasets": { "type": "array", "items": { "type": "string", "enum": [ "PEP", "PEP Level 1", "PEP Level 2", "PEP Level 3", "PEP Level 4", "Sanctions", "Adverse Media", "Warnings and Regulatory Enforcement", "Fitness and Probity", "SIP", "SIE", "Insolvency", "Other Lists" ] }, "description": "Lista de categorias de conjuntos de dados onde a correspondência foi encontrada. Indica se a entidade apareceu em listas de PEP (com nível), bases de dados de sanções, notícias adversas, avisos/fiscalização regulamentar ou outros conjuntos de dados de conformidade. `Other Lists` quando a fonte da entidade não indicar nenhuma destas categorias." }, "features": { "type": "object", "nullable": true, "description": "Funcionalidades adicionais da correspondência" }, "rca_name": { "type": "string", "description": "Nome da RCA, se aplicável" }, "last_seen": { "type": "string", "format": "date-time", "description": "Data em que a correspondência foi vista pela última vez" }, "risk_view": { "type": "object", "properties": { "crimes": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "countries": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "categories": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "custom_list": { "type": "object" } } }, "first_seen": { "type": "string", "format": "date-time", "description": "Data em que a correspondência foi vista pela primeira vez" }, "properties": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "alias": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string", "nullable": true }, "gender": { "type": "array", "items": { "type": "string" } }, "height": { "type": "string", "nullable": true }, "topics": { "type": "string", "nullable": true }, "weight": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "eyeColor": { "type": "string", "nullable": true }, "keywords": { "type": "string", "nullable": true }, "lastName": { "type": "array", "items": { "type": "string" } }, "position": { "type": "string", "nullable": true }, "religion": { "type": "string", "nullable": true }, "birthDate": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "ethnicity": { "type": "string", "nullable": true }, "firstName": { "type": "array", "items": { "type": "string" } }, "hairColor": { "type": "string", "nullable": true }, "weakAlias": { "type": "string", "nullable": true }, "birthPlace": { "type": "array", "items": { "type": "string" } }, "modifiedAt": { "type": "string", "nullable": true }, "wikidataId": { "type": "string", "nullable": true }, "citizenship": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true } } }, "match_score": { "type": "number", "description": "Pontuação de confiança da identidade ponderada (0-100) calculada a partir da semelhança do nome, data de nascimento e correspondência do país. Utilizada para determinar se a ocorrência é um falso positivo ou uma possível correspondência.", "format": "float", "nullable": true }, "risk_score": { "type": "number", "description": "Pontuação de risco da entidade (0-100). Utilizada para determinar o estado final de AML (Aprovada/Em análise/Recusada) com base no risk_score mais elevado entre os resultados que não sejam falsos positivos." }, "review_status": { "type": "string", "description": "Estado de revisão para esta correspondência. Pode ser 'Unreviewed', 'Confirmed Match', 'False Positive' ou 'Inconclusive'.", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ] }, "score_breakdown": { "type": "object", "description": "Detalhamento pormenorizado de como o match_score foi calculado.", "properties": { "name_score": { "type": "integer", "description": "Percentagem de semelhança de nome em bruto (0-100)." }, "name_weight": { "type": "integer", "description": "Ponderação original para nome a partir da configuração (0-100)." }, "name_weight_normalized": { "type": "number", "description": "Peso normalizado para o nome após nova ponderação para dados em falta (0-100)." }, "name_contribution": { "type": "number", "description": "Pontos com que o nome contribuiu para a pontuação total." }, "dob_score": { "type": "integer", "description": "Pontuação de correspondência da data de nascimento (-100 a 100)." }, "dob_weight": { "type": "integer", "description": "Ponderação original para data de nascimento a partir da configuração (0-100)." }, "dob_weight_normalized": { "type": "number", "description": "Peso normalizado para a data de nascimento após nova ponderação para dados em falta (0-100)." }, "dob_contribution": { "type": "number", "description": "Pontos com que a data de nascimento contribuiu para a pontuação total." }, "country_score": { "type": "integer", "description": "Pontuação de correspondência do país (-100 a 100)." }, "country_weight": { "type": "integer", "description": "Ponderação original para país a partir da configuração (0-100)." }, "country_weight_normalized": { "type": "number", "description": "Peso normalizado para o país após nova ponderação para dados em falta (0-100)." }, "country_contribution": { "type": "number", "description": "Pontos com que o país contribuiu para a pontuação total." }, "document_number_match_type": { "type": "string", "description": "Resultado da avaliação da 'Golden Key' do número do documento.", "enum": [ "MATCH", "NEUTRAL", "HARD_MISMATCH" ] }, "document_number_effect": { "type": "string", "description": "Descrição legível do efeito do número do documento na pontuação." }, "total_score": { "type": "integer", "description": "Pontuação de correspondência ponderada final (0-100)." } } }, "pep_matches": { "type": "array", "items": { "type": "object", "properties": { "aliases": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "list_name": { "type": "string" }, "publisher": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "matched_name": { "type": "string" }, "pep_position": { "type": "string" }, "date_of_birth": { "type": "string" }, "other_sources": { "type": "array", "items": { "type": "string" } }, "place_of_birth": { "type": "string" } } } }, "linked_entities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "active": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "details": { "type": "array", "items": { "type": "string" } }, "relation": { "type": "array", "items": { "type": "string" } } } } }, "warning_matches": { "type": "array", "description": "Lista de correspondências de avisos e fiscalização regulamentar. Inclui entradas das categorias: Warning, SIP, Warnings and Regulatory Enforcement, Fitness and Probity, SIE e Insolvency.", "items": { "type": "object", "properties": { "list_name": { "type": "string", "description": "Nome do publicador da lista de avisos" }, "matched_name": { "type": "string", "description": "Nome encontrado na lista de avisos" }, "description": { "type": "string", "description": "Descrição da entrada do aviso" }, "publisher": { "type": "string", "description": "Publicador ou fonte do aviso" }, "source_url": { "type": "string", "format": "uri", "description": "URL da fonte do aviso" }, "other_sources": { "type": "array", "items": { "type": "string" }, "description": "URLs de fontes adicionais" }, "countries": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Países associados ao aviso" }, "created_at": { "type": "string", "nullable": true, "description": "Data em que a entrada de aviso foi criada" }, "updated_at": { "type": "string", "nullable": true, "description": "Data em que a entrada de aviso foi atualizada pela última vez" }, "additional_data": { "type": "object", "description": "Dados adicionais da fonte do aviso. Pode conter um objeto `data` com uma matriz `case_details`.", "properties": { "data": { "type": "object", "properties": { "case_details": { "type": "array", "description": "Detalhes dos casos de aviso associados a esta correspondência", "items": { "type": "object", "properties": { "case_type": { "type": "string", "description": "Tipo do caso de aviso", "enum": [ "Accusation", "Arrest", "Bribery", "Criminal", "Fraud", "Illegal Fundraising", "Non-conviction Terror", "Proclaimed Offender", "Regulatory Enforcement", "Terrorism", "Terrorism-related", "Terrorism-related listing" ] } } } } } } } } } } }, "sanction_matches": { "type": "array", "description": "Lista de correspondências encontradas em listas de sanções para esta entidade.", "items": { "type": "object", "properties": { "list_name": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Nome(s) da(s) lista(s) de sanções" }, "matched_name": { "type": "string", "description": "Nome encontrado na lista de sanções" }, "description": { "type": "string", "description": "Descrição da entrada da sanção" }, "reason": { "type": "string", "nullable": true, "description": "Motivo em texto livre pelo qual a entidade foi sancionada. Combinado a partir das entradas de motivo da lista de sanções. Exemplos: 'Executive Order 13224 (Terrorism)', 'Support for actions undermining Ukraine's sovereignty', 'Listed due to national security concerns.'" }, "source_url": { "type": "string", "format": "uri", "description": "URL da fonte da sanção" }, "other_sources": { "type": "array", "items": { "type": "string" }, "description": "URLs de fontes adicionais" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Detalhes adicionais sobre a sanção" }, "legal_basis": { "type": "array", "items": { "type": "string" }, "description": "Base jurídica da sanção" }, "listed_on": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Data(s) em que a entidade foi listada" }, "sanction_list": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Identificador(es) da lista de sanções" }, "sanction_program": { "type": "array", "items": { "type": "string" }, "description": "Programa(s) de sanções em que a entidade está listada" }, "sanctioning_authority": { "type": "array", "items": { "type": "string" }, "description": "Autoridade/autoridades que aplicaram a sanção" }, "updated_on": { "type": "array", "items": { "type": "string" }, "description": "Data(s) em que a entrada de sanção foi atualizada pela última vez" }, "additional_data": { "type": "object", "description": "Dados adicionais da fonte de sanções não recolhidos nos campos principais" } } } }, "adverse_media_details": { "type": "object", "properties": { "sentiment": { "type": "string" }, "entity_type": { "type": "string" }, "sentiment_score": { "type": "integer" }, "adverse_keywords": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "adverse_media_matches": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "summary": { "type": "string" }, "headline": { "type": "string" }, "sentiment": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" }, "source_url": { "type": "string", "format": "uri" }, "author_name": { "type": "string", "nullable": true }, "other_sources": { "type": "array", "items": { "type": "string" } }, "adverse_keywords": { "type": "array", "items": { "type": "string" } }, "sentiment_score": { "type": "integer" }, "publication_date": { "type": "string", "format": "date-time" } } } }, "additional_information": { "type": "object" } } } }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Pontuação global da triagem AML — a pontuação de risco mais elevada em todas as correspondências (float, 0-100). `null` até ser calculada." }, "screened_data": { "type": "object", "properties": { "full_name": { "type": "string" }, "nationality": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "document_number": { "type": "string", "nullable": true } } }, "is_ongoing_monitoring_enabled": { "type": "boolean", "description": "Se a monitorização AML contínua está ativada para esta triagem. Quando `true`, a entidade é submetida periodicamente a nova triagem e quaisquer novas ocorrências atualizam o relatório." }, "next_ongoing_monitoring_bill_date": { "type": "string", "format": "date", "nullable": true, "description": "Data (YYYY-MM-DD) em que esta subscrição de monitorização contínua será faturada da próxima vez. Calculada como a data da última faturação de monitorização contínua mais 365 dias quando `is_ongoing_monitoring_enabled = true`; caso contrário, `null`. Esta é uma data de faturação, não uma data de triagem - utilize `last_ongoing_screening_at` para isso." }, "last_ongoing_screening_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a monitorização contínua concluiu pela última vez uma nova triagem deste registo, quer o resultado tenha mudado ou não. `null` quando o registo nunca foi submetido a uma nova triagem; nunca é preenchido retroativamente a partir da data de ativação ou de faturação." }, "last_ongoing_screening_datasets_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A data de atualização do conjunto de dados AML mais recente reportada pelo fornecedor no momento dessa triagem. `null` quando o fornecedor não tiver reportado datas do conjunto de dados; nunca é estimada." }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "A funcionalidade que gerou este aviso. O valor identifica o bloco de funcionalidade a que o aviso pertence. Numa triagem AML, este é tipicamente `AML`, mas o enum acima é a referência autoritativa para todos os avisos de funcionalidades no payload da decisão." }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "O ID do nó do grafo do fluxo que gerou este aviso" } } } } } }, "MonitoringEvent": { "type": "object", "description": "Um evento de monitorização armazenado, conforme devolvido pelos endpoints de lista e de linha temporal do titular. As evidências restritas (payload, contexto do dispositivo, evidências de regras) só são devolvidas por `GET /v3/events/{event_uuid}/`.", "required": [ "event_uuid", "event_id", "event_category", "action_type", "occurred_at", "received_at", "status", "score", "subject_vendor_data", "subject_entity_type", "subject_uuid", "counterparty_vendor_data", "session_id", "device_fingerprint", "ip_address", "ip_country", "amount", "currency", "game_id", "round_id", "bonus_id", "affiliate_code", "payment_reference_id", "retention_class", "rules_matched_count", "correlation_pending", "is_droppable" ], "properties": { "event_uuid": { "type": "string", "format": "uuid", "description": "Identificador Didit do evento. Utilize-o como `{event_uuid}` nas chamadas de obtenção e eliminação." }, "event_id": { "type": "string", "maxLength": 128, "description": "O seu próprio identificador, a chave de idempotência que enviou." }, "event_category": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ], "description": "Categoria do evento." }, "action_type": { "type": "string", "maxLength": 128, "description": "O que aconteceu dentro da categoria, tal como enviou." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Quando o evento aconteceu do seu lado." }, "received_at": { "type": "string", "format": "date-time", "description": "Quando a Didit aceitou o evento." }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "`ACCEPTED`: armazenado, nenhuma regra correspondida alterou o seu estado (a resposta normal para a maioria dos eventos, e sempre a resposta numa aplicação sandbox, onde não são executadas regras). `APPROVED`: uma regra correspondeu e a pontuação permaneceu abaixo do seu limiar de revisão. `IN_REVIEW`: uma regra elevou a pontuação acima do limiar de revisão ou definiu o estado. `DECLINED`: uma regra recusou-o ou a pontuação ultrapassou o seu limiar de recusa." }, "score": { "type": "integer", "description": "Pontuação acumulada da regra. Começa em 0; as ações `add_score` da regra alteram-na (são permitidos deltas negativos)." }, "subject_vendor_data": { "type": "string", "maxLength": 255, "description": "`subject.vendor_data` do evento: o seu ID para o utilizador ou empresa." }, "subject_entity_type": { "type": "string", "description": "`individual` ou `company`: que tipo de sujeito é indicado por `subject_vendor_data`.", "example": "individual" }, "subject_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID do utilizador (indivíduo) ou empresa a que o evento foi associado, ou null quando esse registo já não existir." }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "O outro interveniente de um evento P2P (promovido a partir de `payload.counterparty_vendor_data`).", "maxLength": 255 }, "session_id": { "type": "string", "nullable": true, "description": "`session.session_id` enviado com o evento.", "maxLength": 255 }, "device_fingerprint": { "type": "string", "nullable": true, "description": "`device_context.fingerprint` enviado com o evento.", "maxLength": 255 }, "ip_address": { "type": "string", "nullable": true, "description": "Endereço IP do evento. Na via de servidor, este é o `device_context.network_context.ip_address` tal como o enviou; na via de dispositivo, é o IP do pedido.", "maxLength": 64 }, "ip_country": { "type": "string", "nullable": true, "description": "Código do país de `ip_address` a partir do enriquecimento de IP, ou null quando o endereço não foi enriquecido (em falta, privado ou telemetria de baixo valor cujo endereço ainda não era conhecido).", "example": "ES" }, "amount": { "type": "string", "nullable": true, "description": "Montante como uma string decimal com 18 casas decimais, a partir de `transaction_context.amount`, `payload.amount` ou `payload.stake_amount`, por essa ordem.", "example": "250.000000000000000000" }, "currency": { "type": "string", "nullable": true, "description": "Moeda de `transaction_context.currency` ou `payload.currency`.", "maxLength": 10 }, "game_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.game_id`.", "maxLength": 128 }, "round_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.round_id`.", "maxLength": 128 }, "bonus_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.bonus_id`.", "maxLength": 128 }, "affiliate_code": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.affiliate_code`.", "maxLength": 128 }, "payment_reference_id": { "type": "string", "nullable": true, "description": "Referência de pagamento de `transaction_context.payment_reference_id` ou `payload.payment_reference_id`.", "maxLength": 255 }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "Classe de conservação. Os eventos de pagamento e de disputa são `monetary_or_compliance`; os eventos de segurança e de jogo responsável são `risk_relevant`; `session.page_view`, `session.sdk_heartbeat`, `session.sdk_loaded`, `session.device_seen`, `session.bot_signal_observed`, `bonus.promotion_viewed` e `affiliate.referral_clicked` são `low_value`; todos os outros são `standard`. Um evento ao qual correspondeu uma regra ativa é promovido a `risk_relevant` (nunca despromovido)." }, "rules_matched_count": { "type": "integer", "minimum": 0, "description": "Número de regras que corresponderam ao evento, incluindo regras em modo `TEST` (que registam provas mas não aplicam ações)." }, "correlation_pending": { "type": "boolean", "description": "`true` enquanto uma regra assíncrona (correlação entre sujeitos ou uma sequência superior a 24 horas) ainda tem de ser executada para este evento. É resolvida em minutos e `status`, `score` e `rules_matched_count` são atualizados diretamente." }, "is_droppable": { "type": "boolean", "description": "Se um SDK sob contrapressão pode descartar eventos deste tipo. `false` para todos os eventos de `security`, `payment`, `dispute` e `responsible_gambling` e para `gameplay.bet_placed`, `gameplay.bet_settled` e `gameplay.p2p_settlement`." } } }, "MonitoringEventDetail": { "description": "Um evento de monitorização com o respetivo envelope completo, enriquecimento e evidência de regras. Todos os campos de `MonitoringEvent` mais os campos abaixo.", "allOf": [ { "$ref": "#/components/schemas/MonitoringEvent" }, { "type": "object", "required": [ "payload", "custom_values", "device_context", "field_sources", "session_sequence", "table_id", "hand_id", "match_id", "market_id", "side", "role", "net_result_amount", "payment_fingerprint", "instrument_reference_hash", "withdrawal_address_hash", "dispute_id", "chargeback_id", "changed_field", "identity_match_ref", "schema_version", "expires_at", "rules_evaluated_count", "rule_runs", "ip_enrichment", "subject_profile", "tags" ], "properties": { "payload": { "type": "object", "additionalProperties": true, "description": "Os campos de categoria que enviou em `payload`." }, "custom_values": { "type": "object", "additionalProperties": true, "description": "Os `custom_values` escalares que enviou. A Didit adiciona `vpn_or_proxy_detected: true` ou `is_data_center: true` quando o enriquecimento de IP sinaliza o endereço e você não os definiu." }, "device_context": { "type": "object", "additionalProperties": true, "description": "O contexto do dispositivo conforme armazenado: o seu `device_context` (incluindo `fingerprint`, `persistent_device_id` e `bot_score` quando enviados) com `network_context` completado por enriquecimento de IP (`ip_country`, `ip_country_code`, `ip_city`, `asn_number`, `asn_organization`, `is_vpn_or_tor`, `is_data_center`, `proxy_type`, `connection_type`) para chaves que tenha deixado vazias." }, "field_sources": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "customer", "sdk", "server" ] }, "description": "Caminho do campo até à proveniência: `customer` (enviado pelo seu backend), `sdk` (enviado através do canal do dispositivo) ou `server` (derivado pela Didit, como `received_at` e campos de rede enriquecidos). Verifique-o antes de agir sobre uma correspondência." }, "session_sequence": { "type": "integer", "format": "int64", "nullable": true, "description": "`session.sequence` enviado com o evento." }, "table_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.table_id`.", "maxLength": 128 }, "hand_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.hand_id`.", "maxLength": 128 }, "match_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.match_id`.", "maxLength": 128 }, "market_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.market_id`.", "maxLength": 128 }, "side": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.side`.", "maxLength": 64 }, "role": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.role`.", "maxLength": 64 }, "net_result_amount": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.net_result_amount`, como uma string decimal com 18 casas decimais.", "example": "-120.000000000000000000" }, "payment_fingerprint": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.payment_fingerprint`.", "maxLength": 255 }, "instrument_reference_hash": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.instrument_reference_hash`.", "maxLength": 255 }, "withdrawal_address_hash": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.withdrawal_address_hash` (ou `payload.destination_reference_hash`).", "maxLength": 255 }, "dispute_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.dispute_id`.", "maxLength": 255 }, "chargeback_id": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.chargeback_id`.", "maxLength": 255 }, "changed_field": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.changed_field` (eventos de alteração de segurança).", "maxLength": 128 }, "identity_match_ref": { "type": "string", "nullable": true, "description": "Promovido a partir de `payload.identity_match_ref` (correspondências do registo de jogo responsável).", "maxLength": 255 }, "schema_version": { "type": "integer", "description": "Versão do esquema do envelope do evento. Atualmente `1`.", "example": 1 }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o evento expira de acordo com a sua classe de conservação e é eliminado: `occurred_at` mais o período da classe (14, 30 ou 90 dias por predefinição, ajustável por aplicação). Nulo para eventos `monetary_or_compliance`, que seguem a conservação de transações." }, "rules_evaluated_count": { "type": "integer", "minimum": 0, "description": "Número de regras de evento avaliadas para este evento." }, "rule_runs": { "type": "array", "description": "Cada regra que correspondeu ao evento, da mais recente para a mais antiga.", "items": { "$ref": "#/components/schemas/MonitoringEventRuleRun" } }, "ip_enrichment": { "type": "object", "nullable": true, "description": "Enriquecimento do endereço IP do evento, ou null quando o endereço não foi enriquecido. Consulte [Enriquecimento de IP](https://docs.didit.me/pt/transaction-monitoring/ip-enrichment).", "properties": { "ip_country_code": { "type": "string", "nullable": true, "description": "Código do país da morada." }, "ip_city": { "type": "string", "nullable": true, "description": "Cidade da morada." }, "asn_number": { "type": "integer", "nullable": true, "description": "Número de sistema autónomo." }, "asn_organization": { "type": "string", "nullable": true, "description": "Organização que opera o sistema autónomo." }, "is_vpn_or_tor": { "type": "boolean", "description": "Indica se o endereço é uma saída conhecida de VPN ou Tor." }, "is_data_center": { "type": "boolean", "description": "Indica se o endereço pertence a uma rede de alojamento ou de centro de dados." }, "proxy_type": { "type": "string", "nullable": true, "description": "Classificação de proxy do endereço como uma string opaca, ou null." }, "last_enriched_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o endereço foi enriquecido pela última vez." } }, "required": [ "ip_country_code", "ip_city", "asn_number", "asn_organization", "is_vpn_or_tor", "is_data_center", "proxy_type", "last_enriched_at" ] }, "subject_profile": { "type": "object", "nullable": true, "description": "Sinais de risco em cache de e-mail e telefone do sujeito, ou null se não existir qualquer perfil para o sujeito.", "properties": { "email_risk_score": { "type": "integer", "nullable": true, "description": "Pontuação de risco do e-mail." }, "email_deliverability": { "type": "string", "nullable": true, "description": "Veredito de capacidade de entrega do e-mail." }, "email_is_disposable": { "type": "boolean", "nullable": true, "description": "Indica se o endereço de e-mail é descartável." }, "email_is_breached": { "type": "boolean", "nullable": true, "description": "Indica se o endereço de e-mail surge em violações de dados conhecidas." }, "email_social_count": { "type": "integer", "nullable": true, "description": "Número de contas online associadas ao endereço de e-mail." }, "email_social_providers": { "type": "array", "items": { "type": "string" }, "description": "Nomes dos serviços online onde foi encontrada uma conta associada ao endereço de e-mail." }, "phone_risk_score": { "type": "integer", "nullable": true, "description": "Pontuação de risco do telefone." }, "phone_line_type": { "type": "string", "nullable": true, "description": "Tipo de linha telefónica." }, "phone_carrier": { "type": "string", "nullable": true, "description": "Nome da operadora telefónica." }, "phone_social_count": { "type": "integer", "nullable": true, "description": "Número de contas online associadas ao número de telefone." }, "phone_social_providers": { "type": "array", "items": { "type": "string" }, "description": "Nomes dos serviços online onde foi encontrada uma conta associada ao número de telefone." }, "source_provider": { "type": "string", "nullable": true, "description": "Identificador opaco da fonte do perfil." }, "last_enriched_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o perfil foi atualizado pela última vez." } }, "required": [ "email_risk_score", "email_deliverability", "email_is_disposable", "email_is_breached", "email_social_count", "email_social_providers", "phone_risk_score", "phone_line_type", "phone_carrier", "phone_social_count", "phone_social_providers", "source_provider", "last_enriched_at" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Nomes das etiquetas associadas ao evento (ações `add_tags` de regras)." } } } ] }, "MonitoringEventRuleRun": { "type": "object", "properties": { "rule_uuid": { "type": "string", "format": "uuid", "description": "UUID da regra de monitorização de transações." }, "rule_title": { "type": "string", "description": "Título da regra." }, "library_key": { "type": "string", "nullable": true, "description": "Chave da biblioteca quando a regra foi instalada a partir da biblioteca de regras; caso contrário, null." }, "matched": { "type": "boolean", "description": "Sempre `true`: apenas as execuções correspondentes são registadas." }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "Modo da regra quando foi executada. Uma execução em `TEST` regista evidências mas não aplicou quaisquer ações." }, "is_async": { "type": "boolean", "description": "`true` quando a execução resultou da passagem de correlação assíncrona em vez do pedido de ingestão." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "Gravidade da regra. Null para execuções `TEST` e para regras sem gravidade." }, "score_delta": { "type": "integer", "description": "Quanto esta execução alterou a pontuação do evento (0 para execuções de `TEST`)." }, "action_summary": { "type": "string", "nullable": true, "description": "Breve resumo das ações aplicadas, por exemplo `score +40; add_tag:VPN_LOGIN`. Nulo quando nada tiver sido aplicado." }, "matched_payload": { "type": "array", "description": "As condições e agregações correspondentes. Os registos de condição contêm `field`, `operator`, `expected_value`, `current_value`, `matched`, `group_index`, `group_logic` e `field_source` (`server`, `sdk` ou `customer`); os registos de agregação contêm `metric`, `field`, `operator`, `expected_value`, `computed_value`, `window`, `filters`, `matched` e `sample_references`.", "items": { "type": "object", "additionalProperties": true } }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a execução da regra foi registada." } }, "required": [ "rule_uuid", "rule_title", "library_key", "matched", "mode", "is_async", "severity", "score_delta", "action_summary", "matched_payload", "created_at" ] }, "MonitoringEventPage": { "type": "object", "description": "Uma página de eventos de monitorização, os eventos com o `occurred_at` mais recente primeiro.", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Número de eventos correspondentes, exato até 100 e limitado a 100 acima disso. Não calcule contagens de páginas a partir dele; siga `next` até ser null." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página seguinte, ou null na última página." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL da página anterior, ou null na primeira página." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringEvent" } } } }, "MonitoringEventCreateRequest": { "type": "object", "description": "O envelope do evento, igual para todas as categorias. São aceites aliases em camelCase: `eventId`, `eventCategory` (ou `category`), `actionType`, `occurredAt`, `timeZone` (ou `zoneId`), `deviceContext` (ou `device`), `transactionContext`, `customValues` (ou `props`); dentro de `subject`: `vendorData`, `entityType`, `fullName`; dentro de `session`: `sessionId`, `pageUrl`; dentro de `transaction_context`: `paymentReferenceId`.", "required": [ "event_id", "event_category", "action_type", "occurred_at", "subject" ], "properties": { "event_id": { "type": "string", "maxLength": 128, "description": "O seu identificador para o evento, único por aplicação. É a chave de idempotência: reenviar os mesmos `event_category`, `action_type`, `occurred_at`, `subject.vendor_data` e `payload` sob este identificador é uma repetição; qualquer alteração constitui um conflito.", "example": "login-2026-10-17-000001" }, "event_category": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ], "description": "Categoria do evento.", "example": "auth" }, "action_type": { "type": "string", "minLength": 1, "maxLength": 128, "description": "O que aconteceu dentro da categoria. Vocabulário aberto; as ações geridas listadas em [Ingestão de eventos](https://docs.didit.me/pt/transaction-monitoring/events) (por exemplo `login`, `deposit_completed`, `chargeback_opened`) desbloqueiam a validação tipada e campos de regras geridos. Os espaços em branco no início e no final são removidos.", "example": "login" }, "occurred_at": { "type": "string", "format": "date-time", "description": "Quando o evento aconteceu do seu lado, ISO 8601 (um valor sem fuso horário é interpretado como UTC). Não deve ter mais de 7 dias no passado nem mais de 5 minutos no futuro.", "example": "2026-10-17T09:15:02.481Z" }, "time_zone": { "type": "string", "nullable": true, "maxLength": 64, "description": "Fuso horário da ocorrência do seu lado, por exemplo `Europe/Madrid`. Armazenado com o evento; não é devolvido pelos endpoints de leitura." }, "subject": { "type": "object", "description": "O utilizador ou empresa a quem o evento pertence. É resolvido para o utilizador (ou empresa) com este `vendor_data` na sua aplicação; é criado um novo registo se não existir nenhum.", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "minLength": 1, "maxLength": 255, "description": "O seu id para o sujeito.", "example": "user-42" }, "entity_type": { "type": "string", "maxLength": 32, "default": "individual", "description": "`company` associa o sujeito a uma empresa; qualquer outro valor (por predefinição `individual`) associa-o a um indivíduo. O mesmo `vendor_data` pode indicar um de cada.", "example": "individual" }, "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "Nome de apresentação, utilizado apenas quando este evento cria o utilizador ou a empresa." }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Validado como um endereço de e-mail; não armazenado no evento." }, "phone": { "type": "string", "nullable": true, "maxLength": 32, "description": "Validado; não armazenado no evento." }, "country": { "type": "string", "nullable": true, "maxLength": 3, "description": "Validado; não armazenado no evento." } } }, "business": { "type": "object", "description": "A empresa à qual o evento pertence, quando difere do sujeito. Apenas `vendor_data` é lido.", "additionalProperties": true, "properties": { "vendor_data": { "type": "string", "maxLength": 255, "description": "O seu id para a empresa. Filtrável como `business_vendor_data`.", "example": "merchant-7" } } }, "session": { "type": "object", "description": "O seu contexto de sessão para o evento.", "properties": { "session_id": { "type": "string", "nullable": true, "maxLength": 255, "description": "O seu identificador de sessão. Filtrável e devolvido como `session_id`." }, "sequence": { "type": "integer", "nullable": true, "description": "Posição do evento dentro da sessão. Devolvida como `session_sequence`." }, "page_url": { "type": "string", "nullable": true, "maxLength": 2048, "description": "Validado; não armazenado no evento." }, "referrer": { "type": "string", "nullable": true, "maxLength": 2048, "description": "Validado; não armazenado no evento." } } }, "device_context": { "type": "object", "additionalProperties": true, "description": "Contexto de dispositivo e rede, armazenado tal como enviado e devolvido por `GET /v3/events/{event_uuid}/`. Nesta camada do servidor, a Didit não vê a ligação do utilizador final, pelo que o IP enriquecido e utilizado pelas regras é `network_context.ip_address` tal como o enviar.", "properties": { "fingerprint": { "type": "string", "maxLength": 255, "description": "Impressão digital do dispositivo. Filtrável como `device_fingerprint`." }, "persistent_device_id": { "type": "string", "maxLength": 255, "description": "O seu identificador persistente de dispositivo." }, "bot_score": { "type": "integer", "description": "Pontuação de bot da sua própria deteção, como um número inteiro." }, "network_context": { "type": "object", "additionalProperties": true, "properties": { "ip_address": { "type": "string", "maxLength": 64, "description": "Endereço IP do utilizador final. Os endereços públicos são enriquecidos uma vez por endereço exclusivo.", "example": "203.0.113.42" } } } } }, "transaction_context": { "type": "object", "description": "Contexto monetário. Valores não vazios aqui também satisfazem as chaves de payload obrigatórias da ação.", "properties": { "amount": { "type": "string", "nullable": true, "description": "Montante como uma string decimal (também é aceite um número).", "example": "1000.00" }, "currency": { "type": "string", "nullable": true, "maxLength": 10, "description": "Código de moeda." }, "direction": { "type": "string", "nullable": true, "maxLength": 16, "description": "Direção do movimento de dinheiro, por exemplo `inbound` ou `outbound`." }, "payment_reference_id": { "type": "string", "nullable": true, "maxLength": 255, "description": "A sua referência de pagamento. Filtrável como `payment_reference_id`." } } }, "payload": { "type": "object", "additionalProperties": true, "description": "Os campos de domínio da categoria, no máximo 16384 bytes após codificação JSON. Algumas ações exigem chaves (em `payload` ou `transaction_context`): `gameplay.p2p_settlement` requer `game_id`, `counterparty_vendor_data`, `stake_amount`, `net_result_amount`, `role` e um de `hand_id`, `round_id`, `match_id`; `gameplay.bet_placed` e `gameplay.bet_settled` requerem `game_id`; `payment.deposit_initiated`, `payment.deposit_completed`, `payment.withdrawal_requested` e `payment.withdrawal_completed` requerem `payment_reference_id`, `amount`, `currency`, `payment_method`, `status`; `payment.withdrawal_address_changed` requer `withdrawal_address_hash`; `dispute.chargeback_opened`, `dispute.chargeback_won` e `dispute.chargeback_lost` requerem `payment_reference_id` e um de `dispute_id`, `chargeback_id`; `session.bot_signal_observed` requer `telemetry_schema_version` e um de `bot_score`, `actions_per_minute`, `timing_variance_ms`, `pointer_entropy`, `keystroke_entropy`, `reaction_time_ms_p50`; `responsible_gambling.self_exclusion_match` requer `registry_source`, `exclusion_status`, `identity_match_ref`. Todas as ações de `security` que terminam em `_changed` requerem `changed_field`, além de `previous_reference_hash` ou `new_reference_hash` quando o campo for `password`, `mfa_method`, `mfa`, `email`, `phone`, `withdrawal_address`, `payout_method` ou `api_key`. Envie hashes e referências, nunca um número de cartão, um endereço de levantamento completo, um hash de palavra-passe ou um segredo MFA." }, "custom_values": { "type": "object", "description": "Até 100 chaves suas, acessíveis a partir de regras como `custom_values.`. Os valores têm de ser escalares (string, número, booleano ou null); objetos e arrays aninhados são rejeitados.", "additionalProperties": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "time_zone": "Europe/Madrid", "subject": { "vendor_data": "user-42", "entity_type": "individual" }, "session": { "session_id": "web-session-abc", "sequence": 142 }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42" } }, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold" } } }, "MonitoringEventIngestResult": { "type": "object", "description": "Resultado da ingestão de um evento. A mesma estrutura é devolvida para um novo evento e para uma repetição idempotente.", "required": [ "event_uuid", "event_id", "status", "score", "rules_evaluated_count", "rules_matched_count", "correlation_pending", "retention_class", "expires_at", "idempotent_replay", "rule_matches" ], "properties": { "event_uuid": { "type": "string", "format": "uuid", "description": "Identificador Didit do evento armazenado." }, "event_id": { "type": "string", "description": "O seu `event_id`." }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "Estado após a execução das regras em tempo real. Consulte `MonitoringEvent.status`." }, "score": { "type": "integer", "description": "Pontuação após a execução das regras em tempo real." }, "rules_evaluated_count": { "type": "integer", "minimum": 0, "description": "Número de regras de evento avaliadas no pedido. 0 numa aplicação de sandbox, onde não são executadas regras." }, "rules_matched_count": { "type": "integer", "minimum": 0, "description": "Número de regras correspondentes, incluindo regras em modo `TEST`." }, "correlation_pending": { "type": "boolean", "description": "`true` quando uma regra assíncrona ainda tem de ser executada. Leia `GET /v3/events/{event_uuid}/` alguns minutos mais tarde para obter o `status` e o `score` finais." }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "Classe de conservação, após qualquer promoção feita por uma regra correspondente." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o evento expira de acordo com a sua classe de conservação e é eliminado. Nulo para eventos `monetary_or_compliance` (pagamento e disputa)." }, "idempotent_replay": { "type": "boolean", "description": "`true` quando um evento com este `event_id` e o mesmo conteúdo já tinha sido armazenado; os valores são os do evento armazenado e nenhuma regra foi executada novamente." }, "rule_matches": { "type": "array", "description": "Regras que corresponderam ao evento.", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "UUID da regra." }, "library_key": { "type": "string", "nullable": true, "description": "Chave da biblioteca quando a regra foi instalada a partir da biblioteca de regras; caso contrário, null." }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "As regras `TEST` registam a correspondência, mas não aplicam ações." }, "is_async": { "type": "boolean", "description": "`true` quando a correspondência resultou da passagem assíncrona." } } } } } }, "ComplianceList": { "type": "object", "description": "Uma lista de bloqueio, lista de permissões ou lista personalizada de uma aplicação.", "required": [ "uuid", "name", "description", "list_type", "entry_type", "is_system", "entry_count", "last_entry_added_at", "created_at", "updated_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador da lista. Utilize-o como `list_uuid` nos endpoints de listas e entradas, e como o valor de uma condição de regra de fluxo ou de transação com `value_type: \"list\"`." }, "name": { "type": "string", "maxLength": 255, "description": "Nome da lista, único entre as listas da aplicação." }, "description": { "type": "string", "description": "Descrição em texto livre. String vazia quando não definida." }, "list_type": { "type": "string", "enum": [ "blocklist", "allowlist", "custom" ], "description": "`blocklist`: uma correspondência recusa a sessão ou a transação (apenas listas do sistema, uma por tipo de entrada). `allowlist`: os elementos correspondentes são considerados fiáveis, por exemplo, uma lista de permissões faciais ignora a ação de rosto duplicado; nunca substitui uma correspondência de lista de bloqueio. `custom`: usado em condições de regras de fluxo e de transação (`value_type: \"list\"`)." }, "entry_type": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ], "description": "O que a lista contém: `face`, `document` (número do documento), `phone`, `email`, `ip_address` (endereço IP ou intervalo CIDR), `device_fingerprint`, `wallet_address`, `bank_account`, `country` (ISO 3166-1 alfa-3), `user` ou `business` (o seu `vendor_data`), ou `key` (qualquer cadeia de carateres). Determina como os valores de entrada são validados e correspondidos." }, "is_system": { "type": "boolean", "description": "`true` para as listas fornecidas pela Didit: uma lista de bloqueio por tipo de entrada (`face`, `document`, `phone`, `email`, `ip_address`, `device_fingerprint`, `wallet_address`, `bank_account`, `user`, `business`), a lista personalizada **High Risk Countries** e as listas de permissão do sistema. As listas do sistema não podem ser renomeadas, editadas ou eliminadas; pode adicionar e eliminar as suas entradas." }, "entry_count": { "type": "integer", "minimum": 0, "description": "Número de entradas atualmente na lista." }, "last_entry_added_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a entrada atual mais recente foi adicionada. `null` para uma lista vazia." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a lista foi criada." }, "updated_at": { "type": "string", "format": "date-time", "description": "Quando a lista foi atualizada pela última vez." } } }, "ComplianceListEntry": { "type": "object", "description": "Um valor numa lista.", "required": [ "uuid", "value", "display_label", "comment", "added_by", "reference_session_id", "reference_session_number", "reference_session_type", "reference_object_uuid", "metadata", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador da entrada. Utilize-o como `entry_uuid` em Eliminar uma entrada da lista." }, "value": { "type": "string", "description": "O valor listado: um número de telefone em E.164, um endereço de e-mail, um número de documento, um endereço IP ou intervalo CIDR, uma impressão digital do dispositivo, um endereço de carteira, uma conta bancária, um código de país ISO 3166-1 alfa-3, um `vendor_data`, qualquer cadeia de carateres numa lista de `key`, ou o UUID do rosto armazenado numa lista de rostos. Os valores que envia são armazenados em minúsculas, exceto números de telefone e códigos de país. A correspondência não diferencia maiúsculas de minúsculas." }, "display_label": { "type": "string", "nullable": true, "maxLength": 512, "description": "Rótulo legível. A Didit preenche-o para entradas obtidas de uma sessão (por exemplo, o nome do titular e o número do documento) quando não envia nenhum." }, "comment": { "type": "string", "description": "Nota em texto livre. String vazia quando não definida." }, "added_by": { "type": "string", "nullable": true, "description": "Quem adicionou a entrada: `api` (uma chave de API), o endereço de e-mail de um utilizador da consola ou `console`, `system` ou `migration` (entradas criadas pela Didit), ou `rule` (uma ação de regra de transação ou de monitorização)." }, "reference_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessão de verificação da qual a entrada foi retirada. `null` quando a entrada foi adicionada por valor." }, "reference_session_number": { "type": "integer", "nullable": true, "description": "Número dessa sessão no âmbito da aplicação, como mostrado na consola." }, "reference_session_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", null ], "description": "`kyc` para uma sessão de verificação de pessoa, `kyb` para uma sessão de verificação de empresa, `null` quando não existe sessão." }, "reference_object_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "O registo que a entrada representa: o registo de rosto, documento, telefone ou e-mail lido a partir de uma sessão, o rosto criado por Carregar um rosto para uma lista, ou o UUID que enviou (por exemplo, o UUID de uma transação ou o `didit_internal_id` de um utilizador)." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contexto adicional. Contém as chaves definidas pela Didit (aqui listadas) combinadas com quaisquer `metadata` que tenha enviado ao criar a entrada, devolvidas conforme armazenadas. `null` quando não existir nenhum.", "properties": { "reference_image_url": { "type": "string", "description": "Entradas de rosto: URL assinado de curta duração, emitido novamente a cada chamada; `null` para uma chave de API com âmbito sem `media: read`. Ausente quando não existir nenhuma imagem associada à entrada." }, "front_image_url": { "type": "string", "description": "Entradas de documentos que contêm uma imagem da frente do documento: URL assinado de curta duração, emitido novamente a cada chamada; `null` para uma chave de API com âmbito restrito sem `media: read`." }, "full_name": { "type": "string", "description": "Entradas de documentos obtidas de uma sessão: nome completo do titular." }, "issuing_state": { "type": "string", "description": "Entradas de documentos obtidas de uma sessão: país emissor ISO 3166-1 alfa-3." }, "document_type": { "type": "string", "description": "Entradas de documentos obtidas de uma sessão: código do tipo de documento, por exemplo `P`, `ID` ou `DL`." }, "region": { "type": "string", "description": "Entradas de documentos obtidas de uma sessão: estado ou província de emissão de um documento emitido regionalmente, vazio quando não aplicável. Não definido por Adicionar itens da sessão à lista de bloqueio." }, "document_number": { "type": "string", "description": "Entradas de documentos obtidas de uma sessão: o número do documento." }, "face_image_source": { "type": "string", "enum": [ "front_image_camera_front", "back_image_camera_front" ], "description": "Entradas de rosto obtidas a partir de uma selfie de captura de documento: qual é a selfie. Ausente para rostos de prova de vida." }, "reference_node_id": { "type": "string", "nullable": true, "description": "Entradas de rosto obtidas a partir de uma selfie de captura de documento: o nó de Verificação de identidade de onde a selfie teve origem." }, "fingerprint_tier": { "type": "string", "nullable": true, "enum": [ "persistent_id", "composite_hash", "legacy_fp", "unknown", null ], "description": "Entradas da impressão digital do dispositivo recolhidas de uma sessão: como a impressão digital foi obtida. O `persistent_id` identifica um dispositivo; o `composite_hash` e o `legacy_fp` podem ser partilhados por dispositivos do mesmo modelo." }, "sandbox": { "type": "boolean", "description": "`true` numa entrada facial carregada numa aplicação de sandbox; essa entrada não corresponde a nada." }, "reference_type": { "type": "string", "enum": [ "transaction", "vendor_user", "vendor_business" ], "description": "Definido por si: para o que aponta `reference_object_uuid`, para que a consola possa criar uma ligação para o mesmo." }, "reference_id": { "type": "string", "description": "Definido por si: identificador do registo de origem." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a entrada foi adicionada." } } }, "BlocklistedItem": { "type": "object", "description": "Um rosto, documento de identidade, número de telefone ou endereço de e-mail na lista de bloqueio de uma sessão de verificação. Os campos que não se aplicam ao `type` do item são `null`.", "required": [ "type", "session_id", "session_number", "blocklisted_at", "face_image", "document_type", "document_number", "front_image", "phone_number", "country_code", "email" ], "properties": { "type": { "type": "string", "enum": [ "face", "document", "phone", "email" ], "description": "O que foi adicionado à lista de bloqueio." }, "session_id": { "type": "string", "format": "uuid", "description": "Sessão de verificação à qual o item pertence." }, "session_number": { "type": "integer", "nullable": true, "description": "Número dessa sessão no âmbito da aplicação, como mostrado na consola." }, "blocklisted_at": { "type": "string", "format": "date-time", "description": "Quando o item foi adicionado à lista de bloqueio pela última vez." }, "face_image": { "type": "string", "nullable": true, "description": "Itens de rosto: URL assinado de curta duração, emitido novamente a cada chamada; `null` para uma chave de API com âmbito sem `media: read`. Também `null` quando nenhuma imagem de referência estiver guardada." }, "document_type": { "type": "string", "nullable": true, "description": "Itens de documento: código do tipo de documento, por exemplo `P` (passaporte), `ID` (documento de identificação nacional), `DL` (carta de condução) ou `RP` (autorização de residência)." }, "document_number": { "type": "string", "nullable": true, "description": "Itens de documento: o número do documento, ou o número de identificação pessoal quando o documento não tiver nenhum." }, "front_image": { "type": "string", "nullable": true, "description": "Itens de documento: imagem da frente do documento, URL assinado de curta duração, emitido novamente a cada chamada; `null` para uma chave de API com âmbito restrito sem `media: read`." }, "phone_number": { "type": "string", "nullable": true, "description": "Itens de telefone: o número de telefone em E.164." }, "country_code": { "type": "string", "nullable": true, "description": "Itens de telefone: país ISO 3166-1 alpha-2 do número." }, "email": { "type": "string", "nullable": true, "description": "Itens de e-mail: o endereço de e-mail." } } }, "TransactionNote": { "type": "object", "description": "Uma nota na cronologia de revisão de uma transação monitorizada.", "required": [ "uuid", "note", "actor_email", "actor_name", "metadata", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador da nota." }, "note": { "type": "string", "description": "Corpo da nota em texto simples." }, "actor_email": { "type": "string", "format": "email", "nullable": true, "description": "E-mail do utilizador da Consola que escreveu a nota ou alterou o estado. `null` para notas criadas com uma chave de API e para notas adicionadas automaticamente pela Didit." }, "actor_name": { "type": "string", "nullable": true, "description": "Nome de apresentação do utilizador da Console (o seu e-mail quando não tem nome). `Rule Engine` para as notas que a Didit adiciona automaticamente. `null` para notas criadas com uma chave de API." }, "metadata": { "type": "object", "description": "Distingue os tipos de nota. As notas escritas através da API ou da Consola contêm `mentioned_emails`. Uma alteração de estado efetuada na Consola contém `type: status_change` com `previous_status`, `new_status`, `reason_code` e `reason_label`. As notas adicionadas pela Didit contêm `source`: `rule_action` (com `rule_uuid`) para a ação `add_note` de uma regra, ou `remediation_session` para um problema ao criar a sessão de verificação de ação do utilizador.", "properties": { "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Membros da organização mencionados, em minúsculas e sem duplicados. Vazio quando ninguém foi mencionado." }, "type": { "type": "string", "enum": [ "status_change" ], "description": "Presente em notas que registam uma alteração de estado efetuada na Consola." }, "previous_status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Estado antes da alteração." }, "new_status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Estado após a alteração." }, "reason_code": { "type": "string", "nullable": true, "description": "Código do motivo indicado com a alteração." }, "reason_label": { "type": "string", "nullable": true, "description": "Rótulo do motivo indicado com a alteração." }, "source": { "type": "string", "enum": [ "rule_action", "remediation_session" ], "description": "Presente em notas que a Didit adiciona automaticamente." }, "rule_uuid": { "type": "string", "format": "uuid", "description": "Regra cuja ação `add_note` escreveu a nota (com `source: rule_action`)." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a nota foi guardada." } } }, "TransactionSummary": { "type": "object", "description": "Resumo de uma transação monitorizada, com o formato listado por `GET /v3/transactions/`. Chame `GET /v3/transactions/{transaction_id}/` com `uuid` para obter partes, alertas e execuções de regras.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID da transação Didit. Utilize-o como `{transaction_id}` nos endpoints de transação." }, "transaction_number": { "type": "integer", "nullable": true, "description": "Número sequencial no âmbito da aplicação apresentado na Consola." }, "txn_id": { "type": "string", "nullable": true, "description": "O seu próprio identificador da chamada de criação. Único por aplicação." }, "transaction_type": { "type": "string", "description": "Categoria tal como armazenada: `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`, `gamblingLimitChange`, `gamblingBonusChange` ou `auditTrailEvent`." }, "action_type": { "type": "string", "description": "Subtipo dentro da categoria, por exemplo `withdrawal`." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Veredito atual de monitorização." }, "source": { "type": "string", "enum": [ "LIVE", "IMPORTED" ], "description": "`LIVE` para transações submetidas para monitorização, `IMPORTED` para importações históricas." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direção em relação ao sujeito." }, "amount": { "type": "string", "description": "Montante como uma string decimal com os zeros à direita removidos (até 18 casas decimais)." }, "currency": { "type": "string", "description": "Código de moeda ou símbolo de ativo criptográfico de `amount`." }, "currency_type": { "type": "string", "nullable": true, "description": "`fiat` ou `crypto` quando conhecidos." }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` convertido para a moeda preferida da aplicação, quando uma taxa estava disponível." }, "preferred_currency_code": { "type": "string", "nullable": true, "description": "Moeda de `preferred_currency_amount`." }, "payment_details": { "type": "string", "nullable": true, "description": "Referência de pagamento em texto livre." }, "txn_date": { "type": "string", "format": "date-time", "description": "Quando a transação ocorreu." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a Didit o registou." }, "score": { "type": "integer", "description": "Pontuação de risco. Quanto mais alta, maior o risco." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "Gravidade do risco, `null` até que algo a defina." }, "decision_reason_code": { "type": "string", "nullable": true, "description": "Motivo legível por máquina para o `status` atual." }, "decision_reason_label": { "type": "string", "nullable": true, "description": "Rótulo legível para `decision_reason_code`." }, "tags": { "type": "array", "description": "Etiquetas na transação.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "description": "Cor hexadecimal, por exemplo `#F59E0B`." }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "Etiqueta predefinida ou personalizada da Didit." } } } }, "subject_name": { "type": "string", "nullable": true, "description": "Nome completo da parte `APPLICANT`." }, "subject_vendor_data": { "type": "string", "nullable": true, "description": "O seu `vendor_data` para o candidato." }, "subject_type": { "type": "string", "nullable": true, "enum": [ "user", "business", null ], "description": "Indica se o requerente está associado a um utilizador ou a uma empresa na Didit; `null` quando não está associado a nenhum." }, "subject_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID do utilizador ou da empresa Didit a que o candidato está associado." }, "subject_country": { "type": "string", "nullable": true, "description": "Código do país do requerente." }, "counterparty_name": { "type": "string", "nullable": true, "description": "Nome completo da parte `COUNTERPARTY`, se existir." }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "O seu `vendor_data` para a contraparte." }, "counterparty_country": { "type": "string", "nullable": true, "description": "Código do país da contraparte." }, "assigned_to_name": { "type": "string", "nullable": true, "description": "Nome do revisor da consola atribuído à transação." }, "travel_rule_status": { "type": "string", "nullable": true, "description": "Estado da transferência da Travel Rule da transação, ou `null` caso não tenha nenhuma." }, "application_id": { "type": "string", "format": "uuid", "description": "Aplicação que detém a transação." }, "application_name": { "type": "string", "nullable": true, "description": "Nome dessa aplicação." }, "organization_id": { "type": "string", "format": "uuid", "description": "Organização à qual pertence a aplicação." }, "organization_name": { "type": "string", "nullable": true, "description": "Nome dessa organização." } } }, "ApplicationAnalyticsDataPoint": { "type": "object", "description": "Contagens de sessões para um dia, por data de criação (UTC). Cada contagem reflete o estado atual da sessão. Os pontos do período anterior contêm, pelo menos, os campos obrigatórios.", "required": [ "rounded_date", "total", "approved", "declined", "canceled", "pending" ], "properties": { "rounded_date": { "type": "string", "format": "date", "description": "O dia, `YYYY-MM-DD`." }, "total": { "type": "integer", "description": "Sessões criadas nesse dia." }, "approved": { "type": "integer", "description": "Destas, sessões `Approved` ou `Kyc Expired`." }, "declined": { "type": "integer", "description": "Sessões `Declined`." }, "canceled": { "type": "integer", "description": "Sessões `Expired` ou `Abandoned`." }, "pending": { "type": "integer", "description": "Sessões `Not Started`, `In Progress` ou `In Review`." }, "in_review": { "type": "integer", "description": "Sessões `In Review`." }, "expired": { "type": "integer", "description": "Sessões `Expired`." }, "abandoned": { "type": "integer", "description": "Sessões `Abandoned`." }, "in_progress": { "type": "integer", "description": "Sessões `In Progress`." }, "not_started": { "type": "integer", "description": "Sessões `Not Started`." }, "manually_approved": { "type": "integer", "description": "Sessões que um revisor aprovou após o fluxo ter dado outro veredito." }, "manually_declined": { "type": "integer", "description": "Sessões que um revisor recusou após o fluxo ter dado outro veredito." } } }, "ApplicationAnalyticsRequestBreakdown": { "type": "object", "description": "Totais de estado para o intervalo. A discriminação do período anterior contém, no mínimo, os campos obrigatórios.", "required": [ "total_approved", "total_in_review", "total_declined", "total_canceled", "total_pending" ], "properties": { "total_approved": { "type": "integer", "description": "Sessões `Approved` ou `Kyc Expired`." }, "total_in_review": { "type": "integer", "description": "Sessões `In Review`." }, "total_declined": { "type": "integer", "description": "Sessões `Declined`." }, "total_canceled": { "type": "integer", "description": "Sessões `Expired` ou `Abandoned`." }, "total_pending": { "type": "integer", "description": "Sessões `Not Started`, `In Progress` ou `In Review` (inclui `total_in_review`)." }, "total_expired": { "type": "integer", "description": "Sessões `Expired`." }, "total_abandoned": { "type": "integer", "description": "Sessões `Abandoned`." }, "total_in_progress": { "type": "integer", "description": "Sessões `In Progress`." }, "total_not_started": { "type": "integer", "description": "Sessões `Not Started`." }, "total_manually_approved": { "type": "integer", "description": "Aprovada por um revisor." }, "total_manually_declined": { "type": "integer", "description": "Recusada por um revisor." } } }, "ApplicationAnalyticsCountryCount": { "type": "object", "properties": { "country": { "type": "string", "description": "Nome do país." }, "country_code": { "type": "string", "description": "Código de país de duas letras." }, "session_count": { "type": "integer", "description": "Sessões desse país." } } }, "ApplicationAnalyticsLocationStats": { "type": "object", "properties": { "ip_countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "Países dos endereços dos utilizadores, com mais sessões primeiro." }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "A mesma lista que `ip_countries`." }, "id_countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "Países emissores dos documentos de identificação verificados, com mais sessões primeiro." }, "conversion_by_country": { "type": "array", "description": "Por país emissor do documento: sessões terminadas (aprovada, recusada ou em análise) e quantas foram aprovadas. As que têm mais sessões terminadas aparecem primeiro.", "items": { "type": "object", "properties": { "country": { "type": "string" }, "country_code": { "type": "string" }, "finished": { "type": "integer" }, "approved": { "type": "integer" } } } }, "cities": { "type": "array", "description": "Até 100 cidades de IP, com as cidades com mais sessões primeiro.", "items": { "type": "object", "properties": { "location": { "type": "string", "description": "`City, Country`." }, "session_count": { "type": "integer" }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true } } } } } }, "ApplicationAnalyticsDemographicStats": { "type": "object", "properties": { "age_distribution": { "type": "object", "description": "Sessões por faixa etária a partir do documento de identificação. Vazio quando não existem dados.", "properties": { "under_18": { "type": "integer" }, "18_24": { "type": "integer" }, "25_34": { "type": "integer" }, "35_44": { "type": "integer" }, "45_64": { "type": "integer" }, "65_plus": { "type": "integer" } }, "additionalProperties": { "type": "integer" } }, "gender_distribution": { "type": "object", "description": "Sessões por código de género do documento: `M`, `F` ou `U` (desconhecido).", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsDeviceDetails": { "type": "object", "description": "Os cinco principais de cada, primeiro as sessões mais frequentes.", "properties": { "device_models": { "type": "array", "description": "Marcas de dispositivos: `Apple`, `Android`, `LG`, tudo o resto agrupado como `Other`.", "items": { "type": "object", "properties": { "device": { "type": "string" }, "count": { "type": "integer" } } } }, "browsers": { "type": "array", "description": "Navegadores: `Chrome`, `Safari`, `Didit App`, `Firefox`, com todos os outros agrupados como `Other`.", "items": { "type": "object", "properties": { "browser": { "type": "string" }, "count": { "type": "integer" } } } }, "operating_systems": { "type": "array", "description": "Sistemas operativos.", "items": { "type": "object", "properties": { "os": { "type": "string" }, "count": { "type": "integer" } } } } } }, "ApplicationAnalyticsWorkflowFunnel": { "type": "object", "description": "Indexado por ID do fluxo. `total` representa as sessões iniciadas nesse fluxo; `steps` contabiliza as sessões que alcançaram cada passo (`OCR`, `LIVENESS`, `FACE_MATCH`, `AML`, `POA`, `PHONE`, `EMAIL`, `NFC`, `DATABASE_VALIDATION`, `QUESTIONNAIRE`, `IP_ANALYSIS`, `AGE_ESTIMATION`, `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`). Alcançar um passo não significa concluí-lo.", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "steps": { "type": "object", "additionalProperties": { "type": "object", "properties": { "reached": { "type": "integer" } } } } } } }, "ApplicationAnalyticsVerificationTimeStats": { "type": "object", "description": "Tempo ativo que os utilizadores passaram a verificar-se, ignorando intervalos de inatividade. Um objeto vazio quando não existem dados.", "properties": { "overall_avg_seconds": { "type": "number", "description": "Média por sessão, uma casa decimal." }, "overall_count": { "type": "integer", "description": "Sessões medidas." }, "per_feature": { "type": "object", "description": "Indexado por funcionalidade, por exemplo `OCR` ou `LIVENESS`.", "additionalProperties": { "type": "object", "properties": { "avg_seconds": { "type": "number" }, "total_seconds": { "type": "number" }, "count": { "type": "integer" } } } }, "per_sub_step": { "type": "object", "description": "Indexado por funcionalidade e depois por subpasso, por exemplo `front_id_photo`.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "avg_seconds": { "type": "number" }, "total_seconds": { "type": "number" }, "count": { "type": "integer" } } } } } } }, "ApplicationAnalyticsResubmissionStats": { "type": "object", "properties": { "first_pass": { "type": "integer", "description": "Sessões concluídas sem nenhum reenvio." }, "second": { "type": "integer", "description": "Sessões concluídas reenviadas uma vez." }, "third_plus": { "type": "integer", "description": "Sessões concluídas reenviadas duas ou mais vezes." }, "abandoned": { "type": "integer", "description": "Sessões abandonadas." } } }, "ApplicationAnalyticsOriginalStatusStats": { "type": "object", "description": "O veredicto automático do fluxo, antes de qualquer revisor o alterar.", "properties": { "approved": { "type": "integer" }, "in_review": { "type": "integer" }, "declined": { "type": "integer" } } }, "ApplicationAnalyticsWarningStats": { "type": "object", "description": "Indexado por funcionalidade (`ID_VERIFICATION`, `LIVENESS`, `FACEMATCH`, `AML`, `PROOF_OF_ADDRESS`, `PHONE`, `EMAIL`, `NFC`, `LOCATION`, `DATABASE_VALIDATION`, `QUESTIONNAIRE` e as funcionalidades de KYB). `total` representa as sessões que alcançaram a funcionalidade; `risks` contabiliza as sessões por código e nível de aviso.", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "risks": { "type": "object", "additionalProperties": { "type": "object", "properties": { "error": { "type": "integer" }, "warning": { "type": "integer" }, "information": { "type": "integer" } } } } } } }, "ApplicationAnalyticsDemographicPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chave do período: `YYYY-MM-DD` para um dia, a segunda-feira de uma semana ou `YYYY-MM` para um mês, consoante o `grouping_mode`." }, "age_distribution": { "type": "object", "additionalProperties": { "type": "integer" } }, "gender_distribution": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsDevicePoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chave do período: `YYYY-MM-DD` para um dia, a segunda-feira de uma semana ou `YYYY-MM` para um mês, consoante o `grouping_mode`." }, "devices": { "type": "object", "additionalProperties": { "type": "integer" } }, "browsers": { "type": "object", "additionalProperties": { "type": "integer" } }, "operating_systems": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsVerificationTimePoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chave do período: `YYYY-MM-DD` para um dia, a segunda-feira de uma semana ou `YYYY-MM` para um mês, consoante o `grouping_mode`." }, "overall_avg": { "type": "number", "description": "Média de segundos ativos por sessão." }, "per_feature": { "type": "object", "description": "Média de segundos ativos por funcionalidade.", "additionalProperties": { "type": "number" } } } }, "ApplicationAnalyticsResubmissionPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chave do período: `YYYY-MM-DD` para um dia, a segunda-feira de uma semana ou `YYYY-MM` para um mês, consoante o `grouping_mode`." }, "first_pass": { "type": "integer" }, "second": { "type": "integer" }, "third_plus": { "type": "integer" }, "abandoned": { "type": "integer" } } }, "ApplicationAnalyticsOriginalStatusPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chave do período: `YYYY-MM-DD` para um dia, a segunda-feira de uma semana ou `YYYY-MM` para um mês, consoante o `grouping_mode`." }, "approved": { "type": "integer" }, "in_review": { "type": "integer" }, "declined": { "type": "integer" } } }, "ApplicationAnalyticsSummary": { "type": "object", "description": "Resumo da verificação de utilizadores (KYC), devolvido quando não é enviado nem `scope` nem `widget_keys`.", "required": [ "data_points", "request_breakdown", "previous_data_points", "previous_request_breakdown", "conversion_rate", "location_stats", "demographic_stats", "device_details", "workflow_funnel_stats", "verification_time_stats", "resubmission_stats", "warning_stats", "original_status_stats", "grouping_mode", "demographic_time_series", "device_time_series", "verification_time_time_series", "resubmission_time_series", "original_status_time_series" ], "properties": { "data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" }, "description": "Um ponto por dia, desde o primeiro dia com sessões no intervalo até `end_date`. Sempre diário, independentemente do que indicar `grouping_mode`." }, "request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "previous_data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" }, "description": "Pontos diários para o período da mesma duração imediatamente anterior a `start_date`." }, "previous_request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "conversion_rate": { "type": "number", "nullable": true, "description": "`total_approved / (total_approved + total_declined + total_in_review) x 100`, uma casa decimal. `null` quando nada tiver terminado." }, "location_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsLocationStats" }, "demographic_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicStats" }, "device_details": { "$ref": "#/components/schemas/ApplicationAnalyticsDeviceDetails" }, "workflow_funnel_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWorkflowFunnel" }, "verification_time_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimeStats" }, "resubmission_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionStats" }, "warning_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWarningStats" }, "original_status_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusStats" }, "grouping_mode": { "type": "string", "enum": [ "day", "week", "month" ], "description": "Como as listas `*_time_series` são agrupadas: `day` para até 14 dias, `week` até 90, `month` para períodos superiores. Medido a partir do primeiro dia com sessões no intervalo." }, "demographic_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicPoint" } }, "device_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDevicePoint" } }, "verification_time_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimePoint" } }, "resubmission_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionPoint" } }, "original_status_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusPoint" } } } }, "ApplicationAnalyticsWidget": { "type": "object", "description": "Um widget do painel. Todos os widgets têm `kind` e `title`; os outros campos dependem de `kind`. Os widgets de sessão reutilizam os objetos de resumo (`data_points`, `request_breakdown`, `workflow_funnel_stats`, entre outros); os widgets de lista colocam as suas entradas em `items`; as métricas de transações utilizam `value`.", "required": [ "kind", "title" ], "properties": { "kind": { "type": "string", "enum": [ "sessions_volume", "workflow_funnel", "average_verification_time", "country_distribution", "warning_insights", "conversion_rate", "conversion_by_country", "resubmission_insights", "original_status_distribution", "database_validation_coverage", "database_validation_latency", "demographics", "device_details", "horizontal_bar", "kyb_registry_coverage", "kyb_registry_data_completeness", "metric", "time_series", "breakdown", "status_time_series", "leaderboard", "histogram" ], "description": "Tipo de widget." }, "title": { "type": "string", "description": "Título de apresentação, por exemplo `Verification volume`." }, "grouping_mode": { "type": "string", "enum": [ "day", "week", "month" ], "description": "Como as listas `*_time_series` são agrupadas: `day` para até 14 dias, `week` até 90, `month` para períodos superiores. Medido a partir do primeiro dia com sessões no intervalo." }, "data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" } }, "request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "previous_data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" } }, "previous_request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "conversion_rate": { "type": "number", "nullable": true }, "workflow_funnel_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWorkflowFunnel" }, "verification_time_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimeStats" }, "verification_time_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimePoint" } }, "warning_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWarningStats" }, "resubmission_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionStats" }, "resubmission_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionPoint" } }, "original_status_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusStats" }, "original_status_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusPoint" } }, "demographic_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicStats" }, "demographic_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicPoint" } }, "device_details": { "$ref": "#/components/schemas/ApplicationAnalyticsDeviceDetails" }, "device_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDevicePoint" } }, "items": { "type": "array", "description": "Entradas de um widget de lista. `country_distribution` (KYC): `country`, `country_code`, `session_count`. `conversion_by_country`: `country`, `country_code`, `finished`, `approved`. `time_series`: `date`, `value`. `status_time_series`: `date`, `approved`, `declined`, `flagged`. `breakdown`: `transaction_type` ou `action_type` com `count` e `volume`, ou `tag_id`, `tag_name`, `count`. `leaderboard`: `rule_title`, `trigger_count` ou `assignee`, `handled_count`, `average_processing_seconds`, cada um com `approved_percentage`, `declined_percentage`, `flagged_percentage`. `histogram`: `score`, `count`.", "items": { "type": "object", "additionalProperties": {} } }, "previous_items": { "type": "array", "description": "Série temporal de transações para o período com a mesma duração imediatamente anterior a `start_date`.", "items": { "type": "object", "additionalProperties": {} } }, "value": { "type": "number", "description": "widgets `metric`: o valor para o intervalo." }, "currency": { "type": "string", "nullable": true, "description": "Widgets de volume e montante de transações: a moeda de transação predefinida da aplicação." }, "thresholds": { "type": "object", "description": "widget `histogram`: os limiares de pontuação de revisão e de recusa da aplicação.", "properties": { "review": { "type": "integer" }, "decline": { "type": "integer" } } }, "search": { "type": "object", "description": "widget `kyb_registry_coverage`: totais de pesquisa de registo.", "properties": { "searches_total": { "type": "integer" }, "searches_with_no_candidates": { "type": "integer" } } } } }, "ApplicationAnalyticsWidgetResponse": { "type": "object", "description": "Widgets do painel, devolvidos quando `scope` ou `widget_keys` é enviado.", "required": [ "scope", "available_widget_keys", "requested_widget_keys", "widgets" ], "properties": { "scope": { "type": "string", "enum": [ "home", "kyc", "kyb", "transactions" ], "description": "Separador do painel." }, "available_widget_keys": { "type": "array", "items": { "type": "string" }, "description": "Cada chave de widget que este âmbito aceita." }, "requested_widget_keys": { "type": "array", "items": { "type": "string" }, "description": "As chaves do widget devolvidas na resposta, por ordem: as suas `widget_keys` válidas ou as predefinições do âmbito." }, "widgets": { "type": "object", "description": "Indexado pela chave do widget, pela ordem de `requested_widget_keys`.", "additionalProperties": { "$ref": "#/components/schemas/ApplicationAnalyticsWidget" } } } }, "ApplicationAnalyticsToday": { "type": "object", "description": "Verificações de hoje por hora local em comparação com o mesmo dia da semana da semana passada.", "required": [ "time_zone", "date", "current_hour", "previous_date", "hours", "previous_hours", "total", "previous_total_so_far", "outcomes" ], "properties": { "time_zone": { "type": "string", "description": "O fuso horário IANA do dia e das respetivas horas.", "example": "Europe/Madrid" }, "date": { "type": "string", "format": "date", "description": "O dia de hoje nesse fuso horário.", "example": "2026-10-30" }, "current_hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "A hora local atual.", "example": 14 }, "previous_date": { "type": "string", "format": "date", "description": "O dia de comparação: o mesmo dia da semana uma semana antes.", "example": "2026-10-23" }, "hours": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 24, "maxItems": 24, "description": "Verificações criadas hoje, por hora local a partir das 00:00. As horas ainda por decorrer são 0." }, "previous_hours": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 24, "maxItems": 24, "description": "Verificações criadas no dia de comparação, por hora local a partir das 00:00." }, "total": { "type": "integer", "minimum": 0, "description": "Verificações criadas hoje até ao momento.", "example": 165 }, "previous_total_so_far": { "type": "integer", "minimum": 0, "description": "Verificações criadas no dia de comparação até à mesma hora local.", "example": 151 }, "outcomes": { "type": "object", "description": "Das verificações de hoje, quantas estão aprovadas, a aguardar em análise e recusadas neste momento. As restantes ainda não foram concluídas.", "required": [ "approved", "in_review", "declined" ], "properties": { "approved": { "type": "integer", "minimum": 0 }, "in_review": { "type": "integer", "minimum": 0 }, "declined": { "type": "integer", "minimum": 0 } } } } }, "WebhookConfigDestination": { "type": "object", "description": "Um destino do webhook conforme listado na configuração de webhooks, sem métricas de entrega. `GET /v3/webhook/destinations/{destination_uuid}/` adiciona o seu resumo de entrega.", "required": [ "uuid", "label", "url", "enabled", "webhook_version", "secret_shared_key", "subscribed_events", "created_at", "updated_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID do destino." }, "label": { "type": "string", "maxLength": 255, "description": "Nome legível por humanos." }, "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Endpoint HTTPS para o qual a Didit envia eventos." }, "enabled": { "type": "boolean", "description": "`false` pausa as entregas para este destino." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versão do payload enviada para este destino." }, "secret_shared_key": { "type": "string", "description": "O segredo de assinatura deste destino (token de 43 carateres compatível com URL). Verifique cada webhook com o segredo do destino para onde foi enviado. Quem chama a API com uma chave de API recebe-o sempre por extenso; os utilizadores da Consola sem `read:webhooks` recebem uma cadeia vazia." }, "subscribed_events": { "type": "array", "uniqueItems": true, "description": "Tipos de eventos entregues a este destino. Vazios quando o destino foi criado sem eventos, caso em que não recebe nada.", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookConfig": { "type": "object", "description": "Configuração de webhooks ao nível da aplicação, política de conservação e anfitriões de retorno de carteira Digital ID, com todos os destinos de webhook.", "required": [ "webhook_url", "webhook_version", "secret_shared_key", "capture_method", "data_retention_months", "face_retention_policy", "face_retention_days", "available_events", "allowed_return_hosts", "endpoints" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL de webhook ao nível da aplicação (legado). O Didit apenas envia para este URL enquanto a aplicação não tiver nenhum destino ativado, e apenas envia `status.updated` e `data.updated`. Cada criação, atualização ou eliminação de um destino define-o para o URL do destino ativado mais antigo, ou `null` quando nenhum estiver ativado." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versão do payload do `webhook_url` legado. Cada destino tem o seu próprio `webhook_version`." }, "secret_shared_key": { "type": "string", "description": "Segredo de assinatura ao nível da aplicação (token de 43 carateres seguro para URL). Assina apenas entregas para o `webhook_url` legado; cada destino assina com a sua própria `secret_shared_key`. Chamadas autenticadas com chave de API recebem-no sempre na íntegra; utilizadores da Consola sem `read:webhooks` recebem uma cadeia de carateres vazia." }, "capture_method": { "type": "string", "enum": [ "MOBILE", "MOBILE_AND_DESKTOP" ], "description": "Definição legada da aplicação. O fluxo de verificação não a lê: as opções de captura são configuradas por fluxo." }, "data_retention_months": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 120, "description": "Janela de eliminação automática. As sessões de verificação de utilizadores criadas há mais meses do que este valor (um mês conta como 30 dias) são eliminadas automaticamente, e essa eliminação é irreversível. `null` significa que as sessões nunca são eliminadas automaticamente. Consulte [Conservação de dados](https://docs.didit.me/pt/console/data-retention)." }, "face_retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "O que acontece ao embedding facial de uma sessão quando a sessão é eliminada. `delete_with_session` (predefinição) elimina-o com a sessão. `retain_until_user_deleted` é a opção de adesão à [conservação de templates biométricos](https://docs.didit.me/pt/console/data-retention#retenção-de-modelo-biométrico): um template biométrico sem imagem associado ao Utilizador é gerido separadamente até que o seu período de conservação termine, o Utilizador seja eliminado ou o elimine definitivamente." }, "face_retention_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "Período de conservação, em dias, dos templates biométricos sob `retain_until_user_deleted`. Obrigatório quando essa política está definida." }, "biometric_consent_mode": { "type": "string", "enum": [ "auto", "always", "never" ], "description": "Quando o fluxo alojado e os SDKs nativos solicitam à pessoa consentimento biométrico explícito antes de uma captura de rosto. `auto` (predefinição) solicita apenas quando se aplica um acionador: um estado declarado, o IP da pessoa ou o emissor do documento de identificação situa-se em Illinois, Texas ou Colorado, ou a pessoa aparenta estar nos EUA sem um estado conhecido. `always` solicita a todas as pessoas cujo fluxo capture um rosto. `never` nunca apresenta o passo, e recolhe o consentimento por sua conta antes da selfie. Cada alteração é registada no registo de auditoria. Consulte [Consentimento biométrico](https://docs.didit.me/pt/getting-started/biometric-consent)." }, "available_events": { "type": "array", "description": "Todos os tipos de eventos que um destino pode subscrever, com uma etiqueta de exibição.", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "$ref": "#/components/schemas/WebhookEvent" }, "label": { "type": "string", "description": "Etiqueta visível, por exemplo `Session status updated`." } } } }, "allowed_return_hosts": { "type": "array", "maxItems": 20, "description": "Nomes de anfitrião (correspondência exata, apenas HTTPS) para os quais uma verificação autónoma de carteira de Identidade Digital pode reenviar o utilizador com o seu `return_url`. O seu domínio de marca branca também é sempre permitido. Consulte [Registar o seu destino de retorno](https://docs.didit.me/pt/standalone-apis/digital-id-wallets#registe-o-seu-destino-de-retorno).", "items": { "type": "string", "maxLength": 253 } }, "endpoints": { "type": "array", "description": "Todos os destinos de webhook da aplicação, do mais antigo para o mais recente, cada um com o respetivo segredo de assinatura. Apenas de leitura aqui: faça a gestão dos destinos com os endpoints `/v3/webhook/destinations/`.", "items": { "$ref": "#/components/schemas/WebhookConfigDestination" } }, "allowed_domains": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 }, "description": "Origens (por exemplo `https://app.example.com`; `http` apenas para `localhost`) nas quais o fluxo de verificação alojado pode ser incorporado e para as quais pode redirecionar o utilizador com um retorno de chamada da sessão. As chamadas servidor a servidor não são afetadas. Uma lista vazia significa nenhuma restrição. A Didit armazena cada origem em minúsculas sem uma porta predefinida. Uma entrada inválida falha com `400` em `allowed_domains`.", "example": [ "https://app.example.com" ] } } }, "WebhookDestinationDelivery": { "type": "object", "description": "Uma tentativa de entrega para um destino do webhook. O primeiro envio de um evento, cada nova tentativa automática e cada reenvio são entregas separadas.", "required": [ "uuid", "session_id", "request_url", "response_status", "response_time_ms", "status", "webhook_type", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID de entrega, para as chamadas de detalhe e reenvio." }, "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessão de verificação de utilizadores a que o evento se refere. `null` para eventos de sessão de empresa, utilizador, empresa, transação, Travel Rule e fluxo." }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL para onde a entrega foi enviada: o URL do destino quando o evento foi gerado." }, "response_status": { "type": "integer", "nullable": true, "description": "Código de estado HTTP devolvido pelo seu endpoint. `null` enquanto a entrega está na fila e ainda não foi tentada. Quando não foi recebida nenhuma resposta HTTP, a Didit regista um código de estado próprio: `504` quando o seu endpoint não respondeu no prazo de 5 segundos, `503` para uma falha de ligação, `400` quando o URL foi recusado por não ser seguro (por exemplo, um endereço privado ou interno) e `404` para qualquer outro erro no pedido. Valores iguais ou superiores a `400` contam como uma entrega com falha." }, "response_time_ms": { "type": "integer", "nullable": true, "minimum": 0, "description": "Tempo que a tentativa demorou, em milissegundos. `null` enquanto a entrega estiver na fila." }, "status": { "type": "string", "nullable": true, "description": "Estado comunicado pelo evento quando foi gerado: o estado da sessão para eventos de sessão (por exemplo, `Approved` ou `In Review`), o estado da pessoa ou da empresa para eventos de utilizador e de empresa, e o estado da transação para eventos de transação. `null` para eventos que não possuem estado." }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a entrega foi criada." } } }, "WebhookDestinationDeliveryDetail": { "type": "object", "description": "Uma tentativa de entrega para um destino do webhook, com os cabeçalhos e corpo do pedido exatos enviados pela Didit.", "required": [ "uuid", "session_id", "request_url", "response_status", "response_time_ms", "status", "webhook_type", "created_at", "request_header", "request_body" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID de entrega, para as chamadas de detalhe e reenvio." }, "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessão de verificação de utilizadores a que o evento se refere. `null` para eventos de sessão de empresa, utilizador, empresa, transação, Travel Rule e fluxo." }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL para onde a entrega foi enviada: o URL do destino quando o evento foi gerado." }, "response_status": { "type": "integer", "nullable": true, "description": "Código de estado HTTP devolvido pelo seu endpoint. `null` enquanto a entrega está na fila e ainda não foi tentada. Quando não foi recebida nenhuma resposta HTTP, a Didit regista um código de estado próprio: `504` quando o seu endpoint não respondeu no prazo de 5 segundos, `503` para uma falha de ligação, `400` quando o URL foi recusado por não ser seguro (por exemplo, um endereço privado ou interno) e `404` para qualquer outro erro no pedido. Valores iguais ou superiores a `400` contam como uma entrega com falha." }, "response_time_ms": { "type": "integer", "nullable": true, "minimum": 0, "description": "Tempo que a tentativa demorou, em milissegundos. `null` enquanto a entrega estiver na fila." }, "status": { "type": "string", "nullable": true, "description": "Estado comunicado pelo evento quando foi gerado: o estado da sessão para eventos de sessão (por exemplo, `Approved` ou `In Review`), o estado da pessoa ou da empresa para eventos de utilizador e de empresa, e o estado da transação para eventos de transação. `null` para eventos que não possuem estado." }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a entrega foi criada." }, "request_header": { "type": "string", "description": "Texto JSON (uma string) dos cabeçalhos do pedido que a Didit enviou: `Content-Type`, `X-Signature`, `X-Signature-V2`, `X-Signature-Simple`, `X-Timestamp` e `User-Agent`. Efetue o parse com um analisador de JSON. Contém assinaturas, nunca o segredo de assinatura." }, "request_body": { "type": "string", "description": "Texto JSON (uma string) do payload exato que a Didit enviou, com chaves ordenadas, incluindo `event_id` e `timestamp`. Efetue o parse com um analisador de JSON; consulte [Formato do payload](https://docs.didit.me/pt/integration/webhooks#estrutura-do-payload). Para uma chave com âmbito sem `media: read`, os URLs de multimédia no seu interior são `null`; sem `sessions: write`, os tokens de sessão e as ligações de verificação alojadas são `null`. Um corpo alterado dessa forma já não coincide com as suas assinaturas. A Didit não regista o corpo da resposta que o seu endpoint devolveu." } } }, "SessionWebhookDelivery": { "type": "object", "description": "Uma tentativa de entrega de webhook registada para uma sessão de verificação, com os cabeçalhos e o corpo exatos do pedido enviados pela Didit.", "required": [ "uuid", "session_id", "request_url", "response_status", "status", "webhook_type", "request_header", "request_body", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID de entrega. Utilize-o como `{webhook_uuid}` para obter ou reenviar esta entrega." }, "session_id": { "type": "string", "format": "uuid", "description": "A sessão à qual a entrega pertence (a sessão no caminho)." }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL para onde a entrega foi enviada." }, "response_status": { "type": "integer", "nullable": true, "description": "Código de estado HTTP devolvido pelo seu endpoint. `null` enquanto a entrega está na fila e ainda não foi tentada. Quando não foi recebida nenhuma resposta HTTP, a Didit regista um código de estado próprio: `504` quando o seu endpoint não respondeu no prazo de 5 segundos, `503` para uma falha de ligação, `400` quando o URL foi recusado por não ser seguro (por exemplo, um endereço privado ou interno) e `404` para qualquer outro erro no pedido. Valores iguais ou superiores a `400` contam como uma entrega com falha." }, "status": { "type": "string", "nullable": true, "description": "Estado da sessão quando o evento foi gerado, por exemplo `In Progress`, `Approved` ou `Declined`." }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "request_header": { "type": "string", "description": "Texto JSON (uma string) dos cabeçalhos do pedido que a Didit enviou: `Content-Type`, `X-Signature`, `X-Signature-V2`, `X-Signature-Simple`, `X-Timestamp` e `User-Agent`. Efetue o parse com um analisador de JSON. Contém assinaturas, nunca o segredo de assinatura." }, "request_body": { "type": "string", "description": "Texto JSON (uma string) do payload exato que a Didit enviou, com chaves ordenadas, incluindo `event_id` e `timestamp`. Efetue o parse com um analisador de JSON; consulte [Formato do payload](https://docs.didit.me/pt/integration/webhooks#estrutura-do-payload). Para uma chave com âmbito sem `media: read`, os URLs de multimédia no seu interior são `null`; sem `sessions: write`, os tokens de sessão e as ligações de verificação alojadas são `null`. Um corpo alterado dessa forma já não coincide com as suas assinaturas. A Didit não regista o corpo da resposta que o seu endpoint devolveu." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a entrega foi criada." } } }, "SessionEvent": { "type": "object", "description": "Uma entrada da cronologia de eventos de uma sessão de verificação.", "required": [ "uuid", "event_type", "created_at", "component", "feature_step", "step", "details", "ip_address", "user_agent", "device_info", "file_url", "sent_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador do evento." }, "event_type": { "type": "string", "enum": [ "SESSION_CREATED", "SESSION_COMPLETED", "SESSION_STATUS_CHANGED", "LINK_OPENED", "FORM_SUBMITTED", "BUTTON_CLICKED", "FILE_UPLOADED", "ATTEMPT_FAILED", "FEATURE_STEP_CHANGED", "STEP_RENDERED", "NOTE_ADDED", "MANUAL_REVIEW_STARTED", "WORKFLOW_BRANCH_EVALUATED", "WORKFLOW_STATUS_NODE_REACHED", "LOG" ], "description": "O que aconteceu. Comunicado pelo dispositivo durante o fluxo alojado ou SDK: `LINK_OPENED`, `STEP_RENDERED`, `BUTTON_CLICKED`, `FORM_SUBMITTED`, `FILE_UPLOADED`, `ATTEMPT_FAILED` e `LOG` (depuração). Registado pelo servidor: `SESSION_CREATED`, `SESSION_STATUS_CHANGED` (`details.old_status`, `details.current_status`), `FEATURE_STEP_CHANGED` (`details.old_feature_step`, `details.current_feature_step`), `WORKFLOW_BRANCH_EVALUATED` e `WORKFLOW_STATUS_NODE_REACHED` (o rastreio de encaminhamento do fluxo). `SESSION_COMPLETED`, `NOTE_ADDED` e `MANUAL_REVIEW_STARTED` podem aparecer em sessões mais antigas." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a Didit armazenou o evento. Os eventos são armazenados de forma assíncrona, alguns segundos após `sent_at`." }, "component": { "type": "string", "nullable": true, "description": "Componente de UI que reportou o evento (apenas eventos de dispositivo)." }, "feature_step": { "type": "string", "nullable": true, "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "DOCUMENT_AI", "GEOLOCATION", null ], "description": "Funcionalidade de verificação em que a sessão se encontrava quando o evento ocorreu." }, "step": { "type": "string", "nullable": true, "description": "Ecrã dentro da funcionalidade, por exemplo `DOCUMENT_CAPTURE_FRONT` ou `FACE_PASSIVE_LIVENESS`." }, "details": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Dados específicos do evento. As chaves dependem de `event_type`." }, "ip_address": { "type": "string", "nullable": true, "description": "Endereço IP a partir do qual o dispositivo reportou o evento. `null` para eventos registados no servidor." }, "user_agent": { "type": "string", "nullable": true, "description": "Agente do utilizador do dispositivo. `null` para eventos registados pelo servidor." }, "device_info": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Detalhes do dispositivo que o SDK ou navegador comunicou." }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "Ligação pré-assinada de curta duração para um ficheiro anexado ao evento (por exemplo, uma imagem capturada). `null` quando não existir nenhum, e sempre `null` para uma chave de API com âmbito restrito sem `media: read`." }, "sent_at": { "type": "integer", "format": "int64", "description": "Quando o evento aconteceu, como um carimbo de data/hora Unix em milissegundos. Os resultados são ordenados por este campo." } } }, "AMLDatasetSourceFreshness": { "type": "object", "description": "Atualidade de uma família de conjuntos de dados AML.", "required": [ "last_updated_at", "oldest_updated_at", "dataset_count", "dated_dataset_count" ], "properties": { "last_updated_at": { "type": "string", "format": "date-time", "description": "Atualização mais recente de qualquer conjunto de dados da família." }, "oldest_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Limite de desatualização: todos os conjuntos de dados na família são pelo menos tão atuais quanto este valor. `null` quando pelo menos um conjunto de dados na família não comunicou uma data de atualização, dado que o limite é desconhecido." }, "dataset_count": { "type": "integer", "description": "Número de conjuntos de dados na família." }, "dated_dataset_count": { "type": "integer", "description": "Número desses conjuntos de dados que comunicaram uma data de atualização." } } }, "AMLDatasetFreshness": { "type": "object", "description": "O quão atualizados estavam os conjuntos de dados de AML quando uma triagem foi executada. As datas nunca são estimadas.", "required": [ "captured_at", "provider", "catalog_version", "sources" ], "properties": { "captured_at": { "type": "string", "format": "date-time", "description": "Quando a Didit leu o catálogo de conjuntos de dados de onde provém esta informação sobre a atualidade dos dados." }, "provider": { "type": "string", "description": "Identificador opaco da fonte de dados AML. Trate-o como uma string opaca; não crie ramificações lógicas com base nele.", "example": "aml_data_source" }, "catalog_version": { "type": "string", "nullable": true, "description": "Identificador da versão do catálogo do conjunto de dados, quando a fonte comunica um." }, "sources": { "type": "object", "description": "Atualidade por família de conjuntos de dados. Uma família cujos conjuntos de dados não reportaram data de atualização fica ausente em vez de preenchida com `null`.", "properties": { "sanctions": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "pep": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "warnings": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "adverse_media": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" } } } } }, "AMLScreeningRun": { "type": "object", "description": "Uma nova triagem concluída de monitorização contínua de uma verificação AML.", "required": [ "uuid", "run_id", "completed_at", "started_at", "outcome", "trigger", "provider", "status", "score", "total_hits", "new_hits", "entities_screened", "dataset_freshness" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador desta execução de triagem." }, "run_id": { "type": "string", "format": "uuid", "description": "A execução de monitorização à qual esta triagem pertence. Todas as verificações triadas na mesma execução partilham-na." }, "completed_at": { "type": "string", "format": "date-time", "description": "Quando a nova triagem deste sujeito terminou. Os resultados são ordenados por este campo, do mais recente para o mais antigo." }, "started_at": { "type": "string", "format": "date-time", "description": "Quando o lote de monitorização a que esta nova triagem pertence foi iniciado." }, "outcome": { "type": "string", "enum": [ "NO_CHANGE", "CHANGED", "FAILED" ], "description": "`NO_CHANGE`: concluído e o resultado não se alterou. `CHANGED`: concluído e a pontuação, estado, contagem de ocorrências ou ocorrências foram alterados. `FAILED`: sem resposta utilizável para este sujeito, pelo que a verificação foi mantida como estava." }, "trigger": { "type": "string", "enum": [ "ONGOING_MONITORING" ], "description": "O que iniciou a triagem. Atualmente, é sempre `ONGOING_MONITORING`." }, "provider": { "type": "string", "description": "Identificador opaco da fonte de dados AML que respondeu. Trate-o como uma string opaca; não crie ramificações lógicas com base nele.", "example": "aml_data_source" }, "status": { "type": "string", "nullable": true, "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested", null ], "description": "Estado da verificação AML após esta execução." }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Pontuação AML atribuída à verificação nesta execução." }, "total_hits": { "type": "integer", "nullable": true, "description": "Número de resultados com que esta execução deixou a verificação." }, "new_hits": { "type": "integer", "nullable": true, "description": "Número de resultados encontrados nesta execução que a verificação não tinha antes. `0` quando nada de novo foi encontrado; `null` quando a execução falhou ou foi registada antes da existência desta contagem." }, "entities_screened": { "type": "integer", "minimum": 0, "maximum": 1, "description": "Número de entidades triadas nesta execução para a verificação: `1` quando o sujeito foi triado, `0` quando a execução falhou." }, "dataset_freshness": { "allOf": [ { "$ref": "#/components/schemas/AMLDatasetFreshness" } ], "nullable": true, "description": "Atualidade do conjunto de dados subjacente a esta execução, ou `null` quando não havia datas disponíveis." } } }, "KYBKeyPeopleParty": { "type": "object", "description": "Uma parte de pessoas-chave de uma sessão de Verificação de empresas (KYB), com a sua verificação subordinada. A mesma parte aparece em `key_people_checks[].submitted.parties[]` da decisão da sessão da empresa.", "required": [ "uuid", "entity_type", "source", "name", "is_active", "is_skipped", "requires_verification", "roles", "kyc_session_deleted", "kyb_sub_session_deleted" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificador da parte." }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Se a parte é uma pessoa singular ou uma empresa." }, "source": { "type": "string", "enum": [ "REGISTRY", "USER" ], "description": "`REGISTRY`: obtido a partir do registo de empresas. `USER`: introduzido no ecrã Pessoas-chave." }, "name": { "type": "string", "description": "Nome de apresentação da parte." }, "first_name": { "type": "string", "nullable": true, "description": "Primeiro nome (pessoas)." }, "last_name": { "type": "string", "nullable": true, "description": "Apelido (pessoas singulares)." }, "company_name": { "type": "string", "nullable": true, "description": "Nome da empresa (partes empresariais)." }, "registration_number": { "type": "string", "nullable": true, "description": "Número de registo da empresa (partes empresariais)." }, "email": { "type": "string", "format": "email", "nullable": true, "description": "E-mail para o qual a ligação de verificação é enviada." }, "nationality": { "type": "string", "nullable": true, "description": "Nacionalidade para pessoas singulares, país de constituição para empresas." }, "phone_number": { "type": "string", "nullable": true, "description": "Número de telefone recolhido para a parte." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento (pessoas)." }, "position": { "type": "string", "nullable": true, "description": "Cargo em texto livre (pessoas singulares)." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campos personalizados definidos pelo fluxo recolhidos para a parte, indexados pela chave do campo." }, "is_active": { "type": "boolean", "description": "Se a parte está ativa." }, "is_skipped": { "type": "boolean", "description": "Se a parte está isenta de verificação. A regeneração elimina esta isenção." }, "requires_verification": { "type": "boolean", "description": "Se as regras de função e propriedade exigem uma verificação para esta parte." }, "roles": { "type": "array", "description": "Funções que a parte desempenha na empresa.", "items": { "type": "object", "required": [ "role", "ownership_percent", "voting_percent" ], "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Código da função." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Percentagem de propriedade para esta função, quando conhecida." }, "voting_percent": { "type": "number", "nullable": true, "description": "Percentagem de direitos de voto para esta função, quando conhecida." } } } }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessão KYC individual dependente (pessoas singulares)." }, "kyc_session_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User", null ], "description": "Estado da sessão KYC subordinada. Uma sessão eliminada mantém o estado que tinha quando foi eliminada." }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "Ligação alojada da sessão de KYC dependente. `null` quando não existe nenhuma ou se foi eliminada, e para uma chave de API com âmbito restrito sem `sessions: write`." }, "kyc_session_deleted": { "type": "boolean", "description": "A sessão de KYC subordinada foi eliminada, pelo que nunca poderá ser concluída." }, "kyb_sub_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessão KYB dependente (partes empresariais)." }, "kyb_sub_session_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User", null ], "description": "Estado da sessão KYB subordinada." }, "kyb_sub_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "Ligação alojada da sessão de KYB dependente, com as mesmas regras de `null` que `kyc_session_url`." }, "kyb_sub_session_deleted": { "type": "boolean", "description": "Equivalente da parte empresarial de `kyc_session_deleted`." }, "verification_workflow_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", "adaptive_age_verification", "biometric_authentication", "address_verification", "questionnaire_verification", "email_verification", "phone_verification", null ], "description": "Tipo do fluxo que a sessão filha executa." }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Fluxo que a sessão filha executa." }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "Rótulo desse fluxo." }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "Funcionalidades do fluxo da sessão filha com o respetivo estado atual.", "items": { "type": "object", "required": [ "feature", "status" ], "properties": { "feature": { "type": "string", "description": "Código da funcionalidade, por exemplo `ID_VERIFICATION` ou `LIVENESS`." }, "status": { "type": "string", "description": "Estado da funcionalidade, `Not Finished` até ser executada." } } } }, "didit_internal_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Identificador da Didit da pessoa verificada, assim que conhecida." } } }, "TravelRuleDelivery": { "type": "object", "description": "O estado em que se encontra a mensagem mais recente que a transferência deve à outra parte. A Didit contacta a contraparte após o pedido que criou ou alterou a transferência ter retornado, pelo que este objeto indica se essa mensagem chegou ao destino: em fila, a ser enviada, a aguardar nova tentativa após um erro, entregue ou com falha. Uma falha da qual a rede ainda possa recuperar (sem resposta a tempo, ligação falhada, HTTP `408`, `429` ou `5xx`) é tentada novamente após 30 segundos, 2 minutos, 10 minutos, 30 minutos e 1 hora. Quando uma primeira mensagem (`kind: SEND`) falha definitivamente, porque a rede a recusou ou a sexta tentativa também falhou, a transferência transita para `COUNTERPARTY_VASP_NOT_REACHABLE` com `last_error` na sua `timeline`; qualquer outra mensagem que falhe definitivamente é anotada na `timeline`. O `status` da transferência permanece a fonte da verdade para o intercâmbio em si.", "required": [ "kind", "status", "rail", "attempts", "last_error", "next_attempt_at", "delivered_at" ], "properties": { "kind": { "type": "string", "enum": [ "SEND", "ANSWER", "TXID", "CANCEL", "POLL" ], "description": "O que a mensagem transporta. `SEND`: a primeira mensagem da transferência para a contraparte (de saída; o canal é escolhido quando é enviada). `ANSWER`: a sua aceitação ou recusa, devida à rede requerente (de entrada). `TXID`: o hash da transação on-chain, após concluir a transferência. `CANCEL`: o cancelamento, após cancelá-la. `POLL`: uma consulta de estado a uma rede que o disponibilize, repetida a cada 5 minutos enquanto a transferência aguarda a contraparte." }, "status": { "type": "string", "enum": [ "QUEUED", "SENDING", "RETRYING", "DELIVERED", "FAILED" ], "description": "`QUEUED`: a aguardar envio. `SENDING`: tentativa em curso. `RETRYING`: uma tentativa falhou e a próxima será executada em `next_attempt_at`. `DELIVERED`: o outro lado aceitou a mensagem. `FAILED`: o outro lado recusou-a, ou a última tentativa falhou." }, "rail": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "" ], "description": "O canal que transporta a mensagem. Vazio até que a Didit escolha um para uma primeira mensagem." }, "attempts": { "type": "integer", "minimum": 0, "description": "Tentativas efetuadas até ao momento para esta mensagem. Uma mensagem que não seja uma sondagem de estado é tentada no máximo 6 vezes." }, "last_error": { "type": "string", "description": "O tipo de falha ocorrida na última tentativa, `\"\"` se não tiver ocorrido nenhuma: por exemplo `email undeliverable`, `trp identity endpoint unreachable` ou `trp transfer inquiry delivery failed`. Nunca inclui a resposta da própria contraparte, que permanece na `timeline` da transferência.\nQuando a GTR responde com um erro, o respetivo código de estado e mensagem são incluídos. Os corpos de resposta nunca são incluídos.", "example": "email undeliverable" }, "next_attempt_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a próxima tentativa é executada enquanto a mensagem estiver em `QUEUED` ou `RETRYING`." }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a outra parte recebeu a mensagem." } } }, "TravelRuleDiscoveryStep": { "type": "object", "description": "Um passo da deteção de contraparte que a Didit executou para uma transferência de saída, na ordem em que foram executados. O primeiro passo que identifique um VASP com uma rota termina a cadeia.", "properties": { "step": { "type": "string", "enum": [ "internal_address_book", "wallet_attribution", "network_lookup", "customer_hint", "end_user" ], "description": "`internal_address_book`: outro cliente da Didit que provou o controlo da carteira de destino. `wallet_attribution`: a atribuição da carteira na análise de blockchain. `network_lookup`: uma rede que pode indicar qual VASP detém o endereço. `customer_hint`: o nome do VASP, LEI ou jurisdição que enviou em `beneficiary_data`. `end_user`: a contraparte que o utilizador final (ou você) escolheu, ou o pedido para escolher uma." }, "outcome": { "type": "string", "enum": [ "match", "miss", "skipped" ], "description": "`match`: o passo indicou uma contraparte. `miss`: foi executado e não encontrou nenhuma. `skipped`: não pôde ser executado, e `reason` indica o motivo." }, "reason": { "type": "string", "description": "Motivo legível por máquina, `\"\"` numa correspondência: `no_proven_internal_wallet`, `attribution_disabled`, `already_attributed`, `no_attributed_entity`, `directory_match_no_route`, `gtr_address_lookup_runs_on_dispatch`, `no_membership`, `network_switched_off`, `no_network_address_lookup`, `no_directory_match`, `awaiting_end_user` ou `picked_member_without_proven_wallet`." }, "vasp": { "type": "string", "format": "uuid", "nullable": true, "description": "O VASP do diretório indicado pelo passo, quando este tiver indicado um." }, "rail": { "type": "string", "nullable": true, "description": "O canal que alcança essa contraparte, quando o passo encontrou um." }, "at": { "type": "string", "format": "date-time" } } }, "TravelRuleNextAction": { "type": "object", "description": "Um elemento que faz avançar uma transferência com `COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE`. Consulte [Por que motivo uma transferência está bloqueada](/pt/transaction-monitoring/travel-rule#por-que-motivo-uma-transferência-está-bloqueada).", "properties": { "action": { "type": "string", "enum": [ "select_counterparty_vasp", "declare_self_hosted", "add_vasp_hint", "update_compliance_email", "resend" ], "description": "`select_counterparty_vasp`: o utilizador final escolhe o VASP de destino no widget de titularidade da carteira, ou você envia um PATCH com `action=beneficiary_vasp`. `declare_self_hosted`: o utilizador final declara a carteira como autocustodiada no widget. `add_vasp_hint`: indique à Didit quem é a contraparte, com um nome de VASP, LEI ou Travel Address (por exemplo, um `travel_address` na entrada do livro de endereços da carteira de destino) e, em seguida, reenvie. `update_compliance_email` e `resend` são valores de `action` de `PATCH /v3/transactions/{transaction_id}/travel-rule/`: forneça novamente o e-mail de conformidade da contraparte e execute o encaminhamento outra vez." }, "url": { "type": "string", "format": "uri", "description": "A ligação do widget de titularidade da carteira, em `select_counterparty_vasp` e `declare_self_hosted` enquanto a transferência tem uma sessão do widget aberta." } }, "required": [ "action" ] }, "TransactionTravelRule": { "type": "object", "description": "A transferência de Travel Rule de uma transação, tal como `GET /v3/transactions/{transaction_id}/`, o `201` de `POST /v3/transactions/` e cada linha de `GET /v3/transactions/` a devolvem. `direction`, `rail`, `counterparty_vasp`, `delivery`, `discovery`, `reason` e `next_actions` têm o mesmo formato que em `PATCH /v3/transactions/{transaction_id}/travel-rule/`, para que uma leitura de uma transação indique por que motivo a transferência está retida e o que fazer para prosseguir.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "protocol": { "type": "string", "nullable": true }, "required": { "type": "boolean" }, "obligations_count": { "type": "integer" }, "originator_data": { "type": "object", "description": "Parte ordenante. Para uma transferência de entrada, os valores da contraparte são ocultados até que a propriedade seja confirmada." }, "beneficiary_data": { "type": "object", "description": "Parte beneficiária. Para uma transferência de entrada, os valores da contraparte são ocultados até que a propriedade seja confirmada." }, "name_match": { "type": "object", "nullable": true, "description": "A comparação de nomes que decidiu a transferência (pontuação e rigor). Nulo até que uma seja executada. Os nomes comparados são mascarados em conjunto com as partes." }, "data_match": { "$ref": "#/components/schemas/TravelRuleDataMatch" }, "mismatched_fields": { "type": "array", "items": { "type": "string" }, "description": "Atalho para `data_match.mismatched_fields`. Vazio quando nada difere." }, "data_unmasked": { "$ref": "#/components/schemas/TravelRuleDataUnmasked" }, "data_masked": { "type": "boolean", "description": "Verdadeiro enquanto os dados pessoais da contraparte estiverem mascarados nesta resposta." }, "metadata": { "type": "object" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "A que lado da troca pertence esta transferência." }, "rail": { "type": "string", "nullable": true, "description": "O canal através do qual a transferência ocorreu: `INTERNAL`, `TRP`, `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` ou `EMAIL` (`TEST_VASP` numa aplicação sandbox, quando o Didit Test VASP respondeu), ou `null` até que um canal seja escolhido." }, "counterparty_vasp": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "lei": { "type": "string" }, "dd_score": { "type": "integer", "description": "Pontuação de diligência devida de 0 a 100, onde quanto mais alto, melhor. Mesma escala que no diretório VASP." }, "dd_score_breakdown": { "type": "object", "description": "Contribuições por componente para dd_score, um objeto por componente como no diretório VASP (jurisdiction, verification, protocol, lei, history, essentials, responsiveness), cada um com {points, max, reason, detail}. {} até que a contraparte tenha sido avaliada.", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "Pontos atribuídos a este componente." }, "max": { "type": "integer", "description": "Pontos máximos que este componente pode atribuir." }, "reason": { "type": "string", "description": "Código legível por máquina do veredito do componente." }, "detail": { "type": "string", "description": "Motivo legível por humanos para os pontos atribuídos." } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a avaliação de diligência devida foi executada pela última vez. Nulo até que a contraparte tenha sido avaliada." } }, "description": "O registo de diretório da contraparte, ou `null` quando a transferência não associa nenhum." }, "delivery": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TravelRuleDelivery" } ], "description": "A mensagem mais recente que a transferência deve a outra parte. `null` quando não deve nenhuma, por exemplo abaixo de `threshold_amount` ou para uma carteira autocustodiada declarada." }, "discovery": { "type": "array", "description": "Como a Didit procurou a contraparte, uma entrada por passo executado. Vazio quando não foi executada qualquer deteção, por exemplo, numa transferência recebida.", "items": { "$ref": "#/components/schemas/TravelRuleDiscoveryStep" } }, "reason": { "type": "string", "description": "O motivo pelo qual uma transferência `COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE` está bloqueada; `\"\"` para qualquer outro estado. Uma falha na entrega determina-o primeiro, apenas em `COUNTERPARTY_VASP_NOT_REACHABLE`: `email_undeliverable` (o fornecedor de e-mail recusou o e-mail de conformidade e não resta nenhum endereço para tentar: quando foi enviado, num lembrete ou como uma devolução permanente comunicada posteriormente) ou `delivery_failed` (o canal que estava a efetuar a entrega falhou definitivamente: um canal de rede recusou a mensagem ou esgotou as tentativas, um host de identidade `TRP` não respondeu, ou o host `TRP` da contraparte não aceitou a consulta). Caso contrário, o rastreio de `discovery` determina-o: `awaiting_end_user` (nenhum passo identificou uma contraparte que a Didit consiga contactar), `directory_match_no_route` (um passo identificou um VASP de diretório que não tem rota), `picked_member_without_proven_wallet` (o utilizador final escolheu um cliente Didit que não comprovou o controlo da carteira), ou `no_directory_match` quando o rastreio não fornece outro motivo. Um novo envio faz avançar a transferência, pelo que o motivo é limpo. Consulte [Por que motivo uma transferência está bloqueada](/pt/transaction-monitoring/travel-rule#por-que-motivo-uma-transferência-está-bloqueada)." }, "next_actions": { "type": "array", "description": "O que faz a transferência avançar; `[]` para qualquer estado exceto `COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE`. `email_undeliverable` disponibiliza `update_compliance_email` e, em seguida, `resend`. `delivery_failed` disponibiliza `resend`. Um motivo de descoberta disponibiliza `select_counterparty_vasp`, `declare_self_hosted`, `add_vasp_hint` e `resend`.", "items": { "$ref": "#/components/schemas/TravelRuleNextAction" } }, "chain_details": { "$ref": "#/components/schemas/TravelRuleChainDetails" } } }, "NetworkListCounts": { "type": "object", "description": "Contagens de redes para as vistas da lista e opções de filtro, sendo cada rede contada uma vez. Devolvido apenas quando `summary` não for `false`. `scopes` contam todas as redes visíveis para a aplicação. `views` contam as redes visíveis dentro do `scope` selecionado. `facets` contam as redes no `scope` e vista de `status` selecionados (redes dispensadas são excluídas, exceto se `status` as incluir). Os outros filtros da lista não alteram estas contagens.", "properties": { "scopes": { "type": "object", "description": "Redes visíveis por produto.", "properties": { "all": { "type": "integer" }, "identity": { "type": "integer", "description": "Todas as outras redes." }, "transactions": { "type": "integer", "description": "Redes cujos membros são todos partes da transação." } } }, "views": { "type": "object", "description": "Redes visíveis dentro do `scope` selecionado, por estado, mais duas vistas guardadas.", "properties": { "all": { "type": "integer" }, "active": { "type": "integer" }, "in_review": { "type": "integer" }, "resolved": { "type": "integer" }, "dismissed": { "type": "integer" }, "mine": { "type": "integer", "description": "Redes atribuídas ao membro da consola que fez a chamada. É sempre 0 para uma chave de API." }, "high_risk": { "type": "integer", "description": "Redes com uma pontuação de risco igual ou superior a 80 que não foram descartadas." } } }, "facets": { "type": "object", "description": "Contagens para cada opção de filtro, dentro do `scope` e vista de estado selecionados.", "properties": { "total": { "type": "integer", "description": "Redes no `scope` e vista de estado selecionados." }, "last_activity_days": { "type": "object", "description": "Redes com atividade nos últimos 7, 30 e 90 dias, indexadas pelo número de dias.", "properties": { "7": { "type": "integer" }, "30": { "type": "integer" }, "90": { "type": "integer" } } }, "risk_min": { "type": "object", "description": "Redes com uma pontuação de risco de pelo menos 50 e de pelo menos 80, indexadas pelo limiar.", "properties": { "50": { "type": "integer" }, "80": { "type": "integer" } } }, "signal_types": { "type": "object", "description": "Redes com pelo menos um sinal de cada tipo.", "properties": { "ip_address": { "type": "integer" }, "device": { "type": "integer" }, "face": { "type": "integer" }, "document_number": { "type": "integer" }, "phone": { "type": "integer" }, "email": { "type": "integer" }, "address": { "type": "integer" } } }, "priority": { "type": "object", "description": "Redes por prioridade. `none` conta redes sem prioridade.", "properties": { "low": { "type": "integer" }, "medium": { "type": "integer" }, "high": { "type": "integer" }, "none": { "type": "integer" } } }, "assignee": { "type": "object", "description": "Redes por responsável.", "properties": { "me": { "type": "integer", "description": "Atribuído ao membro da consola que efetua a chamada. Sempre 0 para uma chave de API." }, "unassigned": { "type": "integer", "description": "Não atribuído a ninguém." }, "users": { "type": "array", "description": "Uma entrada por responsável atribuído, com mais redes primeiro.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "full_name": { "type": "string", "description": "O nome do responsável atribuído, ou o seu e-mail caso não esteja definido nenhum nome." }, "email": { "type": "string" }, "count": { "type": "integer" } } } } } }, "has_case": { "type": "integer", "description": "Redes para as quais esta aplicação abriu um caso." }, "min_size": { "type": "object", "description": "Redes com pelo menos 10 membros, indexadas pelo tamanho mínimo.", "properties": { "10": { "type": "integer" } } } } } } }, "NetworkTag": { "type": "object", "description": "Uma das etiquetas da sua aplicação na rede.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "O UUID da etiqueta, o mesmo valor transmitido como `tag_uuid`." }, "name": { "type": "string" }, "color": { "type": "string", "description": "Cor hexadecimal, por exemplo `#6366F1`." }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "`didit` para uma etiqueta predefinida da Didit, `custom` para uma etiqueta criada pela sua equipa." }, "added_by": { "type": "string", "nullable": true, "description": "E-mail do membro da consola que adicionou a etiqueta. Null quando adicionada por uma chave de API." }, "added_at": { "type": "string", "format": "date-time" } } }, "NetworkOutcomes": { "type": "object", "description": "O estado em que se encontram as pessoas e empresas da rede. Cada membro que possa ver conta uma vez, pelo estado da sua verificação mais recente que tenha chegado a uma decisão. As partes da transação não são contabilizadas.", "properties": { "approved": { "type": "integer", "description": "Membros cuja verificação decidida mais recente foi aprovada." }, "declined": { "type": "integer", "description": "Membros cuja verificação decidida mais recente foi recusada." }, "in_review": { "type": "integer", "description": "Membros cuja verificação decidida mais recente está em análise." }, "total": { "type": "integer", "description": "Membros com pelo menos uma verificação, decidida ou não. Um membro cujas verificações estejam todas indecisas (não iniciadas, em curso, expiradas ou abandonadas) é contabilizado aqui e em nenhuma outra chave." } } }, "NetworkPatternScore": { "type": "object", "description": "O quão semelhantes são os dados de um determinado tipo dos membros em toda a rede. Um padrão não é um sinal: nenhum valor partilhado liga os membros.", "properties": { "type": { "type": "string", "enum": [ "background" ], "description": "`background`: a similaridade média de cada par de fundos das selfies dos membros, com a pessoa ocultada. Lê a selfie mais recente de cada pessoa, no máximo as 50 mais recentes, e exclui sessões de validação da idade. Abrange toda a rede, não apenas os membros das suas aplicações." }, "score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1, "description": "De 0 a 1, arredondado a 4 casas decimais. Null quando `reason` está definido." }, "members": { "type": "integer", "nullable": true, "description": "Quantas selfies de membros a pontuação comparou. Uma selfie que não possa ser lida, ou que mostre muito pouco fundo, não é comparada. Nulo enquanto estiver em `computing`; 0 ou 1 com `not_enough_selfies`." }, "reason": { "type": "string", "enum": [ "computing", "not_enough_selfies" ], "nullable": true, "description": "O motivo pelo qual não há pontuação. `computing`: a pontuação para os membros atuais está a ser calculada; consulte novamente a rede mais tarde. `not_enough_selfies`: menos de dois membros têm uma selfie utilizável. Nulo quando existe uma pontuação." }, "computed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a pontuação foi calculada. Nulo enquanto estiver em `computing`." } } }, "NetworkDetailResponse": { "description": "Os detalhes da rede, mais o modo de partilha da organização, se os sinais entre organizações se aplicam à mesma, as etiquetas da sua aplicação na rede, os resultados dos membros e as pontuações de padrões.", "allOf": [ { "$ref": "#/components/schemas/NetworkDetail" }, { "type": "object", "properties": { "sharing_mode": { "type": "string", "enum": [ "off", "private", "global" ], "description": "O modo de partilha entre organizações da organização. Apenas `global` compara redes entre organizações; `private` e `off` restringem-nas ao próprio histórico da organização.", "example": "global" }, "cross_org_available": { "type": "boolean", "description": "Se os sinais entre organizações se aplicam a esta organização. Exigem tanto o plano Enterprise como o modo de partilha `global`.", "example": true }, "cross_org_unavailable_reason": { "type": "string", "enum": [ "plan", "sharing_mode" ], "nullable": true, "description": "O motivo pelo qual os sinais interorganizacionais não se aplicam, verificados por esta ordem. `plan`: o plano da organização não inclui a rede de fraude interorganizacional (requer o plano Enterprise), independentemente do modo de partilha. `sharing_mode`: o plano inclui-a, mas o modo de partilha é `private` ou `off`. Nulo quando `cross_org_available` é `true`.", "example": null }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTag" }, "description": "As etiquetas da sua aplicação na rede, as mais antigas primeiro. Cada aplicação vê apenas as suas próprias etiquetas. `fraud_tags` é separado e não se altera: as etiquetas que os membros da rede possuem." }, "outcomes": { "$ref": "#/components/schemas/NetworkOutcomes" }, "patterns": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkPatternScore" }, "description": "Pontuações de padrão em toda a rede. Atualmente um item, `background`." } } } ] }, "NetworkTagRequest": { "type": "object", "required": [ "tag_uuid" ], "properties": { "tag_uuid": { "type": "string", "format": "uuid", "description": "UUID de uma das etiquetas da sua aplicação." } }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "NetworkTimeline": { "title": "Default timeline (no contract)", "type": "object", "description": "Sem `contract`: os eventos próprios da rede, do mais antigo para o mais recente, sem paginação.", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTimelineEvent" } } } }, "NetworkTimelinePage": { "title": "Typed timeline page (contract=2)", "type": "object", "description": "Com `contract=2`: uma página de eventos tipados, os mais recentes primeiro.", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTypedTimelineEvent" } }, "next_cursor": { "type": "string", "nullable": true, "description": "Passe como `cursor` para ler a página seguinte. Nulo na última página." } } }, "NetworkTypedTimelineEvent": { "type": "object", "description": "Um evento de linha cronológica tipificado: os quatro campos padrão, mais o respetivo id, quando a Didit o armazenou, a conta de membro e o registo a que pertence, e o bloco de detalhes do respetivo tipo de evento. Os outros blocos de detalhes são nulos.", "properties": { "id": { "type": "string", "description": "`:`, exclusivo na cronologia.", "example": "session:3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "event_type": { "type": "string", "enum": [ "network_detected", "signal_observed", "network_active", "network_in_review", "network_resolved", "network_dismissed", "verification_attempt", "transaction", "login", "rule_hit", "case_linked", "note_added" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "Quando aconteceu." }, "ingested_at": { "type": "string", "format": "date-time", "description": "Quando a Didit o armazenou." }, "label": { "type": "string", "description": "Uma etiqueta curta em inglês, por exemplo `Verification attempt 2 of 3`." }, "metadata": { "type": "object", "description": "Para os eventos da própria rede, os mesmos metadados que a linha temporal predefinida. Vazio caso contrário." }, "account": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAccount" } ], "nullable": true, "description": "A conta de membro. Nulo para os eventos próprios da rede, `case_linked` e `note_added`." }, "source_ref": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineSourceRef" } ], "nullable": true, "description": "O registo de origem. Nulo para os eventos próprios da rede e para `note_added`." }, "verification_attempt": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAttempt" } ], "nullable": true, "description": "Definido em eventos `verification_attempt`." }, "transaction": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineTransaction" } ], "nullable": true, "description": "Definido em eventos `transaction`." }, "login": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineLogin" } ], "nullable": true, "description": "Definido em eventos `login`." }, "rule_hit": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineRuleHit" } ], "nullable": true, "description": "Definido em eventos `rule_hit`." }, "case_linked": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineCaseLinked" } ], "nullable": true, "description": "Definido em eventos `case_linked`." }, "note_added": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineNoteAdded" } ], "nullable": true, "description": "Definido em eventos `note_added`. Nunca é devolvido a uma chave de API." } } }, "NetworkTimelineAccount": { "type": "object", "description": "A conta de membro à qual o evento pertence.", "properties": { "node_id": { "type": "string", "description": "`:`, onde o tipo é `vendor_user`, `vendor_business` ou `transaction_party`.", "example": "vendor_user:3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "node_type": { "type": "string", "enum": [ "account", "business_account", "transaction_party" ] }, "uuid": { "type": "string", "format": "uuid" }, "vendor_data": { "type": "string", "nullable": true }, "display_name": { "type": "string", "nullable": true }, "ownership": { "type": "string", "enum": [ "owned", "organization" ], "description": "`owned` quando o registo pertence à aplicação que foi chamada (para um membro da consola, a uma aplicação à qual foi concedido acesso). `organization` quando pertence a outra aplicação da sua organização." }, "route": { "$ref": "#/components/schemas/NetworkTimelineRoute" } } }, "NetworkTimelineSourceRef": { "type": "object", "description": "O registo a partir do qual o evento foi lido.", "properties": { "kind": { "type": "string", "enum": [ "session", "business_session", "transaction", "monitoring_event", "case" ] }, "id": { "type": "string", "format": "uuid" }, "ownership": { "type": "string", "enum": [ "owned", "organization" ], "description": "`owned` quando o registo pertence à aplicação que foi chamada (para um membro da consola, a uma aplicação à qual foi concedido acesso). `organization` quando pertence a outra aplicação da sua organização." }, "route": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineRoute" } ], "description": "Não presente em `monitoring_event` e `case`." } } }, "NetworkTimelineRoute": { "type": "object", "description": "Onde o registo abre: o seu tipo, o seu UUID e a aplicação a que pertence.", "properties": { "kind": { "type": "string", "description": "`user`, `business` ou `transaction_party` para uma conta; `session`, `business_session` ou `transaction` para um registo de origem." }, "id": { "type": "string", "format": "uuid" }, "application_id": { "type": "string", "format": "uuid" } } }, "NetworkTimelineAttempt": { "type": "object", "description": "Uma sessão de verificação da conta.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "O UUID da sessão, ou o UUID da sessão de empresa para uma empresa." }, "session_number": { "type": "integer", "nullable": true }, "attempt": { "type": "integer", "description": "A posição desta sessão entre as sessões da conta, por ordem de criação." }, "attempt_count": { "type": "integer", "description": "Quantas sessões a conta tem." }, "status": { "type": "string", "description": "O estado da sessão, por exemplo `Approved` ou `Declined`." }, "status_changed_at": { "type": "string", "format": "date-time", "nullable": true }, "decline_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTimelineDeclineReason" }, "description": "Apenas para uma sessão recusada: os seus avisos, do mais antigo para o mais recente, uma vez por aviso. Vazio caso contrário." } } }, "NetworkTimelineDeclineReason": { "type": "object", "properties": { "risk": { "type": "string", "description": "O código do aviso." }, "feature": { "type": "string", "description": "A funcionalidade que gerou o aviso." }, "short_description": { "type": "string" } } }, "NetworkTimelineTransaction": { "type": "object", "description": "Uma transação na qual uma conta de membro participou, datada pela sua data de transação.", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "transaction_number": { "type": "integer", "nullable": true }, "transaction_type": { "type": "string" }, "action_type": { "type": "string" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAmount" } ], "nullable": true, "description": "Null quando a transação não tem montante." }, "status": { "type": "string" }, "decision_reason_code": { "type": "string", "nullable": true }, "decision_reason_label": { "type": "string", "nullable": true }, "party_role": { "type": "string", "description": "A função da conta na transação: `APPLICANT`, `REMITTER`, `BENEFICIARY` ou `COUNTERPARTY`." } } }, "NetworkTimelineAmount": { "type": "object", "properties": { "value": { "type": "string", "description": "Montante decimal como string." }, "currency": { "type": "string" }, "direction": { "type": "string", "nullable": true } } }, "NetworkTimelineLogin": { "type": "object", "description": "Um evento de início de sessão que enviou para uma pessoa através da API de eventos.", "properties": { "action": { "type": "string", "description": "`.`: `auth.login` ou `security.login_succeeded` para um início de sessão, `auth.login_failed` ou `security.login_failed` para um início de sessão com falha." }, "succeeded": { "type": "boolean" }, "status": { "type": "string", "description": "O estado do evento." }, "ip": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineIP" } ], "nullable": true, "description": "Null quando o evento não tem endereço IP." }, "device": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineDevice" } ], "nullable": true, "description": "Nulo quando o evento não tem impressão digital de dispositivo nem contexto." }, "is_first_login": { "type": "boolean", "description": "O primeiro início de sessão bem-sucedido registado da conta." }, "is_new_device": { "type": "boolean", "description": "Um início de sessão bem-sucedido a partir de um dispositivo a partir do qual não foi efetuado nenhum dos inícios de sessão anteriores bem-sucedidos da conta. Nunca é verdadeiro no primeiro início de sessão." } } }, "NetworkTimelineIP": { "type": "object", "properties": { "address": { "type": "string" }, "country_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "connection_type": { "type": "string", "nullable": true, "description": "A etiqueta do tipo de ligação para o endereço, como texto livre." }, "is_vpn_or_tor": { "type": "boolean" }, "is_data_center": { "type": "boolean" } } }, "NetworkTimelineDevice": { "type": "object", "properties": { "fingerprint": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true, "description": "Uma etiqueta legível do dispositivo criada a partir do contexto do dispositivo do evento." } } }, "NetworkTimelineRuleHit": { "type": "object", "description": "Uma regra ativa que correspondeu a uma transação ou evento de um membro. As correspondências em modo de teste não estão incluídas.", "properties": { "rule_id": { "type": "string", "format": "uuid" }, "rule_title": { "type": "string" }, "rule_category": { "type": "string" }, "rule_source": { "type": "string" }, "severity": { "type": "string", "nullable": true }, "score_delta": { "type": "integer" }, "status_target": { "type": "string", "nullable": true }, "action_summary": { "type": "string", "nullable": true } } }, "NetworkTimelineCaseLinked": { "type": "object", "description": "Um caso aberto para a rede na sua organização. `source_ref.ownership` indica se pertence à aplicação que chamou.", "properties": { "case_id": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "status": { "type": "string" }, "author_email": { "type": "string", "nullable": true }, "author_name": { "type": "string", "nullable": true } } }, "NetworkTimelineNoteAdded": { "type": "object", "description": "Uma nota deixada na rede. O texto da nota não está incluído.", "properties": { "note_id": { "type": "string", "format": "uuid" }, "author_email": { "type": "string" } } }, "FeatureStatusOverride": { "type": "object", "description": "Uma sobreposição do estado de uma verificação (funcionalidade) efetuada com `PATCH /v3/session/{sessionId}/features/{nodeId}/update-status/`: o que altera, se foi aplicada ou se ainda aguarda que a pessoa conclua o fluxo, quem solicitou e porquê.", "required": [ "id", "node_id", "feature_type", "feature_model", "previous_status", "new_status", "state", "forced", "reason", "requested_by", "requested_at", "applied_at", "cancelled_at", "cancel_reason" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador da substituição. Transmita-o para o endpoint de cancelamento.", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "node_id": { "type": "string", "description": "O nó do fluxo indicado pelo pedido (`default` para um passo sem nó).", "example": "feature_ocr_1" }, "feature_type": { "type": "string", "description": "O `feature_type` transmitido pelo pedido, ou uma string vazia se nenhum tiver sido transmitido.", "example": "" }, "feature_model": { "type": "string", "description": "O tipo de verificação que foi substituído, por exemplo `KYC`, `Face`, `AML` ou `GeolocationCheck`.", "example": "KYC" }, "previous_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "O estado da verificação quando a substituição foi solicitada.", "example": "In Review" }, "new_status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "O estado definido pela sobreposição.", "example": "Approved" }, "state": { "type": "string", "enum": [ "applied", "pending_until_flow_finishes", "cancelled" ], "description": "`applied`: a verificação tem o novo estado. `pending_until_flow_finishes`: a substituição aguarda e é aplicada quando a pessoa terminar o fluxo. `cancelled`: aguardou e nunca foi aplicada (consulte `cancel_reason`).", "example": "applied" }, "forced": { "type": "boolean", "description": "`true` quando a substituição foi aplicada de imediato enquanto a pessoa ainda estava no fluxo.", "example": false }, "reason": { "type": "string", "nullable": true, "description": "O `comment` enviado com o pedido, ou `null`.", "example": "Document manually verified by compliance." }, "requested_by": { "type": "object", "nullable": true, "description": "Quem solicitou a substituição, ou `null` quando não for conhecido.", "properties": { "email": { "type": "string", "format": "email", "nullable": true, "description": "E-mail do utilizador da consola, ou `null` para chaves de API e para o sistema.", "example": "reviewer@example.com" }, "name": { "type": "string", "nullable": true, "description": "Nome de apresentação do requerente, ou `null`.", "example": "Alex Reviewer" }, "type": { "type": "string", "enum": [ "CONSOLE_USER", "API_KEY", "SYSTEM" ], "description": "Quem fez o pedido: um utilizador da consola, uma chave de API ou a própria Didit.", "example": "CONSOLE_USER" } } }, "requested_at": { "type": "string", "format": "date-time", "description": "Quando a substituição foi solicitada.", "example": "2026-10-13T09:15:00Z" }, "applied_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a verificação assumiu o novo estado, ou `null` enquanto aguarda ou assim que for cancelada.", "example": "2026-10-13T09:15:00Z" }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando uma substituição em espera foi cancelada, ou `null`.", "example": null }, "cancel_reason": { "type": "string", "nullable": true, "enum": [ "cancelled_by_reviewer", "replaced", "check_changed", "session_closed", null ], "description": "O motivo pelo qual uma sobreposição pendente nunca foi aplicada, ou `null`. `cancelled_by_reviewer`: cancelada com o endpoint de cancelamento. `replaced`: uma sobreposição mais recente na mesma verificação substituiu-a. `check_changed`: a pessoa repetiu a verificação antes de concluir o fluxo. `session_closed`: a sessão saiu do fluxo antes de a pessoa o concluir (abandonada, expirada ou decidida a meio do fluxo).", "example": null } } }, "SandboxSimulateRequest": { "type": "object", "description": "Forçar o estado de uma sessão em sandbox. Todos os campos são opcionais, mas pelo menos um de `new_status`, `scenario` ou `risk` é obrigatório.", "properties": { "new_status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Abandoned" ], "description": "O estado a definir. Se for omitido, assume por predefinição o estado predefinido do caso de risco (`risk`, ou o primeiro risco que os valores mágicos do cenário contiverem); caso contrário, assume o estado predefinido do cenário.", "example": "Declined" }, "comment": { "type": "string", "maxLength": 500, "description": "Nota adicionada à entrada de atividade que a alteração de estado regista.", "example": "Testing the decline path" }, "scenario": { "type": "string", "maxLength": 100, "description": "Um identificador (slug) de cenário do catálogo (`GET /v1/sandbox/scenarios/`). Fornece o estado predefinido e, sem `risk`, o aviso que os seus valores mágicos contêm. Um identificador desconhecido devolve `400`.", "example": "decline_aml_hit" }, "risk": { "type": "string", "maxLength": 128, "description": "Um caso de risco do catálogo. O seu aviso é adicionado à sessão, com um tipo de registo que segue `new_status`. Um valor desconhecido devolve `400`.", "example": "POSSIBLE_MATCH_FOUND" }, "node_id": { "type": "string", "maxLength": 128, "description": "Nó do fluxo ao qual o aviso de risco está associado. A predefinição é o nó atual da sessão.", "example": "feature_aml_1" }, "send_webhooks": { "type": "boolean", "default": true, "description": "`true` envia exatamente os webhooks que uma alteração de estado real envia para os destinos da aplicação de sandbox: `status.updated`, além dos eventos `user.status.updated` / `user.data.updated` (ou `business.status.updated` / `business.data.updated`) causados pela alteração, para destinos subscritos aos mesmos. `false` altera o estado sem registar ou enviar qualquer webhook: a recuperação de webhooks perdidos nunca reenvia essa decisão, a consola continua a atualizar em tempo real e a próxima alteração de estado da sessão envia webhooks normalmente.", "example": true } } }, "SandboxSimulateResponse": { "type": "object", "required": [ "session_id", "previous_status", "status", "scenario", "risk", "send_webhooks" ], "properties": { "session_id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "previous_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "O estado da sessão antes da simulação.", "example": "In Progress" }, "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Abandoned" ], "description": "O estado definido pela simulação.", "example": "Declined" }, "scenario": { "type": "string", "nullable": true, "description": "O slug do cenário que transmitiu, ou `null`.", "example": "decline_aml_hit" }, "risk": { "type": "string", "nullable": true, "description": "O caso de risco aplicado (`risk`, ou o que foi obtido a partir do cenário), ou `null` quando não existir nenhum.", "example": "POSSIBLE_MATCH_FOUND" }, "send_webhooks": { "type": "boolean", "description": "O valor de `send_webhooks` que a simulação aplicou.", "example": false } } }, "CaseTeamSummary": { "type": "object", "nullable": true, "description": "A equipa de revisão responsável pelo caso, ou null quando nenhuma equipa for responsável. O encaminhamento define-a quando uma regra de encaminhamento atribui o caso a uma das suas equipas. Altere ou limpe este valor com `PATCH .../cases/{case_uuid}/` (`team`).", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "CaseChecker": { "type": "object", "nullable": true, "description": "O membro designado para aprovar ou rejeitar a resolução pendente. Definido apenas enquanto uma resolução de quatro olhos aguarda por um revisor designado. Nulo quando nada estiver pendente, enquanto a resolução pendente aguarda na fila de revisores e assim que a resolução for aprovada, rejeitada ou devolvida para uma nova revisão porque as provas foram alteradas.", "properties": { "member_uuid": { "type": "string", "format": "uuid", "description": "O uuid de utilizador do membro: o valor que passa como `checker` ao resolver o caso." }, "name": { "type": "string", "nullable": true, "description": "O nome completo do membro, ou nulo quando não for conhecido." }, "email": { "type": "string", "format": "email" } } }, "ServiceStatusFeed": { "type": "object", "description": "Estado público do serviço: o estado de cada serviço Didit, o estado global e os incidentes que estão em curso ou foram resolvidos nos últimos 7 dias.", "required": [ "status", "updated_at", "services", "incidents" ], "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "down" ], "description": "O pior estado de qualquer serviço neste momento, determinado apenas pelos incidentes em curso.", "example": "degraded" }, "updated_at": { "type": "string", "format": "date-time", "description": "Quando a Didit construiu esta resposta (ISO 8601, UTC). As respostas são guardadas em cache durante 30 segundos, pelo que podem ter até 30 segundos de antiguidade.", "example": "2026-10-13T09:41:07.512345Z" }, "services": { "type": "array", "description": "Uma entrada por serviço, com todos os serviços sempre listados.", "items": { "$ref": "#/components/schemas/ServiceStatusService" } }, "incidents": { "type": "array", "description": "`started_at` mais recente primeiro. Todos os incidentes em curso, mais os incidentes resolvidos nos últimos 7 dias (no máximo 50 incidentes resolvidos). Vazio quando nada aconteceu nesse período.", "items": { "$ref": "#/components/schemas/ServiceStatusIncident" } } } }, "ServiceStatusService": { "type": "object", "required": [ "key", "name", "status" ], "properties": { "key": { "type": "string", "enum": [ "service_id_verification", "service_liveness_face_match", "service_aml_screening", "service_kyb_registries", "service_database_validation", "service_phone_delivery", "service_email_delivery", "service_transaction_monitoring" ], "description": "Chave de serviço estável. Efetue a correspondência com base neste campo, nunca pelo nome de exibição. `service_id_verification`: Verificação de identidade, `service_liveness_face_match`: Prova de vida e correspondência facial, `service_aml_screening`: Triagem AML, `service_kyb_registries`: Registos KYB, `service_database_validation`: Validação de base de dados, `service_phone_delivery`: Entrega de verificação de telefone, `service_email_delivery`: Entrega de verificação de e-mail, `service_transaction_monitoring`: Monitorização de transações.", "example": "service_database_validation" }, "name": { "type": "string", "description": "Nome de apresentação em inglês do serviço.", "example": "Database validation" }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ], "description": "`operational` quando não há incidentes em curso para o serviço; caso contrário, o pior estado dos seus incidentes em curso.", "example": "degraded" } } }, "ServiceStatusIncident": { "type": "object", "required": [ "id", "service", "service_name", "state", "status", "title", "body", "affected", "country_name", "started_at", "resolved_at", "duration_minutes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID do incidente.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "service": { "type": "string", "enum": [ "service_id_verification", "service_liveness_face_match", "service_aml_screening", "service_kyb_registries", "service_database_validation", "service_phone_delivery", "service_email_delivery", "service_transaction_monitoring" ], "description": "Chave do serviço afetado (consulte `services[].key`).", "example": "service_database_validation" }, "service_name": { "type": "string", "description": "Nome de apresentação em inglês do serviço afetado.", "example": "Database validation" }, "state": { "type": "string", "enum": [ "degraded", "down" ], "description": "Como o serviço é afetado. Um incidente resolvido mantém o último estado em que se encontrava.", "example": "degraded" }, "status": { "type": "string", "enum": [ "ongoing", "resolved" ], "description": "`ongoing` até que o serviço recupere, depois `resolved`.", "example": "ongoing" }, "title": { "type": "string", "description": "Título em inglês. Para o traduzir, construa o seu próprio texto a partir de `service`, `state` e `country_name`.", "example": "Database validation is degraded in Brazil." }, "body": { "type": "string", "description": "Linha de detalhe em inglês: desde quando as verificações podem estar lentas ou falhar, ou quando recuperou.", "example": "Checks against Brazil (CPF) may be slow or fail since 08:55 UTC." }, "affected": { "type": "string", "description": "Países ou registos afetados, por exemplo `Brazil (CPF)`. Vazio quando o incidente não está associado a um país ou registo.", "example": "Brazil (CPF)" }, "country_name": { "type": "string", "description": "País afetado, em inglês. Vazio quando o incidente não está associado a um país.", "example": "Brazil" }, "started_at": { "type": "string", "format": "date-time", "description": "Quando o incidente começou (ISO 8601, UTC).", "example": "2026-10-13T08:55:00Z" }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o serviço recuperou (ISO 8601, UTC). `null` enquanto o incidente estiver em curso." }, "duration_minutes": { "type": "integer", "nullable": true, "description": "Minutos inteiros desde `started_at` até `resolved_at`. `null` enquanto o incidente estiver em curso." } } }, "TravelRuleJoinInvitation": { "type": "object", "description": "O que a página de adesão apresenta antes de qualquer elemento ser introduzido.", "properties": { "email": { "type": "string", "format": "email", "description": "O endereço para o qual o convite foi enviado." }, "vasp_name": { "type": "string" }, "source": { "type": "string", "description": "De onde veio o convite, por exemplo `pickup`." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "prefill": { "type": "object", "properties": { "vasp_id": { "type": "string", "format": "uuid", "nullable": true }, "legal_name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } } } } } }, "TravelRuleJoinRegisterRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Tem de ser o endereço para o qual o convite foi enviado." }, "password": { "type": "string", "minLength": 8, "maxLength": 128 } } }, "TravelRuleJoinVerifyRequest": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "code": { "type": "string", "minLength": 6, "maxLength": 6, "description": "O código de 6 carateres enviado por e-mail após o registo." } } }, "TravelRuleJoinCredentials": { "type": "object", "description": "A nova organização gratuita e as credenciais com as quais a sua aplicação chama a API.", "properties": { "organization": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } }, "application": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } }, "client_id": { "type": "string" }, "api_key": { "type": "string", "description": "Envie como o cabeçalho `x-api-key` nos endpoints da área de trabalho." } } }, "TravelRuleWorkspaceClaimRequest": { "type": "object", "required": [ "vasp_id" ], "properties": { "vasp_id": { "type": "string", "format": "uuid", "description": "A entrada do diretório correspondente a este espaço de trabalho. Obtenha os IDs a partir de `GET /v3/travel-rule/vasps/`." } } }, "TravelRuleWorkspaceDomainConfirmRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6 } } }, "TravelRuleWorkspaceBillingRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Apenas `true` é aceite: a faturação de saída não pode ser desativada novamente através da API." } } }, "TravelRuleWorkspaceDomainCodeResponse": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "unverified", "code_sent", "verified" ] }, "txt": { "$ref": "#/components/schemas/TravelRuleWorkspaceTxtRecord" } } }, "TravelRuleWorkspaceTxtRecord": { "type": "object", "description": "O registo TXT a publicar para a prova de DNS. Vazio até que uma prova tenha sido iniciada.", "properties": { "host": { "type": "string", "example": "didit-tr-verify.example.com" }, "value": { "type": "string" } } }, "TravelRuleWorkspace": { "type": "object", "description": "O espaço de trabalho gratuito de Travel Rule de uma aplicação que aderiu gratuitamente.", "properties": { "joined_free": { "type": "boolean" }, "work_email": { "type": "string", "format": "email" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "claim": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unclaimed", "pending_review", "claimed", "rejected" ] }, "proved_by_domain": { "type": "boolean" }, "claimed_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_note": { "type": "string" }, "vasp_id": { "type": "string", "format": "uuid", "nullable": true }, "vasp_name": { "type": "string" } } }, "prefill": { "type": "object", "description": "Valores de perfil obtidos da entrada do diretório: `vasp_id`, `legal_name`, `lei`, `jurisdiction`, `compliance_email`, `domains`. Nada é gravado até que a reivindicação seja feita." }, "domain": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "unverified", "code_sent", "verified" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "txt": { "$ref": "#/components/schemas/TravelRuleWorkspaceTxtRecord" } } }, "billing_enabled": { "type": "boolean", "description": "A receção de dados da Travel Rule é gratuita. O envio só é faturado após a faturação ser ativada." }, "billing_enabled_at": { "type": "string", "format": "date-time", "nullable": true }, "didit_network": { "type": "object", "description": "Se a rede Didit lista este VASP e, caso contrário, cada condição que ainda lhe falta." }, "settings": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" } } }, "InvestigatorDecision": { "type": "object", "description": "Como o elemento saiu da fila do Investigator. `decided_by`, `original_outcome` e `overrides` são devolvidos pelos endpoints de aceitação e substituição e pelo relatório; o bloco `investigator` de uma decisão de sessão inclui os restantes campos.", "properties": { "outcome": { "type": "string", "enum": [ "accepted", "edited", "overridden", "decided_elsewhere", "automated" ], "description": "`accepted` ou `edited` aceitou a recomendação (`edited` com uma narrativa reescrita), `overridden` aplicou outra ação, `decided_elsewhere` é uma decisão tomada fora do Investigator enquanto o relatório estava aberto, `automated` é uma decisão tomada pelo próprio Investigator." }, "action": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "override_category": { "type": "string", "enum": [ "missing_context", "needs_information", "policy_differs", "evidence_misread", "other", "" ], "nullable": true }, "override_reason": { "type": "string", "nullable": true }, "final_status": { "type": "string", "description": "O estado do item após a decisão." }, "agreed": { "type": "boolean", "description": "Indica se a decisão coincidiu com a recomendação.", "nullable": true }, "decided_at": { "type": "string", "format": "date-time" }, "billed": { "type": "boolean", "description": "A revisão foi cobrada." }, "decided_by": { "type": "string", "enum": [ "investigator", "member" ] }, "original_outcome": { "type": "object", "description": "A decisão tomada autonomamente pelo investigador, inalterada por sobreposições posteriores. Null para uma decisão tomada pela equipa.", "properties": { "action": { "type": "string" }, "final_status": { "type": "string" }, "decided_at": { "type": "string", "format": "date-time" } }, "nullable": true }, "overrides": { "type": "array", "description": "Cada anulação de uma decisão tomada autonomamente pelo investigador, da mais antiga para a mais recente.", "items": { "type": "object", "properties": { "action": { "type": "string" }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "override_category": { "type": "string" }, "override_reason": { "type": "string" }, "previous_status": { "type": "string" }, "final_status": { "type": "string" }, "agreed": { "type": "boolean", "nullable": true }, "overridden_at": { "type": "string", "format": "date-time" } } } } } }, "InvestigatorBlock": { "type": "object", "nullable": true, "description": "A revisão mais recente do Investigator sobre o item, ou nulo se nunca tiver tido nenhuma. Transmitida pela decisão da sessão V3 e da sessão empresarial (e, portanto, por webhooks `status.updated`).", "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "stage": { "type": "string", "enum": [ "shadow", "live" ] }, "queue": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] }, "is_open": { "type": "boolean" }, "recommendation": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ], "nullable": true }, "recommendation_detail": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "moderate", "low" ], "nullable": true }, "summary": { "type": "string", "nullable": true }, "ready_to_accept": { "type": "boolean" }, "prepared_at": { "type": "string", "format": "date-time", "nullable": true }, "automated": { "type": "boolean", "description": "O investigador decidiu autonomamente, mesmo que a decisão tenha sido posteriormente substituída." }, "decided_by": { "type": "string", "enum": [ "investigator", "member" ], "nullable": true }, "decision": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InvestigatorDecision" } ], "type": "object" } } }, "InvestigatorQueueRow": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "session", "business_session", "transaction", "case" ] }, "queue": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] }, "stage": { "type": "string", "enum": [ "shadow", "live" ] }, "subject": { "type": "object", "description": "O item em análise: `id`, `number`, `status`, `name` e, dependendo do tipo, `country`, `workflow`, `vendor_data`, `txn_id`, `amount`, `currency`, `direction`, `title` ou `priority`.", "additionalProperties": true }, "recommendation": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "recommendation_detail": { "type": "string" }, "confidence": { "type": "string", "enum": [ "high", "moderate", "low" ] }, "summary": { "type": "string" }, "sources_count": { "type": "integer" }, "ready_to_accept": { "type": "boolean" }, "guardrails": { "description": "Os limites de proteção bloqueados que contêm este item, se existirem." }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "prepared_at": { "type": "string", "format": "date-time", "nullable": true } } }, "InvestigatorRunDetail": { "allOf": [ { "$ref": "#/components/schemas/InvestigatorQueueRow" }, { "type": "object", "properties": { "status": { "type": "string" }, "is_open": { "type": "boolean" }, "lookups": { "type": "integer", "description": "Quantas secções e registos associados foram lidos." }, "duration_ms": { "type": "integer", "nullable": true }, "agent_version": { "type": "string" }, "prepared_before_opened": { "type": "boolean", "nullable": true }, "report": { "type": "object", "additionalProperties": true, "description": "O relatório: fundamentação, pontos de evidência com o respetivo veredicto (`ok`, `risk`, `look`, `explained`, `context`) e fontes citadas, veredictos dos resultados da triagem (`same`, `not_same`, `unclear`) e próximos passos sugeridos." }, "trail": { "description": "O que verifiquei: a visão geral, secções e registos que leu, por ordem." }, "decision": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InvestigatorDecision" } ], "type": "object" }, "autonomy": { "type": "object", "additionalProperties": true, "description": "O que o processamento autónomo determinou para o relatório (`result`, `reason`, `tier`, `policy_version`, `rule`, `agreement`, `decisions`, `threshold`, `at`). Nulo quando a fila não for automatizada.", "nullable": true } } } ] }, "InvestigatorAcceptRequest": { "type": "object", "properties": { "narrative": { "type": "string", "maxLength": 4000, "description": "Um texto descritivo reescrito. O envio regista a decisão como editada e aceite." }, "send_email": { "type": "boolean", "default": false, "description": "Enviar um e-mail à pessoa sobre a decisão." }, "email_address": { "type": "string", "format": "email", "description": "Obrigatório quando `send_email` é true." }, "email_language": { "type": "string", "default": "en", "maxLength": 16 } } }, "InvestigatorOverrideRequest": { "type": "object", "required": [ "action", "category", "reason" ], "properties": { "action": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "category": { "type": "string", "enum": [ "missing_context", "needs_information", "policy_differs", "evidence_misread", "other" ] }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 }, "send_email": { "type": "boolean", "default": false, "description": "Enviar um e-mail à pessoa sobre a decisão." }, "email_address": { "type": "string", "format": "email", "description": "Obrigatório quando `send_email` é true." }, "email_language": { "type": "string", "default": "en", "maxLength": 16 } } }, "InvestigatorBatchAcceptRequest": { "type": "object", "required": [ "run_ids" ], "properties": { "run_ids": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "format": "uuid" } } } }, "InvestigatorBatchAcceptResponse": { "type": "object", "properties": { "accepted": { "type": "integer" }, "skipped": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "result": { "type": "string", "enum": [ "accepted", "skipped" ] }, "reason": { "type": "string", "enum": [ "not_found", "forbidden", "already_decided", "not_ready", "guardrail", "invalid" ] }, "detail": {}, "action": { "type": "string" }, "final_status": { "type": "string" } } } } } }, "InvestigatorSettings": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "none", "shadow", "live" ] }, "stage_changed_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "stage_changed_by": { "type": "string", "readOnly": true }, "monthly_spend_limit": { "type": "string", "format": "decimal", "description": "Limite mensal na sua moeda de faturação, de 0,01 a 1 000 000. Nulo desativa-o.", "nullable": true }, "spend_limit": { "type": "object", "readOnly": true, "properties": { "enabled": { "type": "boolean" }, "limit": { "type": "string", "format": "decimal", "nullable": true }, "spent": { "type": "string", "format": "decimal" }, "reviews": { "type": "integer" }, "reserved": { "type": "string", "format": "decimal", "description": "O preço de cada relatório em tempo real aberto, retido porque a sua aceitação implica cobrança." }, "currency": { "type": "string" }, "paused": { "type": "boolean", "description": "No limite: nenhuma nova revisão tem início." } } } } }, "TravelRuleUtxoEntry": { "type": "object", "description": "Uma entrada ou saída de uma transação UTXO, tal como a blockchain a registou.", "required": [ "address" ], "properties": { "address": { "type": "string", "maxLength": 128 }, "amount": { "type": "string", "nullable": true, "description": "String decimal na própria unidade da moeda (BTC, não satoshis). Opcional.", "example": "0.0125" }, "txid": { "type": "string", "maxLength": 128, "description": "Opcional. A transação que um input gasta." }, "vout": { "type": "integer", "nullable": true, "minimum": 0, "description": "Opcional. O índice do output que é gasto por um input." } } }, "TravelRuleUtxo": { "type": "object", "description": "As entradas e saídas de uma transferência UTXO (BTC, LTC, BCH, DOGE). Só são aceites nestas blockchains: em qualquer outra blockchain devolve um erro `400`. A partir delas, a Didit deduz a carteira do ordenante (a declarada, caso contrário o endereço de entrada que mais contribuiu) e a saída do beneficiário (a declarada, caso contrário a única saída que não devolve troco a um endereço de entrada, caso contrário a única saída que paga o montante da transferência). O resultado encontra-se em `chain_details` da transferência.", "required": [ "outputs" ], "properties": { "inputs": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" }, "description": "Opcional. Sem inputs, nenhum ordenante é inferido e nenhum output de troco é reconhecido." }, "outputs": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } } } }, "TravelRuleChainSide": { "type": "object", "description": "A carteira de uma das partes, conforme a Didit a resolveu a partir dos dados da blockchain.", "properties": { "address": { "type": "string", "description": "A carteira. Numa rede memo, o endereço clássico (um endereço X do XRP é dividido no seu endereço clássico e na respetiva etiqueta); na Lightning, o ID do nó do beneficiário ou o Lightning Address." }, "memo": { "type": "string", "description": "A tag ou memo de destino que faz parte da carteira; `\"\"` quando não existe nenhum memo." }, "source": { "type": "string", "enum": [ "declared", "x_address", "largest_input", "only_non_change_output", "amount_match", "invoice_payee", "updated" ], "description": "Origem da carteira: `declared` (o seu pedido), `x_address` (dividido a partir de um X-address de XRP), `largest_input` (o endereço de entrada UTXO que mais contribuiu), `only_non_change_output` (a única saída UTXO que não é troco), `amount_match` (a única saída UTXO que paga o montante da transferência), `invoice_payee` (o beneficiário indicado por um pedido de pagamento Lightning), `updated` (definido posteriormente com `action: update_originator_wallet`)." } } }, "TravelRuleChainDetails": { "type": "object", "description": "Como a blockchain da transferência designa as suas duas carteiras, quando se trata de mais do que um endereço a pagar a outro. Vazio (`{}`) para uma transferência numa blockchain baseada em contas (EVM, Solana, Tron), onde os dois endereços são as carteiras. A correspondência, o encaminhamento e o livro de endereços leem primeiro as carteiras a partir daqui.", "properties": { "chain": { "type": "string", "description": "Blockchain canónica, por exemplo, `BTC`, `XRP` ou `LIGHTNING` para uma transferência Lightning." }, "shape": { "type": "string", "enum": [ "utxo", "memo", "lightning" ] }, "originator": { "$ref": "#/components/schemas/TravelRuleChainSide" }, "beneficiary": { "$ref": "#/components/schemas/TravelRuleChainSide" }, "utxo": { "type": "object", "description": "Numa transferência UTXO: as entradas e saídas conforme armazenadas (quantias como cadeias decimais) e quais saídas a Didit interpretou como o quê.", "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } }, "change_output_indexes": { "type": "array", "items": { "type": "integer" }, "description": "Saídas que pagam de volta a um endereço de entrada." }, "beneficiary_output_index": { "type": "integer", "nullable": true, "description": "A saída que paga ao beneficiário; null quando não foi possível distingui-la." } } }, "lightning": { "type": "object", "description": "Numa transferência Lightning: o conteúdo do pedido de pagamento. Sempre `kind` (`bolt11`, `bolt12_offer`, `bolt12_invoice`, `bolt12_invoice_request`, `lnurl`, `lightning_address`, `node_id` ou `unknown`); uma fatura BOLT11 adiciona `network`, `payee_node_id`, `payment_hash`, `amount_msat`, `created_at` e `expires_at`; uma cadeia BOLT12 adiciona `blinded_paths` e `payee_node_id`; um LNURL ou um Lightning Address adiciona o seu `domain`. Nada é resolvido através da rede: o pedido é apenas descodificado.", "additionalProperties": true }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "declared_originator_not_an_input", "declared_beneficiary_not_an_output", "beneficiary_output_ambiguous", "beneficiary_output_amount_differs" ] }, "description": "Inconsistências de UTXO que merecem atenção: o ordenante declarado não é uma entrada, o beneficiário declarado não é uma saída, nenhuma saída individual de beneficiário pôde ser identificada ou a saída do beneficiário paga um montante diferente do indicado na transação." }, "not_applicable_reason": { "type": "string", "enum": [ "LIGHTNING_NO_PAYEE_IDENTIFIER", "LIGHTNING_BOLT12_BLINDED_PAYEE", "LIGHTNING_LNURL_NAMES_NO_PAYEE" ], "description": "Numa transferência Lightning de saída cujo pedido de pagamento não indique um beneficiário: o motivo pelo qual a transferência é `NOT_APPLICABLE`. `LIGHTNING_NO_PAYEE_IDENTIFIER` (o pedido não indica o nó do beneficiário ou não pôde ser descodificado), `LIGHTNING_BOLT12_BLINDED_PAYEE` (a oferta oculta o seu beneficiário através de caminhos ocultos), `LIGHTNING_LNURL_NAMES_NO_PAYEE` (um LNURL indica um serviço, não um beneficiário). O mesmo código abre a última entrada de `timeline` da transferência." } } }, "WalletAddressImportRow": { "type": "object", "description": "Uma carteira a importar: pelo respetivo `address`, pelo respetivo `address_hash` ou por ambos. As formas camelCase destes campos também são aceites, tal como `walletAddress`, `walletAddressHash`, `destinationTag` e `externalUserId`.", "properties": { "address": { "type": "string", "maxLength": 128, "description": "O endereço de carteira. Alias: `walletAddress`." }, "address_hash": { "type": "string", "description": "SHA-256 do endereço em minúsculas, como 64 carateres hexadecimais ou 44 carateres base64. Envie-o isoladamente para registar uma carteira sem divulgar o respetivo endereço; enviado com `address`, deve ser o hash desse endereço. Alias: `walletAddressHash`." }, "chain": { "type": "string", "maxLength": 32 }, "memo": { "type": "string", "maxLength": 256, "description": "A tag ou memo de destino. XRP: uma tag de destino, um número inteiro de 0 a 4294967295 (um número JSON é aceite). XLM: um memo de texto de até 28 bytes, um ID de 64 bits ou um hash de 32 bytes em hexadecimal. EOS: até 256 bytes. ATOM: até 256 carateres. HBAR: até 100 bytes. As carteiras de Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning não aceitam memo: incluir um resulta num erro `400`." }, "holder_name": { "type": "string", "maxLength": 255 }, "holder_vendor_data": { "type": "string", "maxLength": 255, "description": "O seu identificador interno para o titular. Alias: `externalUserId`." }, "entity_type": { "type": "string", "enum": [ "individual", "company" ], "default": "individual" }, "label": { "type": "string", "maxLength": 255 }, "owner_type": { "type": "string", "enum": [ "customer", "internal", "vasp" ], "default": "customer" }, "travel_address": { "type": "string", "maxLength": 512 }, "self_declared": { "type": "boolean", "default": false, "description": "Cria a entrada já verificada através de uma autodeclaração, quando as suas definições o permitem." } } }, "WalletAddressImportReport": { "type": "object", "description": "O que aconteceu a cada linha de uma importação, na ordem enviada.", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "existing": { "type": "integer" }, "duplicate": { "type": "integer" }, "failed": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "description": "O número da linha, a partir de 1." }, "status": { "type": "string", "enum": [ "created", "existing", "duplicate", "failed" ], "description": "`created`: adicionada ao livro. `existing`: a carteira já está no livro e foi mantida inalterada. `duplicate`: repete uma linha anterior desta importação. `failed`: consulte `errors`." }, "entry_id": { "type": "string", "format": "uuid", "nullable": true, "description": "A entrada do livro de endereços que a linha criou ou encontrou." }, "errors": { "type": "object", "description": "Erros de campos de uma linha `failed`; vazio caso contrário." }, "duplicate_of_row": { "type": "integer", "nullable": true, "description": "Numa linha `duplicate`, a linha que esta repete." } } } } } }, "TravelRuleCounterpartyContact": { "type": "object", "description": "Um endereço de conformidade para o qual o canal EMAIL escreve relativamente a uma entrada do diretório.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "counterparty": { "type": "string", "format": "uuid", "description": "O `id` da entrada do diretório, conforme apresentado por GET /v3/travel-rule/vasps/." }, "counterparty_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "description": "Etiqueta opcional, por exemplo, o nome da equipa." }, "source": { "type": "string", "enum": [ "staff", "application", "learned" ], "description": "staff: com curadoria da Didit. learned: um endereço num dos próprios domínios do VASP que respondeu a um pedido através da respetiva ligação de resposta. application: adicionado pela sua aplicação." }, "scope": { "type": "string", "enum": [ "platform", "application" ], "description": "platform: com curadoria da Didit ou obtido a partir de uma resposta verificada, utilizado para todos os clientes da Didit, só de leitura para si. application: privado da sua aplicação." }, "created_by": { "type": "string", "description": "Vazio para contactos da plataforma e para contactos adicionados por uma chave de API." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando este endereço respondeu pela última vez a um pedido através da sua ligação de resposta." }, "is_invalid": { "type": "boolean", "description": "true assim que o endereço for devolvido (bounce) ou apresentar reclamação; a via EMAIL ignora-o." }, "invalid_reason": { "type": "string", "enum": [ "", "hard_bounce", "soft_bounce", "spam_complaint", "suppressed" ] }, "invalid_detail": { "type": "string", "description": "O motivo do servidor de correio destinatário, quando fornecido." }, "invalid_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleCounterpartyContactCreate": { "type": "object", "required": [ "counterparty", "email" ], "properties": { "counterparty": { "type": "string", "format": "uuid", "description": "O `id` da entrada do diretório." }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "name": { "type": "string", "description": "Etiqueta opcional.", "maxLength": 255 } } }, "TravelRuleNameMatch": { "type": "object", "nullable": true, "description": "A comparação de nomes que decidiu a transferência, ou nulo até que uma seja executada. Enquanto as partes estiverem mascaradas, e na cópia do outro cliente de uma troca INTERNAL, `transfer_name`, `compared_name`, `matched_names` e `mismatched_names` são ocultados. `score` e `matched` podem divergir: `matched` segue o rigor, `score` é a semelhança dos dois nomes completos.", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Semelhança dos dois nomes completos, de 0 a 100. 0 quando qualquer um dos nomes estiver em branco." }, "matched": { "type": "boolean", "description": "Se os nomes cumprem `strictness`. O resultado da transferência segue `data_match`, que compara todos os campos, pelo que uma transferência pode ser COUNTERPARTY_MISMATCHED_DATA enquanto isto for verdadeiro." }, "method": { "type": "string", "enum": [ "none", "exact_token", "token_subset", "token_containment", "sequence_ratio" ], "description": "Como `matched` foi decidido: nenhum (`NONE`), token exato (`STRICT`), subconjunto de tokens (`DEFAULT`), contenção de tokens (`CONTAINS`) ou proporção de sequência (`FUZZY`)." }, "strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ] }, "compared_with": { "type": "string", "enum": [ "wallet_holder", "counterparty_vasp" ], "description": "wallet_holder: o titular registado para a carteira. counterparty_vasp: o nome que a contraparte indicou na página de resposta por e-mail, ou a resposta do Didit Test VASP na sandbox." }, "transfer_name": { "type": "string", "description": "O nome na transferência." }, "compared_name": { "type": "string", "description": "O nome com o qual foi comparado." }, "matched_names": { "type": "array", "items": { "type": "string" }, "description": "Palavras de `transfer_name` encontradas em `compared_name`." }, "mismatched_names": { "type": "array", "items": { "type": "string" }, "description": "Palavras de `transfer_name` em falta em `compared_name`, seguidas de palavras de `compared_name` em falta em `transfer_name`." } } }, "TravelRuleTransferRow": { "type": "object", "description": "Uma transferência de Travel Rule tal como a lista de transferências a apresenta: apenas nomes de VASP, carteiras e memos, nunca os dados pessoais do ordenante ou do beneficiário.", "properties": { "id": { "type": "string", "format": "uuid", "description": "O ID da transferência." }, "transaction_id": { "type": "string", "format": "uuid", "description": "A transação da Didit à qual a transferência pertence." }, "txn_id": { "type": "string", "nullable": true, "description": "O seu próprio ID para a transação. As transferências que a Didit regista por si, como uma transferência de entrada de um Didit Test VASP, incluem um ID gerado." }, "txn_date": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "withdrawal", "deposit", "message" ], "description": "withdrawal: de saída. message: uma transferência de entrada criada por uma via com base numa mensagem de uma contraparte (um pedido de informação TRP, a perna de entrada INTERNAL ou uma mensagem GTR, VerifyVASP ou Sygna Bridge). deposit: qualquer outra transferência de entrada." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ] }, "reason": { "type": "string", "description": "O motivo pelo qual uma transferência `COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE` está bloqueada, o mesmo valor que o `reason` da própria transferência, para que a lista distinga um e-mail de conformidade devolvido de uma contraparte sem rota sem abrir cada transferência. `\"\"` para qualquer outro estado. Consulte [Por que motivo uma transferência está bloqueada](/pt/transaction-monitoring/travel-rule#por-que-motivo-uma-transferência-está-bloqueada)." }, "rail": { "type": "string", "nullable": true, "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP", null ] }, "asset": { "type": "string", "description": "A moeda da transação." }, "amount": { "type": "string", "description": "O montante como um decimal simples, por exemplo \"1.25\"." }, "originator_vasp": { "type": "string", "description": "Saída: a firma ou denominação social do seu VASP. Entrada: o nome da contraparte, a partir da sua entrada no diretório, do membro da rede Didit, do remetente TRP, do Didit Test VASP ou do nome declarado na transferência. Vazio quando nenhum for conhecido." }, "beneficiary_vasp": { "type": "string", "description": "Saída: o nome da contraparte, determinado da mesma forma. Entrada: a firma ou denominação social do seu VASP." }, "originator_wallet": { "type": "string" }, "beneficiary_wallet": { "type": "string" }, "originator_memo": { "type": "string", "description": "Memo ou etiqueta de destino, vazio em blockchains que não tenham uma." }, "beneficiary_memo": { "type": "string" }, "originator_wallet_type": { "type": "string", "enum": [ "vasp", "self_hosted", "own" ], "description": "vasp, self_hosted (declarada não custodiada) ou own (uma carteira registada no seu livro de endereços como sendo sua). O seu próprio lado é sempre vasp." }, "beneficiary_wallet_type": { "type": "string", "enum": [ "vasp", "self_hosted", "own" ] }, "matched_transaction_id": { "type": "string", "format": "uuid", "nullable": true, "description": "O outro lado de um depósito que associou manualmente a uma transferência anunciada." }, "deadline_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a transferência expira se ainda estiver a aguardar a sua contraparte. Definido em todas as transferências que criar com `POST /v3/transactions/` que precisem de uma troca, de saída ou de entrada. Nulo abaixo do limiar, num pagamento Lightning ao qual a Travel Rule não se aplica e em transferências de entrada que a Didit cria quando uma contraparte o contacta (um inquérito TRP de entrada, uma mensagem de rede ou a etapa de entrada INTERNAL)." }, "created_at": { "type": "string", "format": "date-time" } } }, "BankAccountCheckHolder": { "description": "O nome em relação ao qual a conta é verificada. Envie exatamente um de entre `full_name` e `business_name`.", "oneOf": [ { "$ref": "#/components/schemas/BankAccountCheckPersonHolder" }, { "$ref": "#/components/schemas/BankAccountCheckBusinessHolder" } ] }, "BankAccountCheckRequest": { "type": "object", "required": [ "country", "account", "holder" ], "properties": { "country": { "type": "string", "minLength": 3, "maxLength": 3, "description": "O país da conta, como um código ISO 3166-1 alfa-3, por exemplo `NGA`. Minúsculas são aceites.", "example": "NGA" }, "account": { "type": "object", "description": "A conta tal como o respetivo país a escreve: um `iban`, ou um `account_number` com o código de banco ou de balcão de que o país necessita (`sort_code`, `routing_number`, `transit_institution`, `bsb`, `ifsc`, `bank_code` ou `bic`). O México aceita um `clabe` e a Argentina um `cbu_cvu`, que já identificam o banco. Uma conta empresarial adiciona um `registration_id` onde o país o solicitar. Espaços, traços e pontos são ignorados. As chaves que a verificação do país não utiliza são ignoradas; uma chave de que necessite e não receba resulta num `400` que a identifica.", "properties": { "iban": { "type": "string", "maxLength": 64, "description": "O IBAN, num país que utiliza IBANs. Deve pertencer a `country`." }, "account_number": { "type": "string", "maxLength": 64, "description": "O número de conta, num país que regista a conta com um código de banco ou de balcão separado." }, "sort_code": { "type": "string", "maxLength": 64, "description": "Reino Unido: o código de compensação de 6 dígitos." }, "routing_number": { "type": "string", "maxLength": 64, "description": "Estados Unidos: o número de encaminhamento ABA de 9 dígitos." }, "transit_institution": { "type": "string", "maxLength": 64, "description": "Canadá: o número de trânsito e da instituição de 8 dígitos." }, "bsb": { "type": "string", "maxLength": 64, "description": "Austrália: o BSB de 6 dígitos." }, "ifsc": { "type": "string", "maxLength": 64, "description": "Índia: o IFSC de 11 carateres." }, "bank_code": { "type": "string", "maxLength": 64, "description": "O código do banco, onde o país o exige, por exemplo na Nigéria." }, "bic": { "type": "string", "maxLength": 64, "description": "O BIC do banco, quando a verificação do país o exige." }, "clabe": { "type": "string", "maxLength": 64, "description": "México: a CLABE de 18 dígitos. Já identifica o banco." }, "cbu_cvu": { "type": "string", "maxLength": 64, "description": "Argentina: o CBU ou CVU de 22 dígitos. Já identifica o banco." }, "registration_id": { "type": "string", "maxLength": 64, "description": "O número de registo de uma conta de empresa, nos casos em que o país o exige." } }, "additionalProperties": { "type": "string", "maxLength": 64 }, "example": { "bank_code": "000014", "account_number": "0123450001" } }, "holder": { "$ref": "#/components/schemas/BankAccountCheckHolder" }, "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação, devolvida inalterada.", "example": "payout_20481" }, "consent": { "type": "boolean", "default": false, "description": "Defina como `true` quando o titular da conta tiver dado consentimento explícito para esta verificação. Obrigatório nos países cuja verificação de conta exige esse consentimento: sem ele, a verificação é recusada com um erro `400` cujo `field` é `consent` e cujo `reason` é `required`, e nada é faturado. Noutros locais é opcional, e a Didit regista-o com a cobrança da verificação quando o enviar.", "example": true } } }, "BankAccountCheckResponse": { "type": "object", "required": [ "request_id", "result", "holder_name", "account", "vendor_data", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "O ID desta verificação." }, "result": { "type": "string", "enum": [ "match", "close_match", "no_match", "cannot_verify" ], "description": "`match`: o banco mantém a conta sob o nome que enviou. `close_match`: sob um nome aproximado, por exemplo, a omissão de um segundo nome ou um erro tipográfico. `no_match`: sob outro nome, ou não existe tal conta. `cannot_verify`: o banco respondeu sem comparar o nome, por exemplo, no caso de uma conta bloqueada ou encerrada." }, "holder_name": { "type": "string", "nullable": true, "description": "Apenas num `close_match`, e apenas quando o banco o devolveu: o nome na conta, tal como consta no banco. Caso contrário, `null`." }, "account": { "type": "string", "description": "A conta, mascarada até aos seus últimos 4 carateres." }, "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência, tal como a enviou." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a verificação foi executada, em UTC." } } }, "BankAccountCheckError": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string", "description": "O que correu mal, em inglês." }, "code": { "type": "string", "description": "Um código estável para criar ramificações. Ausente em `401` e `403`." }, "field": { "type": "string", "description": "Apenas `400`: o campo do corpo a corrigir, como um caminho com pontos, por exemplo `account.sort_code`." }, "reason": { "type": "string", "enum": [ "required", "length", "format", "checksum", "country_mismatch", "rejected" ], "description": "Apenas `400`: o motivo pelo qual o campo foi recusado. `required`, `length`, `format`, `checksum` e `country_mismatch` (um IBAN de outro país) são verificações próprias da Didit; `rejected` significa que o banco recusou a conta tal como enviada." } } }, "BankVerificationResult": { "type": "object", "description": "O resultado de um passo de Verificação Bancária, para Verificação de utilizadores e de empresas. `method` indica como a conta foi verificada, e `none` que a pessoa continuou sem banco antes de qualquer tentativa ser avaliada. `continued_without_bank` indica que a pessoa continuou sem banco, inclusive após uma tentativa avaliada. Consulte [Métodos de verificação bancária](/pt/core-technology/bank-verification/verification-methods) e [Quando a pessoa não consegue verificar o seu banco](/pt/core-technology/bank-verification/fallbacks).", "properties": { "schema_version": { "type": "integer", "description": "Versão desta estrutura de resultados. Atualmente `1`." }, "bank_verification_id": { "type": "string", "format": "uuid", "description": "O ID deste resultado." }, "node_id": { "type": "string", "description": "O nó do fluxo a que este resultado pertence." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Expired" ], "description": "O veredito do passo, após as suas ações e regras de estado." }, "original_status": { "type": "string", "nullable": true, "description": "O primeiro veredito a que o passo chegou, antes de qualquer alteração posterior, como uma revisão manual." }, "method": { "type": "string", "nullable": true, "enum": [ "open_banking", "account_lookup", "microdeposits", "statement", "none" ], "description": "Como a conta foi verificada: `open_banking` (início de sessão bancário: a pessoa iniciou sessão no respetivo banco), `account_lookup` (verificação de conta: a pessoa introduziu os dados da conta e o banco confirmou o nome), `microdeposits` ou `statement` (carregamento de extrato). `none` quando a pessoa continuou sem banco antes de qualquer tentativa ser avaliada, pelo que nenhuma conta foi verificada. Após uma tentativa avaliada, permanece o método dessa tentativa. `null` até que uma conta seja avaliada e quando o fluxo restringe os dados que devolve. As regras do fluxo leem o mesmo valor que `bank.method`." }, "provider": { "type": "string", "nullable": true, "description": "A chave da rota que executou a ligação. Consulte `method`, e não esta chave, para saber como a conta foi verificada." }, "credential_source": { "type": "string", "nullable": true, "enum": [ "native", "byok" ], "description": "`native`: rota própria da Didit, faturada ao seu saldo Didit. `byok`: um fornecedor do marketplace que associou à sua conta utilizando as suas próprias credenciais." }, "route": { "type": "object", "nullable": true, "description": "A rota escolhida antes do consentimento. Nunca muda posteriormente.", "properties": { "provider_key": { "type": "string", "nullable": true, "description": "A chave da rota." }, "credential_source": { "type": "string", "enum": [ "native", "byok" ] }, "is_fallback": { "type": "boolean", "description": "Se a rota própria da Didit substituiu um fornecedor do marketplace que não conseguiu ligar-se." }, "provider_connection_id": { "type": "string", "nullable": true, "description": "A ligação ao marketplace utilizada, para `byok`." }, "requested_scopes": { "type": "array", "items": { "type": "string" }, "description": "Os dados que a ligação solicitou, por exemplo `ownership` ou `balances`." } } }, "connection": { "type": "object", "nullable": true, "description": "A ligação da tentativa mais recente. `null` antes da primeira tentativa.", "properties": { "status": { "type": "string", "enum": [ "pending", "connected", "cancelled", "timeout", "failed", "unsupported", "revoked", "expired" ] }, "institution_id": { "type": "string", "nullable": true, "description": "O ID do banco. `null` para uma verificação de conta em que não seja escolhido nenhum banco." }, "institution_name": { "type": "string", "nullable": true, "description": "O nome do banco. `null` para uma verificação de conta." }, "institution_country": { "type": "string", "nullable": true, "description": "O país da conta, ISO 3166-1 alfa-3." }, "oauth": { "type": "boolean", "nullable": true, "description": "Indica se o início de sessão bancário foi realizado por OAuth ou app-to-app. `null` para uma verificação de conta." }, "connected_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a ligação foi bem-sucedida." }, "consent_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o consentimento bancário termina, para o início de sessão bancário." }, "last_refreshed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando os dados financeiros foram lidos novamente pela última vez." }, "attempts": { "type": "integer", "description": "As tentativas que a pessoa despendeu neste passo, com todos os métodos combinados." }, "reason_code": { "type": "string", "nullable": true, "description": "O motivo pelo qual a ligação não está simplesmente `connected`, por exemplo `USER_CANCELLED`, `INSTITUTION_DOWN`, `ACCOUNT_NOT_FOUND`, `REFERENCE_IDENTITY_MISSING` ou `VERIFICATION_COMPLETED`." } } }, "account": { "type": "object", "nullable": true, "description": "A conta avaliada. `null` até que uma conta seja avaliada.", "properties": { "account_id_masked": { "type": "string", "nullable": true, "description": "O número de conta, mascarado." }, "iban_masked": { "type": "string", "nullable": true, "description": "O IBAN, mascarado." }, "sort_code": { "type": "string", "nullable": true, "description": "O sort code, no Reino Unido." }, "routing_number_masked": { "type": "string", "nullable": true, "description": "O routing number, mascarado." }, "type": { "type": "string", "nullable": true, "enum": [ "checking", "current", "savings", "business", "other" ] }, "subtype": { "type": "string", "nullable": true, "description": "O subtipo de conta do próprio banco." }, "currency": { "type": "string", "nullable": true, "description": "Moeda ISO 4217 da conta." }, "holder_type": { "type": "string", "nullable": true, "enum": [ "person", "business", "unknown" ] }, "holders_count": { "type": "integer", "nullable": true }, "is_joint": { "type": "boolean", "nullable": true }, "is_business": { "type": "boolean", "nullable": true } } }, "ownership": { "type": "object", "nullable": true, "description": "Como o titular da conta foi comparado com a identidade verificada. `null` até que uma conta seja avaliada.", "properties": { "result": { "type": "string", "enum": [ "match", "partial_match", "no_match", "unknown", "not_verifiable" ], "description": "`partial_match` é uma correspondência próxima. `not_verifiable`: o banco respondeu sem titular para comparar. `unknown`: o comprovativo não pôde ser lido ou não havia identidade para comparar." }, "reference_identity_source": { "type": "string", "nullable": true, "description": "O passo cuja identidade foi comparada com a do titular: `kyc`, `database_validation`, `expected_details`, `questionnaire`, `document_ai` ou `kyb`." }, "name_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Pontuação do nome do titular da Didit." }, "provider_name_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "A pontuação do nome do titular dada pelo próprio banco, quando fornecida." }, "address_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "A pontuação da morada do titular, quando a correspondência de morada foi executada." }, "email_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "A pontuação do e-mail do titular, quando a correspondência de e-mail foi executada." }, "phone_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "A pontuação do telefone do titular, quando a correspondência de telefone foi executada." }, "dob_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "A pontuação da data de nascimento do titular, quando o banco partilhou essa informação." }, "close_match": { "type": "boolean", "nullable": true, "description": "Se o nome ficou no intervalo de correspondência aproximada." }, "holder_confirmation": { "type": "string", "nullable": true, "enum": [ "pending", "confirmed", "rejected" ], "description": "A resposta da pessoa quando solicitada a confirmar um nome de correspondência aproximada. `null` se nunca tiver sido solicitada." }, "method": { "type": "string", "nullable": true, "enum": [ "exact", "token_set", "nickname", "transliteration", "fuzzy", "provider_only", "microdeposits" ], "description": "Qual a comparação de nomes que gerou a pontuação. Este não é o método de verificação: consulte o `method` de nível superior para isso." }, "matched_holder_index": { "type": "integer", "nullable": true }, "holders": { "type": "array", "items": { "type": "object" }, "description": "Cada titular listado pelo banco, com as respetivas pontuações." }, "owner_identity_available": { "type": "boolean", "nullable": true }, "evidence_freshness": { "type": "string", "nullable": true, "enum": [ "live", "cached", "refreshed" ] }, "evaluated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o veredito foi calculado." } } }, "financial_data": { "type": "object", "description": "Os dados financeiros que o passo leu. Apenas o início de sessão bancário os lê.", "properties": { "balances": { "type": "object", "nullable": true, "description": "Com o âmbito `balances`." }, "transactions": { "type": "object", "nullable": true, "description": "Com o âmbito `transactions`." }, "income": { "type": "object", "nullable": true, "description": "Com o âmbito `income`." }, "categorization": { "type": "object", "nullable": true, "description": "Categorização da Didit das transações consultadas. `null` na ausência das mesmas." }, "not_collected": { "type": "array", "items": { "type": "string", "enum": [ "balances", "income", "transactions" ] }, "description": "Os dados solicitados pelo passo que o método utilizado para verificar a conta não recolhe. Saldos, transações e rendimentos são obtidos exclusivamente através do início de sessão bancário, pelo que uma conta verificada por verificação de conta lista-os aqui. Nunca constitui uma falha. Vazio caso contrário." } } }, "billing": { "type": "object", "nullable": true, "properties": { "route": { "type": "string", "enum": [ "native", "byok" ] }, "billed": { "type": "boolean" }, "marketplace_fee": { "type": "string", "nullable": true, "description": "A taxa da plataforma de marketplace cobrada, para `byok`." }, "usage_type": { "type": "string", "nullable": true, "description": "A linha de utilização na qual a cobrança foi registada: `bank_verification` para um início de sessão bancário ou uma verificação de conta, `bank_statement_upload` para o carregamento de um extrato sem tentativa bancária cobrada anterior e `bank_byok_fee` para a comissão de marketplace no seu próprio fornecedor. `null` se nada foi faturado." } } }, "reference_identity": { "type": "object", "nullable": true, "description": "A identidade com a qual o titular foi comparado, com a respetiva origem." }, "signals": { "type": "object", "nullable": true, "description": "Sinais de conta lidos a partir do histórico de transações, quando o passo leu um desses sinais." }, "connection_abandoned": { "type": "boolean", "nullable": true, "description": "Se o passo terminou sem correspondência após a pessoa ter saído no seu banco." }, "not_covered": { "type": "boolean", "nullable": true, "description": "Se não foi possível aceder ao banco ou ao país da pessoa neste passo. Também é `true` quando a pessoa continuou sem um banco porque nenhum método conseguiu verificar o seu país ou banco." }, "continued_without_bank": { "type": "boolean", "description": "Se a pessoa saiu do passo com **Continue without your bank**. O campo `continuation` indica o motivo. `method` é `none` quando nenhuma tentativa foi avaliada antes de continuar. Após uma tentativa avaliada, como um titular que não corresponde, `method` mantém o método dessa tentativa e o respetivo veredicto e códigos de motivo mantêm-se. Devolvido mesmo quando o fluxo restringe os dados que devolve." }, "continuation": { "type": "object", "nullable": true, "description": "Como a pessoa continuou sem um banco. `null` se não o tiver feito. Quando o fluxo restringe os dados que devolve, `reason` continua a ser devolvido e todas as outras chaves ficam com `null`.", "properties": { "reason": { "type": "string", "enum": [ "no_route", "institution_unsupported", "attempts_exhausted", "person_choice" ], "description": "O motivo, conforme apurado pela Didit quando a pessoa continuou: `no_route` (nenhum início de sessão bancário ou verificação de conta serve o respetivo país), `institution_unsupported` (o banco selecionado não pode ser utilizado neste passo), `attempts_exhausted` (todas as tentativas já foram gastas e nenhuma estava em curso) ou `person_choice` (existia uma forma de verificação disponível e optou por continuar, inclusive quando o banco não pôde ser contactado no momento). `no_route` e `institution_unsupported` seguem `bank_unsupported_action`, `attempts_exhausted` segue `bank_attempts_exhausted_action` e `person_choice` segue `bank_skipped_action`, salvo se uma tentativa avaliada já tiver decidido o passo." }, "country": { "type": "string", "nullable": true, "description": "O país onde a pessoa estava a efetuar a verificação, ISO 3166-1 alfa-3. `null` se tiver prosseguido antes de selecionar um." }, "offered": { "type": "array", "items": { "type": "string", "enum": [ "statement", "microdeposits" ] }, "nullable": true, "description": "As outras formas de verificar esse país disponibilizadas à pessoa quando esta continuou, pela ordem em que foram disponibilizadas: `statement` (carregamento de um extrato) e, em seguida, `microdeposits`. Vazio se não tiver sido disponibilizada nenhuma." }, "institution_id": { "type": "string", "nullable": true, "description": "Para `institution_unsupported`, o ID do banco que a pessoa não conseguiu utilizar: o banco que selecionou ou o banco em que a sua última tentativa terminou. A Didit obtém-no a partir da sua própria lista de bancos, nunca do dispositivo da pessoa, pelo que um banco que não conste dessa lista é `null`. `null` para qualquer outro motivo." }, "institution_name": { "type": "string", "nullable": true, "description": "Para `institution_unsupported`, o nome desse banco, proveniente da mesma lista que `institution_id`. `null` quando essa lista não tiver o banco e para qualquer outro motivo." }, "continued_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando a pessoa continuou." } } }, "evidence_purged_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando as provas bancárias foram eliminadas ao abrigo de `bank_evidence_retention_days`. Caso contrário, `null`." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Códigos informativos, por exemplo `holder_declared`. Um aviso nunca altera o estado por si só." }, "reason_codes": { "type": "array", "items": { "type": "string" }, "description": "O motivo pelo qual o veredito ocorreu dessa forma, por exemplo `OWNER_NAME_PARTIAL`. Podem aplicar-se vários. `NOT_COVERED`: a pessoa continuou sem um banco porque nenhum método conseguiu verificar o seu país ou banco. `SKIPPED`: a pessoa optou por continuar sem um banco existindo uma forma de verificação disponível. Nenhum deles é adicionado quando uma tentativa avaliada já decidiu o passo." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BankAccountCheckPersonHolder": { "type": "object", "description": "A pessoa que deve ser a titular da conta.", "required": [ "full_name" ], "properties": { "full_name": { "type": "string", "maxLength": 255, "description": "O nome completo da pessoa que deve ser titular da conta.", "example": "Maria Oliveira" } } }, "BankAccountCheckBusinessHolder": { "type": "object", "description": "A empresa que deve ser titular da conta. Verifica uma conta empresarial.", "required": [ "business_name" ], "properties": { "business_name": { "type": "string", "maxLength": 255, "description": "O nome da empresa que deve ser titular da conta. Verifica uma conta empresarial." } } }, "BankVerificationPricing": { "type": "object", "description": "Preços de tabela públicos do Bank Verification: o carregamento do extrato, a taxa da chave própria do fornecedor e os métodos de cada país.", "required": [ "currency", "statement_upload", "own_provider_fee_usd", "countries" ], "properties": { "currency": { "type": "string", "enum": [ "USD" ], "description": "Moeda de cada preço na resposta.", "example": "USD" }, "statement_upload": { "$ref": "#/components/schemas/BankStatementUploadPricing" }, "own_provider_fee_usd": { "type": "string", "description": "Taxa para cada verificação de propriedade faturável numa rota que utiliza o seu próprio contrato de fornecedor em vez do da Didit, cobrada independentemente do resultado. Uma ligação cancelada, expirada por tempo limite ou abandonada não é faturada. String decimal com 4 casas decimais, em USD.", "example": "0.0200" }, "countries": { "type": "object", "description": "Todos os países, indexados pelo código ISO 3166-1 alfa-3.", "additionalProperties": { "$ref": "#/components/schemas/BankVerificationPricingCountry" } } } }, "BankStatementUploadPricing": { "type": "object", "description": "Como o carregamento do extrato bancário é faturado.", "required": [ "price_usd", "included_after_charged_bank_attempt", "standalone_available" ], "properties": { "price_usd": { "type": "string", "description": "Preço do carregamento de um extrato após uma tentativa bancária cobrada. String decimal com 4 casas decimais, em USD.", "example": "0.0000" }, "included_after_charged_bank_attempt": { "type": "boolean", "description": "`true` quando o envio de ficheiro está incluído sem custos adicionais após uma tentativa bancária cobrada na mesma sessão.", "example": true }, "standalone_available": { "type": "boolean", "description": "`true` quando o carregamento de um extrato pode ser executado de forma autónoma, sem tentativa bancária prévia. `false` em produção; as sessões de sandbox podem testá-lo sem faturação.", "example": false } } }, "BankVerificationPricingCountry": { "type": "object", "description": "Os métodos de Verificação Bancária de um país e os respetivos preços de tabela.", "required": [ "name", "methods" ], "properties": { "name": { "type": "string", "description": "Nome do país em inglês.", "example": "United Kingdom" }, "methods": { "$ref": "#/components/schemas/BankVerificationPricingMethods" } } }, "BankVerificationPricingMethods": { "type": "object", "description": "Os dois métodos de Verificação bancária num país.", "required": [ "open_banking", "account_lookup" ], "properties": { "open_banking": { "$ref": "#/components/schemas/BankSignInPricing" }, "account_lookup": { "$ref": "#/components/schemas/BankAccountCheckPricing" } } }, "BankSignInPricing": { "type": "object", "description": "Início de sessão bancário: a pessoa inicia sessão no seu banco. O preço varia consoante o mercado e é o mesmo para todos os bancos nele incluídos.", "required": [ "available", "market", "price_usd", "add_ons" ], "properties": { "available": { "type": "boolean", "description": "`true` apenas onde a Didit disponibiliza o início de sessão bancário neste país em produção.", "example": true }, "market": { "type": "string", "nullable": true, "description": "O mercado cujo preço se aplica. `null` quando não estiver disponível.", "example": "UK and EEA" }, "price_usd": { "type": "string", "nullable": true, "description": "Preço de tabela de um início de sessão bancário. `null` quando não estiver disponível. String decimal com 4 casas decimais, em USD.", "example": "0.7900" }, "add_ons": { "type": "object", "description": "Módulos adicionais com preço definido neste país, cada um como string decimal com 4 casas decimais em USD, adicionados ao preço do início de sessão bancário. Apenas são listados os módulos adicionais oferecidos pelo país; vazio quando o início de sessão bancário não está disponível.", "properties": { "balance": { "type": "string", "description": "Suplemento de saldo da conta.", "example": "0.3500" }, "transactions": { "type": "string", "description": "Add-on de transações.", "example": "1.3000" } } } } }, "BankAccountCheckPricing": { "type": "object", "description": "Verificação de conta: a pessoa introduz o seu número de conta e a Didit verifica-o junto do banco. Preço definido por país.", "required": [ "available", "price_usd" ], "properties": { "available": { "type": "boolean", "description": "`true` apenas onde a Didit disponibiliza a verificação de conta neste país em produção.", "example": true }, "price_usd": { "type": "string", "nullable": true, "description": "Preço de tabela de uma verificação de conta à qual o banco responde. `null` quando não estiver disponível. String decimal com 4 casas decimais, em USD.", "example": "0.4000" } } }, "ImportProvider": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ] }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "api_list", "api_ids", "export_file" ], "description": "`api_list`: a Didit lista os registos com a chave. `api_ids`: carregue os IDs de registo a partir de uma exportação. `export_file`: carregue uma exportação no formato da Didit." }, "record_noun": { "type": "string" }, "credential_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "secret": { "type": "boolean" } } } }, "regions": { "type": "array", "items": { "type": "string" } }, "required_permissions": { "type": "array", "items": { "type": "string" } }, "docs_url": { "type": "string", "nullable": true }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] } } } }, "ImportJobSummary": { "type": "object", "description": "Uma tarefa de importação de qualquer tipo, no formato que o painel lateral de tarefas de importação da consola lê.", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "sessions", "businesses", "users", "status_rules", "transactions" ] }, "source": { "type": "string", "enum": [ "file", "api", "provider" ] }, "provider": { "type": "string", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "filename": { "type": "string", "nullable": true }, "state": { "type": "string", "enum": [ "ready", "queued", "running", "paused", "completed", "errors", "failed", "cancelled" ], "description": "O estado da tarefa tal como apresentado na consola; `errors` corresponde a uma tarefa concluída com linhas rejeitadas." }, "status": { "type": "string" }, "is_dry_run": { "type": "boolean" }, "credential_hint": { "type": "string", "nullable": true }, "resumes_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "nullable": true }, "started_by": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "progress": { "type": "object", "properties": { "total": { "type": "integer", "format": "int64" }, "processed": { "type": "integer", "format": "int64" }, "imported": { "type": "integer", "format": "int64" }, "updated": { "type": "integer", "format": "int64" }, "already_in_didit": { "type": "integer", "format": "int64" }, "failed": { "type": "integer", "format": "int64" }, "not_finished": { "type": "integer", "format": "int64" }, "same_person": { "type": "integer", "format": "int64" } } }, "face_templates": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "built": { "type": "integer", "format": "int64" }, "duplicates": { "type": "integer", "format": "int64" }, "blocklisted": { "type": "integer", "format": "int64" } } }, "eta_seconds": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "FiledRegulatoryReport": { "type": "object", "description": "Um relatório regulamentar finalizado que impede a eliminação pedida.", "required": [ "uuid", "report_number", "report_type", "case_uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID do relatório." }, "report_number": { "type": "string", "description": "Número do relatório apresentado na Consola (por exemplo, SAR-0001)." }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "Tipo de relatório regulamentar." }, "case_uuid": { "type": "string", "format": "uuid", "description": "Caso ao qual o relatório pertence." } } }, "FiledReportTransaction": { "type": "object", "description": "Uma transação que não pode ser eliminada porque um relatório regulamentar finalizado a inclui.", "required": [ "uuid", "transaction_id", "reports" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID da transação Didit." }, "transaction_id": { "type": "string", "description": "O identificador de transação fornecido aquando da criação da transação." }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/FiledRegulatoryReport" }, "description": "Relatórios finalizados que listam esta transação." } } }, "InFiledReportError": { "type": "object", "description": "A eliminação foi recusada porque os dados selecionados constam de um relatório regulamentar finalizado. Nada é eliminado. Elimine o relatório e, em seguida, repita o pedido.", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "in_filed_report" ], "description": "Código de erro estável para uma eliminação bloqueada por um relatório regulamentar finalizado." }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/FiledRegulatoryReport" }, "description": "Relatórios que bloqueiam a eliminação de uma pessoa, empresa, caso ou sessão." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/FiledReportTransaction" }, "description": "Transações que bloqueiam a eliminação de uma transação, cada uma com os relatórios que a listam." } } }, "SubjectDeletionInProgressError": { "type": "object", "description": "Outro pedido ainda está a eliminar esta pessoa ou empresa. Este pedido não eliminou nada e pode ser repetido assim que essa eliminação terminar; uma repetição eliminará o que ainda estiver selecionado.", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "subject_deletion_in_progress" ], "description": "Código de erro estável para uma pessoa ou empresa que outro pedido ainda está a eliminar." } } }, "TravelRuleNetworkParticipantSummary": { "type": "object", "nullable": true, "description": "O participante próprio desta aplicação na rede, ou null quando não tiver nenhum.", "properties": { "mode": { "type": "string", "enum": [ "platform", "own" ], "description": "platform: transportado pela adesão da Didit; own: integrado sob a adesão própria da aplicação." }, "status": { "type": "string", "enum": [ "not_requested", "questionnaire_pending", "submitted_to_network", "active", "suspended", "rejected" ], "description": "not_requested: nunca foi pedido, ou a rede recusou o primeiro pedido (consulte last_error); questionnaire_pending: a aguardar que o questionário de diligência devida seja aprovado; submitted_to_network: entregue ao onboarding da rede; active: a rede atribuiu a esta aplicação o seu próprio código de participante; suspended / rejected: a Didit suspendeu-a ou rejeitou-a." }, "participant_code": { "type": "string", "description": "O código que a rede atribuiu a esta aplicação (para a GTR, o seu código de VASP). As mensagens enviadas contêm este código, nunca o da Didit." }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "activated_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "description": "A resposta da rede quando recusou o registo; vazia nos restantes casos." } } }, "TravelRuleNetworkState": { "type": "object", "description": "Como as mensagens da Travel Rule numa rede seriam enviadas para esta aplicação, e porque não podem sê-lo. Estado de configuração, não uma verificação de estado ou de entrega em direto.", "properties": { "rail": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "mode": { "type": "string", "enum": [ "own", "didit", "off", "unavailable" ], "description": "own: é utilizada a adesão associada da aplicação; didit: a adesão da Didit regista a aplicação como o seu próprio participante ativo; off: encaminhamento da plataforma desativado em disabled_networks sem adesão própria; unavailable: ainda nada pode enviar nesta rede (consulte state e reason)." }, "state": { "type": "string", "enum": [ "own_membership", "live_through_didit", "off", "didit_onboarding", "questionnaire_needed", "questionnaire_in_review", "request_access", "request_sent", "unavailable", "error" ], "description": "own_membership: a sua adesão associada envia; live_through_didit: o seu próprio participante na adesão da Didit envia; off: desativou o encaminhamento da plataforma; didit_onboarding: a adesão própria da Didit a esta rede ainda não está ativa, pelo que não pode transportar ninguém; questionnaire_needed / questionnaire_in_review: o questionário de diligência devida tem de ser submetido ou está com a Didit; request_access: o questionário está aprovado, solicite acesso à rede; request_sent: o seu participante está a passar pelo processo de onboarding; unavailable: consulte reason; error: consulte reason." }, "reason": { "type": "string", "enum": [ "own_membership_connected", "platform_network_switched_off", "own_membership_only", "sandbox_application", "didit_membership_not_live", "participant_suspended", "participant_rejected", "questionnaire_not_submitted", "questionnaire_submitted", "questionnaire_changes_requested", "questionnaire_rejected", "participant_not_requested", "participant_active", "participant_key_missing", "participant_key_unresolved", "provisioning_failed", "questionnaire_pending", "submitted_to_network" ], "description": "Detalhe do estado legível por máquina. own_membership_only: a Didit não suporta aplicações nesta rede (TRUST), associe a sua própria adesão; sandbox_application: as transferências em sandbox nunca chegam a uma rede; provisioning_failed: a rede recusou o registo, o last_error do participante indica o motivo e voltar a pedir à rede tenta novamente." }, "platform_available": { "type": "boolean", "description": "Se a adesão da própria Didit a esta rede está configurada; não é uma verificação de estado em tempo real." }, "connected": { "type": "boolean", "description": "Se existe uma adesão de cliente ligada. As credenciais são validadas localmente; a validação de rede ocorre numa troca em direto." }, "participant": { "$ref": "#/components/schemas/TravelRuleNetworkParticipantSummary" }, "vasps_reachable": { "type": "integer", "description": "VASPs do diretório acessíveis nesta rede." }, "routed_30d": { "type": "integer", "description": "As transferências desta aplicação efetuadas nesta rede nos últimos 30 dias." } } }, "TravelRuleNetworkQuestionnaireAnswers": { "type": "object", "description": "Questionário de diligência devida de rede da Didit. As operações de guardar são parciais: uma operação de guardar mantém todas as respostas que não especifica. A submissão exige todos os campos, exceto lei e data_protection_contact_email, e que as três atestações sejam true.", "properties": { "legal_name": { "type": "string", "maxLength": 255 }, "registration_number": { "type": "string", "maxLength": 255 }, "incorporation_country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Código de país ISO 3166-1 alpha-2." }, "registered_address": { "type": "string", "maxLength": 1000 }, "website": { "type": "string", "format": "uri", "maxLength": 500 }, "lei": { "type": "string", "maxLength": 20, "description": "Opcional. Um LEI ISO 17442 válido, quando fornecido." }, "licences": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "regulator", "jurisdiction", "licence_type", "licence_number" ], "properties": { "regulator": { "type": "string", "maxLength": 255 }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Código de país ISO 3166-1 alpha-2." }, "licence_type": { "type": "string", "maxLength": 255 }, "licence_number": { "type": "string", "maxLength": 255 } } }, "description": "Todas as licenças ou registos que o VASP detém." }, "operating_jurisdictions": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Código de país ISO 3166-1 alpha-2." } }, "compliance_officer_name": { "type": "string", "maxLength": 255 }, "compliance_officer_email": { "type": "string", "format": "email" }, "aml_ctf_policy_attested": { "type": "boolean", "description": "Tem de ser verdadeiro para enviar." }, "sanctions_screening_attested": { "type": "boolean", "description": "Tem de ser verdadeiro para enviar." }, "data_protection_attested": { "type": "boolean", "description": "Tem de ser verdadeiro para enviar." }, "data_protection_contact_email": { "type": "string", "format": "email", "description": "Opcional." }, "expected_monthly_transfers": { "type": "integer", "minimum": 0 }, "expected_monthly_volume_usd": { "type": "string", "format": "decimal", "description": "Volume mensal esperado em USD, até 2 casas decimais. Devolvido como uma cadeia de caracteres." }, "assets": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "maxLength": 32 }, "description": "Tickers de ativos, guardados em maiúsculas, ordenados e sem duplicados." } } }, "TravelRuleNetworkQuestionnaire": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "submitted", "changes_requested", "approved", "rejected" ], "description": "As respostas podem ser guardadas enquanto estiverem em rascunho (draft) ou alterações solicitadas (changes_requested); a alteração dos estados submetido (submitted), aprovado (approved) e rejeitado (rejected) cabe à Didit." }, "answers": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaireAnswers" }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_note": { "type": "string", "description": "Nota da Didit sobre a sua última decisão, por exemplo o que alterar." }, "history": { "type": "array", "readOnly": true, "description": "Cada alteração de estado, da mais antiga para a mais recente.", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "string" }, "note": { "type": "string", "description": "Nota de revisão ou resposta da rede, quando existir." } } } }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "TravelRuleNetworkParticipant": { "type": "object", "description": "O participante próprio desta aplicação numa rede.", "properties": { "network": { "type": "string", "enum": [ "gtr", "trust", "verifyvasp", "sygna" ] }, "rail": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "mode": { "type": "string", "enum": [ "platform", "own" ] }, "status": { "type": "string", "enum": [ "not_requested", "questionnaire_pending", "submitted_to_network", "active", "suspended", "rejected" ], "description": "not_requested: nunca foi pedido, ou a rede recusou o primeiro pedido (consulte last_error); questionnaire_pending: a aguardar que o questionário de diligência devida seja aprovado; submitted_to_network: entregue ao onboarding da rede; active: a rede atribuiu a esta aplicação o seu próprio código de participante; suspended / rejected: a Didit suspendeu-a ou rejeitou-a." }, "participant_code": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "activated_at": { "type": "string", "format": "date-time", "nullable": true }, "suspended_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "description": "A resposta da rede quando recusou o registo; vazia nos restantes casos." }, "history": { "type": "array", "readOnly": true, "description": "Cada alteração de estado, da mais antiga para a mais recente.", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "string" }, "note": { "type": "string", "description": "Nota de revisão ou resposta da rede, quando existir." } } } } } }, "TravelRuleNetworksOverview": { "type": "object", "properties": { "platform_networks_enabled": { "type": "boolean", "description": "Se o acesso à rede através da adesão da Didit está aberto. Enquanto for false, as operações de gravação de questionários, submissões e pedidos de rede respondem com 403." }, "questionnaire": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleNetworkParticipant" } }, "networks": { "type": "object", "readOnly": true, "description": "Por rede, como esta aplicação enviaria e por que motivo não o consegue fazer. Nenhuma rede, incluindo a GTR, está incluída por predefinição: uma rede fica acessível através da sua própria adesão ligada, ou através da adesão da Didit assim que a adesão da Didit a essa rede estiver ativa e o seu próprio participante nela estiver ativo. Não se trata de uma verificação de estado ou de entrega em tempo real.", "properties": { "gtr": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "trust": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "verifyvasp": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "sygna": { "$ref": "#/components/schemas/TravelRuleNetworkState" } } } } }, "AddressValidationResult": { "type": "object", "description": "O resultado de uma Address Validation: se a morada existe e a sua forma normalizada. Confirma apenas a morada; nunca associa a morada a uma pessoa.", "required": [ "status", "verification_level", "address", "formatted_address", "latitude", "longitude" ], "properties": { "status": { "type": "string", "enum": [ "verified", "partially_verified", "not_verified", "unavailable" ], "description": "`verified`: a morada foi confirmada até ao edifício (ou fração/apartamento ou apartado). `partially_verified`: foi confirmada apenas até à rua, ou até ao nível mais preciso que os dados de referência postal contêm para essa localização. `not_verified`: apenas a região ou a cidade corresponderam, ou nada correspondeu. `unavailable`: não foi possível executar a validação (por exemplo, o serviço de referência não respondeu); não é cobrada e nunca afeta uma verificação." }, "verification_level": { "type": "string", "nullable": true, "enum": [ "administrative_area", "locality", "thoroughfare", "premise", "delivery_point", null ], "description": "O nível mais preciso com o qual a morada foi correspondida. `null` quando nada correspondeu ou `status` for `unavailable`." }, "address": { "type": "object", "nullable": true, "description": "A morada normalizada. `null` quando `status` é `unavailable`.", "properties": { "address_line_1": { "type": "string", "nullable": true, "description": "Primeira linha de entrega, escrita da forma como o país a escreve.", "example": "1600 Amphitheatre Pkwy" }, "address_line_2": { "type": "string", "nullable": true, "description": "Segunda linha de entrega (um apartamento, edifício ou bairro), quando a morada possuir uma." }, "city": { "type": "string", "nullable": true, "example": "Mountain View" }, "region": { "type": "string", "nullable": true, "description": "Estado, província ou região.", "example": "CA" }, "postal_code": { "type": "string", "nullable": true, "example": "94043-1351" }, "country": { "type": "string", "nullable": true, "description": "Código de país ISO 3166-1 alpha-2.", "example": "US" } } }, "formatted_address": { "type": "string", "nullable": true, "description": "A morada normalizada numa única linha.", "example": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351" }, "latitude": { "type": "number", "nullable": true, "example": 37.422022 }, "longitude": { "type": "number", "nullable": true, "example": -122.08429 } } }, "AddressValidationRequest": { "type": "object", "required": [ "country" ], "description": "Uma morada: numa única linha (`address`) ou como campos estruturados com pelo menos `address_line_1`, nunca ambos.", "properties": { "address": { "type": "string", "maxLength": 500, "description": "A morada completa numa linha.", "example": "Paseo de la Castellana 259, 28046 Madrid" }, "address_line_1": { "type": "string", "maxLength": 255, "description": "Rua e número.", "example": "1600 Amphitheatre Pkwy" }, "address_line_2": { "type": "string", "maxLength": 255, "description": "Apartamento, suite, piso ou edifício." }, "city": { "type": "string", "maxLength": 128, "description": "Cidade ou localidade.", "example": "Mountain View" }, "region": { "type": "string", "maxLength": 128, "description": "Estado, província ou região.", "example": "CA" }, "postal_code": { "type": "string", "maxLength": 32, "example": "94043" }, "country": { "type": "string", "maxLength": 3, "description": "Código ISO 3166-1 alfa-2 ou alfa-3 do país da morada.", "example": "US" } } }, "AddressValidationResponse": { "type": "object", "required": [ "request_id", "address_validation", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Identificador deste pedido; refira-o ao suporte. Nenhuma sessão é criada." }, "address_validation": { "$ref": "#/components/schemas/AddressValidationResult" }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWalletProofFailureReason": { "type": "string", "enum": [ "", "SIGNATURE_INVALID", "SIGNATURE_UNSUPPORTED_SCHEME", "DEPOSIT_NOT_FOUND", "DEPOSIT_UNCONFIRMED", "DEPOSIT_LOOKUP_FAILED", "DEPOSIT_MISMATCH", "DEPOSIT_STALE", "TXID_REUSED", "CHAIN_UNSUPPORTED", "WINDOW_EXPIRED", "OWNERSHIP_CHANGED", "METHOD_SWITCHED", "REVIEW_REJECTED", "ABANDONED" ], "description": "O motivo pelo qual uma prova de propriedade da carteira, ou a sua última tentativa, não alcançou o estado VERIFIED. Vazio quando nada falhou. Uma prova PENDING pode conter um motivo: a última tentativa falhou e o utilizador final pode tentar novamente. DEPOSIT_MISMATCH, DEPOSIT_STALE, TXID_REUSED e REVIEW_REJECTED encerram a prova como REJECTED. SIGNATURE_INVALID: a assinatura não corresponde à carteira e ao desafio. SIGNATURE_UNSUPPORTED_SCHEME: a carteira assinou num formato que a Didit não verifica. DEPOSIT_NOT_FOUND, DEPOSIT_UNCONFIRMED, DEPOSIT_LOOKUP_FAILED: o depósito de teste não está legível ou ainda não foi confirmado; a Didit continua a verificá-lo até que a janela de teste termine. DEPOSIT_MISMATCH: a transação não envia o montante esperado da carteira para o endereço de depósito. DEPOSIT_STALE: a transação é anterior ao desafio. TXID_REUSED: a transação já comprovou outra carteira. CHAIN_UNSUPPORTED: o método não está disponível nesta blockchain. WINDOW_EXPIRED: a janela de teste terminou. OWNERSHIP_CHANGED: o titular da carteira mudou, ou a carteira foi eliminada do seu livro de endereços, após a criação da sessão do widget. METHOD_SWITCHED: o utilizador final escolheu outro método antes de concluir este. REVIEW_REJECTED: o seu revisor rejeitou a captura de ecrã. ABANDONED: a sessão do widget expirou antes de o utilizador final concluir." }, "TravelRuleWidgetProofError": { "type": "object", "properties": { "detail": { "type": "string", "description": "Mensagem legível em inglês." }, "code": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "Motivo legível por máquina, para que um cliente possa apresentar a sua própria mensagem traduzida." }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "description": "Presente quando o comprovativo está fechado: REJECTED pelo depósito acabado de submeter (400), ou REJECTED ou EXPIRED quando são enviadas provas para um comprovativo que já está fechado (409)." }, "proof_id": { "type": "string", "format": "uuid", "description": "Presente com o estado: o comprovativo fechado." }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ], "description": "Presente com o estado: o método do comprovativo fechado." }, "max_attempts": { "type": "integer", "description": "Presente com o estado: comprovativos de carteira rejeitados que esta sessão permite." }, "attempts_used": { "type": "integer", "description": "Presente com o estado: comprovativos rejeitados até ao momento." }, "attempts_remaining": { "type": "integer", "description": "Presente com o estado: quando for 0, iniciar outro comprovativo devolve 409 e gera uma nova sessão de widget." } } }, "TravelRuleWidgetProofCreate": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ], "description": "O método de comprovativo escolhido pelo utilizador final. Deve ser um dos allowed_methods do contexto." }, "wallet_address": { "type": "string", "maxLength": 128, "description": "Assume por predefinição o wallet_address da sessão. Tem de corresponder à carteira da transferência quando a sessão estiver associada a uma transferência." }, "chain": { "type": "string", "maxLength": 32, "description": "Assume por predefinição a blockchain da sessão." } } }, "TravelRuleWidgetProofVerifyResult": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ] }, "is_ownership_verified": { "type": "boolean", "description": "Presente quando o comprovativo está VERIFIED: a entrada do livro de endereços foi agora verificada quanto à propriedade." }, "transfer_status": { "type": "string", "nullable": true, "description": "Presente quando o comprovativo está VERIFIED: o estado da transferência associada, ou null quando não existir nenhuma." }, "detail": { "type": "string", "description": "Presente enquanto o comprovativo permanece PENDING: uma captura de ecrã submetida que aguarda revisão, ou um depósito de teste que ainda não está confirmado." }, "code": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "Presente num depósito de teste pendente: o motivo pelo qual ainda não foi confirmado." } } }, "TravelRuleWalletProofReview": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "SCREENSHOT" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ] }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "Identificador canónico da blockchain, por exemplo, ETH, BTC, SOL, TRX." }, "holder_name": { "type": "string" }, "is_ownership_verified": { "type": "boolean", "description": "Indica se a propriedade da entrada do livro de endereços está verificada, por este ou por outro comprovativo." }, "transaction_id": { "type": "string", "format": "uuid", "nullable": true, "description": "A transação para cuja transferência de Travel Rule a sessão do widget foi gerada. Nulo para uma sessão gerada sem um transaction_id." }, "file_name": { "type": "string", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "screenshot_url": { "type": "string", "nullable": true, "description": "Ligação com limite de tempo para a captura de ecrã carregada. Liste a fila novamente para obter uma ligação nova." }, "attempts": { "type": "integer", "description": "Quantos ficheiros o utilizador final carregou para este comprovativo." }, "failure_reason": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "REVIEW_REJECTED após uma rejeição, OWNERSHIP_CHANGED quando a carteira mudou de titular ou foi eliminada antes de uma decisão. Vazio caso contrário." }, "method_chosen_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o utilizador final escolheu o método de captura de ecrã." }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "decided_by": { "type": "string", "description": "Quem fechou o comprovativo: review: para um revisor da consola, review para uma decisão por chave de API, widget ou sweeper quando a Didit o fechou automaticamente. Vazio enquanto PENDING." }, "review_note": { "type": "string", "description": "A nota enviada com a decisão. Vazia se não existir nenhuma." }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWalletProofDecision": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "note": { "type": "string", "maxLength": 512, "description": "Opcional. Mantido com a prova e devolvido como review_note." } } }, "DigitalIdWalletApiWalletDigitalCredentialsRequest": { "type": "object", "properties": { "protocol": { "type": "string", "description": "openid4vp-v1-signed." }, "request": { "type": "object", "additionalProperties": {}, "description": "Passe tal como está: navigator.credentials.get({digital: request}) no navegador, ou JSON.stringify(request) como requestJson de GetDigitalCredentialOption no Android. Assinado pela Didit para a sua aplicação." } }, "required": [ "protocol", "request" ] }, "DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest": { "type": "object", "description": "Iniciar uma verificação com Google Wallet (USA, GBR, BRA, SGP, TWN).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "A sua própria referência para esta verificação (ex.: o seu ID de utilizador). Devolvida nos resultados e webhooks." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Objeto JSON opcional armazenado com a verificação e devolvido nos resultados e webhooks." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Apenas aplicações em sandbox: o resultado simulado - 'wallet_cancelled', 'wallet_timeout' ou 'wallet_provider_error'; qualquer outro cenário (ou a ausência de cenário) resulta numa verificação bem-sucedida. Rejeitado em aplicações em produção. O catálogo completo está disponível em GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartCountryEnum" } ], "description": "País ISO 3166-1 alfa-3 da identidade Google Wallet.\n\n* `USA` - USA\n* `GBR` - GBR\n* `BRA` - BRA\n* `SGP` - SGP\n* `TWN` - TWN" }, "origin": { "type": "string", "minLength": 1, "description": "Onde a sua página ou aplicação irá solicitar à carteira: a origem https da sua página (o seu host deve constar de allowed_return_hosts da aplicação, ou ser o seu domínio de marca branca), por exemplo, https://app.example.com, ou android:apk-key-hash:. A carteira recusa o pedido em qualquer outro local.", "maxLength": 256 } }, "required": [ "country", "origin" ] }, "DigitalIdWalletApiGoogleWalletWalletVerificationStartCountryEnum": { "enum": [ "USA", "GBR", "BRA", "SGP", "TWN" ], "type": "string", "description": "* `USA` - USA\n* `GBR` - GBR\n* `BRA` - BRA\n* `SGP` - SGP\n* `TWN` - TWN" }, "DigitalIdWalletApiWalletDigitalCredentialResponseRequest": { "type": "object", "description": "O que a carteira respondeu à sua página ou aplicação, para uma verificação de ``request_digital_credential``.", "properties": { "response": { "type": "object", "additionalProperties": {}, "description": "Exatamente o que a carteira devolveu: {protocol, data} da DigitalCredential de navigator.credentials.get, ou o credentialJson analisado da DigitalCredential do Android. Encriptado para a Didit; não o altere." } }, "required": [ "response" ] }, "SessionFilesExport": { "type": "object", "description": "Um ZIP com todos os ficheiros de uma sessão, na qualidade original.", "required": [ "export_id", "session_id", "status", "file_count", "size_bytes", "download_url", "expires_at", "error", "created_at", "completed_at" ], "properties": { "export_id": { "type": "string", "format": "uuid", "description": "ID da exportação. Passe-o a `GET /v3/session/{sessionId}/files-export/{exportId}/`." }, "session_id": { "type": "string", "format": "uuid", "description": "A sessão da qual os ficheiros são provenientes." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "READY", "FAILED", "EXPIRED" ], "description": "`PENDING` e `PROCESSING` enquanto o ZIP está a ser preparado, `READY` assim que puder ser descarregado, `FAILED` quando não foi possível prepará-lo (solicite uma nova exportação), `EXPIRED` assim que o ZIP for eliminado." }, "file_count": { "type": "integer", "nullable": true, "description": "Ficheiros no ZIP. Definido apenas enquanto `status` for `READY`." }, "size_bytes": { "type": "integer", "format": "int64", "nullable": true, "description": "Tamanho do ZIP em bytes. Definido apenas enquanto `status` for `READY`." }, "download_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL assinado do ZIP, válido por um curto período de tempo. Definido apenas enquanto `status` for `READY`; leia a exportação novamente para obter um novo." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o ficheiro ZIP é eliminado, 24 horas após ficar pronto. Definido apenas enquanto o `status` for `READY`." }, "error": { "type": "string", "nullable": true, "description": "O motivo pelo qual a exportação falhou, quando `status` é `FAILED`." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando a exportação foi pedida." }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o ficheiro ZIP ficou pronto ou a exportação falhou." } } }, "TransactionRuleSuggestionsCreatedEvent": { "description": "Uma execução de sugestões de regras de transação propôs novas alterações de regras para a sua aplicação. Enviado quando as definições de sugestão de regras têm as notificações por webhook ativadas. Não existe um `status` de nível superior.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction_rule_suggestions.created" ], "description": "Sempre `transaction_rule_suggestions.created`." }, "run_id": { "type": "string", "format": "uuid", "description": "A execução de sugestões que produziu as novas sugestões." }, "open_count": { "type": "integer", "description": "Número de sugestões que ainda estão abertas após esta execução, incluindo as novas." }, "suggestions": { "type": "array", "description": "As sugestões criadas por esta execução.", "items": { "type": "object", "required": [ "suggestion_id", "kind", "title", "rule_id", "expected_impact" ], "properties": { "suggestion_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "ADD", "TWEAK", "DISABLE" ], "description": "`ADD` propõe uma nova regra, `TWEAK` altera uma existente, `DISABLE` desativa uma regra." }, "title": { "type": "string" }, "rule_id": { "type": "string", "format": "uuid", "nullable": true, "description": "A regra à qual se aplica uma sugestão `TWEAK` ou `DISABLE`; `null` para `ADD`." }, "expected_impact": { "type": "object", "additionalProperties": true, "description": "O que a alteração faria, tal como a sugestão apresenta na Console." } } } } }, "required": [ "webhook_type", "run_id", "open_count", "suggestions" ] } ] }, "GeolocationCheck": { "type": "object", "description": "Um resultado de verificação de Localização, a tentativa aceite de um nó do fluxo. Medição, incerteza e autenticidade são chaves separadas, de modo que uma determinação precisa sem atestação é interpretada de forma diferente de uma determinação imprecisa com atestação.", "properties": { "node_id": { "type": "string", "nullable": true, "description": "Nó do fluxo que gerou este resultado, para que um fluxo com dois passos de verificação de localização permaneça legível." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado ao nível da funcionalidade deste passo de verificação de localização, determinado a partir dos respetivos avisos. Independente do `status` da sessão." }, "outcome": { "type": "string", "nullable": true, "description": "O que aconteceu nesta tentativa.", "enum": [ "verified", "low_accuracy", "accuracy_undetermined", "stale", "approximate", "denied", "restricted", "unavailable", "timeout", "mock_detected", "outside_geofence", "in_blocked_area", "anonymizer_detected", "skipped", "replay_rejected", "unsupported_client", null ] }, "permission": { "type": "string", "nullable": true, "description": "O que o sistema operativo ou navegador concedeu. `not_requested` significa que o passo utiliza apenas a localização IP da ligação, pelo que nunca é solicitada uma permissão à pessoa.", "enum": [ "granted_precise", "granted_approximate", "denied", "restricted", "unavailable", "timeout", "dismissed", "not_requested", null ] }, "latitude": { "type": "number", "nullable": true, "description": "Latitude WGS84 da localização obtida. `null` quando não existe localização.", "format": "double" }, "longitude": { "type": "number", "nullable": true, "description": "Longitude WGS84 da localização obtida. `null` quando não existe localização.", "format": "double" }, "accuracy_m": { "type": "number", "nullable": true, "description": "Raio de incerteza em metros, no nível de confiança indicado em `accuracy_confidence`.", "format": "double" }, "accuracy_confidence": { "type": "string", "nullable": true, "description": "Nível de confiança que a plataforma atribui a `accuracy_m`: `p95` (navegadores), `p68` (Android) ou `unspecified` (iOS).", "enum": [ "p95", "p68", "unspecified", null ] }, "measured_at": { "type": "string", "nullable": true, "description": "Quando o dispositivo obteve a correção, de acordo com o seu próprio relógio.", "format": "date-time" }, "age_seconds": { "type": "integer", "nullable": true, "description": "Segundos entre o dispositivo obter a posição e a Didit a receber." }, "source": { "type": "string", "nullable": true, "description": "De onde proveio a localização, quando a plataforma o indicar. `ip` significa que a posição é a localização IP da ligação.", "enum": [ "gps", "fused", "network", "wifi", "cell", "browser", "unknown", "ip", null ] }, "platform": { "type": "string", "nullable": true, "description": "O cliente que produziu a correção.", "enum": [ "web", "ios", "android", "react_native", "flutter", null ] }, "sdk_version": { "type": "string", "nullable": true, "description": "Versão do SDK que gerou a correção." }, "is_mock": { "type": "boolean", "nullable": true, "description": "`true` quando o dispositivo indica que a localização obtida veio de um fornecedor de localização simulada ou software de simulação. `null` quando a plataforma não o comunica (os navegadores não conseguem determinar); `null` não é `false`." }, "produced_by_accessory": { "type": "boolean", "nullable": true, "description": "Apenas iOS: `true` quando a localização foi determinada por um acessório externo. `null` noutros casos." }, "integrity": { "type": "string", "enum": [ "attested", "not_attested", "failed", "unsupported", "not_determined" ], "description": "Se a atestação de dispositivo suporta a correção. `unsupported` é o que os navegadores comunicam, porque a Web não tem qualquer mecanismo de atestação; não é uma falha." }, "country_code": { "type": "string", "nullable": true, "description": "País ISO 3166-1 alfa-2 onde se encontra a localização." }, "region_code": { "type": "string", "nullable": true, "description": "Subdivisão ISO 3166-2 onde se encontra a posição geográfica." }, "city": { "type": "string", "nullable": true, "description": "Localidade povoada mais próxima, uma etiqueta para os revisores." }, "geofence": { "type": "object", "description": "Resultado das regras de país e área do passo.", "properties": { "enabled": { "type": "boolean", "description": "Se o passo aplica alguma regra de país ou área." }, "result": { "type": "string", "nullable": true, "description": "Onde a posição se situa em relação às regras. `undetermined` significa que o círculo de precisão abrange a fronteira ou que não foi possível determinar o país da posição; não constitui prova de estar fora.", "enum": [ "inside", "outside", "undetermined", null ] } } }, "inside_geofence": { "type": "boolean", "nullable": true, "description": "`true` quando `geofence.result` é `inside`, `false` quando `outside`, `null` caso contrário." }, "geofence_basis": { "type": "string", "nullable": true, "description": "A partir de que posição o resultado da área foi avaliado: a localização do `device` ou a localização do `ip` da ligação.", "enum": [ "device", "ip", null ] }, "inside_areas": { "type": "array", "items": { "type": "string" }, "description": "IDs das áreas permitidas configuradas dentro das quais se encontra a posição." }, "blocked_areas": { "type": "array", "items": { "type": "string" }, "description": "IDs das áreas bloqueadas configuradas em que a posição se encontra." }, "position_source": { "type": "string", "nullable": true, "description": "De onde o passo obtém a posição, conforme configurado: o dispositivo comparado com a localização do IP, apenas o dispositivo ou apenas a localização do IP.", "enum": [ "device_and_ip", "device_only", "ip_only", null ] }, "anonymizers": { "type": "object", "nullable": true, "description": "Como se apresentam a ligação e o dispositivo, cada um `true`, `false` ou `null` quando a origem não consegue determinar.", "properties": { "vpn": { "type": "boolean", "nullable": true }, "proxy": { "type": "boolean", "nullable": true }, "tor": { "type": "boolean", "nullable": true }, "spoofing": { "type": "boolean", "nullable": true }, "emulator": { "type": "boolean", "nullable": true } } }, "ip_distance_km": { "type": "number", "nullable": true, "description": "Distância até à localização IP da sessão após subtrair ambos os raios de incerteza; `0` quando se sobrepõem.", "format": "double" }, "ip_distance_uncertainty_km": { "type": "number", "nullable": true, "description": "Raio combinado que foi subtraído: o raio da localização por IP mais a precisão desta localização.", "format": "double" }, "ip_consistent": { "type": "boolean", "nullable": true, "description": "Se `ip_distance_km` está dentro da distância configurada no passo. `null` quando algum dos lados for desconhecido." }, "document_distance_km": { "type": "number", "nullable": true, "description": "Distância até à morada geocodificada no documento de identificação ou comprovativo de morada. `null` quando não existe nenhuma morada registada.", "format": "double" }, "travel_excused": { "type": "boolean", "nullable": true, "description": "Se a tolerância de deslocação do passo dispensou a distância em relação à morada. `null` quando a tolerância está desativada." }, "consecutive_mismatches": { "type": "integer", "nullable": true, "description": "Na tentativa final: esta verificação mais as discrepâncias anteriores da mesma pessoa consecutivas." }, "attempts": { "type": "integer", "description": "Número desta tentativa dentro do nó, a começar em 1." }, "consent": { "type": "object", "nullable": true, "description": "O consentimento dado pela pessoa antes da instrução do sistema, registado com a versão do texto e o idioma apresentados.", "properties": { "accepted_at": { "type": "string", "format": "date-time" }, "version": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "A funcionalidade que gerou este aviso. O valor identifica o bloco de funcionalidade a que o aviso pertence. O array de avisos de cada módulo utiliza tipicamente o valor correspondente ao seu módulo (por exemplo, `PHONE` dentro de `phone_verifications[].warnings`), mas o enum acima é a referência autoritativa para todos os avisos de funcionalidades no payload da decisão." }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "O ID do nó do grafo do fluxo que gerou este aviso" } } }, "description": "Avisos gerados por este passo de verificação de localização, com `feature` definido como `GEOLOCATION`. Os códigos de aviso começam com `LOCATION_`." } } }, "GeolocationAttempt": { "type": "object", "description": "Uma tentativa de um passo de verificação de localização: as mesmas chaves que `geolocation_checks[]` exceto `warnings`, mais o momento em que a Didit a recebeu.", "properties": { "node_id": { "type": "string", "nullable": true, "description": "Nó do fluxo que gerou este resultado, para que um fluxo com dois passos de verificação de localização permaneça legível." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Estado ao nível da funcionalidade deste passo de verificação de localização, determinado a partir dos respetivos avisos. Independente do `status` da sessão." }, "outcome": { "type": "string", "nullable": true, "description": "O que aconteceu nesta tentativa.", "enum": [ "verified", "low_accuracy", "accuracy_undetermined", "stale", "approximate", "denied", "restricted", "unavailable", "timeout", "mock_detected", "outside_geofence", "in_blocked_area", "anonymizer_detected", "skipped", "replay_rejected", "unsupported_client", null ] }, "permission": { "type": "string", "nullable": true, "description": "O que o sistema operativo ou navegador concedeu. `not_requested` significa que o passo utiliza apenas a localização IP da ligação, pelo que nunca é solicitada uma permissão à pessoa.", "enum": [ "granted_precise", "granted_approximate", "denied", "restricted", "unavailable", "timeout", "dismissed", "not_requested", null ] }, "latitude": { "type": "number", "nullable": true, "description": "Latitude WGS84 da localização obtida. `null` quando não existe localização.", "format": "double" }, "longitude": { "type": "number", "nullable": true, "description": "Longitude WGS84 da localização obtida. `null` quando não existe localização.", "format": "double" }, "accuracy_m": { "type": "number", "nullable": true, "description": "Raio de incerteza em metros, no nível de confiança indicado em `accuracy_confidence`.", "format": "double" }, "accuracy_confidence": { "type": "string", "nullable": true, "description": "Nível de confiança que a plataforma atribui a `accuracy_m`: `p95` (navegadores), `p68` (Android) ou `unspecified` (iOS).", "enum": [ "p95", "p68", "unspecified", null ] }, "measured_at": { "type": "string", "nullable": true, "description": "Quando o dispositivo obteve a correção, de acordo com o seu próprio relógio.", "format": "date-time" }, "age_seconds": { "type": "integer", "nullable": true, "description": "Segundos entre o dispositivo obter a posição e a Didit a receber." }, "source": { "type": "string", "nullable": true, "description": "De onde proveio a localização, quando a plataforma o indicar. `ip` significa que a posição é a localização IP da ligação.", "enum": [ "gps", "fused", "network", "wifi", "cell", "browser", "unknown", "ip", null ] }, "platform": { "type": "string", "nullable": true, "description": "O cliente que produziu a correção.", "enum": [ "web", "ios", "android", "react_native", "flutter", null ] }, "sdk_version": { "type": "string", "nullable": true, "description": "Versão do SDK que gerou a correção." }, "is_mock": { "type": "boolean", "nullable": true, "description": "`true` quando o dispositivo indica que a localização obtida veio de um fornecedor de localização simulada ou software de simulação. `null` quando a plataforma não o comunica (os navegadores não conseguem determinar); `null` não é `false`." }, "produced_by_accessory": { "type": "boolean", "nullable": true, "description": "Apenas iOS: `true` quando a localização foi determinada por um acessório externo. `null` noutros casos." }, "integrity": { "type": "string", "enum": [ "attested", "not_attested", "failed", "unsupported", "not_determined" ], "description": "Se a atestação de dispositivo suporta a correção. `unsupported` é o que os navegadores comunicam, porque a Web não tem qualquer mecanismo de atestação; não é uma falha." }, "country_code": { "type": "string", "nullable": true, "description": "País ISO 3166-1 alfa-2 onde se encontra a localização." }, "region_code": { "type": "string", "nullable": true, "description": "Subdivisão ISO 3166-2 onde se encontra a posição geográfica." }, "city": { "type": "string", "nullable": true, "description": "Localidade povoada mais próxima, uma etiqueta para os revisores." }, "geofence": { "type": "object", "description": "Resultado das regras de país e área do passo.", "properties": { "enabled": { "type": "boolean", "description": "Se o passo aplica alguma regra de país ou área." }, "result": { "type": "string", "nullable": true, "description": "Onde a posição se situa em relação às regras. `undetermined` significa que o círculo de precisão abrange a fronteira ou que não foi possível determinar o país da posição; não constitui prova de estar fora.", "enum": [ "inside", "outside", "undetermined", null ] } } }, "inside_geofence": { "type": "boolean", "nullable": true, "description": "`true` quando `geofence.result` é `inside`, `false` quando `outside`, `null` caso contrário." }, "geofence_basis": { "type": "string", "nullable": true, "description": "A partir de que posição o resultado da área foi avaliado: a localização do `device` ou a localização do `ip` da ligação.", "enum": [ "device", "ip", null ] }, "inside_areas": { "type": "array", "items": { "type": "string" }, "description": "IDs das áreas permitidas configuradas dentro das quais se encontra a posição." }, "blocked_areas": { "type": "array", "items": { "type": "string" }, "description": "IDs das áreas bloqueadas configuradas em que a posição se encontra." }, "position_source": { "type": "string", "nullable": true, "description": "De onde o passo obtém a posição, conforme configurado: o dispositivo comparado com a localização do IP, apenas o dispositivo ou apenas a localização do IP.", "enum": [ "device_and_ip", "device_only", "ip_only", null ] }, "anonymizers": { "type": "object", "nullable": true, "description": "Como se apresentam a ligação e o dispositivo, cada um `true`, `false` ou `null` quando a origem não consegue determinar.", "properties": { "vpn": { "type": "boolean", "nullable": true }, "proxy": { "type": "boolean", "nullable": true }, "tor": { "type": "boolean", "nullable": true }, "spoofing": { "type": "boolean", "nullable": true }, "emulator": { "type": "boolean", "nullable": true } } }, "ip_distance_km": { "type": "number", "nullable": true, "description": "Distância até à localização IP da sessão após subtrair ambos os raios de incerteza; `0` quando se sobrepõem.", "format": "double" }, "ip_distance_uncertainty_km": { "type": "number", "nullable": true, "description": "Raio combinado que foi subtraído: o raio da localização por IP mais a precisão desta localização.", "format": "double" }, "ip_consistent": { "type": "boolean", "nullable": true, "description": "Se `ip_distance_km` está dentro da distância configurada no passo. `null` quando algum dos lados for desconhecido." }, "document_distance_km": { "type": "number", "nullable": true, "description": "Distância até à morada geocodificada no documento de identificação ou comprovativo de morada. `null` quando não existe nenhuma morada registada.", "format": "double" }, "travel_excused": { "type": "boolean", "nullable": true, "description": "Se a tolerância de deslocação do passo dispensou a distância em relação à morada. `null` quando a tolerância está desativada." }, "consecutive_mismatches": { "type": "integer", "nullable": true, "description": "Na tentativa final: esta verificação mais as discrepâncias anteriores da mesma pessoa consecutivas." }, "attempts": { "type": "integer", "description": "Número desta tentativa dentro do nó, a começar em 1." }, "consent": { "type": "object", "nullable": true, "description": "O consentimento dado pela pessoa antes da instrução do sistema, registado com a versão do texto e o idioma apresentados.", "properties": { "accepted_at": { "type": "string", "format": "date-time" }, "version": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true } } }, "received_at": { "type": "string", "nullable": true, "description": "Quando a Didit recebeu a tentativa.", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "BiometricRetention": { "type": "object", "description": "Quando os dados biométricos em tempo real desta sessão são eliminados.", "required": [ "jurisdictions", "deletes_at" ], "properties": { "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "Códigos dos estados dos EUA cujas regras biométricas definem um limite de eliminação para esta pessoa (`US` quando o estado é desconhecido). Vazio se nenhum se aplicar." }, "deletes_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A data em que os dados biométricos em tempo real (imagens faciais e modelos) desta sessão são eliminados, com base na definição de conservação da sua aplicação e, quando aplicável, no limite legal para a jurisdição da pessoa. `null` quando ainda não se aplica nenhuma data." } } }, "TravelRuleManualMatchRequest": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "O `transaction_id` da mensagem de Travel Rule recebida (uma linha com `kind: message`)." } } }, "TravelRuleManualMatchResponse": { "type": "object", "required": [ "deposit", "message" ], "properties": { "deposit": { "$ref": "#/components/schemas/TravelRuleTransferRow" }, "message": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "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." }, "TransactionTokenAuth": { "type": "apiKey", "in": "header", "name": "X-Transaction-Token", "description": "Token de curta duração com âmbito restrito gerado pelo seu backend através de POST /v3/transactions/sdk-token/. Utilizado pelos SDKs da Didit nos endpoints /v1/transactions/ direcionados ao dispositivo." }, "SessionTokenAuth": { "type": "apiKey", "in": "header", "name": "Session-Token", "description": "Token de curta duração devolvido no campo `session_token` de POST /v3/session/. Utilizado pelo fluxo de verificação alojado (e por interfaces sandbox personalizadas) para chamar endpoints com âmbito de sessão em nome do utilizador em verificação, sem a sua chave de API do lado do servidor." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "O token de acesso de credenciais de cliente da aplicação." }, "CaseRequestToken": { "type": "apiKey", "in": "header", "name": "X-Case-Request-Token", "description": "Credencial específica do pedido proveniente da ligação segura. Concede acesso apenas a este pedido." } }, "responses": { "Unauthorized": { "description": "Não autorizado", "content": { "application/json": { "examples": { "Invalid API Key": { "summary": "Chave de API inválida", "value": { "detail": "Invalid API Key." } } } } } }, "Forbidden": { "description": "Proibido", "content": { "application/json": { "examples": { "No Permission": { "summary": "Sem permissão", "value": { "detail": "You do not have permission to perform this action." } }, "Not Enough Credits": { "summary": "Créditos insuficientes", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "NotFound": { "description": "Não encontrado", "content": { "application/json": { "examples": { "Not Found": { "summary": "Não encontrado", "value": { "detail": "Resource not found." } } } } } }, "PhoneRiskValidationError": { "description": "A validação do pedido falhou.", "content": { "application/json": { "examples": { "Missing phone number": { "summary": "Número de telefone em falta", "value": { "phone_number": [ "This field is required." ] } }, "Invalid phone number": { "summary": "Número de telefone inválido", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Invalid signal IP": { "summary": "IP de sinal inválido", "value": { "signals": { "ip": [ "Enter a valid IPv4 or IPv6 address." ] } } } } } } }, "EmailRiskValidationError": { "description": "A validação do pedido falhou.", "content": { "application/json": { "examples": { "Missing email": { "summary": "E-mail em falta", "value": { "email": [ "This field is required." ] } }, "Invalid email": { "summary": "E-mail inválido", "value": { "email": [ "Enter a valid email address." ] } }, "Invalid country hint": { "summary": "Indicação de país inválida", "value": { "country_code": [ "Ensure this field has no more than 3 characters." ] } } } } } }, "IPRiskValidationError": { "description": "A validação do pedido falhou.", "content": { "application/json": { "examples": { "Missing IP address": { "summary": "Endereço IP em falta", "value": { "ip_address": [ "This field is required." ] } }, "Invalid IP address": { "summary": "Endereço IP inválido", "value": { "ip_address": [ "Enter a valid IPv4 or IPv6 address." ] } }, "Country hint too long": { "summary": "Sugestão de país demasiado longa", "value": { "claimed_country": [ "Ensure this field has no more than 3 characters." ] } } } } } }, "RiskPermissionDenied": { "description": "A chave de API está em falta ou é inválida, ou a organização não pode cobrir a consulta em tempo real. Esta API nunca devolve `401`.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Sem cabeçalho `x-api-key`, ou a chave é inválida ou foi revogada", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "O saldo da organização não cobre o preço da consulta", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "RateLimitedWrite": { "description": "O limite de escrita partilhado de 300 pedidos por minuto por chave de API foi excedido. Respeite o `Retry-After` antes de tentar novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } }, "AddressValidationValidationError": { "description": "O corpo do pedido é inválido: um `country` em falta ou desconhecido, sem morada, ou com `address` e os campos estruturados em simultâneo.", "content": { "application/json": { "examples": { "Unknown country": { "value": { "country": [ "Use an ISO 3166-1 alpha-2 or alpha-3 country code, e.g. 'US' or 'USA'." ] } }, "No address": { "value": { "address": [ "Send the address: 'address' on one line, or the structured fields with 'address_line_1'." ] } }, "Both shapes": { "value": { "address": [ "Send either 'address' or the structured fields (address_line_1, ...), not both." ] } } } } } }, "AddressValidationPermissionDenied": { "description": "A chave de API está em falta ou é inválida, uma chave com âmbito carece de acesso de escrita a `sessions`, ou a organização não pode cobrir a validação. Esta API nunca devolve `401`.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } } } } } }, "DocumentProcessingBusy": { "description": "Estão a ser processados demasiados documentos neste momento, pelo que este carregamento não foi processado: nada foi armazenado e nenhuma tentativa foi utilizada. Envie o mesmo ficheiro novamente após o número de segundos em `Retry-After`. Ramifique com base no `code`, não no texto da mensagem.", "headers": { "Retry-After": { "description": "Segundos a aguardar antes de enviar o mesmo pedido novamente.", "schema": { "type": "integer", "example": 10 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "document_processing_busy" ] } } }, "example": { "detail": "We are busy processing documents. Please try again in a moment.", "code": "document_processing_busy" } } } } }, "parameters": { "WebhookSignature": { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 em hexadecimal minúsculo, usando o segredo do destino como chave, do corpo bruto exato do pedido." }, "WebhookSignatureV2": { "name": "X-Signature-V2", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 em hexadecimal minúsculo, usando o segredo do destino como chave, do JSON canónico do corpo (chaves ordenadas, sem espaços em branco, carateres não-ASCII sem escape). Recomendado, porque resiste a middleware que recodifica o corpo." }, "WebhookSignatureSimple": { "name": "X-Signature-Simple", "in": "header", "required": true, "deprecated": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 em hexadecimal minúsculo, usando o segredo do destino como chave, de `{timestamp}:{session_id}:{status}:{webhook_type}` (campos em falta como strings vazias). Cobre apenas o invólucro, nunca o payload." }, "WebhookTimestamp": { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Hora Unix em segundos, igual ao `timestamp` do corpo. Rejeite entregas com mais de alguns minutos." } } }, "x-webhooks": { "status.updated": { "post": { "summary": "Estado da sessão alterado", "description": "Uma sessão de verificação mudou de estado. `decision` só é enviado para `Approved`, `Declined`, `In Review` e `Abandoned`; tem o formato de `GET /v3/session/{sessionId}/decision/` para destinos na versão 3 de webhooks (a predefinida), e o formato reduzido anterior para destinos nas versões 1 ou 2. As sessões de empresas recebem sempre a decisão de empresa da versão 3.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "data.updated": { "post": { "summary": "Dados da sessão alterados", "description": "Os dados de uma sessão de verificação foram alterados sem alteração de estado, por exemplo, após a edição de uma revisão manual, uma substituição de passo ou uma nova triagem de monitorização contínua. `decision` é enviado apenas para `Approved`, `Declined`, `In Review` e `Abandoned`; tem o formato de `GET /v3/session/{sessionId}/decision/` para destinos na versão 3 de webhook (a predefinição), e o formato reduzido anterior para destinos nas versões 1 ou 2. As sessões de empresas recebem sempre a decisão de empresa na versão 3.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "user.status.updated": { "post": { "summary": "Estado do utilizador alterado", "description": "Um utilizador mudou de estado. Não é enviado quando o utilizador é criado.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "user.data.updated": { "post": { "summary": "Dados do utilizador alterados", "description": "Campos de um utilizador alterados. Não é enviado quando o utilizador é criado. Uma única gravação pode produzir tanto um evento de estado como de dados.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "business.status.updated": { "post": { "summary": "Estado da empresa alterado", "description": "Uma empresa mudou de estado. Não é enviado quando a empresa é criada.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "business.data.updated": { "post": { "summary": "Dados da empresa alterados", "description": "Campos de uma empresa alterados. Não é enviado quando a empresa é criada. Uma única gravação pode produzir tanto um evento de estado como de dados.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "transaction.created": { "post": { "summary": "Transação criada", "description": "Uma transação foi criada e analisada. Enviado apenas para aplicações em produção.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCreatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "transaction.status.updated": { "post": { "summary": "Estado da transação alterado", "description": "Uma transação mudou de estado, a partir de uma regra, de uma revisão ou de uma ação do utilizador final. Enviado apenas para aplicações em produção.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "travel_rule.status.updated": { "post": { "summary": "Estado da Travel Rule alterado", "description": "Uma troca de Travel Rule mudou de estado. É enviado em cada transição até `FINISHED`, `CANCELLED` ou `EXPIRED`, inclusive, e nunca depois. Enviado para aplicações de produção e, no caso de trocas de Travel Rule, também para aplicações sandbox (`environment: sandbox`). Não existe nenhum `status` de nível superior.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "workflow.compliance_changed": { "post": { "summary": "Conformidade do fluxo alterada", "description": "O estado de conformidade de um fluxo publicado mudou após uma reavaliação. Um evento por fluxo. Não existe um `status` de nível superior.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowComplianceChangedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "kyb.registry_search.resolved": { "post": { "summary": "Pesquisa de empresa resolvida (callback não assinado)", "description": "Corpo do retorno de chamada enviado para o `webhook_url` de `POST /v3/kyb/search/` assim que a pesquisa no registo for resolvida. Não é assinado: o pedido inclui `X-Didit-Unsigned-Callback: true` e nenhum dos cabeçalhos de assinatura; portanto, confirme-o comparando o `request_id` com o de uma pesquisa que iniciou. Utiliza `event_type`, e não `webhook_type`.", "tags": [ "Webhook" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistrySearchResolvedCallback" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } }, "transaction_rule_suggestions.created": { "post": { "summary": "Sugestões de regras de transação criadas", "description": "Uma execução de sugestões de regras de transação propôs novas alterações de regras para a sua aplicação. Enviado quando as definições de sugestão de regras têm as notificações por webhook ativadas. Não existe um `status` de nível superior.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } } } }, "responses": { "2XX": { "description": "Qualquer resposta 2xx confirma a entrega. Em caso de outras respostas e de tempos limite esgotados, são feitas novas tentativas; consulte https://docs.didit.me/integration/webhooks." } } } } } }