API y MCP

Toda la API usa una clave de tipo bearer. Se crea en Ajustes → API y webhooks, y se muestra una sola vez: de la clave solo guardamos un hash, así que si se pierde hay que crear otra. Cada clave pertenece a una empresa y no puede ver datos de ninguna otra.

curl "https://www.whatthefactura.es/api/v1/invoices?limit=5" \
  -H "Authorization: Bearer wtf_live_tu_clave_aqui"

La clave nunca viaja en la URL: acabaría en los registros de cualquier proxy por el que pase. Usa una clave por integración, así puedes revocar una sin cortar las demás. Revocar tiene efecto inmediato.

Permisos

Cada clave lleva los permisos que le marques. Son todos de lectura; no existe ningún permiso de escritura porque la API no escribe.

Errores de autenticación

URL base: https://www.whatthefactura.es/api/v1. Todo es JSON, todo es GET, y todas las respuestas llevan Cache-Control: no-store.

{ "data": { "id": "…", "reference": "FAC-2026-00042", … } }

{ "data": [ … ], "next_cursor": "eyJ…" }

next_cursor siempre está presente en las listas, y vale null cuando ya no hay más páginas.

{ "error": { "code": "not_found", "message": "Invoice not found." } }

El orden es siempre por fecha de creación descendente, y la paginación es por cursor, no por offset: si se crean registros mientras recorres las páginas, no se te duplican ni se te saltan.

let cursor = null;
do {
  const url = new URL("https://www.whatthefactura.es/api/v1/invoices");
  url.searchParams.set("limit", "200");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

  const { data, next_cursor } = await res.json();
  for (const invoice of data) process(invoice);
  cursor = next_cursor;
} while (cursor);

Sobre qué fecha filtra since

No es la misma columna en todos los recursos, porque no significan lo mismo:

Filtros adicionales

Solo hay uno: status en /invoices, con valores draft, sent, paid, overdue y cancelled. Cualquier otro valor da un 400 en vez de ignorarse.

{
  "data": {
    "id": "8f2c…",
    "period_start": "2026-08-01",
    "period_end": "2026-08-31",
    "status": "discrepancy",
    "supplier_id": "1a9e…",
    "supplier": { "id": "1a9e…", "name": "Distribuciones Ibiza SL", "cif_nif": "B07…" },
    "expected_total": 4210.55,
    "computed_total": 4188.20,
    "variance": -22.35,
    "invoice_expense_id": null,
    "closed_at": null,
    "created_at": "2026-09-01T08:12:44.120Z",
    "updated_at": "2026-09-02T10:03:01.880Z",
    "albaranes": [
      {
        "id": "c31d…",
        "albaran_number": "ALB-40921",
        "supplier_id": "1a9e…",
        "sucursal_id": null,
        "issue_date": "2026-08-04",
        "received_date": "2026-08-05",
        "subtotal": 180.00,
        "tax_total": 18.00,
        "total": 198.00,
        "currency": "EUR",
        "status": "matched",
        "source": "ocr",
        "created_at": "…",
        "updated_at": "…"
      }
    ]
  }
}

albaranes solo aparece en el detalle: en la lista el campo no viene. Y ojo con el nombre del impuesto en un albarán, que es tax_total y no total_iva.

Los importes son números, nunca cadenas. Las fechas simples van como YYYY-MM-DD y las marcas de tiempo en ISO 8601.

Factura

Gasto

id, reference, expense_number, original_invoice_number, status, category, issue_date, due_date, subtotal, total_iva, total_irpf, total, currency, sucursal_id, source, paid_at, supplier, created_at, updated_at.

Proveedor y cliente

Tienen exactamente la misma forma: id, name, cif_nif, email, phone, address (con line1, line2, city, postal_code, province, country), created_at y updated_at.

Damos de alta la URL en Ajustes, marcas los eventos que te interesan y te mandamos un POST firmado cuando ocurren. Solo https.

{
  "id": "3f0b…",                       // id de la entrega: úsalo como clave de idempotencia
  "type": "invoice.created",
  "created_at": "2026-09-10T07:15:22.008Z",
  "organization_id": "7f28…",
  "data": { "reference": "FAC-2026-00042", "id": "…", "total": 1210, … }
}

Cabeceras

Verificar la firma

Firmamos con HMAC-SHA256 la cadena `${t}.${cuerpo_sin_tocar}`, usando el secreto de ese endpoint. Verifica sobre el cuerpo tal y como llega, antes de parsearlo: si lo parseas y lo vuelves a serializar, la firma ya no cuadra.

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

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=").map((s) => s.trim())),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;

  // Rechaza envíos viejos: es lo que impide reenviar un aviso capturado antes.
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1 ?? "", "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

Compara en tiempo constante, como en el ejemplo. Un === de cadenas se corta en el primer byte distinto y filtra cuántos caracteres acertaste.

Reintentos

Consideramos entregado cualquier 2xx. Si no, reintentamos hasta 5 veces con esperas de 1 minuto, 5, 30 y 2 horas, lo que cubre unas 2 horas y media de caída tuya. Las esperas se redondean al siguiente ciclo de 5 minutos del planificador. Cada intento corta a los 10 segundos.

No seguimos redirecciones: apunta el endpoint a su URL final. Y rechazamos direcciones internas (localhost, rangos privados, enlace local) comprobando la IP a la que resuelve el nombre, no el texto de la URL.

El mismo contenido, en el protocolo que hablan los asistentes de IA. JSON-RPC 2.0 sobre POST, sin sesión y sin SSE, con la misma clave que la API REST.

{
  "mcpServers": {
    "whatthefactura": {
      "type": "http",
      "url": "https://www.whatthefactura.es/api/mcp",
      "headers": { "Authorization": "Bearer wtf_live_tu_clave_aqui" }
    }
  }
}

curl -sS https://www.whatthefactura.es/api/mcp \
  -H "Authorization: Bearer wtf_live_tu_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Los métodos implementados son initialize, ping, tools/list y tools/call. Los gastos no están expuestos por MCP, aunque el permiso read:expenses exista para la API REST.

Hay un límite de 120 peticiones por minuto y por clave. Es protección frente a un bucle o un reintento desbocado, no una cuota facturable, y no está garantizado al alza: si te acercas a ese número, pagina con limit=200 y usa since en vez de recorrerlo todo cada vez.

La API es de solo lectura por diseño. Si necesitas escribir en WhatTheFactura desde tu sistema, escríbenos a hola@whatthefactura.com y lo hablamos: preferimos entender el caso antes que abrir una superficie de escritura genérica.