Ús · Factuarea API

L'arbre de comandes cobreix tots els recursos de l'API (factuarea <recurs> [<sub-recurs>] <acció>), generat des de l'especificació OpenAPI perquè mai es desincronitzi de la superfície real.

Llegir dades

# Llistar (amb paginació automàtica per cursor)
factuarea invoices list --json
factuarea contacts list --paginate --json

# Obtenir-ne un
factuarea invoices show <uuid> --json

--json emet el cos cru de l'API per stdout. --paginate recorre totes les pàgines per tu, seguint next_cursor fins que has_more sigui fals. Consulta Paginació per a la semàntica del cursor subjacent.

Escriure dades

Passa el cos JSON amb -d (en línia) o --data-file (una ruta). L'API calcula els totals — no els arrodoneixis per endavant.

factuarea invoices create -d '{"client_id":"…","series_id":"…","lines":[…]}'

Cada mutació rep un Idempotency-Key automàtic perquè una petició reintentada mai creï el recurs dues vegades. Consulta Idempotència.

Accions de domini

Els canvis d'estat són accions discretes, no un flag d'estat genèric — reflectint el disseny propi de l'API:

factuarea invoices send <uuid>
factuarea invoices mark-paid <uuid>

Algunes accions són irreversibles (esborrats, void, conversions, emissió fiscal). El CLI et demana confirmar-les abans de la crida — consulta Operacions irreversibles i la guia de scopes i irreversibilitat.

Control horari (fitxatges i absències)

L'add-on de control horari afegeix els recursos de jornada — empleats, horaris, fitxatges, absències, presència, festius, tancaments mensuals i el resum de gestoria. Cada comanda es genera des de l'especificació i queda protegida pel seu scope fi (employees:*, time_entries:*, absences:*, work_schedules:*, presence:read, holidays:read, payroll_exports:*).

# Fitxar entrada i sortida (cada assentament encadena la seva empremta — RD-llei 8/2019)
factuarea time-entries clock-in  -d '{"employee_id":"…","source":"web"}'
factuarea time-entries clock-out -d '{"employee_id":"…","source":"web"}'

# Sol·licitar una absència i aprovar-la
factuarea absence-requests create \
  -d '{"employee_id":"…","absence_type_id":"…","start_date":"2026-08-01","end_date":"2026-08-05"}'
factuarea absence-requests approve <uuid>

# Presència de l'equip en viu
factuarea presence live --json

# Tancar el registre mensual inalterable i exportar-lo (ITSS RD-llei 8/2019)
factuarea monthly-time-record-closes create -d '{"year":2026,"month":7}'
factuarea monthly-time-record-closes export <uuid> --format rdley_8_2019 --json

Automatitzacions

L'add-on d'automations exposa el motor de regles: una regla escolta un esdeveniment, una condició decideix si actuar, i s'executa una llista ordenada d'accions. El mòdul protegeix tot el grup, i cada comanda porta el seu scope fi — automations:read (8 comandes), automations:write (6), automation_runs:read (3) i automations:delete (1). Quatre subgrups emmirallen l'API: catalog, rules (amb rules versions), runs (amb runs steps) i usage. Consulta la guia d'automatitzacions per al model.

Comença pel catàleg. Els camps avaluables d'un activador són una segona crida, una per activador — no viatgen dins del catàleg:

# Què es pot automatitzar: activadors, operadors i accions registrades.
factuarea automations catalog show --json

# Els camps avaluables d'un activador concret.
factuarea automations catalog trigger-fields invoice.paid --json

L'alta d'una regla va pel cos JSON complet. actions és una llista d'objectes, així que no es genera cap opció tipada per a ella, i el binari es nega a barrejar opcions de camp amb -d/--data-file — tria'n una. --skeleton imprimeix la plantilla del cos sense cridar l'API:

factuarea automations rules create --skeleton

{
  "actions": [],
  "conditions": {
    "<key>": "<string>"
  },
  "description": "<string>",
  "name": "<string>",
  "scope": "<empresa|cartera>",
  "trigger_type": "<string>"
}

# Omple-la i envia-la sencera. L'`scope` es tria aquí i després no es pot canviar.
factuarea automations rules create --json -d '{
  "name": "Warn me on a large payment",
  "scope": "empresa",
  "trigger_type": "invoice.paid",
  "conditions": {"field": "total", "operator": "gte", "value": 1000},
  "actions": [
    {"type": "notify_in_app", "order": 0, "parameters": {
      "recipient_type": "role", "role": "admin", "category": "invoice",
      "title": "Large payment", "message": "An invoice over 1000 EUR has been paid"
    }}
  ]
}'

# Assaja-la contra un esdeveniment d'exemple: torna la traça per pas i no materialitza res.
factuarea automations rules dry-run <rule_id> --json \
  -d '{"event_type":"invoice.paid","event_payload":{"total":1200,"status":"paid"}}'

# Una regla neix en draft i no dispara res fins que l'actives.
factuarea automations rules activate <rule_id>
factuarea automations rules pause <rule_id>

# Llegeix-la i edita-la — cada edició segella una versió nova.
factuarea automations rules show <rule_id> --json
factuarea automations rules update <rule_id> --json -d '{"name":"Warn me on a payment over 2000"}'

# Llista-les amb filtres, recorrent el cursor per tu.
factuarea automations rules list --paginate --json
factuarea automations rules list --status active --trigger_type invoice.paid --json

# Només les regles de cartera d'una gestoria.
factuarea automations rules list --scope cartera --json

# Les versions segellades de la definició.
factuarea automations rules versions list <rule_id> --json
factuarea automations rules versions show <rule_id> 2 --json

# Què ha disparat, i què va fer cada pas.
factuarea automations runs list --paginate --json
factuarea automations runs list --automation_rule_id <rule_id> --status failed --json

# Què va fer una regla de cartera sobre una empresa gestionada concreta.
factuarea automations runs list --subject_company_id <company_id> --json
factuarea automations runs show <run_id> --json
factuarea automations runs steps list <run_id> --json

# Consum davant del pressupost del pla per al període.
factuarea automations usage show --json

Quatre llistats paginen per cursor —rules list, rules versions list, runs list i runs steps list— i --paginate recorre totes les pàgines per tu. L'historial de versions és l'únic el cursor del qual és una cadena numèrica opaca en comptes d'un UUID, perquè pagina per posició; torna el next_cursor que et van donar i no en construeixis cap a mà.

Tres comandes d'aquest grup són irreversibles i es neguen a endevinar:

# Rellançar torna a executar DE DEBÒ la feina aparcada: envia correu i entrega webhooks.
factuarea automations runs replay <run_id> --confirm <run_id>
factuarea automations runs steps replay <run_id> 0 --confirm 0

# Esborrar una regla la deixa sense disparar per sempre; les seves versions i execucions segueixen auditables.
factuarea automations rules delete <rule_id> --confirm <rule_id>

--confirm pren l'últim argument posicional de la comanda: l'id de la regla a rules delete, l'id de l'execució a runs replay i l'índex del pas a runs steps replay. Sense terminal interactiu (o amb --no-input) i sense --confirm, la comanda surt amb 2 en comptes d'endevinar. A més, tota mutació feta amb una clau fact_live_ necessita el flag explícit --live — consulta Mode de prova i Operacions irreversibles.

Descàrregues binàries i pujades

Els endpoints de PDF, ZIP i XML transmeten un binari que deses amb -o. Les pujades multipart prenen el fitxer amb un flag --file-<camp>:

# Descarregar un PDF
factuarea invoices pdf <uuid> -o invoice.pdf

# Pujar un certificat (multipart)
factuarea verifactu certificates upload \
  -d '{"certificate_password":"…"}' --file-certificate_file cert.p12

L'escape hatch `api`

Qualsevol endpoint és accessible directament amb factuarea api <mètode> <ruta>, fins i tot els que encara no tenen una comanda dedicada:

factuarea api get /v1/account --json
factuarea api post /v1/invoices -d '{…}'

El manifest de comandes

factuarea commands --json aboca el manifest complet de comandes en una sola crida — path, args, flags, si cadascuna muta, si és binària o paginada, el seu scope requerit, si és irreversible, i un exemple. Un agent descobreix tota la superfície en una sola crida:

factuarea commands --json

Consulta Agents i scripting per als camps del manifest i el contracte JSON.

Referència de l'API incrustada

Una referència ràpida de l'API viatja amb el binari — les cerques no surten de la teva màquina:

factuarea docs search invoice

docs search consulta l'especificació OpenAPI incrustada al binari i respon a «quina comanda crido?». Retorna operacions — comanda, resum, mètode i ruta — i no toca mai la xarxa.

Cercar a la documentació publicada

docs list, docs grep i docs get consulten la documentació publicada —el corpus llms-full de docs.factuarea.com— i responen a «què diu la documentació sobre això?». Retornen pàgines i seccions, de les guies, la referència de l'API i el catàleg d'errors:

factuarea docs list                    # totes les pàgines: <ruta> — <títol>
factuarea docs list /guides            # només les que pengen d'aquest prefix
factuarea docs grep "idempotency-key"  # seccions de documentació que coincideixen
factuarea docs get /guides/idempotency # la pàgina sencera, en Markdown

El corpus es descarrega sencer i una sola vegada, es desa al directori de memòria cau del sistema (~/Library/Caches/factuarea/docs/ a macOS, ~/.cache/factuarea/docs/ a Linux) i es filtra en local. Mentre la còpia tingui menys de 15 minuts, no hi ha cap petició de xarxa, així que una sessió que encadeni list, grep i get descarrega una vegada.

El teu terme de cerca no surt mai de la màquina. La URL que es demana és fixa i no depèn del que teclegis — no hi ha cap servidor de cerca a l'altre costat. Cap de les quatre subcomandes de docs llegeix ni envia una API key.

Opció	Què fa
`--refresh`	Torna a descarregar, ignorant una còpia encara vigent
`--lang`	Idioma de les guies: `en`, `es` o `ca` (per defecte `en`, l'idioma font). La referència de l'API no es tradueix i surt sempre
`--json`	Sortida estable per stdout: `path`/`title` a `list`, `path`/`title`/`section`/`snippet` a `grep`, `path`/`title`/`markdown` a `get`

Si la descàrrega falla i hi ha una còpia a la memòria cau —encara que hagi caducat—, es fa servir aquesta còpia, l'avís va a stderr perquè el JSON de stdout continuï essent parsejable, i l'exit code és 0. Sense cap còpia, l'exit code és 10 (xarxa). Apunta FACTUAREA_DOCS_URL a un altre origen per descarregar el corpus des d'allà.

Alternativa mitjançant REST

El catàleg de comandes del CLI prové del seu spec integrat. A la referència de setembre de 2026 està disponible la versió v0.2.0 i el spec de la branca principal conté 414 entrades; falten 38 endpoints REST a les comandes generades. Consulta factuarea commands --json per a la versió instal·lada. Fes servir la comanda HTTP genèrica per a un endpoint REST disponible que falti en aquest catàleg:

factuarea api get /v1/stores

Ús

En aquesta pàgina