API de comprovant de domicili: verificació POA i OCR

cURL

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

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)

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);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{
	Document:            didit.FileFromPath("document.pdf"),
	ExpectedAddress:     didit.String("Av. Monseñor Tavella 1291, Salta, Argentina"),
	ExpectedCountry:     didit.String("ARG"),
	ExpectedFirstName:   didit.String("Sophia"),
	ExpectedLastName:    didit.String("Martinez"),
	POALanguagesAllowed: didit.String("en,es"),
	SaveAPIRequest:      didit.Bool(true),
	VendorData:          didit.String("user-123"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

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);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->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());

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

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));

{
  "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"
}

POST

poa

cURL

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

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)

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);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{
	Document:            didit.FileFromPath("document.pdf"),
	ExpectedAddress:     didit.String("Av. Monseñor Tavella 1291, Salta, Argentina"),
	ExpectedCountry:     didit.String("ARG"),
	ExpectedFirstName:   didit.String("Sophia"),
	ExpectedLastName:    didit.String("Martinez"),
	POALanguagesAllowed: didit.String("en,es"),
	SaveAPIRequest:      didit.Bool(true),
	VendorData:          didit.String("user-123"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

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);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->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());

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

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));

{
  "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"
}

Autoritzacions

x-api-key

string

header

requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

multipart/form-data

document

file

requerit

El document de comprovant de domicili. Extensions permeses: tiff, jpg, jpeg, png, pdf, webp. Mida màxima de càrrega: 15 MB (els fitxers més grans es rebutgen amb 400). S'admeten PDF multipàgina (espera una latència més alta); els PDF xifrats requereixen document_password. Les imatges es comprimeixen automàticament abans de processar-les.

document_password

string

write-only

Contrasenya per desxifrar document quan és un PDF xifrat. Enviar un PDF xifrat sense contrasenya (o amb una d'incorrecta) retorna 400.

expected_address

string

Adreça a verificar en comparació amb el document. Es geocodifica i es compara amb l'adreça extreta; una discrepància (o una adreça esperada que no es pot geocodificar/verificar) afegeix ADDRESS_MISMATCH_WITH_PROVIDED, regit per poa_address_mismatch_action. La forma geocodificada es retorna a expected_details_formatted_address / expected_details_parsed_address.

Exemple:

"Av. Monseñor Tavella 1291, Salta, Argentina"

expected_country

string

País per verificar respecte al document (codi ISO 3166-1, p. ex. ARG o AR). Una discrepància amb el país del document afegeix POA_COUNTRY_MISMATCH_WITH_PROVIDED, regit per poa_address_mismatch_action.

Exemple:

"ARG"

expected_first_name

string

Nom de pila a verificar respecte a name_on_document (coincidència difusa, compatible amb transliteració). Una puntuació inferior al llindar de coincidència afegeix NAME_MISMATCH_WITH_PROVIDED, regit per poa_address_mismatch_action.

Exemple:

"Sophia"

expected_last_name

string

Cognom a verificar contra name_on_document, combinat amb expected_first_name per a la puntuació de coincidència.

Exemple:

"Martinez"

poa_languages_allowed

string

Llista separada per comes dels idiomes de documents acceptats com a codis ISO 639-1 (p. ex. en,es,fr). Quan s'omet o es deixa en blanc, s'accepten tots 51 idiomes admesos. Un document en un idioma que no sigui a la llista afegeix UNSUPPORTED_DOCUMENT_LANGUAGE (regit per poa_unsupported_language_action); un codi desconegut a la llista retorna 400 amb el conjunt complet de codis admesos.

Exemple:

"en,es"

poa_document_age_months

string

Parells key:value separats per comes que estableixen l'antiguitat màxima del document en mesos per tipus de document — claus: utility_bill, bank_statement, government_issued_document, other_poa_document; valors: 1–120, o -1 per a il·limitat (sense comprovació d'antiguitat). Valors per defecte si s'omet: utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12. Un document més antic que el seu límit es rebutja amb POA_DOCUMENT_EXPIRED. Atenció: quan proporcionis aquest camp, llista tots els tipus que acceptes — els tipus omesos es tracten com a no acceptats (informatiu POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION) i s'omet la seva comprovació d'antiguitat.

Exemple:

"utility_bill:3,bank_statement:6"

poa_name_mismatch_action

enum<string>

predeterminat:DECLINE

S'accepta però actualment no s'aplica: les advertències de discordança de nom (NAME_MISMATCH_WITH_PROVIDED) segueixen poa_address_mismatch_action. Defineix poa_address_mismatch_action per controlar el comportament de discordança tant de nom com d'adreça.

Opcions disponibles:

DECLINE,

NO_ACTION

poa_document_issues_action

enum<string>

predeterminat:DECLINE

Què fer davant de problemes d'integritat del fitxer — a la pràctica, aquest endpoint només produeix DOCUMENT_METADATA_MISMATCH.

Opcions disponibles:

DECLINE,

NO_ACTION

poa_document_authenticity_action

enum<string>

predeterminat:DECLINE

Què fer quan se sospita de manipulació del document (SUSPECTED_DOCUMENT_MANIPULATION) — p. ex., el PDF s'ha modificat després de la signatura digital, s'ha processat amb un editor de PDF conegut, mostra manipulació de text superposat o té dates EXIF incoherents. També regeix POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT (un camp de text reescrit que el fitxer no pot demostrar si ha canviat o no): DECLINE també el rebutja, NO_ACTION el manté com a advertència.

Opcions disponibles:

DECLINE,

NO_ACTION

poa_unsupported_language_action

enum<string>

predeterminat:DECLINE

Què fer quan l'idioma del document està fora de poa_languages_allowed (UNSUPPORTED_DOCUMENT_LANGUAGE).

Opcions disponibles:

DECLINE,

NO_ACTION

poa_address_mismatch_action

enum<string>

predeterminat:DECLINE

Què fer quan les dades extretes no coincideixen amb els camps expected_*: ADDRESS_MISMATCH_WITH_PROVIDED, NAME_MISMATCH_WITH_PROVIDED i POA_COUNTRY_MISMATCH_WITH_PROVIDED segueixen tots aquesta acció.

Opcions disponibles:

DECLINE,

NO_ACTION

poa_issuer_not_identified_action

enum<string>

predeterminat:DECLINE

Què fer quan no es pot identificar cap empresa/organització emissora al document (ISSUER_NOT_IDENTIFIED).

Opcions disponibles:

DECLINE,

NO_ACTION

save_api_request

boolean

predeterminat:true

Quan és true (per defecte), manté la crida com una sessió de tipus API — visible a la Business Console, recuperable mitjançant GET /v3/session/{sessionId}/decision/ utilitzant el request_id retornat, anunciada a través d'un webhook status.updated i amb el document carregat emmagatzemat. Quan és false, no s'emmagatzema res i request_id és un UUID transitori només per a la correlació de la resposta.

Exemple:

true

vendor_data

string

Cadena opaca opcional (el teu ID d'usuari intern, correu electrònic, UUID…) desada a la sessió persistent i retornada a la resposta. Utilitza-la per correlacionar crides a l'API amb els teus propis registres i per filtrar sessions més endavant.

Exemple:

"user-123"

metadata

object

Objecte JSON opcional emmagatzemat amb la sessió (quan save_api_request=true) i retornat a la resposta. En sol·licituds multipart, envia'l com a camp de cadena codificat en JSON (p. ex., metadata={"flow":"onboarding"}); s'analitza com un objecte.

Exemple:

{ "flow": "onboarding" }

Resposta

Document processat. poa.status és Approved o Declined; cada problema detectat es detalla a poa.warnings. Un document caducat, no coincident o sospitós continua retornant 200 amb status: "Declined"; inspecciona el cos, no només el codi HTTP. Quan save_api_request=true, request_id és l'id de sessió persistit.

request_id

string<uuid>

ID de sessió persistida quan save_api_request=true (utilitzable amb GET /v3/session/{sessionId}/decision/); en cas contrari, un UUID de correlació transitori.

poa

object

Show child attributes

vendor_data

string | null

Ressò de les vendor_data que has enviat, o null.

metadata

object | null

Ressò de l'objecte metadata que has enviat, o null.

created_at

string<date-time>

Marca de temps ISO 8601 (UTC) de quan s'ha generat la resposta.

Darrera modificació el 7 de novembre del 2026