Agents i scripting
El contracte agent-first del CLI factuarea — JSON estable per stdout, errors estructurats per stderr, exit codes semàntics, el manifest commands --json, scope-check local i confirmació tipada d'operacions irreversibles.
El CLI és agent-first: un assistent d'IA o un script pot descobrir tota la superfície en una crida, obtenir sortida estable llegible per màquina, i ramificar segons exit codes semàntics en lloc de parsejar prosa.
Descobreix la superfície en una crida
factuarea commands --jsonAixò aboca el manifest complet de comandes. Cada entrada porta:
| Camp | Significat |
|---|---|
path | El path de la comanda, p. ex. invoices create. |
args | Arguments posicionals (path params). |
flags | Flags disponibles. |
mutating | Si la comanda escriu (necessita --live en producció). |
binary | Si retorna un binari (PDF/ZIP/XML) en lloc de JSON. |
paginated | Si la comanda suporta paginació per cursor. |
required_scope | El scope que l'API key ha de tenir, p. ex. invoices:read. |
irreversible | Si l'operació no es pot desfer. |
example | Una invocació d'exemple llesta per adaptar. |
required_scope i irreversible vénen directament de les extensions
x-required-scope i x-irreversible de l'especificació OpenAPI, així que el CLI
i la referència de l'API
coincideixen per construcció.
Contracte de sortida
--jsonemet el cos cru de l'API per stdout.- Els errors van a stderr com a JSON estructurat — el mateix
embolcall d'error que l'API:
error.{type,code,message,request_id,doc_url}. - Reserva stdout per a les dades i stderr per als diagnòstics: canalitza stdout
a
jq, registra stderr.
Exit codes
Ramifica segons l'exit code, mai segons el missatge:
| Codi | Significat |
|---|---|
0 | OK |
2 | Error d'ús / guard local |
3 | Error d'autenticació |
4 | Permís / scope absent |
5 | Error de validació |
6 | No trobat |
7 | Límit de peticions |
8 | Conflicte / idempotència |
9 | Error del servidor |
10 | Xarxa / timeout |
Scope-check local
Abans d'una crida, el CLI comprova que la teva key té el required_scope de
l'operació. Si no el té, la comanda falla en local amb exit 4 i un missatge
clar — sense gastar un round trip que l'API rebutjaria amb 403 de tota manera.
- La comprovació només corre quan l'operació declara un scope i resol els scopes
de la key de manera lazy (com a molt un
GET /v1/accountper invocació, memoïtzat). - Un scope
*a la key cobreix qualsevol operació. --skip-scope-checkdegrada el bloqueig a un avís i continua — útil si els teus scopes en cache estan desactualitzats. El403real de l'API segueix sent l'última línia de defensa.
Operacions irreversibles
Les operacions que l'especificació marca x-irreversible (esborrats, void,
conversions terminals, emissió fiscal, rotació de certificat, oblit GDPR…)
demanen una confirmació tipada abans de la crida:
factuarea invoices delete <uuid> --confirm <uuid>- Passa
--confirm <id>amb l'id del recurs per continuar. - En un context no interactiu (
--no-inputo sense TTY) sense--confirm, la comanda es nega amb exit2en lloc d'endevinar.
Consulta la guia de scopes i irreversibilitat per a la llista completa de quines operacions porten cada scope i quines són irreversibles.
Vols que l'agent manegi Factuarea a través de tools en lloc de comandes del CLI? Connecta'l al servidor MCP — la mateixa superfície exposada com a tools, amb autenticació OAuth i per API key.
Devloop
Prova els webhooks de Factuarea en local sense desplegar ni ngrok — factuarea listen reenvia els esdeveniments del teu compte a localhost amb un cos signat, factuarea trigger produeix esdeveniments reals en sandbox.
Paginació
Paginació per cursor amb starting_after i ending_before. Sense ?page=, semàntica a l'estil Stripe.