Conecta Puli con tu software, Zapier o Make.

Autenticación

Crea una clave en Ajustes → API y webhooks. La clave se muestra una sola vez; guárdala como un secreto. Cada petición lleva la cabecera Authorization. Una clave de «solo lectura» no puede crear ni modificar nada.

curl https://puli.es/api/v1/me \
  -H "Authorization: Bearer puli_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

• Base: https://puli.es/api/v1
• Formato: JSON en UTF-8; fechas ISO 8601 (2026-10-13); importes en euros; IVA en %.
• Límite: 120 peticiones por minuto y clave. Pasado, 429 con Retry-After.
• Paginación: limite (máx. 100) y cursor; la respuesta trae siguienteCursor o null.

Errores

Siempre con la misma forma: { "error": { "codigo": "…", "mensaje": "…" } }. Códigos: 400 datos_invalidos, 401 no_autenticado / clave_invalida, 402 plan_insuficiente, 403 sin_permiso, 404 no_encontrado, 409 conflicto (p. ej. límite del plan o factura ya emitida), 429 limite_peticiones.

Endpoints

Ejemplo: crear y emitir una factura

Necesitas el id de un cliente (créalo con POST /clientes o búscalo por NIF). El servidor calcula los totales, asigna el número de serie y registra la factura en VeriFactu.

curl -X POST https://puli.es/api/v1/facturas \
  -H "Authorization: Bearer puli_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "clienteId": "9D1F…",
    "fechaExpedicion": "2026-10-13",
    "descripcion": "Servicios de octubre",
    "lineas": [
      { "concepto": "Diseño web", "cantidad": 10, "precioUnitario": 60, "iva": 21 },
      { "productoId": "3F1B…", "concepto": "Taza (del catálogo: descuenta stock al emitir)", "cantidad": 2, "precioUnitario": 4, "iva": 21 },
      { "concepto": "Hosting", "precioUnitario": 20, "iva": 21, "descuento": 10 }
    ],
    "tipoIRPF": 15,
    "emitir": true
  }'

Respuesta (resumida):

{
  "factura": {
    "id": "7C2A…", "serie": "A", "numero": "2026-0042", "numeroCompleto": "A-2026-0042",
    "estado": "emitida", "fechaExpedicion": "2026-10-13T10:00:00.000Z",
    "cliente": { "id": "9D1F…", "nombre": "Acme SL", "nif": "B12345678", "email": "admin@acme.es" },
    "baseImponible": 618, "cuotaIVA": 129.78, "tipoIRPF": 15, "cuotaIRPF": 92.7, "total": 655.08,
    "pagada": false, "saldoPendiente": 655.08,
    "verifactu": { "estadoAeat": "pendiente_envio", "csv": null, "uuid": "…" },
    "pdf": "https://puli.es/api/v1/facturas/7C2A…/pdf"
  },
  "verifactu": { "estadoAeat": "pendiente_envio", "csv": null }
}

Para cobrarla: POST /facturas/{id}/pagos con { "importe": 655.08, "fecha": "2026-10-20", "metodoPago": "Transferencia" }.

Webhooks

Añade una URL https en Ajustes → API y webhooks (o con POST /webhooks) y elige los eventos. Puli hace un POST con JSON y reintenta hasta 6 veces si tu servidor no responde 2xx (al minuto, a los 5, a los 30, a las 2 h y a las 12 h). Tras 25 fallos seguidos el webhook se desactiva solo.

Cuerpo de un evento:

POST https://tu-servidor.com/puli
Content-Type: application/json
X-Puli-Event: factura.pagada
X-Puli-Delivery: evt_8f3c…
X-Puli-Signature: t=1760349600,v1=3b2a…

{
  "id": "evt_8f3c…",
  "tipo": "factura.pagada",
  "creado": "2026-10-13T10:00:00.000Z",
  "intento": 1,
  "datos": {
    "factura": {
      "id": "7C2A…", "numeroCompleto": "A-2026-0042", "estado": "pagada",
      "cliente": { "nombre": "Acme SL", "nif": "B12345678", "email": "admin@acme.es" },
      "total": 655.08, "totalPagado": 655.08, "saldoPendiente": 0, "pagada": true,
      "fechaCobro": "2026-10-20T12:00:00.000Z",
      "pdf": "https://puli.es/api/v1/facturas/7C2A…/pdf"
    }
  }
}

Verificar la firma

La cabecera X-Puli-Signature lleva la marca de tiempo t y v1 = HMAC-SHA256(secreto, t + "." + cuerpo) en hexadecimal, sobre el cuerpo crudo tal como llega. Rechaza firmas de más de 5 minutos.

import { createHmac, timingSafeEqual } from "node:crypto";

export function firmaValida(secreto, cabecera, cuerpoCrudo) {
  const partes = Object.fromEntries(cabecera.split(",").map((p) => p.split("=")));
  const t = Number(partes.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const esperado = createHmac("sha256", secreto).update(`${t}.${cuerpoCrudo}`).digest("hex");
  const recibido = String(partes.v1 || "");
  return recibido.length === esperado.length && timingSafeEqual(Buffer.from(recibido), Buffer.from(esperado));
}

Zapier y Make