Desarrollo agentico con FactuCat

Factura desde tu agente de código. Usa FactuCat desde Cursor, Claude Code u otro agente con skills. La skill factucat-integration le enseña el flujo real: sandbox primero, llave fc_test_, emitir solo cuando tú lo pidas.

Por qué instalar la skill

Sin ella, el agente improvisa endpoints, apunta a producción o pide tarjeta antes de tiempo. Con ella:

• Arranca en sandbox (https://sandbox.factucat.com), no en producción.
• Crea o usa una llave fc_test_… y comprueba la conexión con GET /me.
• Respeta el flujo customer → draft → meta → items → revisión → timbrar (tú autorizas).
• Enlaza las guías oficiales en lugar de inventar rutas.

Pasos cortos

1. Cuenta de pruebas. Regístrate en sandbox. No necesitas tarjeta para la primera solicitud.
2. API key. En Configuración → API keys crea una llave fc_test_… y guárdala como FACTUCAT_API_KEY.
3. Instala la skill.

npx skills add factucat/ai-skills --skill factucat-integration

Alternativa (manifiesto): npx copia SKILL.md y references/. Si solo haces curl del SKILL.md, descarga también la carpeta references/ del repo.

curl -fsSL https://raw.githubusercontent.com/factucat/ai-skills/main/factucat-integration/SKILL.md -o factucat-integration.SKILL.md

4. URL de pruebas.

export FACTUCAT_API_URL='https://sandbox.factucat.com/api/v1'

5. Universal Starter. Pide a tu agente el prompt de abajo: explorar docs + tu codebase e integrar en el repo. No timbrar hasta que tú lo autorices. (GET /me queda como check opcional.)

Detalle del alta sin tarjeta: Tu primera solicitud. Ambientes: Ambientes y pruebas.

Universal Starter Prompt

Copia esto en el chat de tu agente (con la skill instalada). Es la pieza principal: explorar recursos + tu codebase e integrar. No timbrar hasta que tú lo autorices.

Quiero integrar FactuCat en mi codebase — API de facturación CFDI 4.0 para México.

## Recursos FactuCat

**Docs:**
- Docs: https://docs.factucat.com
- Primeros pasos: https://docs.factucat.com/guias/primeros-pasos/
- Emitir factura: https://docs.factucat.com/guias/emitir-factura/
- Ambientes: https://docs.factucat.com/guias/ambientes/
- SDK TypeScript: https://docs.factucat.com/guias/sdk/
- Referencia OpenAPI: https://docs.factucat.com/api/
- Spec: https://docs.factucat.com/openapi.json

**Skill (instálala antes):**
- factucat-integration: npx skills add factucat/ai-skills --skill factucat-integration
- Con la skill instalada, **léela** (`SKILL.md`) **y sus** `references/` antes de cablear endpoints.
- Starter canónico de la skill (sandbox + PUE): https://github.com/factucat/ai-skills/blob/main/factucat-integration/SKILL.md

**Sandbox:**
- App: https://sandbox.factucat.com
- API: https://sandbox.factucat.com/api/v1
- Llaves de prueba: prefijo fc_test_ (sin tarjeta para la primera solicitud)

## Qué es FactuCat

FactuCat es una API para emitir CFDI en México. En sandbox usas fc_test_ sin tarjeta. El flujo PUE es customer → draft (con customerId) → meta → items → revisión → stamp; solo timbra cuando yo lo autorice. No inventes endpoints ni uses producción como default.

## Arquitectura mínima

- Auth: header X-API-Key (o SDK @factucat/sdk con FACTUCAT_API_KEY)
- Sandbox vs prod: fc_test_ → sandbox; fc_live_ → prod (el origen sigue el prefijo de la llave)
- Flujo PUE: POST /customers → POST /invoice-drafts (customerId) → PATCH .../meta → POST .../items → GET draft → POST .../stamp
- Antes de inventar rutas: lee la skill factucat-integration y sus references/ (stamp-flow, environments, idempotency, errors)
- Guías: primeros-pasos, emitir-factura, skill factucat-integration

## Cierre

Explora los recursos de arriba y mi codebase. Pregúntame stack, qué quiero facturar y cuándo emitir. Luego intégralo en el repo (cliente o SDK + env). No timbres nada hasta que yo lo diga.

Check rápido (opcional): GET /me

Si solo quieres validar la llave en sandbox: pide GET /me y para ahí (sin borrador ni timbre). No es el prompt estrella.

Después: integrar en tu codebase

Cuando el starter termine (o tras un GET /me OK), el siguiente paso es cablear FactuCat en el repo:

1. FACTUCAT_API_KEY (fc_test_) en el entorno del proyecto.
2. Cliente HTTP o @factucat/sdk con el flujo customer → draft → meta → items → revisión → timbrar solo si tú autorizas.
3. Contrato de emisión: Cómo timbrar un CFDI completo.

Sandbox

• App: https://sandbox.factucat.com
• API: https://sandbox.factucat.com/api/v1
• Llaves de prueba: prefijo fc_test_
• Los timbres de sandbox no son fiscales y no se cobran.

Producción (cuenta real, CSD, plan con API) va en primeros-pasos «Pasa a producción» y Ambientes. No uses el fallback de producción en los ejemplos.

Sandbox y fc_test_... no exigen plan de pago. Antes de timbrar en producción, consulta GET /me. Si responde 403 plan_required, indica a la persona que active Miau Pro o FactuCat API en Configuración → Suscripción. No hay un endpoint público para subir de plan.