CLI de FactuCat

El CLI @factucat/cli 0.2.6 opera FactuCat Cloud desde la terminal. Sirve para flujos interactivos y para scripts o agentes con salida estable (--json, --no-input).

Cuándo usar el CLI (vs el SDK)

	CLI	SDK
Dónde corre	Terminal, CI, agentes	Tu app Node.js / TypeScript
Paquete	@factucat/[email protected]	@factucat/[email protected]
Ideal para	Probar, automatizar sin embeber código	Integrar timbrado dentro de tu producto

Ambos hablan con la misma API Cloud. El CLI no es un despliegue self-host.

Instalar

npm i -g @factucat/[email protected]
factucat --help

Sin instalar global:

npx @factucat/[email protected] --help

Autenticación (empieza en sandbox)

1. Regístrate o entra en sandbox.factucat.com.
2. Crea una llave fc_test_... en Configuración → API keys. El secreto completo se muestra una sola vez.
3. Guárdala en el CLI:

factucat auth api-key set
# o:
factucat auth api-key set --value fc_test_...
# o por entorno (tiene prioridad sobre la config local):
export FACTUCAT_API_KEY=fc_test_...

4. Comprueba:

factucat auth status
factucat auth status --json

Más detalle de permisos y rotación: Autenticación y permisos.

El ambiente se elige con tu llave

Igual que el SDK, si no fijas un origen el CLI usa el prefijo de la API key:

API key	Origen
fc_test_...	https://sandbox.factucat.com
fc_live_... y demás	https://factucat.com

No mezcles prefijo y ambiente. Para local u otro host, usa FACTUCAT_BASE_URL (origen sin /api/v1); ese valor tiene prioridad sobre el prefijo. Consulta Ambientes y pruebas.

Producción: llave fc_live_... desde Configuración → API keys en la cuenta productiva.

Flujo de un borrador

El servidor es la fuente de verdad. El CLI solo recuerda el borrador activo en tu máquina por comodidad.

1. Crear borrador
2. Asignar cliente o datos de receptor
3. Metadatos (uso CFDI, método/forma de pago, moneda…)
4. Conceptos
5. Previa (invoice show)
6. Timbrar (invoice stamp)
7. Descargar XML o PDF si hace falta

Comandos principales

auth api-key set | show | clear
auth status
invoice create | use <draftId> | current | show | list
invoice set-customer | set-receiver | set-meta
invoice add-item | update-item <itemId> | remove-item <itemId> | items
invoice discard | stamp | get <invoiceRef>
invoice download xml <invoiceRef>
invoice download pdf <invoiceRef>
customer list | search <query> | create

Notas útiles:

• invoice add-item puede inferir Clave SAT, unidad, IVA e ISR si los omites.
• invoice set-meta --currency USD sin --exchange-rate consulta el tipo de cambio oficial del DOF.
• invoice stamp en terminal interactiva muestra previa; puede ofrecer envío a contactos del cliente.
• invoice get y download aceptan UUID o folio.
• Para agentes y scripts: --json y, en stamp, --no-input / --draft-id.

Ejemplo rápido en sandbox

export FACTUCAT_API_KEY=fc_test_...

factucat invoice create --customer "Cliente de prueba"
factucat invoice add-item \
  --description "Servicio de consultoría" \
  --unit-price 1000
factucat invoice set-meta \
  --cfdi-use G03 \
  --payment-method PUE \
  --payment-form 03
factucat invoice show
factucat invoice stamp

Flujo HTTP equivalente (misma API): Timbrar un CFDI completo. Para agentes con skill: Desarrollo agentico.

Sin interacción (agentes / CI)

factucat invoice create --json
factucat invoice set-receiver --draft-id dft_... --json ...
factucat invoice set-meta --draft-id dft_... --json ...
factucat invoice add-item --draft-id dft_... --json ...
factucat invoice show --draft-id dft_... --json
factucat invoice stamp --draft-id dft_... --no-input --json

Si algo falla

Situación	Qué hacer
Sin API key / inválida	factucat auth api-key set y auth status
No hay borrador activo	invoice create o invoice use <draftId>
Cliente ambiguo	customer search "..." o --customer-id
plan_required en producción	En la webapp: Configuración → Suscripción (Miau Pro / FactuCat API). No hay endpoint público de upgrade. En sandbox con fc_test_... no aplica plan.

Siguiente

• SDK para TypeScript (@factucat/[email protected])
• Tu primera solicitud
• OpenAPI