Ús

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 clients 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>

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

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.

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à.