> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API de Validação de Base de Dados: ID Nacional > Valide dados de identidade com a API Didit em 100+ fontes nacionais e globais, com correspondência waterfall 1x1 e 2x2. Pagamento por chamada. ## Serviços baseados em morada Para serviços que validam uma morada residencial ou de serviços públicos, pode enviar uma única `address` e a Didit irá separá-la antes de processar a verificação. Para obter a melhor taxa de correspondência, envie diretamente os campos de morada estruturados da Didit: | Campo | Significado | | - | - | | `address_element_1` | Morada, incluindo número e tipo de via | | `address_element_2` | Opcional: unidade, edifício, andar ou linha de morada adicional | | `address_element_3` | Subúrbio, distrito, localidade ou bairro | | `address_element_4` | Cidade, vila, estado, província ou região | | `address_element_5` | Código postal | Os campos estruturados substituem o valor de `address`. `postal_code` é aceite como alias de `address_element_5`. ## Consentimento Alguns serviços de base de dados exigem o consentimento explícito do utilizador final antes de o fornecedor poder ser consultado. O catálogo de serviços assinala estas linhas com `requires_consent=true`. Envie `consent=true` quando o consentimento do utilizador se aplicar aos serviços selecionados. A Didit rejeita o pedido antes de qualquer chamada ao fornecedor ou evento de faturação se um serviço selecionado exigir consentimento e não o enviar. ## Carregamento de ficheiros A validação de base de dados usa `multipart/form-data`. Os serviços biométricos que exigem `selfie` apresentam-na como um campo de carregamento de ficheiro no ambiente de teste da API, para que possa selecionar uma imagem diretamente, em vez de colar um caminho ou uma string base64. No código, carregue o ficheiro com a sintaxe multipart normal: ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## Erros de validação A Didit valida os campos obrigatórios, a estrutura da morada e os formatos específicos de cada serviço antes de chamar o fornecedor. Por exemplo, os serviços de registo chineses, como `chn_national_id` e `chn_passport_verification`, esperam `full_name` no sistema de escrita chinês original, e `chn_national_id` exige também um número de identificação nacional chinês válido, com 15 ou 18 caracteres e uma soma de verificação correta. Se um pedido não puder ser executado, a API devolve erros explícitos por campo e não é cobrada qualquer utilização. Se um fornecedor falhar após a validação prévia, a resposta inclui `validation_errors`, e os pedidos de API guardados armazenam esses erros no resultado da validação de base de dados. ## Entrada rejeitada e resultados indisponíveis Quando nenhum serviço devolve um resultado utilizável, analise cada entrada de `validation_errors` antes de decidir se deve tentar novamente. O estado HTTP, por si só, não determina se uma nova tentativa é adequada. Uma resposta `400` com `code: "provider_rejected_input"` e `retryable: false` significa que todas as tentativas sem resposta recusaram explicitamente a entrada. Corrija os dados fornecidos antes de voltar a tentar. Estas tentativas não são faturadas. Uma resposta `502` com `code: "empty_provider_response"` e `retryable: true` significa que o serviço não conseguiu produzir um resultado utilizável por outro motivo. Isto inclui uma entrada recusada seguida de um mecanismo alternativo indisponível, ou de um mecanismo alternativo que não fornece qualquer explicação. Tente novamente mais tarde; a resposta não indica que a entrada está errada. Se uma base de dados continuar a falhar, a Didit envia um email às organizações que a utilizaram recentemente, uma vez, quando a interrupção se prolongar, e novamente quando verificações reais confirmarem que está a responder. Consulte [Notificações de disponibilidade](https://docs.didit.me/pt/core-technology/database-validation/overview.md#notificações-de-disponibilidade). Quando apenas alguns dos serviços selecionados falham, o pedido é bem-sucedido: a resposta é `200` e os serviços com falha são listados em `database_validation.errors[]`, cada um com os mesmos campos `code` e `retryable`. `database_validation.status` segue então os serviços que responderam e pode ser `Approved`, por isso inspecione `errors[]` em todas as respostas, e não apenas em respostas `4xx` ou `5xx`. Um serviço indicado aí está ausente de `validations` e de `services_used`, e não é faturado; volte a tentar apenas esse serviço. Outros erros `502` podem exigir dados corrigidos. Por exemplo, `provider_invalid_input` e `provider_validation_error` descrevem dados que a fonte rejeitou e não devem ser repetidos sem alteração, mesmo quando a resposta legada omite `retryable`. A orientação para novas tentativas de `empty_provider_response` não se aplica a estes códigos. Um resultado conclusivo sem correspondência é uma verificação concluída, não uma falha de disponibilidade. ## OpenAPI ````yaml pt/openapi-25.json POST /v3/database-validation/ 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 security: [] tags: [] paths: /v3/database-validation/: post: tags: - Standalone APIs summary: Validação de base de dados (independente) 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. **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. **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`. **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`. **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. **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). **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`. **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. Envie o pedido como `application/json`, ou como `multipart/form-data` ao carregar uma `selfie`. operationId: post_v3database-validation parameters: [] 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`. 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 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 security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/database-validation/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "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" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.database_validation.validate( 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", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.databaseValidation.validate({ 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", }); console.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; import java.util.List; import me.didit.Didit; import me.didit.types.DatabaseValidationValidateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder() .issuingState("BRA") .services(List.of("bra_cpf")) .identificationNumber("12345678900") .firstName("John") .lastName("Doe") .dateOfBirth(LocalDate.parse("1980-01-01")) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- databaseValidation->validate([ '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', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.database_validation.validate( 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" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams { IssuingState = "BRA", Services = new string[] { "bra_cpf" }, IdentificationNumber = "12345678900", FirstName = "John", LastName = "Doe", DateOfBirth = "1980-01-01", VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.