Autenticacion en un minuto
Todas las llamadas usan una API key en la cabecera X-API-Key. Se crea desde el portal (seccion API Keys) con el permiso desktop:upload, caducidad configurable y rotacion en un clic. Cuota por key: 600 peticiones/minuto (429 con Retry-After al superarla).
Identifica tu cliente HTTP: la API esta detras de un WAF que bloquea con 403 los User-Agent por defecto de algunas librerias (por ejemplo Python-urllib). Envia 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 numeracion si quieres)
El paso que cierra el ciclo: numeracion, QR tributario AEAT y registro segun el modo del tenant. invoice_number es opcional; si lo envias, el QR y el registro llevan exactamente tu numero.
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 numeracion, respetada
Si tu programa lleva su propio correlativo, envia invoice_number en el finalize y el numero registrado y el del QR seran exactamente los tuyos. SelloQR aplica cuatro guardas: formato compatible AEAT (hasta 60 caracteres), unicidad dentro de tu serie y ano (409 si se repite), regimen unico por serie (una serie no mezcla numeracion tuya y automatica) e idempotencia en reintentos. La correlatividad de tu serie sigue siendo tuya, como emisor.
Errores que veras
| HTTP | Significado |
|---|---|
| 401 | API key ausente, invalida, revocada o caducada |
| 402 | El tenant no tiene el modulo de conector (plan API o superior) |
| 403 | Key valida pero sin el scope requerido (JSON) - o WAF si el cuerpo es HTML |
| 409 | Estado invalido (finalize antes de draft) o numero de factura duplicado |
| 422 | PDF invalido, campos de finalize incompletos o formato de numero invalido |
| 429 | Cuota de la key (600 req/min) o limite de facturas del plan |
Preguntas frecuentes
Que 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. Segun el modo del tenant, ademas genera el registro de facturacion con encadenamiento de huellas SHA-256 y, en modalidad VERI*FACTU, la remision a la AEAT. Tu programa conserva su flujo; SelloQR actua como capa VeriFactu.
Puedo mantener mi propia numeracion de facturas?
Si. El finalize acepta un campo opcional invoice_number con tu numero tal cual lo imprimes (hasta 60 caracteres, formato NumSerieFactura de la AEAT). SelloQR garantiza la unicidad dentro de tu serie y ano, y el QR codifica exactamente tu numero. Si no lo envias, SelloQR autonumera. Una serie usa un unico regimen: o la numeras tu o la numera SelloQR.
Como pruebo la integracion 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 remision 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 automaticamente, y desconfia de quien prometa lo contrario: la AEAT no homologa software. Si tu producto usa SelloQR como componente, tu producto necesita su propia declaracion responsable que identifique la arquitectura y la version del componente. SelloQR reduce lo que tienes que construir y declarar, y su propia declaracion responsable esta publicada.
Que necesito para empezar?
Una cuenta con el modulo 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 tipicamente en menos de una hora siguiendo los 5 pasos del quickstart.
Fabricas software de facturacion?
Te acompanamos en la integracion: entorno de pruebas, primera factura aceptada y la documentacion de arquitectura para preparar tu propia declaracion responsable como fabricante.