Saltar para o conteúdo principal
POST
curl
Didit’s Address Validation API confirma que uma morada postal existe e devolve-a normalizada, com as respetivas linhas de entrega, componentes e coordenadas. Use POST /v3/address-validation/ quando o seu backend tiver uma morada e precisar de saber se ela existe e em que forma normalizada. A Address Validation API confirma apenas a morada. Nunca associa a morada a uma pessoa: um resultado verified significa que o local existe, não que alguém lá viva.

Envie a morada

Envie-a numa única linha em address, ou como campos estruturados: address_line_1 e, quando os tiver, address_line_2, city, region e postal_code. Nunca envie as duas formas no mesmo pedido. country é sempre obrigatório, como código ISO 3166-1 alpha-2 ou alpha-3.

Interprete a resposta

  • address_validation.status é a resposta em que deve basear-se:
    • verified: a morada foi confirmada até ao edifício (ou ao apartamento ou à caixa postal).
    • partially_verified: foi confirmada apenas até à rua, ou até ao nível mais preciso que os dados de referência postais têm para esse local.
    • not_verified: só a região ou a cidade coincidiram, ou nada coincidiu.
    • unavailable: a validação não pôde ser executada. Tente novamente mais tarde.
  • address_validation.verification_level é o nível mais preciso que coincidiu: administrative_area, locality, thoroughfare, premise ou delivery_point.
  • address_validation.address e address_validation.formatted_address contêm a morada normalizada, escrita da forma como o país a escreve.
  • address_validation.latitude e address_validation.longitude situam a morada encontrada.
  • request_id identifica o pedido. Não é criada nenhuma sessão e o resultado é devolvido apenas nesta resposta, por isso guarde o que precisar.
O código HTTP é 200 para todos os pedidos concluídos, incluindo unavailable.

Address Validation dentro de um fluxo

A mesma verificação é um complemento dos passos do fluxo de Verificação de identidade e de Comprovativo de morada. Ative address_validation_enabled nas definições do passo, e a morada fornecida pela pessoa (impressa no documento de identidade ou no comprovativo de morada) é validada assim que o carregamento dela for lido. O resultado é o objeto address_validation da entrada desse passo na decisão da sessão (id_verifications[] ou poa_verifications[]). Uma morada partially_verified ou not_verified gera o aviso ADDRESS_NOT_VERIFIED, cuja ação é o address_not_verified_action do passo (NO_ACTION por predefinição, que apenas regista o aviso). Uma validação unavailable nunca gera esse aviso e nunca altera a verificação.

Comportamento no sandbox

As chaves de sandbox validam o pedido e devolvem sempre um resultado verified determinístico que repete a morada que enviou. Não consomem créditos.

Faturação

Cada chamada à API de Address Validation custa $0.10 por morada validada. Um resultado `unavailable` não é cobrado. Num fluxo, o complemento custa $0.10 por cada morada validada num passo.

Autorizações

x-api-key
string
header
obrigatório

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.

Corpo

application/json

Uma morada: numa única linha (address) ou como campos estruturados com pelo menos address_line_1, nunca ambos.

country
string
obrigatório

Código ISO 3166-1 alfa-2 ou alfa-3 do país da morada.

Maximum string length: 3
Exemplo:

"US"

address
string

A morada completa numa linha.

Maximum string length: 500
Exemplo:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

Rua e número.

Maximum string length: 255
Exemplo:

"1600 Amphitheatre Pkwy"

address_line_2
string

Apartamento, suite, piso ou edifício.

Maximum string length: 255
city
string

Cidade ou localidade.

Maximum string length: 128
Exemplo:

"Mountain View"

region
string

Estado, província ou região.

Maximum string length: 128
Exemplo:

"CA"

postal_code
string
Maximum string length: 32
Exemplo:

"94043"

Resposta

A validação foi concluída. Consulte address_validation.status; o HTTP é sempre 200 para um pedido concluído.

request_id
string<uuid>
obrigatório

Identificador deste pedido; refira-o ao suporte. Nenhuma sessão é criada.

address_validation
object
obrigatório

O resultado de uma Address Validation: se a morada existe e a sua forma normalizada. Confirma apenas a morada; nunca associa a morada a uma pessoa.

created_at
string<date-time>
obrigatório
Última modificação em 7 de novembro de 2026