Autenticación en un minuto
Todas las llamadas usan una API key en la cabecera X-API-Key. Se crea desde el portal (sección API Keys) con el permiso desktop:upload, caducidad configurable y rotación en un clic. Cuota por key: 600 peticiones/minuto (429 con Retry-After al superarla).
Identifica tu cliente HTTP: la API está detrás de un WAF que bloquea con 403 los User-Agent por defecto de algunas librerías (por ejemplo Python-urllib). Envía siempre un User-Agent propio, como MiPrograma/1.0. Un 403 con cuerpo HTML es el WAF; los errores de permisos de la API llegan en JSON.
Quickstart: primera factura sellada en 5 pasos
1. Sube el PDF de la factura
Respuesta inmediata con el invoice_id; el OCR corre en segundo plano. Subir dos veces el mismo PDF no crea duplicados (idempotente por hash).
curl -X POST https://api.selloqr.com/desktop/invoices/upload \
-H "X-API-Key: sk_live_..." \
-H "User-Agent: MiPrograma/1.0" \
-F "[email protected]"2. Espera a que el OCR termine
Polling al estado hasta que devuelva draft (~30 segundos). El finalize solo acepta facturas en draft o validated.
curl https://api.selloqr.com/desktop/invoices/1234/status \
-H "X-API-Key: sk_live_..." -H "User-Agent: MiPrograma/1.0"3. Finaliza: emite y sella (con TU numeración si quieres)
El paso que cierra el ciclo: numeración, QR tributario AEAT y registro según el modo del tenant. invoice_number es opcional; si lo envías, el QR y el registro llevan exactamente tu número.
curl -X POST https://api.selloqr.com/desktop/invoices/1234/finalize \
-H "X-API-Key: sk_live_..." -H "User-Agent: MiPrograma/1.0" \
-H "Content-Type: application/json" \
-d '{
"customer_tax_id": "B87654321",
"customer_name": "CLIENTE SL",
"series": "C",
"invoice_number": "2026/C/024",
"lines": [
{"description": "Servicio", "quantity": 1,
"unit_price": 100.0, "vat_rate": 21.0}
]
}'4. Descarga el PDF sellado
El PDF original de tu programa, con el doble QR estampado (tributario + cobro), listo para entregar al cliente.
curl -L https://api.selloqr.com/desktop/invoices/1234/pdf \
-H "X-API-Key: sk_live_..." -H "User-Agent: MiPrograma/1.0" \
-o factura_sellada.pdf5. Consulta por REST cuando lo necesites
Superficie /api/v1 con la misma API key: listado paginado y detalle de facturas (scope invoices:read) y finalize (scope invoices:write).
curl "https://api.selloqr.com/api/v1/invoices?limit=50" \
-H "X-API-Key: sk_live_..." -H "User-Agent: MiPrograma/1.0"Tu numeración, respetada
Si tu programa lleva su propio correlativo, envía invoice_number en el finalize y el número registrado y el del QR serán exactamente los tuyos. SelloQR aplica cuatro guardas: formato compatible AEAT (hasta 60 caracteres), unicidad dentro de tu serie y año (409 si se repite), régimen único por serie (una serie no mezcla numeración tuya y automática) e idempotencia en reintentos. La correlatividad de tu serie sigue siendo tuya, como emisor.
Errores que verás
| HTTP | Significado |
|---|---|
| 401 | API key ausente, inválida, revocada o caducada |
| 402 | El tenant no tiene el módulo de conector (plan API o superior) |
| 403 | Key válida pero sin el scope requerido (JSON) - o WAF si el cuerpo es HTML |
| 409 | Estado inválido (finalize antes de draft) o número de factura duplicado |
| 422 | PDF inválido, campos de finalize incompletos o formato de número inválido |
| 429 | Cuota de la key (600 req/min) o límite de facturas del plan |
Preguntas frecuentes
¿Qué hace exactamente la API de SelloQR?
Recibe el PDF de una factura (o sus datos), lo procesa y devuelve la factura sellada con doble QR: el QR tributario conforme a las especificaciones de la AEAT (RD 1007/2023) y un QR de cobro opcional. Según el modo del tenant, además genera el registro de facturación con encadenamiento de huellas SHA-256 y, en modalidad VERI*FACTU, la remisión a la AEAT. Tu programa conserva su flujo; SelloQR actúa como capa VeriFactu.
¿Puedo mantener mi propia numeración de facturas?
Sí. El finalize acepta un campo opcional invoice_number con tu número tal cual lo imprimes (hasta 60 caracteres, formato NumSerieFactura de la AEAT). SelloQR garantiza la unicidad dentro de tu serie y año, y el QR codifica exactamente tu número. Si no lo envías, SelloQR autonumera. Una serie usa un único régimen: o la numeras tú o la numera SelloQR.
¿Cómo pruebo la integración sin valor fiscal?
Los tenants pueden operar en modo prueba (sandbox): el flujo completo funciona igual (subida, OCR, finalize, PDF sellado) pero el registro es interno, sin remisión a la AEAT y con el PDF marcado como factura de prueba. Es el modo recomendado para desarrollar; el paso a modalidad real se activa por tenant.
¿Integrarme con SelloQR certifica mi software ante la AEAT?
No automáticamente, y desconfía de quien prometa lo contrario: la AEAT no homologa software. Si tu producto usa SelloQR como componente, tu producto necesita su propia declaración responsable que identifique la arquitectura y la versión del componente. SelloQR reduce lo que tienes que construir y declarar, y su propia declaración responsable está publicada.
¿Qué necesito para empezar?
Una cuenta con el módulo de conector habilitado (plan API o superior) y una API key con el permiso desktop:upload, que se crea desde el portal en un minuto. La primera factura sellada por API se consigue típicamente en menos de una hora siguiendo los 5 pasos del quickstart.
¿Fabricas software de facturación?
Te acompañamos en la integración: entorno de pruebas, primera factura aceptada y la documentación de arquitectura para preparar tu propia declaración responsable como fabricante.
o escríbenos a [email protected]