Ús · Factuarea API

L'arbre de comandes de factuarea — list, show, create, accions de domini, descàrregues binàries, pujades multipart, l'escape hatch genèric api i el manifest commands --json.

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>

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.

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

Ús