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

Referencia de la API

La API de IDBird es deliberadamente pequeña: dos endpoints, una forma de petición, un sobre de error. Esta página es la superficie completa. La especificación legible por máquina y la referencia interactiva viven en api.idbird.eu.

URL base y autenticación

Cada petición lleva una clave API Bearer emitida por el equipo de IDBird. Las claves se almacenan solo como hash SHA-256 y se comprueban en vivo en cada petición — la revocación surte efecto en la llamada siguiente.

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

Endpoints

`POST`	`/v1/redact`	Anonimizar un documento y recibir la imagen limpia más findings y warnings.
`POST`	`/v1/inspect`	Ensayo en seco: solo findings y warnings — nunca se devuelve una imagen.
`GET`	`/up`	Comprobación de salud, sin autenticación.

Petición

Ambos endpoints aceptan la misma petición multipart/form-data.

Campo	Obligatorio	Descripción
`document`	sí	El archivo: JPEG, PNG, BMP o PDF (hasta 5 páginas por defecto), máx. 10 MiB. El tipo se detecta por el contenido — nombre de archivo y cabecera Content-Type se ignoran.
`country_hint`	no	Código ISO 3166-1 alpha-2 del país emisor, sin distinguir mayúsculas (EL se acepta como alias de GR). Si se omite, modo automático — con pista, la detección es más precisa.
`photo_redaction`	no	redact (por defecto) elimina la fotografía. keep la deja visible y añade el warning photo_not_redacted. both devuelve dos imágenes: totalmente anonimizada y con foto visible.

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

Respuestas

El campo image es siempre un PNG codificado en base64 y siempre la versión más anonimizada de la petición. findings contiene nombres de detectores y recuentos — nunca valores. warnings y findings están siempre presentes, vacíos cuando todo está limpio.

POST /v1/redact — una sola página

{
  "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 multipágina (pages sustituye a image, numeración desde 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, nunca una imagen

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

Códigos de aviso

HTTP 200 significa procesado, no protegido. Los warnings llegan en un orden fijo y documentado; compruébelos antes de archivar. Los ocho códigos posibles:

Errores

Todos los errores usan un mismo sobre con un código estable y un mensaje estático en inglés — seguro para hacer matching, libre de contenido 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.

Límites y facturación

Límite de tasa: 30 peticiones por minuto y clave; 429 con cabecera Retry-After al superarlo.
Cupo diario: 50 llamadas por clave y día por defecto (UTC); el equipo de IDBird lo amplía por clave con efecto inmediato.
Una petición completamente procesada es una llamada facturable — incluido un PDF multipágina. Las peticiones rechazadas (4xx) o fallidas (5xx) nunca se facturan, y el cupo se comprueba antes de procesar: una petición por encima del cupo no cuesta nada.

Cobertura por país

Número nacional + MRZ + foto + firma

NL Países Bajos
DE Alemania
FR Francia
ES España
AT Austria
BE Bélgica
HR Croacia
CZ Chequia
DK Dinamarca
FI Finlandia
IE Irlanda
IT Italia
PL Polonia
PT Portugal
SE Suecia

MRZ + foto + firma

BG Bulgaria
CY Chipre
EE Estonia
GR Grecia
HU Hungría
LV Letonia
LT Lituania
LU Luxemburgo
MT Malta
RO Rumanía
SK Eslovaquia
SI Eslovenia

Los documentos de cualquier otro país emisor se rechazan de plano — nunca se anonimizan a medias en silencio.

Documentación legible por máquina

La especificación OpenAPI 3.1 está fijada a la implementación mediante un test de CI: cada código de error y cada warning que el servicio puede emitir debe estar documentado, y nada más. La documentación no puede desviarse.

Referencia interactiva (Redoc) openapi.yaml llms-full.txt