Agentes y scripting
El contrato agent-first del CLI factuarea — JSON estable por stdout, errores estructurados por stderr, exit codes semánticos, el manifiesto commands --json, scope-check local y confirmación tipada de operaciones irreversibles.
El CLI es agent-first: un asistente de IA o un script puede descubrir toda la superficie en una llamada, obtener salida estable legible por máquina, y ramificar según exit codes semánticos en lugar de parsear prosa.
Descubre la superficie en una llamada
factuarea commands --jsonEsto vuelca el manifiesto completo de comandos. Cada entrada lleva:
| Campo | Significado |
|---|---|
path | El path del comando, p. ej. invoices create. |
args | Argumentos posicionales (path params). |
flags | Flags disponibles. |
mutating | Si el comando escribe (necesita --live en producción). |
binary | Si devuelve un binario (PDF/ZIP/XML) en lugar de JSON. |
paginated | Si el comando soporta paginación por cursor. |
required_scope | El scope que la API key debe tener, p. ej. invoices:read. |
irreversible | Si la operación no se puede deshacer. |
example | Una invocación de ejemplo lista para adaptar. |
required_scope e irreversible vienen directamente de las extensiones
x-required-scope y x-irreversible de la especificación OpenAPI, así que el
CLI y la referencia de la API
coinciden por construcción.
Contrato de salida
--jsonemite el cuerpo crudo de la API por stdout.- Los errores van a stderr como JSON estructurado — el mismo
envoltorio de error que la API:
error.{type,code,message,request_id,doc_url}. - Reserva stdout para los datos y stderr para los diagnósticos: canaliza stdout
a
jq, registra stderr.
Exit codes
Ramifica según el exit code, nunca según el mensaje:
| Código | Significado |
|---|---|
0 | OK |
2 | Error de uso / guard local |
3 | Fallo de autenticación |
4 | Permiso / scope ausente |
5 | Error de validación |
6 | No encontrado |
7 | Límite de peticiones |
8 | Conflicto / idempotencia |
9 | Error del servidor |
10 | Red / timeout |
Scope-check local
Antes de una llamada, el CLI comprueba que tu key tiene el required_scope de
la operación. Si no lo tiene, el comando falla en local con exit 4 y un
mensaje claro — sin gastar un round trip que la API rechazaría con 403 de
todos modos.
- La comprobación solo corre cuando la operación declara un scope y resuelve los
scopes de la key de forma lazy (como mucho un
GET /v1/accountpor invocación, memoizado). - Un scope
*en la key cubre cualquier operación. --skip-scope-checkdegrada el bloqueo a un aviso y continúa — útil si tus scopes cacheados están desactualizados. El403real de la API sigue siendo la última línea de defensa.
Operaciones irreversibles
Las operaciones que la especificación marca x-irreversible (borrados, void,
conversiones terminales, emisión fiscal, rotación de certificado, olvido
GDPR…) piden una confirmación tipada antes de la llamada:
factuarea invoices delete <uuid> --confirm <uuid>- Pasa
--confirm <id>con el id del recurso para continuar. - En un contexto no interactivo (
--no-inputo sin TTY) sin--confirm, el comando se niega con exit2en lugar de adivinar.
Consulta la guía de scopes e irreversibilidad para la lista completa de qué operaciones llevan cada scope y cuáles son irreversibles.
¿Quieres que el agente maneje Factuarea a través de tools en lugar de comandos del CLI? Conéctalo al servidor MCP — la misma superficie expuesta como tools, con autenticación OAuth y por API key.
Devloop
Prueba los webhooks de Factuarea en local sin desplegar ni ngrok — factuarea listen reenvía los eventos de tu cuenta a localhost con un cuerpo firmado, factuarea trigger produce eventos reales en sandbox.
Paginación
Paginación por cursor con starting_after y ending_before. Sin ?page=, semántica al estilo Stripe.