Uso

El árbol de comandos de factuarea — list, show, create, acciones de dominio, descargas binarias, subidas multipart, el escape hatch genérico api y el manifiesto commands --json.

El árbol de comandos cubre todos los recursos de la API (factuarea <recurso> [<sub-recurso>] <acción>), generado desde la especificación OpenAPI para que nunca se desincronice de la superficie real.

Leer datos

# Listar (con paginación automática por cursor)
factuarea invoices list --json
factuarea clients list --paginate --json

# Obtener uno
factuarea invoices show <uuid> --json

--json emite el cuerpo crudo de la API por stdout. --paginate recorre todas las páginas por ti, siguiendo next_cursor hasta que has_more sea falso. Consulta Paginación para la semántica del cursor subyacente.

Escribir datos

Pasa el cuerpo JSON con -d (en línea) o --data-file (una ruta). La API calcula los totales — no los redondees por adelantado.

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

Cada mutación recibe un Idempotency-Key automático para que una petición reintentada nunca cree el recurso dos veces. Consulta Idempotencia.

Acciones de dominio

Los cambios de estado son acciones discretas, no un flag de estado genérico — reflejando el propio diseño de la API:

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

Algunas acciones son irreversibles (borrados, void, conversiones, emisión fiscal). El CLI te pide confirmarlas antes de la llamada — consulta Operaciones irreversibles y la guía de scopes e irreversibilidad.

Descargas binarias y subidas

Los endpoints de PDF, ZIP y XML transmiten un binario que guardas con -o. Las subidas multipart toman el archivo con un flag --file-<campo>:

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

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

El escape hatch `api`

Cualquier endpoint es accesible directamente con factuarea api <método> <ruta>, incluso los que aún no tienen un comando dedicado:

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

El manifiesto de comandos

factuarea commands --json vuelca el manifiesto completo de comandos en una sola llamada — path, args, flags, si cada uno muta, si es binario o paginado, su scope requerido, si es irreversible, y un ejemplo. Un agente descubre toda la superficie en una sola llamada:

factuarea commands --json

Consulta Agentes y scripting para los campos del manifiesto y el contrato JSON.

Referencia de la API embebida

Una referencia rápida de la API viaja con el binario — las búsquedas no salen de tu máquina:

factuarea docs search invoice