La API de Cairos, abierta y documentada

Lo que tienen en común los cuatro: el dato fiscal —la numeración, el registro de VeriFactu, el cálculo del IVA— se queda dentro de Cairos y no se replica fuera. Una tienda que se guarda su propio contador de facturas acaba con dos numeraciones que no cuadran, y eso no se arregla con una consulta: se arregla con rectificativas.

Toda llamada lleva Authorization: Bearer con la clave. Sólo HTTPS: una petición por HTTP no se redirige, se rechaza, porque una redirección con la clave dentro es la clave viajando en claro una vez.

Hay dos clases de clave y la diferencia no es la que espera casi todo el mundo:

La regla que sorprende: escribir no implica leer

Los permisos van por recurso y por operación: invoices:read y invoices:write son dos, y tener el segundo no te da el primero. Una clave con invoices:write emite facturas y no puede listarlas.

Va al revés de lo que hace casi todo el mundo, y es deliberado. La integración de una tienda sólo necesita escribir; el día que esa clave se filtre —un repositorio público, un registro de errores, un becario— quien la tenga podrá meterte facturas de broma, que se rectifican, y no podrá descargarse tu cartera de clientes ni tu facturación, que no se deshace. Quien necesite las dos cosas pide las dos, y lo hace a sabiendas.

Un permiso que falta da 403 sin_permiso, y el error dice cuál falta y cuáles tienes. Una clave mala o ausente da 401 no_autenticado. No se confunden nunca: si te sale 403, la clave es buena.

Los permisos, por área

La raya se pone donde cambia lo que se ve, no donde cambia la pantalla. Las comisiones enseñan cuánto cobra cada comercial y las horas del equipo son datos de personas: ninguna de las dos cosas la quiere una clave hecha para meter pedidos de una tienda.

Paginación por cursor, nunca por número de página

No existe ?page=2. Una lista se recorre con ?limite= —50 por defecto, 200 de tope— y el campo siguiente que viene en la respuesta, que ya es la URL entera de la página que sigue, con los filtros que llevabas puestos. Cuando llega a null, se acabó.

Los números de página pierden filas y repiten otras, y no en un caso raro: es lo normal. Si mientras recorres cuatro mil contactos alguien da de alta uno, todo se desplaza una posición y la última fila de la primera página sale también la primera de la segunda. Con un borrado, al revés: una fila se cuela entre dos páginas y no sale en ninguna. Quien importa acaba con duplicados y con huecos sin saber por qué.

// Recorrer una lista entera, sea del tamaño que sea.
// "antiguo" va sobre una fecha que no se mueve: es el orden
// que hay que usar para el histórico.
let url = "https://erp.cairos.es/api/v1/facturas" +
          "?limite=200&orden=antiguo";

while (url) {
  const r = await fetch(url, {
    headers: { Authorization: "Bearer " + CLAVE },
  });
  const pagina = await r.json();
  for (const factura of pagina.datos) {
    // lo tuyo
  }
  url = pagina.siguiente;   // ya viene con los filtros dentro
}

Hay un tercer orden, orden=modificado, y existe para los disparadores por sondeo de Make, Zapier y n8n: pone lo último que ha cambiado arriba, no lo último que se creó. Tiene un coste que hay que decir: el orden se mueve mientras paginas, así que sirve para mirar las últimas y no para recorrer el histórico.

Errores: siempre el mismo sobre

Un fallo llega con el código HTTP que le toca y con este cuerpo, siempre igual, venga de donde venga:

{
  "error": {
    "codigo": "datos_invalidos",
    "mensaje": "La línea 2 no tiene precio.",
    "detalles": {
      "campos": [
        { "campo": "lineas[1].precio", "motivo": "es obligatorio" }
      ]
    }
  }
}

Los códigos son un puñado corto y estable —no_autenticado, sin_permiso, no_encontrado, datos_invalidos, conflicto, demasiadas_peticiones y error_interno— y sólo el 422 te dice dónde mirar, con el índice de la línea que falla dentro del nombre del campo. Qué hacer con cada uno, en errores.

El límite de peticiones

120 peticiones por minuto y por clave, en ventana deslizante. No es un contador que se pone a cero al dar la hora: con eso se podrían meter 120 a las 10:00:59 y otras 120 a las 10:01:00, que es justo el pico que se quiere evitar.

Da de sobra para lo que se hace de verdad: una sincronización nocturna gasta unas tres llamadas por pedido, así que son unos cuarenta pedidos por minuto. Y es lo bastante bajo para que una integración en bucle no deje sin respuesta al resto de clientes, que no es una hipótesis: es lo que hace cualquier integración con un fallo de paginación.

Las cabeceras RateLimit-* van en todas las respuestas, no sólo en el rechazo —Retry-After, ésa sí, sólo en el 429—. Un cliente bien hecho mira RateLimit-Remaining y se frena solo antes de comerse el 429.

Idempotencia: la cabecera que evita facturar dos veces

Todo lo que crea algo admite Idempotency-Key. Mandas una llave tuya —el identificador del pedido, no un aleatorio— y si esa misma petición llega dos veces, la segunda recibe la respuesta de la primera en vez de crear otra cosa. Misma llave con un cuerpo distinto es un 409 conflicto: eso no es un reintento, es un fallo tuyo, y decírtelo es mejor que crear dos. Las llaves viven 24 horas.

Importa porque una factura emitida no se borra. Se rectifica, que es lo que exige el reglamento de facturación, así que una factura de más no es un registro sobrante: es una rectificativa, un asiento y una llamada a tu cliente. La cabecera es una línea. El porqué, largo, está en idempotencia.

Un caso que conviene saberse: POST /facturas/{id}/emitir es idempotente sin cabecera. Emitir una factura ya emitida devuelve la misma factura con su mismo número —200 en vez de 201—, no un error ni un número nuevo. Es la única respuesta que no arriesga un salto en la numeración cuando quien reintenta no sabe si la primera llegó.

1 · Pedido de la tienda → contacto → factura → cobro

El caso más común con diferencia. Se dispara desde el webhook de «pedido pagado» de tu tienda, y son cinco llamadas.

# 1 · El comprador: se busca por NIF y se crea si no está
POST /contactos/upsert
     Idempotency-Key: pedido-1042-contacto
     { "nif": "B17654321", "nombre": "Grupo Bonaire SL",
       "email": "compras@bonaire.example", "tipo": "customer" }
# -> 201 creado:true   ·   200 creado:false si ya existía

# 2 · La factura, todavía borrador y sin número
POST /facturas
     Idempotency-Key: pedido-1042
     { "contacto_id": "...", "serie": "TIENDA",
       "precios_con_iva": true,
       "lineas": [ { "descripcion": "Camiseta talla M",
                     "cantidad": 2, "precio": 24.20,
                     "tipo_iva": 21 } ] }
# -> 201 estado:"draft"  numero:null

# 3 · Emitir: aquí se reserva el número y se registra en VeriFactu
POST /facturas/{id}/emitir
# -> 201 si la emites tú   ·   200 si ya estaba emitida

# 4 · El cobro que ya hizo la pasarela
POST /cobros
     Idempotency-Key: pedido-1042-cobro
     { "factura_id": "...", "importe": 48.40, "metodo": "card" }

# 5 · El PDF, para adjuntarlo a tu propio correo
GET  /facturas/{id}/pdf

La trampa está en el paso 2. El precio que existe en una tienda al público es el de la etiqueta —12,10 €—, que es lo que cobró la pasarela y lo que aparece en el extracto del banco; la base imponible no es un dato de la tienda, es una consecuencia. Por eso está precios_con_iva: sin él hay que desglosar a mano, y ese desglose se escribe mal casi siempre —se calcula hacia delante en vez de hacia atrás—, con lo que la factura acaba uno o dos céntimos por debajo del cobro y el descuadre se acumula hasta que el 303 no cuadra con la caja.

Y la Idempotency-Key es el número de pedido, siempre el mismo. Si la tienda reintenta su webhook, no sale una segunda factura. El enganche escrito está en WooCommerce y en Shopify; si no quieres escribir nada, el conector de tiendas del propio ERP hace estos cinco pasos solo.

2 · Formulario de la web → oportunidad → presupuesto aceptado

Un formulario de contacto que no se queda en un correo. Todo esto ya tiene ruta: el CRM y los presupuestos se abrieron con sus acciones, así que el recorrido entero —incluido aceptar el presupuesto, que hasta ahora sólo se podía desde la pantalla— se hace desde fuera.

La trampa aquí es el paso 1: si en vez de upsert se encadena «buscar / si hay resultados / si no crear», el día que la búsqueda devuelva una lista vacía y nadie mire, se crea un contacto por cada formulario. Y una nota sobre el paso 5: perder también avisa —quote.rejected—, que es lo que impide que el seguimiento siga persiguiendo algo ya cerrado. Ver el módulo de CRM.

3 · Cada lunes a las ocho, el resumen de ventas

Una sola llamada, y ésa es la gracia.

GET /informes/ventas?desde=2026-08-24&hasta=2026-08-30

# -> { "facturas": 37, "base_imponible": 18420.00,
#      "cuota_iva": 3868.20, "total": 22288.20,
#      "cobrado": 14105.60, "pendiente": 8182.60,
#      "ticket_medio": 602.38, "divisa": "EUR",
#      "por_serie": [...], "por_estado": [...] }

La receta obvia es otra: GET /facturas?estado=paid&limite=200 y sumar. Está mal de tres maneras y las tres son silenciosas. Se queda corta pasadas 200 facturas, porque el escenario coge la primera página y no sigue el cursor, y un número más bajo del esperado parece una mala semana. estado=paid no son las ventas, es lo cobrado: una factura a 30 días emitida el jueves no está pagada el lunes. Y si hay facturas en otra moneda, sumar euros con dólares da un número que no es dinero de ninguna moneda.

El informe suma en el servidor, sobre el periodo entero, con el cambio congelado de cada documento —el del devengo, que es el que manda el artículo 79.Once de la Ley del IVA—, deja fuera los borradores porque un borrador no es una venta, y va por fecha de emisión, que es donde lo va a contar Hacienda. Además contesta por separado a lo facturado y a lo cobrado, que son dos preguntas distintas.

4 · Sincronizar el stock en los dos sentidos

Dos medias sincronizaciones que hay que montar por separado.

De la tienda a Cairos: POST /productos/upsert, con el SKU como llave. Actualiza lo que mandas y no vacía lo que no mandas, así que un catálogo que sólo conoce precio y existencias no destroza la ficha del producto en cada pasada.

De Cairos a la tienda: escucha los avisos de producto modificado y de existencias bajo mínimo. Y si tu herramienta no recibe webhooks, sondea con GET /productos?orden=modificado, que es el orden que existe justo para eso.