API REST pública v1

Integra Tabula con tu ERP, BI o flujos internos. Disponible en plan Sala y superiores.

Especificación OpenAPI 3.1 · Gestiona tus API keys

Autenticación

Cabecera X-API-Key: tk_live_…. Las claves se crean desde Configuración → API.

Endpoints

• POST /api/v1/invoices — crear factura (scope write)
• GET /api/v1/invoices — listar (cursor, filtros: from, to, supplier_id, location_id)
• GET /api/v1/invoices/{id} — detalle con líneas
• GET /api/v1/products
• GET /api/v1/suppliers
• GET /api/v1/alerts
• POST /api/v1/webhooks · GET /api/v1/webhooks · DELETE /api/v1/webhooks/{id}

Ejemplo curl

curl -H "X-API-Key: tk_live_xxx" \
  https://app.tabula.com/api/v1/invoices?limit=10

JavaScript

const res = await fetch("https://app.tabula.com/api/v1/invoices", {
  headers: { "X-API-Key": "tk_live_xxx" }
});
const { data, next_cursor } = await res.json();

Python

import requests
r = requests.get(
    "https://app.tabula.com/api/v1/invoices",
    headers={"X-API-Key": "tk_live_xxx"},
    params={"limit": 10},
)
print(r.json())

Webhooks

Eventos: invoice.processed, invoice.failed, alert.created. Cada entrega se firma con HMAC SHA-256 usando el secret devuelto al crear el webhook (cabecera X-Tabula-Signature: sha256=…). Reintentos: hasta 5 con backoff exponencial (0s, 30s, 2m, 10m, 1h). Tras fallos persistentes el webhook pasa a degraded.

import crypto from "crypto";
function verify(body, signature, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Rate limiting

Límite enforced de 60 req/min por cuenta (sumando todas las API keys de la cuenta), en ventanas de 1 minuto. Al superarlo se devuelve 429 Rate limit exceeded con la cabecera Retry-After. Las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset se devuelven en cada respuesta.

Errores

{ "error": { "code": "invalid_api_key", "message": "..." } }