Los recursos de la API, ruta a ruta

Los convenios, que valen para todo

Antes de mirar recurso por recurso, seis cosas que son iguales en toda la API. Sabiéndolas, la mitad de la referencia sobra.

• JSON en los dos sentidos. Si mandas cuerpo, va con Content-Type: application/json. Sin esa cabecera el cuerpo llega y no se lee, y el error que sale despista.
• Identificadores con prefijo. con_ contactos, pro_ productos, fac_ facturas, gas_ gastos, cob_ cobros. Son opacos: no los interpretes, guárdalos tal cual.
• Fechas en AAAA-MM-DD y marcas de tiempo en ISO 8601 con zona UTC. La fecha de una factura es una fecha, no un instante: no lleva hora.
• Importes en decimales, no en céntimos, y con el punto como separador. 435.60, no 43560 ni 435,60.
• Los campos que no conoces, déjalos pasar. Se pueden añadir campos nuevos a una respuesta sin previo aviso; eso no es un cambio que rompa nada. Lo que sí romperías es tú, si tu código explota al ver una clave que no esperaba.
• Modificar es PATCH, no PUT. Se manda sólo lo que cambia. Lo que no mandas, se queda como estaba.

Organización

Los datos fiscales de tu empresa: nombre, NIF, régimen y series de facturación. Es de sólo lectura y no pide ningún scope, así que es la llamada con la que se comprueba que una clave vale.

{
  "id": "org_3Kd8vR",
  "nombre": "Talleres Miralles SL",
  "nif": "B12345674",
  "regimen": "general",
  "moneda": "EUR",
  "series": ["F27", "R27"]
}

No hay ruta para cambiar estos datos. Los datos fiscales de una empresa se tocan desde la aplicación y con una persona delante: cambiar un NIF por API es de esas cosas que sólo pueden salir mal.

Contactos

Clientes y proveedores. Es la primera parada de casi cualquier integración, porque una factura necesita a quién va dirigida.

curl -X POST https://erp.cairos.es/api/v1/contactos \
  -H "Authorization: Bearer $CAIROS_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: alta-cliente-1042" \
  -d '{
    "nombre": "Grupo Bonaire SL",
    "nif": "B17654321",
    "email": "admin@bonaire.example",
    "tipo": "cliente",
    "direccion": {
      "via": "Carrer del Carme 14",
      "cp": "17004",
      "ciudad": "Girona",
      "pais": "ES"
    }
  }'

const r = await fetch(BASE + "/contactos?limite=100", {
  headers: { Authorization: "Bearer " + CLAVE },
});
const { datos, total, siguiente } = await r.json();

<?php
// Buscar un contacto por NIF antes de crearlo es la forma
// sencilla de no llenar la agenda de duplicados.
$url = $base . "/contactos?nif=B17654321";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $clave,
]);
$lista = json_decode(curl_exec($ch), true);
curl_close($ch);

$existe = $lista["datos"][0] ?? null;

El NIF se valida. Un NIF con la letra mal devuelve 422 datos_invalidos con el campo señalado en error.detalles. Es deliberado: un NIF mal escrito no se ve hasta que el 347 no cuadra en febrero.

Productos

El catálogo de lo que vendes, con su precio y su tipo de IVA. No hace falta para facturar —una línea de factura puede llevar el concepto escrito a mano— pero si lo usas, los precios y los impuestos dejan de repetirse en cada línea.

{
  "referencia": "REV-ANUAL",
  "nombre": "Revisión anual",
  "precio": 180.00,
  "iva": 21,
  "unidad": "servicio"
}

Si tu tienda ya lleva su propio catálogo, no lo dupliques aquí: manda las líneas con su concepto y su precio y deja el catálogo donde está. Sincronizar dos catálogos es trabajo permanente y casi nunca hace falta.

Facturas

El recurso central, y el único con dos pasos. Una factura se crea en borrador y se emite aparte.

Crear el borrador

{
  "contacto_id": "con_7Qb3xK",
  "serie": "F27",
  "fecha": "2027-03-02",
  "vencimiento": "2027-04-01",
  "lineas": [
    {
      "concepto": "Revisión anual",
      "cantidad": 2,
      "precio": 180.00,
      "iva": 21
    },
    {
      "producto_id": "pro_2Xf9tL",
      "cantidad": 1
    }
  ]
}

Las dos formas de línea conviven: una con el concepto y el precio escritos, otra apuntando a un producto del catálogo, que aporta los suyos. Y la respuesta trae ya base, cuota_iva y total calculados, que es lo que hay que comparar con lo que esperabas cobrar antes de emitir.

Emitir, que es lo que no se deshace

Al emitir pasan tres cosas a la vez: la factura toma el siguiente número de su serie, se genera el registro encadenado de VeriFactu y el documento deja de ser modificable.

{
  "id": "fac_5Np2wD",
  "numero": "F27/0042",
  "estado": "emitida",
  "fecha": "2027-03-02",
  "base": 360.00,
  "cuota_iva": 75.60,
  "total": 435.60,
  "pendiente": 435.60,
  "verifactu": {
    "estado": "remitida",
    "huella": "7f3c1a…d904"
  }
}

El PDF

GET /facturas/{id}/pdf devuelve el fichero con el código QR y la leyenda ya impresos. Si pides el PDF de un borrador vuelve un 409 conflicto: un borrador no tiene número, y un PDF de factura sin número no es una factura.

Gastos

Lo que te facturan a ti. Es el otro lado del IVA y lo que hace que el modelo 303 salga bien: sin gastos sólo tienes la mitad de la cuenta.

{
  "contacto_id": "con_9Wr4hM",
  "numero_proveedor": "A-2027/118",
  "fecha": "2027-02-28",
  "base": 240.00,
  "iva": 21,
  "categoria": "suministros"
}

Un gasto lleva el número que le puso el proveedor, no uno tuyo: la numeración correlativa es cosa de quien emite. Por eso numero_proveedor es un texto libre y no se valida contra ninguna serie.

Cobros

Cuándo y cómo te han pagado. Registrar el cobro es lo que baja el pendiente de una factura y lo que hace que la previsión de tesorería signifique algo.

{
  "factura_id": "fac_5Np2wD",
  "fecha": "2027-03-05",
  "importe": 435.60,
  "medio": "transferencia",
  "referencia": "Pedido 1042 · Stripe"
}

Los cobros parciales son normales y la API no los estorba: manda el importe que sea y la factura queda parcialmente cobrada. Lo que no acepta es cobrar más de lo que queda pendiente, que devuelve 409 conflicto.

Si vendes por internet, el cobro suele existir antes que la factura: el pedido ya está pagado por la pasarela cuando llegas aquí. El orden entonces es crear la factura, emitirla y registrar el cobro seguido, que es lo que hacen las guías de WooCommerce y Shopify.

Webhooks

Las suscripciones a sucesos se administran también por API, con el scope webhooks:manage.

Cómo se comprueba la firma, qué trae cada suceso y qué hacer con un reenvío está entero en la página de webhooks, que es donde vive lo que de verdad hay que entender de esto.

La especificación, que es la fuente de la verdad

Toda la API está descrita en OpenAPI y se sirve en la propia base:

curl https://erp.cairos.es/api/v1/openapi.json -o cairos.json

Con ese fichero, un generador de clientes te saca el tuyo en el lenguaje que uses, y una herramienta como Postman o Insomnia te monta la colección entera sin teclear una ruta.

Y sirve para algo más importante: cuando esta página y la especificación no coincidan, gana la especificación. Es lo que genera el propio servidor; esto es texto escrito por personas. Si encuentras una diferencia, dínosla a hola@cairos.es y se corrige la página.