API de Factuarea

L'API ve amb el teu pla

L'API pública està inclosa en tots els plans de Factuarea — sense programa beta ni add-on a banda. Durant el trial de 10 dies ja tens accés a l'API amb el tier free; els plans de pagament pugen el tier de rate limit. Consulta Límits de peticions.

Crea la teva primera API key

Obre Dashboard → Developers → API Keys i crea una clau amb els scopes que necessitis (per exemple invoices:read,contacts:read per començar). Copia el secret només un cop — no el podràs tornar a veure.

Tria l'entorn Test per obtenir una clau fact_test_ que opera sobre un sandbox aïllat sense efectes en el món real. Crea contra ell primer i després crea una clau fact_live_ per passar a producció. Consulta Mode de prova i sandbox.

Verifica la teva clau

Abans de res, confirma que la clau funciona. GET /v1/me introspecciona la credencial i no necessita cap scope: qualsevol clau vàlida es pot consultar a si mateixa. Retorna el compte al qual pertany la clau (el seu entorn, si és proveïdor de comptes i els scopes privilegiats que Factuarea li va concedir), els scopes i el tier de límit de peticions de la mateixa clau, els NIF que assoleix i, amb una clau de proveïdor, els comptes dels teus clients que el teu compte assoleix. L'id de cada NIF és el segment {company} de tota ruta de l'eix d'empresa:

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

Hauries de veure un 200 amb una instantània de me. Aquesta és la d'una clau live d'un proveïdor de comptes, així que tots els blocs vénen omplerts:

{
  "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 és el compte de la clau. El seu id és el segment {account} de les rutes de compte, i is_provider indica si aprovisiona comptes gestionats per als seus clients.
• scope llista els NIF que assoleix la clau, cadascun amb el seu id, el seu tax_id i el seu name. Sempre s'enumeren, també quan n'hi ha un de sol.
• client_accounts llista els comptes dels teus clients que el teu compte assoleix: granted quan et van cedir accés, provisioned quan els vas aprovisionar i encara els gestiones. Només s'omple quan la clau porta l'scope privilegiat accounts:read; si no, torna buida i client_accounts_visible és false.

Si obtens 401 invalid_api_key, torna a comprovar el valor. L'array scopes et diu exactament què pot fer aquesta clau — una crida posterior que falli amb 403 insufficient_scope no en té algun. Cada camp està descrit a Comptes i NIF.

Fes la teva primera petició de dades

Ara llista un recurs real. GET /v1/companies/{company}/contacts retorna un embolcall estàndard amb data (resultats), has_more i next_cursor (paginació per cursor). Substitueix {company} per l'id d'un dels NIF de scope — un de propi, un al qual un altre compte t'ha cedit accés o un d'un compte gestionat, com explica Arribar a un NIF — i filtra per rol. Un mateix contacte acumula els rols customer i supplier que li pertoquin:

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

Llest per emetre la teva primera factura de principi a fi? Segueix l' Inici ràpid. Si reps un error, cerca'l a Errors pel code retornat.

Configura webhooks (opcional)

Si la teva integració necessita reaccionar a esdeveniments (factura pagada, pressupost acceptat, etc.), configura un webhook endpoint signat amb HMAC SHA256. Consulta Webhooks.