Documentación

documents.suils.es

API HTTP de solo lectura que renderiza documentos de identidad españoles especimen a partir de una URL. Cada salida lleva un pie permanente ESPECIMEN · SIN VALIDEZ LEGAL. Pensada para QA: pruebas de OCR, formularios KYC, maquetas y demostraciones.

Endpoints

Tipos

Países para eu: PT FR IT DE RO BG PL NL. Cada país aporta su bandera, su nombre oficial en el idioma local, su tinte y un banco de nombres propio.

Parámetros

Todos son opcionales. Lo que no se indique se deriva de seed; si no hay seed, la semilla es number, y si tampoco hay número, "especimen". Los valores inválidos devuelven 400 con un JSON explicativo ({ error, expected… }).

Raster: size es la anchura en píxeles (máximo 1600 en esta instancia); la altura sigue la proporción ID-1 (85,6 × 53,98 mm) o la de la página del pasaporte (125 × 88 mm). jpg se aplana sobre blanco.

Determinismo

• La semilla se convierte en un hash FNV-1a y alimenta un PRNG mulberry32 con flujos independientes por campo (persona, fechas, domicilio, número, soporte, firma…). Cambiar un parámetro no altera el resto.
• Las fechas se anclan al año natural en curso: edad 18–85, expedición en los últimos 0–9 años, validez según la edad en la expedición (DNI: +5 si <30, +10 si <70, PERMANENTE si ≥70, impreso 01 01 9999; pasaporte +5/+10; TIE +5; UE +10). Si necesitas estabilidad absoluta entre años, fija birth, issue y expiry.
• La provincia, el prefijo del código postal, el equipo de expedición y (en CIF) los dos primeros dígitos del número son coherentes entre sí. El sexo es coherente con el banco de nombres.
• La foto es avatars.suils.es/{photo}/png?seed={photoSeed}, incrustada en base64. Si el servicio de avatares no responde en 4 s se dibuja una silueta neutra.

Algoritmos

• DNI / NIF: letra = "TRWAGMYFPDXBNJZSQVHLCKE"[número mod 23]. 12345678 → Z, 00000000 → T.
• NIE: se sustituye X→0, Y→1, Z→2 y se aplica el algoritmo del DNI. X1234567 → L, Y1234567 → X, Z1234567 → R.
• CIF: letra de entidad + 7 dígitos + control. Control = (10 − ((Σ pares + Σ dígitos de 2×impares) mod 10)) mod 10; letra JABCDEFGHI[n] si la entidad es P, Q, R, S, N o W, dígito si es A, B, E o H, cualquiera en el resto. A58818501, B12345674, Q2826000H son válidos.
• Pasaporte: 3 letras + 6 dígitos, sin carácter de control (PAB123456).
• MRZ (ICAO 9303): TD1 de 3 × 30 en DNI, TIE y UE; TD3 de 2 × 44 en el pasaporte. Dígito de control con pesos 7-3-1 (0-9 valor, A=10…Z=35, <=0) mod 10, incluido el compuesto. En DNI/TIE la línea 1 lleva IDESP + número de soporte + control y el DNI/NIE en el campo opcional, como en las tarjetas reales; el pasaporte lleva el DNI como número personal. Transliteración: Ñ→N, sin acentos, espacios→<.

Ejemplos

Autoalojado

docker compose up -d --build levanta la API (Node 20, node:http, resvg + sharp) y una pasarela nginx publicada en :8182. Variables: PUBLIC_BASE_URL, AVATARS_BASE_URL, MAX_SIZE, CACHE_CONTROL_MAX_AGE, UV_THREADPOOL_SIZE. Las respuestas llevan Cache-Control: public, max-age=… y CORS abierto.

Aviso y licencia

Los diseños son originales (no reproducen escudos ni elementos de seguridad reales) y cada cara incluye un pie de especimen que no puede desactivarse. Los datos son ficticios y generados a partir de la semilla. Código © 2026 Suils, licencia MIT.