API para desarrolladores

La API REST pública de EUFactura (plan Scale) permite que sus propias herramientas — un CRM, una tienda online, un script personalizado — creen clientes, redacten y emitan facturas y presupuestos, registren pagos y reciban notificaciones de eventos clave mediante webhooks. Cada endpoint utiliza exactamente la misma lógica que la propia aplicación EUFactura, de modo que nada se comporta de forma distinta a través de la API que en la interfaz.

Referencia completa

La API completa está descrita como una especificación OpenAPI 3.1 — impórtela directamente en Postman, Insomnia o cualquier herramienta compatible con OpenAPI.

Autenticación

Cree una clave desde la página Configuración → Desarrolladores de su organización (solo propietario/administrador). Cada clave está limitada a una organización y tiene un rol — member (lectura y escritura) o accountant (solo lectura). El secreto completo se muestra una sola vez al crearlo; guárdelo de forma segura.

curl https://app.eufactura.eu/api/v1/customers?companyId=<company-id> \
  -H "Authorization: Bearer eufk_..."

Crear un cliente y emitir una factura

curl -X POST https://app.eufactura.eu/api/v1/customers \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "<company-id>",
    "type": "business",
    "legalName": "Acme GmbH",
    "countryCode": "DE"
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a UUID you generate>" \
  -d '{
    "companyId": "<company-id>",
    "customerId": "<customer-id>",
    "currency": "EUR",
    "issueDate": "2026-01-01",
    "lines": [{ "description": "Consulting", "quantity": "1", "unitPriceNet": "500" }]
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices/<invoice-id>/issue \
  -H "Authorization: Bearer eufk_..."

Las facturas siempre se crean como borradores y se emiten como un paso separado y explícito — la emisión asigna el número de factura legal y hace que la factura sea inmutable, de forma coherente con cómo funciona la propia aplicación.

Idempotencia

Envíe una cabecera Idempotency-Key (cualquier cadena que genere, normalmente un UUID) en una solicitud que modifique datos. Reintentar la misma solicitud con la misma clave devuelve la respuesta original en lugar de realizar la acción por segunda vez — seguro frente a reintentos de red y dobles clics.

Límites de tasa

Las solicitudes están limitadas por clave de API. Una respuesta que supere el límite devuelve 429 con un campo Retry-After equivalente, retryAfter, en el cuerpo del error.

Errores

Todos los errores se devuelven como {"error": {"code": "...", "message": "..."}}. El identificador de un recurso perteneciente a otra organización siempre devuelve 404, nunca 403 — EUFactura nunca confirma que un recurso existe antes de confirmar que puede acceder a él.

Webhooks

Registre una URL de endpoint y elija qué eventos recibir desde Configuración → Desarrolladores: invoice.issued, invoice.payment_recorded, quote.converted y credit_note.issued. Cada entrega es un POST HTTPS firmado:

POST <your endpoint>
Content-Type: application/json
X-EUFactura-Signature: t=1700000000,v1=<hex-encoded HMAC-SHA256>

{"id": "...", "type": "invoice.issued", "data": { ... }}

Verifíquelo calculando un HMAC-SHA256 de la marca de tiempo, un punto literal y el cuerpo de la solicitud en bruto usando el secreto de su endpoint, y comparando el resultado con el valor v1 — el mismo formato t=...,v1=... que utiliza Stripe para sus webhooks, por lo que cualquier código de verificación de webhooks de Stripe que ya tenga es un buen punto de partida. Las entregas se reintentan con backoff en caso de fallo (hasta cinco intentos en unas 12 horas); su endpoint debe ser idempotente respecto al id del payload.

Preguntas

Contáctenos en hello@eufactura.eu.