> ## 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 Comprovativo de Morada: Verificação POA e OCR > Didit verifica faturas, extratos e contratos via POST /v3/poa/. OCR de moradas, autenticidade, preços por utilização, sem contratos. ## OpenAPI ````yaml pt/openapi-25.json POST /v3/poa/ 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/poa/: post: tags: - Standalone APIs summary: Comprovativo de morada (OCR do documento + verificações de morada) description: >- Extraia e valide um documento de Comprovativo de morada — faturas de serviços públicos, extratos bancários e documentos emitidos pelo governo — numa única chamada. Devolve o emissor, as datas de emissão/validade, o nome do titular, a morada bruta e processada/geocodificada, um `status` `Approved`/`Declined`, e uma lista de `warnings` que explica cada problema encontrado. **Latência.** A extração é baseada em LLM: as chamadas típicas demoram **5–15 segundos**, e PDFs de várias páginas até **~30 segundos**. Configure um tempo limite do cliente de **pelo menos 45 segundos** e não tente novamente antes de a chamada ser concluída. **Como funciona.** O documento (imagem ou PDF, até 15 MB; PDFs encriptados requerem `document_password`) é classificado num tipo e subtipo de documento (por exemplo, `UTILITY_BILL` / `WATER_BILL`), e o emissor, as datas, o nome do titular e a morada são extraídos através de extração baseada em LLM. A morada é processada e geocodificada em `poa_parsed_address`. A análise forense de PDF/EXIF verifica adulterações — modificação após assinatura digital, editores de PDF conhecidos, manipulação de texto sobreposto, reexportações suspeitas — apresentando `SUSPECTED_DOCUMENT_MANIPULATION` ou `DOCUMENT_METADATA_MISMATCH`. Um campo de texto que foi apagado e reescrito noutro tipo de letra, em que o próprio ficheiro não permite determinar se o seu conteúdo foi alterado, apresenta `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. A antiguidade do documento é validada em relação a `poa_document_age_months`, e o idioma em relação a `poa_languages_allowed`. Se transmitir `expected_address`, `expected_country` ou `expected_first_name`/`expected_last_name`, os valores extraídos são cruzados e as discrepâncias são sinalizadas. **Lógica de decisão.** O `status` é `Approved`, a menos que pelo menos um aviso resulte numa recusa. Falhas graves resultam sempre em recusa: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, além de `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` (não configuráveis neste endpoint). Cinco grupos de risco são configuráveis por pedido através das opções `poa_*_action` (`DECLINE` ou `NO_ACTION`, todas com predefinição `DECLINE`). `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` e `UNPARSABLE_OR_INVALID_ADDRESS` são informativos neste endpoint e nunca recusam. Um documento que não possa de todo ser processado devolve `400`; um documento legível mas problemático devolve `200` com `status: "Declined"` — inspecione sempre `poa.status` e `poa.warnings`, e não apenas o código HTTP. **Faturação.** Cada resposta `200` consome um crédito da API de Comprovativo de morada (pago a partir do crédito do seu plano ou do saldo de carregamento). Quando o saldo da organização não consegue cobrir a chamada, o endpoint devolve `403` com o erro de créditos insuficientes antes de qualquer processamento do documento. **Persistência da sessão (`save_api_request`, predefinição `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API: aparece na Business Console, o documento carregado é armazenado, o `request_id` devolvido é um ID de sessão real que pode passar para `GET /v3/session/{sessionId}/decision/` (a decisão expõe adicionalmente `document_file` e a análise forense em `document_metadata`, que esta resposta omite), e é emitido um webhook `status.updated`. Quando `false`, nada é armazenado e `request_id` é um UUID de correlação único que não pode ser consultado posteriormente. **Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada com formato incorreto continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved` (uma fatura de eletricidade fictícia da "Sandbox Power Co."), nenhuma sessão é persistida e não são consumidos créditos. **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 partilhado de escrita de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-lo devolve `429`. Nota: `FUTURE_ISSUE_DATE` e `POOR_DOCUMENT_QUALITY` existem em sessões de fluxo, mas nunca são gerados por este endpoint autónomo — um documento com data futura não é recusado automaticamente aqui. operationId: post_v3poa parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - document properties: document: type: string format: binary description: >- O documento de Comprovativo de morada. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. Tamanho máximo de carregamento: **15 MB** (ficheiros maiores são rejeitados com `400`). São suportados PDFs de várias páginas (espere uma latência mais elevada); PDFs encriptados exigem `document_password`. As imagens são comprimidas automaticamente antes do processamento. document_password: type: string description: >- Palavra-passe para desencriptar `document` quando for um PDF encriptado. O envio de um PDF encriptado sem palavra-passe (ou com uma incorreta) devolve `400`. writeOnly: true expected_address: type: string description: >- Morada a verificar contra o documento. É geocodificada e comparada com a morada extraída; uma divergência (ou uma morada esperada que não possa ser geocodificada/verificada) adiciona `ADDRESS_MISMATCH_WITH_PROVIDED`, regido por `poa_address_mismatch_action`. A forma geocodificada é devolvida em `expected_details_formatted_address` / `expected_details_parsed_address`. example: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: type: string description: >- País a verificar em relação ao documento (código ISO 3166-1, por ex., `ARG` ou `AR`). Uma discrepância com o país do documento adiciona `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, o que é regido por `poa_address_mismatch_action`. example: ARG expected_first_name: type: string description: >- Primeiro nome a verificar contra `name_on_document` (correspondência difusa, sensível a transliteração). Uma pontuação abaixo do limiar de correspondência adiciona `NAME_MISMATCH_WITH_PROVIDED`, regido por `poa_address_mismatch_action`. example: Sophia expected_last_name: type: string description: >- Apelido a verificar face a `name_on_document`, combinado com `expected_first_name` para a pontuação de correspondência. example: Martinez poa_languages_allowed: type: string description: >- Lista separada por vírgulas de idiomas de documentos aceites como códigos ISO 639-1 (por exemplo, `en,es,fr`). Quando omitida ou em branco, são aceites **todos os 51 idiomas suportados**. Um documento num idioma fora da lista adiciona `UNSUPPORTED_DOCUMENT_LANGUAGE` (regulado por `poa_unsupported_language_action`); um código desconhecido na lista devolve `400` com o conjunto completo de códigos suportados. example: en,es poa_document_age_months: type: string description: >- Pares `key:value` separados por vírgulas que definem a idade máxima do documento em meses por tipo de documento — chaves: `utility_bill`, `bank_statement`, `government_issued_document`, `other_poa_document`; valores: `1`–`120`, ou `-1` para ilimitado (sem verificação da idade). Valores predefinidos se omitido: `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. Um documento mais antigo do que o seu limite é recusado com `POA_DOCUMENT_EXPIRED`. **Atenção:** ao fornecer este campo, liste *todos* os tipos que aceita — os tipos omitidos são tratados como não aceites (informativo `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`) e a respetiva verificação da idade é ignorada. example: utility_bill:3,bank_statement:6 poa_name_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Aceite, mas **atualmente não aplicado** — os avisos de não correspondência de nome (`NAME_MISMATCH_WITH_PROVIDED`) seguem `poa_address_mismatch_action`. Defina `poa_address_mismatch_action` para controlar o comportamento de não correspondência tanto de nome como de morada. poa_document_issues_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- O que fazer perante problemas de integridade do ficheiro — na prática, apenas `DOCUMENT_METADATA_MISMATCH` é gerado por este endpoint. poa_document_authenticity_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- O que fazer quando houver suspeita de manipulação do documento (`SUSPECTED_DOCUMENT_MANIPULATION`) — por ex., o PDF foi modificado após assinatura digital, processado por um editor de PDF conhecido, apresenta manipulação de texto sobreposto ou tem datas EXIF inconsistentes. Também rege `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (um campo de texto redigitado que o ficheiro não consegue comprovar se foi alterado ou não): `DECLINE` também o recusa, `NO_ACTION` mantém-no como aviso. poa_unsupported_language_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- O que fazer quando o idioma do documento está fora de `poa_languages_allowed` (`UNSUPPORTED_DOCUMENT_LANGUAGE`). poa_address_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- O que fazer quando os detalhes extraídos não coincidem com os campos `expected_*`: `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED` e `POA_COUNTRY_MISMATCH_WITH_PROVIDED` seguem todos esta ação. poa_issuer_not_identified_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- O que fazer quando não for possível identificar nenhuma empresa/organização emissora no documento (`ISSUER_NOT_IDENTIFIED`). save_api_request: type: boolean default: true description: >- Quando for `true` (predefinição), persiste a chamada como uma sessão do tipo API — visível na Business Console, recuperável através de `GET /v3/session/{sessionId}/decision/` utilizando o `request_id` devolvido, anunciada através de um webhook `status.updated` e com o documento carregado armazenado. Quando for `false`, nada é armazenado e `request_id` é um UUID transitório apenas para correlação de respostas. example: true vendor_data: type: string description: >- String opaca opcional (o seu ID de utilizador interno, e-mail, UUID...) guardada na sessão persistida e devolvida na resposta. Utilize-a para correlacionar chamadas de API com os seus próprios registos e para filtrar sessões mais tarde. example: user-123 metadata: type: object additionalProperties: true description: >- Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido na resposta. Em pedidos multipart, envie-o como um campo de texto codificado em JSON (por exemplo, `metadata={"flow":"onboarding"}`) — é convertido num objeto. example: flow: onboarding example: document: (binary JPEG/PNG/PDF of the utility bill or bank statement) expected_address: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: ARG expected_first_name: Sophia expected_last_name: Martinez poa_languages_allowed: en,es save_api_request: true vendor_data: user-123 responses: '200': description: >- Documento processado. `poa.status` é `Approved` ou `Declined`; cada problema detetado é discriminado em `poa.warnings`. Um documento expirado, que não corresponde ou suspeito continua a devolver `200` com `status: "Declined"` — inspecione o corpo, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id da sessão persistida. content: application/json: examples: Approved: summary: >- Fatura de serviços públicos lida sem problemas, sem verificações dos detalhes esperados value: request_id: 4b523a8d-ed32-45e4-8aa8-a89eda459d88 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2026-04-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA detected_codes: - type: QR_CODE page_number: 1 position: - - 820 - 1120 - - 1002 - 1120 - - 1002 - 1302 - - 820 - 1302 x: 820 'y': 1120 width: 182 height: 182 page_width: 1190 page_height: 1684 raw_payload: >- aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ== parsed_payload: https://aguasdelnorte.com/factura/998811 - type: CODE_128 page_number: 1 position: - - 112 - 1480 - - 560 - 1480 - - 560 - 1540 - - 112 - 1540 x: 112 'y': 1480 width: 448 height: 60 page_width: 1190 page_height: 1684 raw_payload: MDA5OTg4MTEwMDA0Mg== parsed_payload: '0099881100042' status: Approved warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:29:02.439655+00:00' Declined - document too old: summary: >- Data de emissão anterior ao limite permitido por `poa_document_age_months` value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: POA_DOCUMENT_EXPIRED feature: PROOF_OF_ADDRESS additional_data: expiration_reason: age_window max_age_months: 3 document_subtype: WATER_BILL document_type: UTILITY_BILL issue_date: '2021-02-10' log_type: error short_description: Document expired long_description: >- The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:23:02.165493+00:00' Declined - name mismatch: summary: >- `expected_first_name`/`expected_last_name` não correspondem a `name_on_document` value: request_id: 0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: NAME_MISMATCH_WITH_PROVIDED feature: PROOF_OF_ADDRESS additional_data: null log_type: error short_description: Name mismatch with provided information long_description: >- The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:21.330172+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório. poa: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` quando nenhum aviso resultar numa recusa; `Declined` caso contrário — a lista `warnings` explica o motivo. issuing_state: type: string nullable: true description: >- País onde o documento foi emitido, conforme extraído do documento — normalmente ISO 3166-1 alpha-3 (por ex., `ARG`). example: ARG document_type: type: string enum: - UTILITY_BILL - BANK_STATEMENT - GOVERNMENT_ISSUED_DOCUMENT - OTHER_POA_DOCUMENT - UNKNOWN description: >- Categoria de documento detetada. `UNKNOWN` significa que o documento não pôde ser classificado como um Comprovativo de morada aceitável e é automaticamente recusado com `INVALID_DOCUMENT_TYPE`. Nunca é nulo — falhas de classificação revertem para `UNKNOWN`. document_subtype: type: string description: >- Classificação mais detalhada dentro de `document_type` — ex.: `ELECTRICITY_BILL`, `WATER_BILL`, `GAS_BILL`, `INTERNET_BILL`, `PHONE_BILL` (faturas de serviços públicos); `ACCOUNT_STATEMENT`, `CREDIT_CARD_STATEMENT` (extratos bancários); `TAX_ASSESSMENT`, `RESIDENCY_CERTIFICATE` (documentos governamentais). `UNKNOWN` quando não foi possível determinar o subtipo. Nunca é nulo — falhas de classificação recaem para `UNKNOWN`. example: WATER_BILL document_language: type: string nullable: true description: Idioma do documento detetado (ISO 639-1). example: es issuer: type: string nullable: true description: >- Empresa ou organização que emitiu o documento. `null` adiciona `ISSUER_NOT_IDENTIFIED`. example: Aguas del Norte issue_date: type: string format: date nullable: true description: >- Data de emissão do documento (`YYYY-MM-DD`). `null` quando não foi possível extrair — o pedido é recusado com `UNABLE_TO_EXTRACT_ISSUE_DATE` neste endpoint. example: '2021-02-10' expiration_date: type: string format: date nullable: true description: >- Data de validade explícita impressa no documento, quando presente. Independente da verificação de idade `poa_document_age_months`. poa_address: type: string nullable: true description: >- Morada exatamente como impressa no documento. `null` recusa automaticamente com `MISSING_ADDRESS_INFORMATION`. poa_formatted_address: type: string nullable: true description: Versão geocodificada e normalizada de `poa_address`. example: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: type: object nullable: true description: >- Detalhes estruturados e geocodificados da morada do documento. `null` quando a morada não pôde ser analisada. properties: street_1: type: string nullable: true example: Avenida Monseñor Tavella 1291 street_2: type: string nullable: true city: type: string nullable: true example: Salta region: type: string nullable: true example: Salta country: type: string nullable: true description: Código de país ISO 3166-1 alpha-2. example: AR postal_code: type: string nullable: true example: A4400 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: Coordenadas geocodificadas da morada do documento. expected_details_address: type: string nullable: true description: Eco do `expected_address` que enviou, ou `null`. expected_details_formatted_address: type: string nullable: true description: >- Versão geocodificada e normalizada de `expected_address`; `null` quando não fornecida ou não passível de geocodificação. expected_details_parsed_address: type: object nullable: true additionalProperties: true description: >- Resultado completo de geocodificação para `expected_address` (rua/cidade/região/país/código postal mais a saída bruta do geocodificador e um indicador `is_verified`). `null` quando `expected_address` não foi fornecido. name_on_document: type: string nullable: true description: >- Nome do titular principal extraído do documento; comparado com `expected_first_name`/`expected_last_name` quando fornecido. `null` indica uma recusa com `POA_NAME_NOT_DETECTED` neste endpoint. example: OESTE EMBOTELLADORA S.A. extra_fields: type: object description: >- Dados adicionais específicos do documento. Os campos bancários são preenchidos para extratos bancários quando impressos no documento; `null` caso contrário. properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true description: >- Número de telefone de contacto impresso no documento. additional_names: type: array items: type: string description: >- Outros nomes de titulares encontrados no documento (por exemplo, cotitulares de conta, nomes de conta anteriores). warnings: type: array description: >- Vazio numa aprovação limpa. Cada entrada explica um risco detetado; entradas com `log_type: "error"` definem `status` como `Declined`. items: type: object properties: risk: type: string description: >- Código de risco legível por máquina. Recusa obrigatória: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, mais `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` (definidos para recusar neste endpoint). Determinados pelas opções do pedido: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED` (`poa_address_mismatch_action`), `POOR_DOCUMENT_QUALITY` (nunca gerado por este endpoint) / `DOCUMENT_METADATA_MISMATCH` (`poa_document_issues_action`), `SUSPECTED_DOCUMENT_MANIPULATION` e `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (`poa_document_authenticity_action`), `UNSUPPORTED_DOCUMENT_LANGUAGE` (`poa_unsupported_language_action`), `ISSUER_NOT_IDENTIFIED` (`poa_issuer_not_identified_action`). Informativos neste endpoint: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNPARSABLE_OR_INVALID_ADDRESS`. example: POA_DOCUMENT_EXPIRED feature: type: string enum: - PROOF_OF_ADDRESS description: >- Funcionalidade que gerou o aviso. Sempre `PROOF_OF_ADDRESS` neste endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Contexto adicional para alguns riscos — por exemplo, `POA_DOCUMENT_EXPIRED` inclui `expiration_reason` (`printed_expiration` ou `age_window`), `document_type`, `document_subtype` e `issue_date`, além de `expiration_date` no caminho `printed_expiration` ou `max_age_months` no caminho `age_window`; `SUSPECTED_DOCUMENT_MANIPULATION` inclui `reason` e `detection_method`; `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` inclui `reason`, `detection_method` (`unproven_text_replacement`), `replaced_text`, `manipulated_regions` e `manipulated_blocks`. `null` para a maioria dos riscos. log_type: type: string enum: - error - information description: >- Gravidade. Os avisos `error` alteram o `status` para `Declined`; as entradas `information` são informativas e nunca recusam por si sós. (`warning` não é produzido por este endpoint — as suas opções só aceitam `DECLINE` ou `NO_ACTION`.) short_description: type: string description: >- Resumo de uma linha legível por humanos sobre o risco. long_description: type: string description: Explicação legível do risco. detected_codes: type: array description: >- Códigos QR e códigos de barras detetados em todas as páginas processadas do documento. Vazio quando nenhum é encontrado. Um código QR localizado mas não descodificável tem `parsed_payload: null`. items: $ref: '#/components/schemas/DocumentAIDetectedCode' vendor_data: type: string nullable: true description: Eco do `vendor_data` que enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que enviou, ou `null`. created_at: type: string format: date-time description: >- Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada. '400': description: >- Erro de validação ou de processamento. Problemas ao nível do campo devolvem o envelope padrão do DRF (um array de mensagens por campo afetado). Problemas com PDF encriptado devolvem `{"detail": ...}`. Um documento que o pipeline de extração não consiga processar devolve `{"error": ["Error extracting POA information"]}`. content: application/json: examples: Missing document: summary: '`document` não incluído nos dados do formulário' value: document: - No file was submitted. Unsupported file extension: summary: Extensão de ficheiro fora de tiff/jpg/jpeg/png/pdf/webp value: document: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp. File too large: summary: O carregamento excede o limite de 15 MB value: document: - File size should not exceed 15 MB Encrypted PDF: summary: PDF carregado sem a palavra-passe obrigatória value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`document_password` não desencripta o PDF' value: detail: >- The PDF password is incorrect. Please provide the correct password. Invalid language code: summary: '`poa_languages_allowed` contém um código não suportado' value: poa_languages_allowed: - >- Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']. Invalid document age value: summary: >- valor de `poa_document_age_months` fora do intervalo 1–120 / -1 value: poa_document_age_months: - >- Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120. Extraction failure: summary: >- Não foi possível processar o documento através do pipeline de extração value: error: - Error extracting POA information '403': description: >- Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{"error": ...}` antes de qualquer processamento de documentos ocorrer. content: application/json: examples: Missing or invalid API key: summary: Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre a chamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 pedidos de escrita no minuto atual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/poa/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'document=@./utility-bill.pdf' \ -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \ -F 'expected_country=ARG' \ -F 'expected_first_name=Sophia' \ -F 'expected_last_name=Martinez' \ -F 'poa_languages_allowed=en,es' \ -F 'vendor_data=user-123' \ --max-time 45 - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.proof_of_address.verify( document=open("document.pdf", "rb"), expected_address="Av. Monseñor Tavella 1291, Salta, Argentina", expected_country="ARG", expected_first_name="Sophia", expected_last_name="Martinez", poa_languages_allowed="en,es", save_api_request=True, vendor_data="user-123", ) 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.proofOfAddress.verify({ document: await fileFromPath("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import me.didit.Didit; import me.didit.types.ProofOfAddressVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder() .document(Path.of("document.pdf")) .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina") .expectedCountry("ARG") .expectedFirstName("Sophia") .expectedLastName("Martinez") .poaLanguagesAllowed("en,es") .saveApiRequest(true) .vendorData("user-123") .build()); System.out.println(result); - lang: php label: PHP source: |- proofOfAddress->verify([ 'document' => File::fromPath('document.pdf'), 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina', 'expected_country' => 'ARG', 'expected_first_name' => 'Sophia', 'expected_last_name' => 'Martinez', 'poa_languages_allowed' => 'en,es', 'save_api_request' => true, 'vendor_data' => 'user-123', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.proof_of_address.verify( document: Pathname("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123" ) 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.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams { Document = FileUpload.FromPath("document.pdf"), ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina", ExpectedCountry = "ARG", ExpectedFirstName = "Sophia", ExpectedLastName = "Martinez", PoaLanguagesAllowed = "en,es", SaveApiRequest = true, VendorData = "user-123", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: >- Simbologia detetada, por exemplo `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` ou `PDF_417`. page_number: type: integer minimum: 1 description: Número de página de base 1. position: type: array nullable: true description: >- Polígono detetado em coordenadas de píxeis da página renderizada. `null` quando não está disponível nenhuma localização fiável. items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: >- Margem esquerda da caixa delimitadora em píxeis da página renderizada. 'y': type: integer nullable: true description: >- Limite superior da caixa delimitadora em píxeis da página renderizada. width: type: integer nullable: true description: Largura da caixa delimitadora em píxeis da página renderizada. height: type: integer nullable: true description: Altura da caixa delimitadora em píxeis da página renderizada. page_width: type: integer description: Largura da página renderizada em píxeis. page_height: type: integer description: Altura da página renderizada em píxeis. raw_payload: type: string description: >- Payload do descodificador em bruto como string base64 quando disponível; caso contrário, uma string vazia. parsed_payload: nullable: true description: >- String descodificada ou valor estruturado. `null` quando o código foi localizado mas não pôde ser descodificado. 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.