API de Factuarea

L'API REST de Factuarea exposa recursos de facturació (contactes, productes, factures, pressupostos, factures proforma, albarans, factures recurrents, factures de compra) sobre HTTPS amb autenticació per API key. Tota la superfície pública viu a https://api.factuarea.com/v1 i retorna principalment JSON. Les descàrregues fan servir el format XML, CSV o binari declarat per cada endpoint; les respostes 204 i 304 no tenen cos. Els recursos exposen un id opac, generalment un UUID v7; els identificadors del proveïdor es documenten per separat.

Inici ràpid — la teva primera factura en 5 minuts

Una seqüència de copiar i enganxar contra una clau fact_test_: verifica la teva clau, obtén una sèrie i un impost, crea un contacte, emet una factura i envia-la.

Inici ràpid

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/account introspecciona la credencial — retorna l'empresa a què pertany, el pla, i els scopes i el tier de límit de peticions de la mateixa clau (necessita account:read):

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

Hauries de veure un 200 amb una instantània d'account:

{
  "data": {
    "object": "account",
    "company": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Soluciones SL",
      "tax_id": "B12345678"
    },
    "plan": { "slug": "empresario", "name": "Empresario" },
    "api_key": {
      "id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
      "name": "Sandbox integration",
      "prefix": "fact_test_3pXnR2Vb",
      "scopes": ["account:read", "contacts:read", "invoices:read"],
      "tier": "starter"
    }
  }
}

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.

Fes la teva primera petició de dades

Ara llista un recurs real. GET /v1/contacts retorna un embolcall estàndard amb data (resultats), has_more i next_cursor (paginació per cursor):

curl https://api.factuarea.com/v1/contacts \
  -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.

Què cobreix l'API

Contactes

Una identitat, rols acumulables customer/supplier/lead, perfils, importació i arxivat/desarxivat.

Catàleg

Productes i serveis amb estoc decimal, unitats UNECE, presentacions, variants, ofertes de proveïdor i tarifes per client.

Documents de venda

Factures, pressupostos, factures proforma, albarans, factures recurrents — amb línies, retencions i recàrrec d'equivalència.

Accions de document

Enviar per email, marcar com a pagada/acceptada, generar PDF, anul·lar, crear factura rectificativa, convertir entre tipus.

Compres

Factures de proveïdor amb pujada de PDF, mark_paid, mark_received.

Sèries de documents

Sèries de numeració legal per tipus de document (de només lectura via API per garantir la continuïtat fiscal).

Facturació FACe (B2G)

Descàrrega de l'XML FacturaE 3.2.2 i enviaments a FACe — envia, segueix l'estat de tramitació i sol·licita anul·lacions.

Control horari

Empleats, horaris de treball, el registre de fitxatges, tancaments mensuals, absències, presència i festius — el registre de jornada del RD-ley 8/2019.

Automatitzacions

Regles dirigides per esdeveniments — un esdeveniment activa, una condició decideix i s'executa una llista ordenada d'accions, amb versions segellades, assaig i historial d'execucions.

Servidor MCP per a agents d'IA

Tota l'API com a 457 eines Model Context Protocol, amb OAuth 2.1 i autenticació per API key — connecta Claude i altres agents en segons.

Disseny del contracte

L'API segueix els patrons que esperaries d'un proveïdor modern:

Identificadors opacs — els recursos solen fer servir strings UUID v7. L'esborrament de dades de signatures conserva un ID d'auditoria numèric, i els identificadors externs fan servir el format del seu proveïdor. Consulta Paginació per a la semàntica del cursor.
Errors normalitzats — cada error retorna un embolcall amb type, code, message, param, doc_url i request_id. Consulta Errors.
Idempotency keys — suportades a cada POST per evitar duplicats en els reintents. Consulta Idempotència.
Límits de peticions per tier — quotes per minut i mensuals, amb capçaleres X-RateLimit-* a cada resposta. Consulta Límits de peticions.
Versionat per URL — /v1/*. Els canvis incompatibles disparen /v2/* amb una política de deprecació documentada. Consulta Versionat.
Webhooks amb rotació de doble secret — HMAC SHA256, reintent exponencial amb fins a 8 intents. Consulta Webhooks.

SDKs

Oferim SDKs oficials de TypeScript i PHP (@factuarea/sdk i factuarea/factuarea-php) amb reintents, idempotència, paginació per cursor, errors tipats i verificació de webhooks integrats. Si el teu llenguatge no està cobert, qualsevol client HTTP estàndard (curl, Postman, axios, requests, Guzzle) funciona — l'API és REST pla sobre JSON.

L'API REST pública complementa el client web de Factuarea (app.factuarea.com) — no el reemplaça. Les operacions que l'API no exposa (gestió de plans, branding, configuració fiscal global de l'empresa) segueixen vivint a l'app.

Integracions i fluxos guiats

Connecta botigues, configura WooCommerce o Shopify i consumeix esdeveniments amb n8n. Comença per l’índex d’integracions. Per al correu, consulta enviament de documents; per a agents, el protocol MCP i els recursos fiscals i prompts.