API de Tributs

Visió general

L'API té dues adreces. La de comptes, accounts.tributs.ad, et diu a quines empreses tens accés. Cada empresa serveix les seves dades a la seva pròpia adreça, i aquestes dades només passen per allà.

Qualsevol usuari pot crear un token, sigui quin sigui el seu rol. Si treballes en una gestoria, un sol token llegeix totes les empreses dels teus clients.

Inici ràpid

1. Crea un token

   A Tributs, obre el teu perfil → Connexions externes → Crear token. Posa-li el nom del programa que el farà servir i tria quan caduca: 30 dies, 90 dies o 1 any. El token (trb_…) es mostra una sola vegada: copia'l en aquell moment.

2. Troba les teves empreses

   Cada empresa arriba amb el seu api_base_url, que és on llegiràs les seves dades.

   cURL Copia

   curl https://accounts.tributs.ad/api/v1/companies \
     -H "Authorization: Bearer $TRIBUTS_TOKEN"

   200 OK · application/json Copia

   {
     "data": [
       {
         "id": "acme.tributs.ad",
         "name": "Acme Serveis SL",
         "display_name": "Acme",
         "role": "advisor",
         "status": "active",
         "api_base_url": "https://acme.tributs.ad/api/v1"
       }
     ],
     "next_cursor": null,
     "has_more": false
   }

3. Llegeix dades

   Les llistes es lliuren per pàgines. Aquest exemple porta totes les factures de venda des de l'1 de gener.

   cURL Python JavaScript

   Copia

   curl "https://acme.tributs.ad/api/v1/sales_invoices?date_from=2026-01-01&limit=200" \
     -H "Authorization: Bearer $TRIBUTS_TOKEN"

Autenticació

Envia el token a la capçalera Authorization de cada petició, amb l'esquema Bearer. Totes les peticions van per HTTPS.

Authorization: Bearer trb_…

• El token és opac: trb_ seguit de 40 caràcters. Tributs en guarda només una empremta (SHA-256), així que ningú el pot tornar a veure.
• Caduca sempre: als 30 dies, als 90 dies o a l'any. T'escrivim 7 dies abans i el dia que caduca.
• Renovar genera una clau nova per al mateix token. L'anterior deixa de funcionar en menys d'un minut; el nom i l'historial es conserven.
• El pots revocar quan vulguis. La revocació arriba a totes les empreses en 60 segons com a màxim.
• Actua com tu: a cada empresa té exactament el teu rol i els teus permisos.
• Fins a 10 tokens actius per persona. Fes servir un token per a cada programa.

Paginació i sincronització

Les llistes retornen data, next_cursor i has_more. Mentre has_more sigui true, torna a cridar amb els mateixos paràmetres i cursor=<next_cursor>. limit va d'1 a 200 (50 per defecte, i 50 com a màxim amb expand=lines).

Els elements surten ordenats pel darrer canvi, del més antic al més recent. Per mantenir una còpia al dia, desa l'updated_at de l'últim element i passa'l com a updated_since la propera vegada: t'arriba el que ha canviat des de llavors. Desa els elements per id, substituint els que ja tens, perquè els de l'últim segon poden tornar a sortir.

Un document anul·lat torna a sortir amb status: "cancelled". Els esborranys no surten: només hi ha documents emesos. L'excepció són els moviments bancaris, que no s'emeten: surten sempre, i un de manual que s'elimini desapareix sense avís.

Les factures i els moviments bancaris accepten sort: total_desc (les factures de més import primer), issue_date_desc (les factures més recents primer) i date_desc (els moviments més recents primer). Un cursor només val per a l'ordre amb què es va demanar. Amb include=totals, la primera pàgina (la crida sense cursor) porta totals: quants elements compleixen els filtres i quant sumen, comptant totes les pàgines. Els anul·lats es compten a part i no sumen.

Recursos

Tots els recursos responen a GET. El contracte complet, amb cada camp i cada paràmetre, és el fitxer OpenAPI 3.1 que cada empresa serveix sense token a {api_base_url}/openapi.json. Importa'l a Postman o genera'n un client.

Les llistes paginades (tots els recursos excepte companies, bank_accounts, payroll_summary i els informes) accepten també limit i cursor, i updated_since excepte receivables i payables, que són saldos a dia d'avui.

Per llegir un sol document: GET /sales_invoices/{id}, /purchase_invoices/{id}, /contacts/{id} i /obligations/{id} (per id o per code, com ara M900-T2-2026). Les factures hi arriben sempre amb les línies, i l'obligació amb les xifres de la declaració desada (filing): resultat i desglossament per casella dels models 900, 910, 800, 805, 810, 700, 710, 310 i 311. Les retencions surten en totals, sense la relació de perceptors.

Fora de la v1: PDF i adjunts, pressupostos, albarans, subscripcions i projectes. De les persones de la plantilla no surten mai el NRT, el número d'afiliació a la CASS, l'IBAN ni la data de naixement.

Exemple de resposta

{
  "data": [
    {
      "id": "FV-26-00042",
      "number": "FV-26-00042",
      "type": "invoice",
      "status": "unpaid",
      "issue_date": "2026-10-02",
      "due_date": "2026-11-01",
      "contact_id": "Grup Ferrer SL",
      "contact_name": "Grup Ferrer SL",
      "contact_tax_id": "L712345A",
      "currency": "EUR",
      "net_amount": 1200.0,
      "tax_amount": 54.0,
      "total": 1254.0,
      "outstanding_amount": 1254.0,
      "document_currency": "EUR",
      "document_total": 1254.0,
      "exchange_rate": 1.0,
      "credited_invoice_id": null,
      "project_ids": [],
      "description": "Consultoria setembre",
      "disbursements_amount": 0.0,
      "created_at": "2026-10-02T08:14:03Z",
      "updated_at": "2026-10-02T08:14:03Z"
    }
  ],
  "next_cursor": "WyIyMDI2LTEwLTAyIDEwOjE0OjAzIiwiRlYtMjYtMDAwNDIiXQ",
  "has_more": true
}

Convencions

• JSON, amb noms de camp en anglès i en snake_case.
• Els estats són codis estables (paid, unpaid, cancelled…) i no es tradueixen.
• Les dates comptables van en format YYYY-MM-DD (calendari d'Andorra). Els moments, en RFC 3339 i UTC.
• Els imports són números amb 2 decimals en EUR, la moneda dels llibres. Els documents en moneda estrangera porten també document_currency, document_total i exchange_rate.
• Els epígrafs dels informes s'identifiquen pel seu code (Decret 479/2025). El text és l'oficial en català.
• Les xifres d'un model tributari s'identifiquen pel número de casella (box); l'etiqueta és en català, la llengua del formulari oficial.

Límits

60 peticions per minut per token i empresa, amb ràfegues de fins a 20. Un informe compta com 5, igual que bank_accounts, receivables, payables i payroll_summary. Com que el límit és per empresa, una gestoria pot llegir moltes empreses alhora; a més, cada adreça IP té un sostre global de 600 peticions per minut.

Errors

Els errors segueixen l'RFC 9457 (application/problem+json). El camp code és estable i type enllaça amb la fila corresponent d'aquesta taula.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://tributs.ad/developers#errors-expired-token",
  "title": "Access token expired",
  "status": 401,
  "code": "expired_token",
  "instance": "/api/v1/sales_invoices"
}

Excel i Power BI

A Excel o a Power BI, crea primer un paràmetre de text TributsToken amb el token (Administra els paràmetres). Després obre Obtén dades → Consulta en blanc → Editor avançat i enganxa aquesta consulta, que recorre totes les pàgines.

let
    Token = TributsToken,
    Base = "https://acme.tributs.ad/api/v1/sales_invoices",
    GetPage = (cursor as nullable text) =>
        Json.Document(Web.Contents(Base, [
            Query = if cursor = null
                then [limit = "200"]
                else [limit = "200", cursor = cursor],
            Headers = [Authorization = "Bearer " & Token]
        ])),
    Pages = List.Generate(
        () => GetPage(null),
        each _ <> null,
        each if _[has_more] then GetPage(_[next_cursor]) else null
    ),
    Rows = List.Combine(List.Transform(Pages, each _[data])),
    Invoices = Table.FromRecords(Rows)
in
    Invoices

Si et demana credencials, tria Anònim: el token ja viatja a la capçalera. L'URL base fixa i els paràmetres a Query permeten actualitzar l'informe des del servei de Power BI; allà, a les credencials de l'origen de dades, marca «Skip test connection» (omet la prova de connexió), perquè aquesta prova es fa sense token i rep un error 401. El token queda desat dins del fitxer: fes-ne servir un només per a aquest informe i comparteix el fitxer només amb qui pot veure aquestes dades.

Assistents d'IA

Un assistent d'IA (ChatGPT, Claude i altres programes compatibles amb MCP) pot llegir les mateixes dades que aquesta API, amb les mateixes consultes i els teus permisos. No cal cap token: entres amb el teu usuari de Tributs.

1. A l'assistent, afegeix un connector personalitzat amb l'adreça https://mcp.tributs.ad/mcp, amb el /mcp del final.
2. S'obre una pantalla de Tributs: entra amb el teu usuari i prem Permetre.
3. A Ajustos → Perfil → Connexions externes veus l'aplicació connectada i li pots retirar el permís.

• Només lectura. Cada recurs d'aquesta pàgina és una consulta de l'assistent, i els que s'hi afegeixin li arriben sols.
• Límit propi: 120 peticions per minut per connexió, amb ràfegues de fins a 40, a més del límit de l'API per empresa.
• Claude Code, Cursor o un programa propi que parli MCP també poden entrar amb un token: envia'l com a Authorization: Bearer trb_… a la mateixa adreça.
• El que l'assistent llegeix passa pel proveïdor que tu has triat, amb les seves condicions.

Què es pot preguntar i què veu l'empresa

Seguretat

Com protegim l'accés:

• Només lectura: cap endpoint de l'API modifica dades.
• Tributs només guarda una empremta del token (SHA-256).
• Caducitat obligatòria, i revocació i renovació des del perfil.
• Cada empresa veu qui la llegeix, i el propietari pot tallar l'accés.
• Límits per token i empresa, i HTTPS a totes les peticions.

Bones pràctiques

• Desa el token en un gestor de secrets o en una variable d'entorn. Mantén-lo fora del codi, dels repositoris i de les aplicacions que s'executen al navegador.
• Crea un token per a cada programa, amb la caducitat més curta que et vagi bé.
• Envia'l sempre a la capçalera Authorization: les URL queden als historials i als registres dels servidors.
• Si creus que s'ha filtrat, revoca'l des del perfil i crea'n un de nou. El prefix trb_ facilita que els escàners de secrets el trobin.

Per informar d'una vulnerabilitat, escriu a security@tributs.ad.

Versions

La versió va a l'URL (/api/v1/). La v1 només guanya camps: un canvi incompatible va a la v2.