API para desarrolladores

Empezar

Introducción

La API pública de AMAI Budget te permite leer tus presupuestos, clientes y facturas, y crear presupuestos en borrador de forma programática. Todas las peticiones se autentican con una API key (Bearer), están limitadas por empresa y devuelven JSON. Los errores siguen el estándar RFC 9457 (problem+json).

Auth por token

Bearer <clave>, por empresa.

Scopes

Permisos de lectura y escritura.

120 req/min

Límite por clave, ventana deslizante.

Credenciales

Obtener un token

Genera y gestiona tus API keys desde la app, en Ajustes → API. Elige los scopes que necesite tu integración y copia la clave: se muestra una sola vez en el momento de crearla (solo almacenamos su hash, nunca el texto plano). Si la pierdes, revócala y crea una nueva.

1Inicia sesión y abre Ajustes → API.
2Crea una clave con un nombre descriptivo (p. ej. «Zapier producción») y los scopes necesarios.
3Copia la clave (amai_live_…) y guárdala en el gestor de secretos de tu sistema.

¿No ves la pestaña API? La API pública se habilita por despliegue; contacta con tu administrador de AMAI Budget.

Seguridad

Autenticación

Envía tu clave en la cabecera Authorization: Bearer <clave>. La API nunca usa cookies de sesión: cada petición se autentica exclusivamente con el token. Usa siempre HTTPS.

cURL

curl https://budget.amai.run/api/v1/budgets \
  -H "Authorization: Bearer amai_live_xxxxxxxxxxxxxxxx"

Permisos

Scopes

Cada clave tiene un conjunto de scopes. Una petición a un endpoint cuyo scope no está concedido devuelve 403 Forbidden.

ScopeAccesoDescripción

budgets:readLecturaListar los presupuestos de tu empresa.

clients:readLecturaListar tus clientes guardados.

invoices:readLecturaListar tus facturas (solo lectura).

budgets:writeEscrituraCrear presupuestos en BORRADOR (no fiscales). Nunca facturas ni numeración fiscal.

Referencia

Endpoints

GET/api/v1/budgetsbudgets:read

Lista los presupuestos (documentos de tipo budget) de tu empresa, ordenados por fecha de creación descendente.

Parámetros de consulta

limitentero 1..100

Tamaño de página. Por defecto 50.

offsetentero ≥ 0

Desplazamiento para paginar. Por defecto 0.

Respuesta 200

{
  "data": [
    {
      "id": "b3f1a2c4-…",
      "budget_number": "PRES-2026-0042",
      "document_type": "budget",
      "status": "draft",
      "client_name": "ACME SL",
      "document_currency": "EUR",
      "subtotal": 1600,
      "iva_amount": 336,
      "total": 1936,
      "created_at": "2026-07-08T10:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

POST/api/v1/budgetsbudgets:write

Crea un presupuesto en borrador. Los totales (subtotal, IVA, total) se calculan en el servidor a partir de las líneas.

El endpoint de escritura solo crea presupuestos en BORRADOR (no fiscales). Nunca emite facturas, notas de crédito, numeración fiscal ni registros VeriFactu. El servidor fuerza document_type="budget" y status="draft", y recalcula los totales.

Cabeceras

Idempotency-Keycadena

Opcional (recomendado). Deduplica reintentos: la misma clave devuelve el mismo presupuesto.

Cuerpo (application/json)

client_namecadenarequerido

Nombre del cliente.

client_emailcadena

Email del cliente (opcional).

items[]arrayrequerido

Líneas: concept (req), units (req), unit_price (req), unit_type, iva_rate, discount_type, discount_value.

notescadena

Notas del presupuesto (opcional).

descriptioncadena

Descripción / introducción (opcional).

document_currencycadena

Código ISO 4217, p. ej. EUR (opcional).

validitycadena

Periodo de validez en texto libre (opcional).

cURL

curl -sS -X POST https://budget.amai.run/api/v1/budgets \
  -H "Authorization: Bearer amai_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 11111111-1111-1111-1111-111111111111" \
  -d '{
    "client_name": "ACME SL",
    "client_email": "ops@acme.example",
    "items": [
      { "concept": "Landing page", "units": 1, "unit_type": "proyecto", "unit_price": 400 },
      { "concept": "Mantenimiento", "units": 12, "unit_type": "mes", "unit_price": 100 }
    ]
  }'

Respuesta 201

{
  "id": "c7a2d9e1-…",
  "budget_number": "PRES-2026-0043",
  "status": "draft",
  "document_type": "budget",
  "subtotal": 1600,
  "iva_amount": 336,
  "total": 1936,
  "document_currency": "EUR",
  "created_at": "2026-07-08T10:05:00Z"
}

GET/api/v1/clientsclients:read

Lista los clientes guardados de tu empresa, ordenados por nombre.

Parámetros de consulta

limitentero 1..100

Tamaño de página. Por defecto 50.

offsetentero ≥ 0

Desplazamiento para paginar. Por defecto 0.

Respuesta 200

{
  "data": [
    {
      "id": "a1b2c3d4-…",
      "name": "ACME SL",
      "cif": "B12345678",
      "email": "ops@acme.example",
      "country": "ES",
      "created_at": "2026-05-01T09:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

GET/api/v1/invoicesinvoices:read

Lista tus facturas (documentos de tipo invoice). Solo lectura: este endpoint nunca toca el libro fiscal ni VeriFactu.

Parámetros de consulta

limitentero 1..100

Tamaño de página. Por defecto 50.

offsetentero ≥ 0

Desplazamiento para paginar. Por defecto 0.

Respuesta 200

{
  "data": [
    {
      "id": "f9e8d7c6-…",
      "budget_number": "FAC-2026-0007",
      "document_type": "invoice",
      "status": "issued",
      "payment_status": "paid",
      "total": 1936,
      "document_currency": "EUR",
      "created_at": "2026-06-15T12:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

Formato

Errores (RFC 9457)

Los errores se devuelven como application/problem+json con un type estable, title, status y detail. Los mensajes son genéricos: nunca filtran datos internos ni de otra empresa.

400Cuerpo inválido o document_type fiscal rechazado.

401Clave ausente, malformada, inválida o revocada.

403La clave no tiene el scope requerido.

404La API pública está deshabilitada (flag OFF).

429Límite de peticiones superado.

500Error interno.

Ejemplo 403

{
  "type": "https://budget.amai.run/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks required scope 'budgets:write'."
}

Cuotas

Límites de uso

Cada clave admite hasta 120 peticiones por minuto (ventana deslizante). Al superarlo, la API responde 429 Too Many Requests. Implementa reintentos con backoff exponencial.

Fiabilidad

Idempotencia

En las escrituras (POST) puedes enviar la cabecera Idempotency-Key con un valor único (se recomienda un UUID). Si reintentas una petición con la misma clave, la API devuelve el presupuesto ya creado en lugar de crear un duplicado — ideal para reintentos ante timeouts de red.

Especificación OpenAPI 3.1

Impórtala en Postman, Insomnia o tu generador de SDKs favorito.

openapi.json

API de AMAI Budget

Introducción

Obtener un token

Autenticación

Scopes

Endpoints

Errores (RFC 9457)

Límites de uso

Idempotencia