API<REFERENCE<V1<<<<<<<<<<<<

Riferimento API

L'API IDBird è volutamente piccola: due endpoint, una forma di richiesta, una busta di errore. Questa pagina ne è la superficie completa. La specifica leggibile dalle macchine e il riferimento interattivo vivono su api.idbird.eu.

URL di base e autenticazione

Ogni richiesta porta una chiave API Bearer emessa dal team IDBird. Le chiavi sono archiviate solo come hash SHA-256 e verificate in tempo reale a ogni richiesta — la revoca ha effetto dalla chiamata successiva.

https://api.idbird.eu
Authorization: Bearer idb_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Endpoint

`POST`	`/v1/redact`	Oscura un documento e ricevi l'immagine ripulita più findings e warnings.
`POST`	`/v1/inspect`	Prova a vuoto: solo findings e warnings — non viene mai restituita un'immagine.
`GET`	`/up`	Controllo di stato, senza autenticazione.

Richiesta

Entrambi gli endpoint accettano la stessa richiesta multipart/form-data.

Campo	Obbligatorio	Descrizione
`document`	sì	Il file: JPEG, PNG, BMP o PDF (fino a 5 pagine per impostazione predefinita), max 10 MiB. Il tipo è rilevato dal contenuto — nome del file e header Content-Type sono ignorati.
`country_hint`	no	Codice ISO 3166-1 alpha-2 del paese emittente, senza distinzione di maiuscole (EL è accettato come alias di GR). Se omesso, modalità automatica — con l'indicazione il rilevamento è più preciso.
`photo_redaction`	no	redact (predefinito) rimuove la fototessera. keep la lascia visibile e aggiunge il warning photo_not_redacted. both restituisce due immagini: completamente oscurata e con foto visibile.

curl https://api.idbird.eu/v1/redact \
  -H "Authorization: Bearer idb_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -F document=@passport-scan.jpg \
  -F country_hint=NL

Risposte

Il campo image è sempre un PNG codificato in base64 e sempre la versione più oscurata della richiesta. findings contiene nomi di rilevatori e conteggi — mai valori. warnings e findings sono sempre presenti, vuoti quando è tutto pulito.

POST /v1/redact — una sola pagina

{
  "image": "iVBORw0KGgoAAAANSUhEUgAA…",
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_1": 1,
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_PASSPORT": 1,
    "OBJECT_TYPE/PERSON/FACE": 2,
    "OBJECT_TYPE/PERSON/SIGNATURE": 1
  }
}

POST /v1/redact — photo_redaction=both

{
  "image": "…fully redacted PNG…",
  "image_photo_visible": "…portrait intact, everything else redacted…",
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_BSN_NUMBER": 1
  }
}

POST /v1/redact — PDF multipagina (pages sostituisce image, numerazione da 1)

{
  "pages": [
    { "page": 1, "image": "iVBORw0KGgo…", "findings": { "OBJECT_TYPE/PERSON/FACE": 1 } },
    { "page": 2, "image": "iVBORw0KGgo…", "findings": { "MRZ_TD3_LINE_2": 1, "NETHERLANDS_BSN_NUMBER": 1 } }
  ],
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_BSN_NUMBER": 1,
    "OBJECT_TYPE/PERSON/FACE": 1
  }
}

POST /v1/inspect — solo findings, mai un'immagine

{
  "findings": {
    "NETHERLANDS_BSN_NUMBER": 1,
    "MRZ_TD3_LINE_2": 1
  },
  "warnings": ["no_country_hint"]
}

Codici di avviso

HTTP 200 significa elaborato, non protetto. I warnings arrivano in un ordine fisso e documentato; controllali prima di archiviare. Gli otto codici possibili:

Errori

Tutti gli errori usano un'unica busta con un codice stabile e un messaggio statico in inglese — sicuro per il matching, privo di contenuti del documento:

{
  "error": {
    "code": "country_not_supported",
    "message": "The issuing country \"US\" is not supported by this service."
  }
}

HTTP	code	message
`401`	`invalid_api_key`	The bearer API key is missing, unknown, or revoked.
`404`	`not_found`	Not found.
`405`	`method_not_allowed`	Method not allowed.
`413`	`payload_too_large`	The document exceeds the 10 MiB limit.
`415`	`unsupported_media_type`	The document must be a JPEG, PNG, BMP or PDF; the type is detected from file content.
`422`	`country_hint_invalid`	The country_hint must be a two-letter ISO 3166-1 alpha-2 code.
`422`	`country_not_supported`	The issuing country "US" is not supported by this service.
`422`	`file_required`	The document file is required.
`422`	`photo_redaction_invalid`	The photo_redaction field must be one of: redact, keep, both.
`422`	`too_many_pages`	The PDF exceeds the 5-page limit; split it and submit the pages separately.
`422`	`pdf_encrypted`	Encrypted PDFs are not supported.
`422`	`unreadable_image`	The document could not be decoded as an image.
`422`	`image_normalization_failed`	The image could not be reduced to the redaction backend request budget without degrading below the quality floor.
`429`	`rate_limited`	Too many requests; retry later.
`429`	`daily_quota_exceeded`	The daily allowance of 50 API call(s) for this key is exhausted for today (UTC).
`500`	`internal_error`	Internal error.
`502`	`dlp_unavailable`	The redaction backend is unavailable; no image was produced.

Limiti e fatturazione

Rate limit: 30 richieste al minuto per chiave; 429 con header Retry-After in caso di superamento.
Quota giornaliera: 50 chiamate per chiave al giorno per impostazione predefinita (UTC); aumentata per chiave dal team IDBird con effetto immediato.
Una richiesta elaborata per intero è una chiamata fatturabile — PDF multipagina incluso. Le richieste respinte (4xx) o fallite (5xx) non vengono mai fatturate, e la quota viene verificata prima dell'elaborazione: una richiesta oltre quota non costa nulla.

Copertura paesi

Numero nazionale + MRZ + foto + firma

NL Paesi Bassi
DE Germania
FR Francia
ES Spagna
AT Austria
BE Belgio
HR Croazia
CZ Cechia
DK Danimarca
FI Finlandia
IE Irlanda
IT Italia
PL Polonia
PT Portogallo
SE Svezia

MRZ + foto + firma

BG Bulgaria
CY Cipro
EE Estonia
GR Grecia
HU Ungheria
LV Lettonia
LT Lituania
LU Lussemburgo
MT Malta
RO Romania
SK Slovacchia
SI Slovenia

I documenti di qualsiasi altro paese emittente vengono respinti subito — mai oscurati a metà in silenzio.

Documentazione leggibile dalle macchine

La specifica OpenAPI 3.1 è ancorata all'implementazione da un test CI: ogni codice di errore e ogni warning che il servizio può emettere deve essere documentato, e niente di più. La documentazione non può divergere.

Riferimento interattivo (Redoc) openapi.yaml llms-full.txt