API de Factuarea

La API viene con tu plan

La API pública está incluida en todos los planes de Factuarea — sin programa beta ni add-on aparte. Durante el trial de 10 días ya tienes acceso a la API con el tier free; los planes de pago suben el tier de rate limit. Consulta Límites de peticiones.

Crea tu primera API key

Abre Dashboard → Developers → API Keys y crea una clave con los scopes que necesites (por ejemplo invoices:read,contacts:read para empezar). Copia el secreto una sola vez — no podrás volver a verlo.

Elige el entorno Test para obtener una clave fact_test_ que opera sobre un sandbox aislado sin efectos en el mundo real. Crea contra él primero y luego crea una clave fact_live_ para pasar a producción. Consulta Modo de prueba y sandbox.

Verifica tu clave

Antes que nada, confirma que la clave funciona. GET /v1/me introspecciona la credencial y no necesita ningún scope: cualquier clave válida puede consultarse a sí misma. Devuelve la cuenta a la que pertenece la clave (su entorno, si es proveedor de cuentas y los scopes privilegiados que Factuarea le concedió), los scopes y el tier de límite de peticiones de la propia clave, los NIF que alcanza y, con una clave de proveedor, las cuentas de tus clientes a las que llega tu cuenta. El id de cada NIF es el segmento {company} de toda ruta del eje de empresa:

curl https://api.factuarea.com/v1/me \
  -H "Authorization: Bearer fact_test_xxxxxxxxxxxxxxxxxxxxxxxx"

Deberías ver un 200 con una instantánea de me. Esta es la de una clave live de un proveedor de cuentas, así que todos los bloques vienen rellenos:

{
  "data": {
    "object": "me",
    "account": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00",
      "name": "Asesoría Martínez",
      "environment": "live",
      "is_provider": true,
      "privileged_scopes": [
        "accounts:read",
        "accounts:write"
      ]
    },
    "api_key": {
      "id": "019e81ef-e1d4-7208-a51d-94c2c2a54a84",
      "name": "Producción",
      "prefix": "fact_live_1OSf9KdP",
      "scopes": [
        "account:read",
        "series:read",
        "series:write"
      ],
      "tier": "scale",
      "environment": "live",
      "created_at": "2026-01-15T09:30:00Z",
      "last_used_at": "2026-05-25T18:00:00Z",
      "expires_at": null
    },
    "scope": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
        "tax_id": "B12345674",
        "name": "Acme Corporation"
      },
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
        "tax_id": "B87654323",
        "name": "Acme Logística S.L."
      }
    ],
    "client_accounts": [
      {
        "id": "0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f",
        "name": "Construcciones Ruiz",
        "origin": "granted",
        "access_level": "view",
        "status": "active",
        "paid_by_provider": false,
        "environment": "live"
      },
      {
        "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
        "name": "Talleres García",
        "origin": "provisioned",
        "access_level": "operate",
        "status": "provisioned",
        "paid_by_provider": true,
        "environment": "live"
      }
    ],
    "client_accounts_visible": true,
    "client_accounts_has_more": false
  }
}

• account es la cuenta de la clave. Su id es el segmento {account} de las rutas de cuenta, e is_provider indica si aprovisiona cuentas gestionadas para sus clientes.
• scope lista los NIF que alcanza la clave, cada uno con su id, su tax_id y su name. Siempre se enumeran, también cuando solo hay uno.
• client_accounts lista las cuentas de tus clientes que tu cuenta alcanza: granted cuando te cedieron acceso, provisioned cuando las aprovisionaste y las sigues gestionando. Solo se rellena cuando la clave lleva el scope privilegiado accounts:read; si no, vuelve vacía y client_accounts_visible es false.

Si obtienes 401 invalid_api_key, vuelve a comprobar el valor. El array scopes te dice exactamente qué puede hacer esta clave — una llamada posterior que falle con 403 insufficient_scope carece de alguno de ellos. Cada campo está descrito en Cuentas y NIF.

Haz tu primera petición de datos

Ahora lista un recurso real. GET /v1/companies/{company}/contacts devuelve un envoltorio estándar con data (resultados), has_more y next_cursor (paginación por cursor). Sustituye {company} por el id de uno de los NIF de scope — uno propio, uno al que otra cuenta te cedió acceso o uno de una cuenta gestionada, como explica Alcanzar un NIF — y filtra por rol. Un mismo contacto acumula los roles customer y supplier que le correspondan:

curl "https://api.factuarea.com/v1/companies/{company}/contacts?roles[]=customer" \
  -H "Authorization: Bearer fact_test_xxxxxxxxxxxxxxxxxxxxxxxx"

¿Listo para emitir tu primera factura de principio a fin? Sigue el Inicio rápido. Si recibes un error, búscalo en Errores por el code devuelto.

Configura webhooks (opcional)

Si tu integración necesita reaccionar a eventos (factura pagada, presupuesto aceptado, etc.), configura un webhook endpoint firmado con HMAC SHA256. Consulta Webhooks.