> ## 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 Verificação de ID: OCR e Autenticidade > Didit verifica documentos de identidade de 220+ países e 14.000+ tipos: autenticidade, OCR, MRZ, inferência sub-2s, pague por uso, sem contrato. ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/id-verification/ 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/id-verification/: post: tags: - Standalone APIs summary: Verificação de identidade (OCR do documento + verificações de fraude) description: >- Faça o OCR de um documento de identidade e execute verificações de fraude documental em uma única chamada: a resposta traz os campos extraídos do titular, a MRZ interpretada, um `status` `Approved`/`Declined`/`In Review` e uma lista `warnings` que explica cada problema encontrado. Compatível com 14,000+ tipos de documento de 220+ países e territórios. **Como funciona.** Envie a `front_image` do documento (obrigatória) e, para documentos com frente e verso, a `back_image`. Envie fotos sem recorte, com os quatro cantos do documento visíveis. O próprio serviço detecta, alinha e recorta o documento, portanto não faça o recorte antes. O documento é classificado automaticamente (você nunca informa o país nem o tipo de documento), a zona visual é lida com OCR, e a MRZ e eventuais códigos de barras são decodificados. Em seguida, verificações cruzadas validam datas, formatos de número e dígitos verificadores da MRZ, e comparam a zona visual com a MRZ. Com `perform_document_liveness=true`, as imagens também são analisadas para detectar reprodução em tela, cópias impressas e manipulação do retrato. **Lógica de decisão.** O `status` é `Approved`, a menos que pelo menos um aviso resulte em recusa. Riscos de fraude e falhas graves sempre resultam em recusa: `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 gerados por este endpoint independente. `COULD_NOT_DETECT_DOCUMENT_TYPE` é retornado aqui quando a imagem da frente não corresponde, com alta confiança, a um modelo conhecido de documento oficial, e a requisição é recusada.) Três grupos de risco podem ser configurados por requisição com `invalid_mrz_action`, `inconsistent_data_action` e `expiration_date_not_detected_action` (`DECLINE` ou `NO_ACTION`). Todos os demais avisos (por exemplo, `POSSIBLE_DUPLICATED_USER`) são informativos e nunca causam recusa por si só. Quando `perform_document_liveness=true` (o padrão) e a verificação de falsificação não retorna uma pontuação utilizável (o provedor falhou, respondeu com código diferente de 200 ou respondeu HTTP 200 com `status="ERR"`), a chamada retorna `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 é evidência de que o documento é autêntico. Esse escalonamento não é configurável e nunca substitui um `Declined`. Com `perform_document_liveness=false`, a verificação é ignorada e o status segue os demais avisos, como antes. Um documento que não pode ser processado de forma alguma retorna `400` com `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`. Um documento legível, mas com problemas, retorna `200` com `status: "Declined"`. Sempre verifique `id_verification.status` e `id_verification.warnings`, e não apenas o código HTTP. **Faturamento.** Cada resposta `200` consome um crédito da API de Verificação de identidade (pago com o crédito do seu plano ou com o saldo recarregado). Quando o saldo da organização não cobre a chamada, o endpoint retorna `403` com o erro de créditos insuficientes antes de qualquer processamento de imagem. **Persistência da sessão (`save_api_request`, padrão `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API: ela aparece no Business Console, o `request_id` retornado é um ID de sessão real que você pode passar para `GET /v3/session/{sessionId}/decision/`, as imagens recortadas do documento e do retrato são armazenadas e retornadas como URLs de mídia de curta duração (`https:///ocr/...`), e um webhook `status.updated` é enviado aos endpoints de webhook configurados. Quando `false`, nada é armazenado, `request_id` é um UUID de correlação de uso único, e `portrait_image`/`front_image`/`back_image` são retornados inline como strings JPEG codificadas em base64. **Sandbox.** Chaves de API de sandbox ignoram todo o processamento e o faturamento: após a validação da requisição (entradas malformadas continuam retornando `400`), o endpoint retorna um payload simulado estático `Approved` (uma carteira de identidade fictícia dos EUA de "Sandbox User"), nenhuma sessão é persistida e nenhum crédito é consumido. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais ausentes ou inválidas retornam `403` (`{"detail": "You do not have permission to perform this action."}`). Esta API nunca retorna `401`. **Limite de requisições.** Cota de escrita compartilhada de 300 requisições/min por chave de API entre todos os endpoints POST/PATCH/DELETE. Ao excedê-la, a API retorna `429`. operationId: post_v3id-verification 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 identidade. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`, `pdf`. Tamanho máximo de upload: **10 MB** (arquivos maiores são rejeitados com `400`). PDFs são renderizados como imagem antes do OCR; PDFs criptografados exigem `front_image_password`. As imagens são comprimidas automaticamente para ~0,5 MB e a orientação EXIF é aplicada. Envie a captura completa, sem recorte, com os quatro cantos do documento visíveis. front_image_password: type: string description: >- Senha para descriptografar `front_image` quando for um PDF criptografado. Enviar um PDF criptografado sem senha (ou com uma senha errada) retorna `400`. writeOnly: true back_image: type: string format: binary description: >- Verso do documento: envie-o sempre que o documento tiver um (muitas carteiras de identidade trazem a MRZ ou um código de barras no verso; omiti-lo apenas deixa a MRZ e os campos do verso vazios na resposta, e este endpoint não gera um aviso de MRZ ausente). Mesmo formato e limites de tamanho de `front_image`. Quando omitido, `back_image` e os campos do verso são `null` na resposta. back_image_password: type: string description: >- Senha para descriptografar `back_image` quando for um PDF criptografado. writeOnly: true perform_document_liveness: type: boolean default: true description: >- Analisa as duas imagens em busca de fraude de apresentação: reprodução em tela (`SCREEN_CAPTURE_DETECTED`), cópias impressas (`PRINTED_COPY_DETECTED`) e manipulação do retrato (`PORTRAIT_MANIPULATION_DETECTED`). Qualquer uma delas resulta em recusa automática. Ativado por padrão; defina como `false` para pular a análise de fraude e reduzir a latência. Quando ativado e o provedor não retorna 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: >- Aceito e validado (1–120), mas **atualmente não aplicado** por este endpoint — ele nunca gera um aviso `MINIMUM_AGE_NOT_MET` a partir deste campo. Aplique as regras de idade com base em `date_of_birth`/`age` retornados, ou use 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 nenhuma data de validade pode ser lida (`EXPIRATION_DATE_NOT_DETECTED`). Padrão `NO_ACTION`, pois muitos documentos de identidade não trazem data de validade impressa. Observação: uma data de validade *detectada e já vencida* sempre 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 dos dígitos verificadores (`MRZ_VALIDATION_FAILED`). A ausência de MRZ não gera aviso neste endpoint. Relevante apenas para documentos que possuem MRZ. `REVIEW` não é compatível com este endpoint e retorna `400`. inconsistent_data_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- O que fazer quando os dados extraídos são internamente inconsistentes: `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` (a zona visual diverge da 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 coberto na captura (`CRITICAL_FIELD_OCCLUSION_DETECTED`): um número de identidade, um nome, a data de nascimento ou a data de validade. Recusa por padrão, como os demais riscos de integridade de documento deste endpoint: cobrir os números com os quais um relatório é conciliado é justamente a aparência de um documento censurado. O valor lido de um campo coberto é descartado da extração de qualquer forma, então o aviso `*_NOT_DETECTED` correspondente geralmente o acompanha. `REVIEW` não é compatível com este endpoint e retorna `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 corresponde ao formato que a autoridade emissora usa para aquele tipo de documento (`DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`). Padrão `NO_ACTION`, que informa o aviso sem alterar o status. `REVIEW` não é compatível com este endpoint e retorna `400`. preferred_characters: type: string enum: - latin - non_latin default: latin description: >- Escrita preferencial para os campos de nome/endereço em documentos que imprimem texto latino e não latino (árabe, cirílico, CJK, …). `latin` retorna valores transliterados/latinos; `non_latin` dá preferência à escrita nativa. save_api_request: type: boolean default: true description: >- Quando `true` (padrão), persiste a chamada como uma sessão do tipo API: visível no Business Console, recuperável via `GET /v3/session/{sessionId}/decision/` usando o `request_id` retornado, anunciada por meio de um webhook `status.updated` e com as imagens do documento retornadas como URLs de mídia. Quando `false`, nada é armazenado, `request_id` é um UUID transitório e as imagens são retornadas inline como strings JPEG em base64. example: true vendor_data: type: string description: >- String opaca opcional (seu ID interno de usuário, e-mail, UUID…) armazenada na sessão persistida e devolvida na resposta. Use-a para correlacionar chamadas de API com seus próprios registros e para filtrar sessões posteriormente. 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 requisições multipart, envie-o como um campo de string codificada em JSON (por exemplo, `metadata={"flow":"onboarding"}`), que é convertido em um 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 detectado é detalhado em `id_verification.warnings`. `In Review` é retornado quando uma verificação de prova de vida do documento solicitada não produziu resultado utilizável (`DOCUMENT_LIVENESS_NOT_COMPUTED`). Um documento com problemas ainda retorna `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 mídia de curta duração; com `save_api_request=false`, eles são strings JPEG em base64 inline. content: application/json: examples: Approved: summary: >- Documento de identidade de dois lados lido sem problemas (salvo, com as imagens como URLs de mí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 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 brightness_score: 95.6 brightness_issue: ok is_document_fully_visible: true resolution_score: 43 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<<<<<< 8001139M3203318ESP<<<<<<<<<<<3 FORES- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: address_components: - long_name: b short_name: b types: - subpremise - long_name: '52' short_name: '52' types: - street_number - long_name: Avenida el Cardonal short_name: Av. el Cardonal types: - route - long_name: La Laguna short_name: La Laguna types: - locality - political - long_name: Spain short_name: ES types: - country - political - long_name: '38108' short_name: '38108' types: - postal_code formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain geometry: location: lat: 28.4501161 lng: -16.3004407 location_type: ROOFTOP types: - street_address - subpremise document_location: latitude: 28.4501161 longitude: -16.3004407 label: Spain Identity Card Address is_verified: true category: Residential warnings: [] barcodes: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-06-12T02:21:56.013573+00:00' Declined - expired document: summary: >- Upload somente da frente de uma carteira de identidade expirada value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 id_verification: status: Declined document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: BNK123072 personal_number: 21771255F portrait_image: >- https:///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 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 resulta em recusa e a verificação de prova de vida do documento solicitada produziu um resultado utilizável; `In Review` quando essa verificação solicitada não produziu um resultado utilizável (`DOCUMENT_LIVENESS_NOT_COMPUTED`); `Declined` quando um aviso resulta em recusa. A lista `warnings` explica o motivo. document_type: type: string nullable: true description: >- Nome de exibição do tipo de documento detectado: `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 (por exemplo, `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. Uma URL de mídia de curta duração (`https:///ocr/...`) quando `save_api_request=true` (padrão); uma string JPEG codificada em base64 inline quando `save_api_request=false`. `null` quando nenhum retrato foi detectado. front_image: type: string nullable: true description: >- Recorte alinhado da frente do documento. URL de mídia quando salvo; caso contrário, JPEG em base64 inline. back_image: type: string nullable: true description: >- Recorte alinhado do verso do documento. `null` quando nenhuma `back_image` foi enviada. front_image_camera_front: type: string nullable: true description: >- Sempre `null` neste endpoint (preenchido apenas em sessões de verificação com captura pela câmera). 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óstico da qualidade de captura da imagem enviada (`null` quando o lado não foi fornecido ou a pontuação falhou). Todas as pontuações vã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 detectado (por exemplo, escuro demais / claro demais). is_document_fully_visible: type: boolean nullable: true description: >- Indica 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óstico da qualidade de captura da imagem enviada (`null` quando o lado não foi fornecido ou a pontuação falhou). Todas as pontuações vã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 detectado (por exemplo, escuro demais / claro demais). is_document_fully_visible: type: boolean nullable: true description: >- Indica 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 alpha-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/detectado.' example: M address: type: string nullable: true description: Endereço exatamente como impresso 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 traga 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 extras específicos do documento que não têm coluna dedicada (por exemplo, `first_surname`/`second_surname` em documentos de identidade espanhóis, categorias de habilitação em carteiras de motorista). mrz: type: object description: >- Zona de leitura mecânica interpretada. Um **objeto vazio** (`{}`) quando o documento não tem MRZ ou ela não pôde ser lida; nesse caso, verifique também a lista `warnings`. As datas dentro da MRZ usam o formato 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 alpha-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 bruta da MRZ (`YYMMDD`). example: '800113' expiry_date: type: string description: Data de validade bruta da MRZ (`YYMMDD`). example: '320331' sex: type: string example: M document_type: type: string description: >- Código do tipo de documento da 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 verificador da MRZ para a data de nascimento. example: '9' expiry_date_hash: type: string description: Dígito verificador da MRZ para a data de validade. example: '8' document_number_hash: type: string description: >- Dígito verificador da MRZ para o número do documento. example: '3' final_hash: type: string description: Dígito verificador composto da MRZ. example: '3' personal_number: type: string nullable: true example: 20446581H warnings: type: array items: type: string description: Avisos não fatais da análise da MRZ. errors: type: array items: type: string description: >- Erros de dígito verificador/análise da MRZ. Erros não vazios aparecem como um aviso `MRZ_VALIDATION_FAILED`. mrz_type: type: string description: >- Layout da MRZ: `TD1` (carteiras de identidade, 3 linhas), `TD2` ou `TD3` (passaportes, 2 linhas). example: TD1 mrz_string: type: string description: >- Texto bruto da MRZ conforme lido, com as linhas separadas por `\n`. mrz_key: type: string description: >- Chave composta (número do documento + dígitos verificadores) usada em verificações cruzadas. parsed_address: type: object nullable: true description: >- Detalhamento estruturado e geocodificado de `address`. `null` quando o documento não contém endereço ou ele não pôde ser interpretado. 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: String canônica do endereço geocodificado. example: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: type: object additionalProperties: true description: >- Payload bruto de geocodificação (`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 do endereço do documento. label: type: string nullable: true description: De qual campo do documento o endereço foi lido. example: Spain Identity Card Address is_verified: type: boolean description: >- Indica se a geocodificação confirmou que o endereço existe. category: type: string nullable: true description: >- Categoria do endereço (por exemplo, `Residential`, `Commercial`). example: Residential warnings: type: array description: >- Vazio em uma aprovação sem ressalvas. Cada entrada explica um risco detectado; entradas com `log_type: "error"` definem `status` como `Declined`, e `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) o define como `In Review`. items: type: object properties: risk: type: string description: >- Código de risco legível por máquina. Riscos que sempre resultam em recusa: `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`. Controlados por opções da requisição: `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 (por exemplo, `POSSIBLE_DUPLICATED_USER`) são informativos. `DOCUMENT_LIVENESS_NOT_COMPUTED` é gerado quando `perform_document_liveness=true`, mas a verificação de falsificação não retornou uma pontuação utilizável; ele define `status` como `In Review`. `COULD_NOT_DETECT_DOCUMENT_TYPE` também é retornado quando a frente do documento não corresponde, com alta confiança, a um modelo de documento oficial conhecido, 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: >- Recurso que emitiu 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: >- Severidade. Avisos `error` levam o `status` para `Declined`; `warning` (somente `DOCUMENT_LIVENESS_NOT_COMPUTED`, quando a verificação de falsificação solicitada não produziu uma pontuação utilizável) leva o `status` para `In Review`; entradas `information` são apenas informativas e nunca alteram o status. short_description: type: string description: Resumo legível do risco em uma linha. long_description: type: string description: Explicação legível do risco. barcodes: type: array description: >- Códigos de barras decodificados do documento (PDF417, QR, …). Vazio quando o documento não tem nenhum ou quando 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 decodificado. data_raw: type: string description: >- Payload bruto (não decodificado), quando diferente. side: type: string nullable: true description: '`front` ou `back`.' vendor_data: type: string nullable: true description: Eco do `vendor_data` que você enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que você enviou, ou `null`. created_at: type: string format: date-time description: >- Timestamp ISO 8601 (UTC) do momento em que a resposta foi gerada. '400': description: >- Erro de validação ou de processamento. Problemas em nível de campo retornam o envelope padrão do DRF (um array de mensagens para cada campo com problema). Problemas com PDFs criptografados retornam `{"detail": ...}`. Uma imagem de documento em que nenhum documento pode ser reconhecido retorna `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`. Envios de PDF também podem falhar com "The submitted PDF file is corrupted or invalid." ou com 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 arquivo 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 upload excede o limite de 10 MB value: front_image: - File size should not exceed 10 MB Invalid option value: summary: As opções aceitam apenas DECLINE ou NO_ACTION value: invalid_mrz_action: - '"REVIEW" is not a valid choice.' Encrypted PDF: summary: PDF enviado sem a senha exigida 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 descriptografa o PDF value: detail: >- The PDF password is incorrect. Please provide the correct password. Document not recognized: summary: Nenhum documento de identidade pôde ser detectado na imagem value: error: COULD_NOT_RECOGNIZE_DOCUMENT PDF conversion failure: summary: Não foi possível converter o PDF enviado em imagem value: error: Failed to convert front image PDF. '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente e também quando o saldo da organização que faz a chamada não cobre a chamada; uma chave incorreta, revogada ou expirada retorna `401`. Uma chave ausente retorna `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada retorna `401`. Créditos insuficientes retornam `403` com `{"error": ...}` antes de qualquer processamento da imagem. content: application/json: examples: Missing or invalid API key: summary: Nenhum 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 requisições excedido. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API. 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 requisições 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/id-verification/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'front_image=@./id_front.jpg' \ -F 'back_image=@./id_back.jpg' \ -F 'perform_document_liveness=true' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.id_verification.verify( front_image=open("front_image.jpg", "rb"), back_image=open("back_image.jpg", "rb"), perform_document_liveness=True, save_api_request=True, vendor_data="user-123", metadata={"flow": "onboarding"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.idVerification.verify({ front_image: await fileFromPath("front_image.jpg"), back_image: await fileFromPath("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" }, }); console.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; import java.util.Map; import me.didit.Didit; import me.didit.types.IdVerificationVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.idVerification().verify(IdVerificationVerifyParams.builder() .frontImage(Path.of("front_image.jpg")) .backImage(Path.of("back_image.jpg")) .performDocumentLiveness(true) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "onboarding")) .build()); System.out.println(result); - lang: php label: PHP source: |- idVerification->verify([ 'front_image' => File::fromPath('front_image.jpg'), 'back_image' => File::fromPath('back_image.jpg'), 'perform_document_liveness' => true, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'onboarding'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.id_verification.verify( front_image: Pathname("front_image.jpg"), back_image: Pathname("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams { FrontImage = FileUpload.FromPath("front_image.jpg"), BackImage = FileUpload.FromPath("back_image.jpg"), PerformDocumentLiveness = true, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "onboarding" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.