> ## 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 identidade: OCR e autenticidade > Verifique documentos de identidade em 220+ países e 14,000+ tipos com a Didit. OCR, MRZ, autenticidade, pago por utilização e sem contratos. ## OpenAPI ````yaml pt/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 de documentos + verificações de fraude) description: >- Efetue o OCR de um documento de identidade e execute verificações de fraude documental numa única chamada — devolve os campos extraídos do titular, a MRZ processada, um `status` `Approved`/`Declined`/`In Review` e uma lista `warnings` que explica cada problema detetado. Suporta 14,000+ tipos de documentos de 220+ países e territórios. **Como funciona.** Envie a `front_image` do documento (obrigatória) e, para documentos com dois lados, a `back_image`. Carregue fotos não recortadas com os quatro cantos do documento visíveis — o serviço deteta, alinha e recorta o documento autonomamente, pelo que não deve recortar previamente. O documento é classificado automaticamente (nunca declara o país ou o tipo de documento), a zona visual é lida por OCR e a MRZ e quaisquer códigos de barras são descodificados. As verificações cruzadas validam depois as datas, os formatos numéricos e os dígitos de controlo da MRZ, e comparam a zona visual com a MRZ. Com `perform_document_liveness=true`, as imagens são adicionalmente analisadas quanto a reproduções em ecrã, cópias impressas e manipulação de retrato. **Lógica de decisão.** O `status` é `Approved`, a menos que pelo menos um aviso resulte numa recusa. Os riscos de fraude e falha crítica recusam sempre: `DOCUMENT_EXPIRED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, além de falhas de extração (`NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`). (`PORTRAIT_IMAGE_NOT_DETECTED`, `INVALID_DATE` e `MRZ_NOT_DETECTED` existem em sessões de fluxo, mas nunca são produzidos por este endpoint autónomo. `COULD_NOT_DETECT_DOCUMENT_TYPE` é devolvido aqui quando a imagem frontal não corresponde com elevada confiança a um modelo de documento oficial conhecido, recusando o pedido.) Três grupos de risco são configuráveis por pedido através de `invalid_mrz_action`, `inconsistent_data_action` e `expiration_date_not_detected_action` (`DECLINE` ou `NO_ACTION`). Todos os outros avisos (por exemplo, `POSSIBLE_DUPLICATED_USER`) são informativos e nunca recusam por si próprios. Quando `perform_document_liveness=true` (a predefinição) e a verificação de falsificação não devolve uma pontuação utilizável — o fornecedor falhou, respondeu com um código diferente de 200 ou respondeu com HTTP 200 e `status="ERR"` - a chamada devolve `200` com `status: "In Review"` e um aviso `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) em vez de `Approved`: uma verificação que não foi executada não constitui prova de que o documento seja genuíno. Este escalonamento não é configurável e nunca se sobrepõe a `Declined`; com `perform_document_liveness=false`, a verificação é ignorada e o estado segue os restantes avisos como anteriormente. Um documento que não possa de todo ser processado devolve `400` com `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`; um documento legível mas com problemas devolve `200` com `status: "Declined"` — inspecione sempre `id_verification.status` e `id_verification.warnings`, e não apenas o código HTTP. **Faturação.** Cada resposta `200` consome um crédito da API de Verificação de identidade (pago a partir do crédito do seu plano ou do saldo carregado). Quando o saldo da organização não cobre a chamada, o endpoint devolve `403` com o erro de créditos insuficientes antes de qualquer processamento de imagem. **Persistência da sessão (`save_api_request`, predefinição `true`).** Quando for `true`, a chamada é persistida como uma sessão do tipo API: aparece na Business Console, o `request_id` devolvido é um ID de sessão real que pode passar a `GET /v3/session/{sessionId}/decision/`, as imagens recortadas do documento/retrato são armazenadas e devolvidas como URLs de multimédia de curta duração (`https:///ocr/...`), e um webhook `status.updated` é emitido para os seus endpoints de webhook configurados. Quando for `false`, nada é armazenado, `request_id` é um UUID de correlação pontual e `portrait_image`/`front_image`/`back_image` são devolvidos diretamente como strings JPEG codificadas em base64. **Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada malformados continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved` (um documento de identidade fictício dos EUA do utilizador "Sandbox User"), nenhuma sessão é persistida e nenhum crédito é consumido. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{"detail": "You do not have permission to perform this action."}`) — esta API nunca devolve `401`. **Limite de pedidos.** Limite de pedidos de escrita partilhado de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; exceder este limite devolve `429`. operationId: post_v3id-verification parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - front_image properties: front_image: type: string format: binary description: >- Frente do documento de identificação. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`, `pdf`. Tamanho máximo de carregamento: **10 MB** (ficheiros maiores são rejeitados com `400`). Os PDFs são convertidos numa imagem antes do OCR; PDFs encriptados requerem `front_image_password`. As imagens são comprimidas automaticamente para ~0.5 MB e a orientação EXIF é aplicada. Carregue a captura completa e sem cortes com os quatro cantos do documento visíveis. front_image_password: type: string description: >- Palavra-passe para desencriptar `front_image` quando for um PDF encriptado. O envio de um PDF encriptado sem palavra-passe (ou com uma incorreta) devolve `400`. writeOnly: true back_image: type: string format: binary description: >- Verso do documento — envie-o sempre que o documento tiver um (muitos cartões de identificação contêm o MRZ ou um código de barras no verso; omiti-lo apenas deixa o MRZ e os campos do verso vazios na resposta — este endpoint não gera um aviso de MRZ em falta). Mesmos limites de formato e tamanho que `front_image`. Quando omitido, `back_image` e os campos do verso ficam a `null` na resposta. back_image_password: type: string description: >- Palavra-passe para desencriptar `back_image` quando for um PDF encriptado. writeOnly: true perform_document_liveness: type: boolean default: true description: >- Analisa ambas as imagens à procura de fraude de apresentação: reproduções de ecrã (`SCREEN_CAPTURE_DETECTED`), cópias impressas (`PRINTED_COPY_DETECTED`) e manipulação de retrato (`PORTRAIT_MANIPULATION_DETECTED`). Qualquer uma destas situações causa recusa automática. Ativado por predefinição; defina como `false` para ignorar a triagem de fraude e reduzir a latência. Quando ativado e o fornecedor não devolve uma pontuação utilizável, a resposta é `In Review` com um aviso `DOCUMENT_LIVENESS_NOT_COMPUTED` em vez de `Approved`. example: true minimum_age: type: integer nullable: true default: null minimum: 1 maximum: 120 description: >- Aceite e validado (1–120), mas **atualmente não aplicado** por este endpoint — nunca produz um aviso `MINIMUM_AGE_NOT_MET` a partir deste campo. Aplique regras de idade a partir de `date_of_birth`/`age` devolvidos, ou utilize um fluxo de sessão de verificação com restrições de idade. expiration_date_not_detected_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- O que fazer quando não for possível ler qualquer data de validade (`EXPIRATION_DATE_NOT_DETECTED`). Predefinição `NO_ACTION`, pois muitos documentos de identidade não imprimem a data de validade. Nota: uma data de validade *detetada e ultrapassada* resulta sempre numa recusa (`DOCUMENT_EXPIRED`), independentemente desta opção. invalid_mrz_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- O que fazer quando a MRZ extraída falha na validação do dígito de controlo (`MRZ_VALIDATION_FAILED`). Uma MRZ em falta não gera qualquer aviso neste endpoint. Relevante apenas para documentos que possuem uma MRZ. `REVIEW` não é suportado neste endpoint e devolve `400`. inconsistent_data_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- O que fazer quando os dados extraídos forem internamente inconsistentes: `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` (a zona visual não coincide com a MRZ) ou `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`. critical_field_occlusion_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- O que fazer quando um campo impresso crítico foi fisicamente tapado na captura (`CRITICAL_FIELD_OCCLUSION_DETECTED`) - um número de identificação, um nome, a data de nascimento ou a data de validade. Recusa por predefinição, tal como outros riscos de integridade do documento deste endpoint: tapar os números face aos quais um relatório é reconciliado é o aspeto típico de um documento rasurado. O valor lido para um campo tapado é descartado da extração de qualquer forma, pelo que o aviso `*_NOT_DETECTED` correspondente costuma acompanhá-lo. O valor `REVIEW` não é suportado neste endpoint e devolve `400`. document_or_personal_number_format_mismatch_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- O que fazer quando um número não corresponder ao formato que a sua autoridade emissora utiliza para esse tipo de documento (`DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`). Predefinição `NO_ACTION`, que comunica o aviso sem alterar o estado. O valor `REVIEW` não é suportado neste endpoint e devolve `400`. preferred_characters: type: string enum: - latin - non_latin default: latin description: >- Sistema de escrita preferencial para os campos de nome/morada em documentos que imprimem texto latino e não latino (árabe, cirílico, CJK, …). `latin` devolve valores transliterados/latinos; `non_latin` prefere o sistema de escrita nativo. save_api_request: type: boolean default: true description: >- Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido, anunciada através de um webhook `status.updated` e com imagens de documentos devolvidas como URLs de multimédia. Quando for `false`, nada é armazenado, `request_id` é um UUID transitório e as imagens são devolvidas em linha como strings JPEG em base64. example: true vendor_data: type: string description: >- String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde. example: user-123 metadata: type: object additionalProperties: true description: >- Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={"flow":"onboarding"}`) — é convertido num objeto. example: flow: onboarding example: front_image: (binary JPEG/PNG/PDF of the document front) back_image: (binary JPEG/PNG/PDF of the document back) perform_document_liveness: true save_api_request: true vendor_data: user-123 metadata: flow: onboarding responses: '200': description: >- Documento processado. `id_verification.status` é `Approved`, `Declined` ou `In Review`; cada problema detetado é discriminado em `id_verification.warnings`. `In Review` é devolvido quando uma verificação de prova de vida no documento solicitada não produziu nenhum resultado utilizável (`DOCUMENT_LIVENESS_NOT_COMPUTED`). Um documento com problemas continua a devolver `200` com `status: "Declined"` — inspecione o corpo, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id da sessão persistida e os campos de imagem são URLs de multimédia de curta duração; com `save_api_request=false`, são strings JPEG base64 inline. content: application/json: examples: Approved: summary: >- Cartão de cidadão/identidade frente e verso lido com sucesso (guardado — imagens como URLs de multimédia) value: request_id: 11d219ed-d59c-4b1d-8d65-9b933f12d5b8 id_verification: status: Approved document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: CBX164224 personal_number: 20446581H portrait_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=... front_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=... back_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=... front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 78 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: >- Carregamento apenas da frente de um documento de identificação expirado 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 resultar numa recusa e a verificação de prova de vida do documento solicitada tiver produzido um resultado utilizável; `In Review` quando essa verificação solicitada não tiver produzido nenhum resultado utilizável (`DOCUMENT_LIVENESS_NOT_COMPUTED`); `Declined` quando um aviso resultar numa recusa — a lista `warnings` explica o motivo. document_type: type: string nullable: true description: >- Nome de apresentação do tipo de documento detetado: `Identity Card`, `Passport`, `Driver's License`, `Residence Permit`, `Health Insurance Card` ou `Tax Card`. `null` quando o documento não pôde ser classificado. example: Identity Card document_subtype: type: string nullable: true description: >- Subtipo mais detalhado quando disponível (ex.: `ID_CARD_GENERIC`, `EPASSPORT`). example: ID_CARD_GENERIC document_number: type: string nullable: true example: CBX164224 personal_number: type: string nullable: true description: >- Número pessoal/nacional secundário impresso em alguns documentos. example: 20446581H portrait_image: type: string nullable: true description: >- Foto de retrato recortada do documento. Um URL de multimédia de curta duração (`https:///ocr/...`) quando `save_api_request=true` (predefinição); uma string JPEG em base64 inline quando `save_api_request=false`. `null` se nenhum retrato tiver sido detetado. front_image: type: string nullable: true description: >- Recorte alinhado da frente do documento. URL de multimédia quando guardado, JPEG inline em base64 caso contrário. back_image: type: string nullable: true description: >- Recorte alinhado do verso do documento. `null` quando não foi carregada nenhuma `back_image`. front_image_camera_front: type: string nullable: true description: >- Sempre `null` neste endpoint (preenchido apenas em sessões de verificação com captura por câmara). back_image_camera_front: type: string nullable: true description: Sempre `null` neste endpoint. front_image_camera_front_face_match_score: type: number nullable: true description: Sempre `null` neste endpoint. back_image_camera_front_face_match_score: type: number nullable: true description: Sempre `null` neste endpoint. front_image_quality_score: type: object nullable: true description: >- Diagnósticos de qualidade de captura para a imagem carregada (`null` quando o lado não foi fornecido ou a pontuação falhou). Todas as pontuações são de 0 a 100. properties: focus_score: type: number format: float description: >- Nitidez do recorte do documento (quanto maior, mais nítido). brightness_score: type: number format: float description: Qualidade da exposição (quanto maior, melhor). brightness_issue: type: string nullable: true description: >- `ok` quando a exposição está adequada; caso contrário, o problema detetado (por exemplo, demasiado escuro / demasiado claro). is_document_fully_visible: type: boolean nullable: true description: >- Se os quatro cantos do documento estão dentro do enquadramento. resolution_score: type: number format: float description: Resolução efetiva da área do documento. overall_score: type: number format: float description: Pontuação de qualidade agregada. back_image_quality_score: type: object nullable: true description: >- Diagnósticos de qualidade de captura para a imagem carregada (`null` quando o lado não foi fornecido ou a pontuação falhou). Todas as pontuações são de 0 a 100. properties: focus_score: type: number format: float description: >- Nitidez do recorte do documento (quanto maior, mais nítido). brightness_score: type: number format: float description: Qualidade da exposição (quanto maior, melhor). brightness_issue: type: string nullable: true description: >- `ok` quando a exposição está adequada; caso contrário, o problema detetado (por exemplo, demasiado escuro / demasiado claro). is_document_fully_visible: type: boolean nullable: true description: >- Se os quatro cantos do documento estão dentro do enquadramento. resolution_score: type: number format: float description: Resolução efetiva da área do documento. overall_score: type: number format: float description: Pontuação de qualidade agregada. date_of_birth: type: string format: date nullable: true example: '1980-01-13' age: type: integer nullable: true description: >- Idade do titular em anos, calculada a partir de `date_of_birth`. example: 46 expiration_date: type: string format: date nullable: true example: '2032-03-31' date_of_issue: type: string format: date nullable: true example: '2022-03-31' issuing_state: type: string nullable: true description: País emissor (ISO 3166-1 alfa-3). example: ESP issuing_state_name: type: string nullable: true example: Spain first_name: type: string nullable: true example: Julio Francisco last_name: type: string nullable: true example: Fores Sena full_name: type: string nullable: true example: Julio Francisco Fores Sena gender: type: string nullable: true description: '`M`, `F`, ou `null` quando não impresso/detetado.' example: M address: type: string nullable: true description: Morada exatamente como impressa no documento. formatted_address: type: string nullable: true description: Versão geocodificada e normalizada de `address`. place_of_birth: type: string nullable: true example: Valencia, Valencia marital_status: type: string nullable: true description: >- `UNKNOWN`, a menos que o documento tenha o estado civil impresso. example: UNKNOWN nationality: type: string nullable: true description: Nacionalidade do titular (ISO 3166-1 alfa-3). example: ESP extra_fields: type: object nullable: true additionalProperties: true description: >- Dados adicionais específicos do documento que não têm uma coluna dedicada (por exemplo, `first_surname`/`second_surname` em documentos de identificação espanhóis, categorias de carta de condução em cartas de condução). mrz: type: object description: >- Zona de leitura ótica analisada. Um **objeto vazio** (`{}`) quando o documento não tem MRZ ou ela não pôde ser lida — consulte também a lista `warnings` nesse caso. As datas no interior da MRZ utilizam o formato em bruto `YYMMDD`. properties: surname: type: string example: FORES SENA name: type: string example: JULIO FRANCISCO country: type: string description: País emissor (ISO 3166-1 alfa-3). example: ESP nationality: type: string description: Nacionalidade do titular (ISO 3166-1 alfa-3). example: ESP birth_date: type: string description: Data de nascimento em bruto da MRZ (`YYMMDD`). example: '800113' expiry_date: type: string description: Data de validade em bruto da MRZ (`YYMMDD`). example: '320331' sex: type: string example: M document_type: type: string description: >- Código do tipo de documento do MRZ (por exemplo `ID`, `P`). example: ID document_number: type: string example: CBX164224 optional_data: type: string nullable: true example: 20446581H optional_data_2: type: string nullable: true example: '' birth_date_hash: type: string description: >- Dígito de controlo do MRZ para a data de nascimento. example: '9' expiry_date_hash: type: string description: Dígito de controlo do MRZ para a data de validade. example: '8' document_number_hash: type: string description: >- Dígito de controlo do MRZ para o número do documento. example: '3' final_hash: type: string description: Dígito de controlo MRZ composto. example: '3' personal_number: type: string nullable: true example: 20446581H warnings: type: array items: type: string description: Avisos não fatais de análise do MRZ. errors: type: array items: type: string description: >- Erros de dígito de controlo/análise do MRZ. Os erros que não estejam vazios surgem como um aviso `MRZ_VALIDATION_FAILED`. mrz_type: type: string description: >- Esquema do MRZ: `TD1` (cartões de cidadão/identidade, 3 linhas), `TD2` ou `TD3` (passaportes, 2 linhas). example: TD1 mrz_string: type: string description: >- Texto em bruto da MRZ conforme lido, linhas separadas por `\n`. mrz_key: type: string description: >- Chave composta (número do documento + dígitos de controlo) utilizada para verificações cruzadas. parsed_address: type: object nullable: true description: >- Detalhes estruturados e geocodificados de `address`. `null` quando o documento não tem morada ou esta não pôde ser analisada. properties: street_1: type: string nullable: true example: Avenida el Cardonal 52 street_2: type: string nullable: true example: b city: type: string nullable: true example: La Laguna region: type: string nullable: true example: Canarias country: type: string nullable: true description: Código de país ISO 3166-1 alpha-2. example: ES postal_code: type: string nullable: true example: '38108' address_type: type: string nullable: true example: Avenida formatted_address: type: string nullable: true description: >- Cadeia de caracteres de morada geocodificada canónica. example: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: type: object additionalProperties: true description: >- Payload de geocodificação em bruto (`address_components`, `geometry.location`, `place_id`, …) para consumidores avançados. document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: Coordenadas geocodificadas da morada do documento. label: type: string nullable: true description: De que campo do documento a morada foi lida. example: Spain Identity Card Address is_verified: type: boolean description: Se a geocodificação confirmou que a morada existe. category: type: string nullable: true description: >- Categoria de morada (por exemplo, `Residential`, `Commercial`). example: Residential warnings: type: array description: >- Vazio numa aprovação limpa. Cada entrada explica um risco detetado; entradas com `log_type: "error"` definem `status` como `Declined`, e `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) define-o como `In Review`. items: type: object properties: risk: type: string description: >- Código de risco legível por máquina. Riscos de recusa obrigatória: `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT` (apenas 400, nunca um aviso), `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`. Determinados pelas opções do pedido: `MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED` (`invalid_mrz_action`), `DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` (`inconsistent_data_action`), `EXPIRATION_DATE_NOT_DETECTED` (`expiration_date_not_detected_action`). Outros riscos (p. ex. `POSSIBLE_DUPLICATED_USER`) são informativos. `DOCUMENT_LIVENESS_NOT_COMPUTED` é acionado quando `perform_document_liveness=true`, mas a verificação de falsificação não devolveu uma pontuação utilizável; define `status` para `In Review`. `COULD_NOT_DETECT_DOCUMENT_TYPE` também é devolvido quando a frente do documento não coincide com um modelo de documento oficial conhecido com elevada confiança, por exemplo, um documento editado ou gerado por computador, ou um modelo que ainda não é suportado. example: DOCUMENT_EXPIRED feature: type: string enum: - ID_VERIFICATION description: >- Funcionalidade que gerou o aviso. Sempre `ID_VERIFICATION` neste endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Contexto adicional para alguns riscos (por exemplo, `POSSIBLE_DUPLICATED_USER` inclui `duplicated_session_id`); `null` para a maioria. log_type: type: string enum: - error - warning - information description: >- Gravidade. Os avisos `error` alteram o `status` para `Declined`; `warning` (apenas `DOCUMENT_LIVENESS_NOT_COMPUTED`, quando a verificação de falsificação solicitada não produziu nenhuma pontuação utilizável) altera o `status` para `In Review`; as entradas `information` são informativas e nunca alteram o estado. short_description: type: string description: >- Resumo de uma linha legível por humanos sobre o risco. long_description: type: string description: Explicação legível do risco. barcodes: type: array description: >- Códigos de barras descodificados do documento (PDF417, QR, …). Vazio quando o documento não tem nenhum ou nenhum pôde ser lido. items: type: object properties: type: type: string description: >- Tipo de código de barras (por exemplo, `PDF417`, `QR_CODE`, `UNKNOWN`). position: type: object nullable: true additionalProperties: true description: >- Localização do código de barras na imagem, quando disponível. data: type: string description: Payload descodificado. data_raw: type: string description: >- Payload em bruto (não descodificado), quando diferente. side: type: string nullable: true description: '`front` ou `back`.' vendor_data: type: string nullable: true description: Eco do `vendor_data` que enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que enviou, ou `null`. created_at: type: string format: date-time description: >- Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada. '400': description: >- Erro de validação ou de processamento. Problemas ao nível do campo devolvem o envelope padrão do DRF (um array de mensagens por campo afetado). Problemas com PDF encriptado devolvem `{"detail": ...}`. Uma imagem de documento na qual nenhum documento possa ser reconhecido devolve `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`. Os carregamentos de PDF também podem falhar com "The submitted PDF file is corrupted or invalid." ou um erro de ausência de páginas. content: application/json: examples: Missing front image: summary: '`front_image` não incluído nos dados do formulário' value: front_image: - No file was submitted. Unsupported file extension: summary: Extensão de ficheiro fora de tiff/jpg/jpeg/png/webp/pdf value: front_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf. File too large: summary: O carregamento excede o limite de 10 MB value: front_image: - File size should not exceed 10 MB Invalid option value: summary: As opções apenas aceitam DECLINE ou NO_ACTION value: invalid_mrz_action: - '"REVIEW" is not a valid choice.' Encrypted PDF: summary: PDF carregado sem a palavra-passe obrigatória value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: >- `front_image_password` / `back_image_password` não desencripta o PDF value: detail: >- The PDF password is incorrect. Please provide the correct password. Document not recognized: summary: >- Nenhum documento de identificação pôde ser detetado na imagem value: error: COULD_NOT_RECOGNIZE_DOCUMENT PDF conversion failure: summary: O PDF carregado não pôde ser convertido numa imagem value: error: Failed to convert front image PDF. '403': description: >- Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{"error": ...}` antes de qualquer processamento de imagens ocorrer. content: application/json: examples: Missing or invalid API key: summary: Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre a chamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 pedidos de escrita no minuto atual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/id-verification/' \ -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: responses: DocumentProcessingBusy: description: >- Estão a ser processados demasiados documentos neste momento, pelo que este carregamento não foi processado: nada foi armazenado e nenhuma tentativa foi utilizada. Envie o mesmo ficheiro novamente após o número de segundos em `Retry-After`. Ramifique com base no `code`, não no texto da mensagem. headers: Retry-After: description: Segundos a aguardar antes de enviar o mesmo pedido novamente. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy 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.