API pública

CanaryFactura tiene una API REST para que conectes tus propias herramientas: un script que importa clientes, tu CRM creando borradores de factura, un panel que lee el estado de cobro. Disponible en el plan Plus (y durante la prueba).

La especificación completa (OpenAPI 3.1) está en /api/v1/openapi.json.

Precaución

La API no emite facturas. Puede crear borradores, pero emitir — asignar número, encadenar la huella, enviar a la AEAT — se hace siempre desde la aplicación. Así ningún script puede tocar el material fiscal por accidente. La única excepción es la integración con Stripe incorporada: forma parte de la aplicación, se activa expresamente y emite con sus propias salvaguardas. Ver Facturas desde Stripe.

Claves API

En Ajustes → Claves API creas una clave: le pones un nombre, marcas los permisos y la clave aparece una sola vez. Cópiala en ese momento; en nuestro lado solo se guarda un hash, así que no hay forma de recuperarla después. Solo el propietario de la cuenta puede crear y revocar claves.

Cada clave lleva un prefijo que dice de qué entorno es: cf_live_ para producción y cf_test_ para el entorno de pruebas. Una clave de un entorno no funciona en el otro.

Precaución

Una clave API funciona sin verificación en dos pasos: es una credencial propia, pensada para programas, no para personas. Quien tenga la clave tiene acceso con sus permisos, sin más barreras. Trátala como una contraseña: no la subas a un repositorio, no la pegues en chats, y revócala en cuanto dejes de usarla. Desde Ajustes puedes revocar cualquier clave al instante, también con la suscripción caducada.

Autenticación

Manda la clave como token Bearer en cada petición:

curl https://app.canaryfactura.es/api/v1/invoices \
  -H "Authorization: Bearer cf_live_TU_CLAVE"

Una clave revocada o desconocida devuelve 401; una clave sin el permiso necesario, o de un plan sin API, devuelve 403.

Permisos

Cada clave lleva solo los permisos que marcaste al crearla:

Permiso	Qué deja hacer
invoices:read	Leer facturas, con líneas y estado VERI*FACTU
invoices:draft	Crear borradores de factura (nunca emitir)
customers:read	Leer clientes
customers:write	Crear y editar clientes

Dale a cada integración lo mínimo que necesite: un panel de solo lectura no tiene por qué poder escribir clientes.

Endpoints

Método y ruta	Qué hace
GET /api/v1/invoices	Lista facturas (paginada por cursor; filtros estado, serie, from, to)
GET /api/v1/invoices/{id}	Una factura con sus líneas y el estado del registro VERI*FACTU
POST /api/v1/invoices	Crea un borrador con sus líneas en una sola llamada
GET /api/v1/customers	Lista clientes
POST /api/v1/customers	Crea un cliente
GET /api/v1/customers/{id}	Un cliente
PATCH /api/v1/customers/{id}	Actualiza un cliente (se manda el objeto completo)

Crear un borrador:

curl -X POST https://app.canaryfactura.es/api/v1/invoices \
  -H "Authorization: Bearer cf_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "serieId": "…",
    "tipo": "F1",
    "fechaExpedicion": "2026-07-19",
    "customerId": "…",
    "lines": [{
      "description": "Desarrollo web",
      "qty": "1",
      "unitPrice": "500.00",
      "impuesto": "03",
      "claveRegimen": "01",
      "calificacion": "S1",
      "tipoPct": "7"
    }]
  }'

Los importes van siempre como texto ("500.00"), nunca como números con coma flotante. Un cuerpo inválido devuelve 422 con el detalle de cada campo.

Límite de peticiones

Cada clave puede hacer 60 peticiones por minuto de forma sostenida, con ráfagas de hasta 120. Al pasarte recibes 429 con una cabecera Retry-After que dice cuántos segundos esperar. Si tu integración necesita más ritmo de forma habitual, escríbenos antes de ponerle un bucle de reintentos.

En Ajustes

La tabla de claves muestra el prefijo de cada una (cf_live_a1b2c3d4…), sus permisos, cuándo se creó y cuándo se usó por última vez — útil para detectar claves olvidadas que ya no usa nadie. Revocar una clave corta el acceso al momento; las peticiones con esa clave pasan a 401.