API de facturación

La API de Fiscalisto timbra comprobantes fiscales (CFDI 4.0) desde su servidor. Usted manda los datos de la factura en JSON; Fiscalisto llena lo que tiene un valor usual, revisa las reglas del SAT antes de gastar un timbre, la sella con el certificado del emisor, la timbra con el PAC y le contesta con la factura timbrada, su UUID, el PDF y el XML.

Los nombres de la API están en inglés, como en cualquier API (customer, items, unit_price); los textos, los errores y estas guías están en español.

Su primera factura en un minutoCopiar enlace a esta sección

1. Abra una cuenta API en Fiscalisto (selector de empresa › Nueva cuenta API). Al crearla le damos una llave de pruebas que empieza con fk_test_ y un emisor de pruebas listo para timbrar.
2. Guarde la llave en una variable de entorno de su servidor:

export FISCALISTO_API_KEY="fk_test_..."

3. Timbre una factura:

curl https://api.fiscalisto.com/v1/invoices \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Idempotency-Key: pedido-A-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "tax_id": "ICV060329BY0",
      "legal_name": "INMOBILIARIA CVA",
      "tax_system": "601",
      "zip": "33826"
    },
    "payment_form": "03",
    "items": [
      { "description": "Mensualidad", "product_key": "86121700", "quantity": 2, "unit_price": 2500 }
    ]
  }'

La respuesta es la factura timbrada (201):

{
  "id": "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg",
  "object": "invoice",
  "livemode": false,
  "status": "valid",
  "uuid": "5F1E8C2A-3B7D-4C9E-A1B2-C3D4E5F60718",
  "folio": "1",
  "subtotal": 5000,
  "taxes": { "iva": 800, "ieps": 0, "iva_withheld": 0, "isr_withheld": 0, "local_transferred": 0, "local_withheld": 0 },
  "total": 5800,
  "...": "..."
}

4. Descargue el PDF o el XML:

curl https://api.fiscalisto.com/v1/invoices/inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg/pdf \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" -o factura.pdf

No mandó el uso del CFDI, el método de pago, la moneda, la unidad, el objeto de impuesto ni el IVA: tienen su valor usual (uso G03, PUE, MXN, unidad E48, objeto 02, IVA 16%). Mande solo lo que cambia.

Con TypeScript, Python, PHP, Go, Java o C#, los SDKs le dan tipos para cada campo y la Idempotency-Key sin pensarlo:

import { Fiscalisto } from "fiscalisto";

const fiscalisto = new Fiscalisto(process.env.FISCALISTO_API_KEY);
const invoice = await fiscalisto.invoices.create({ customer, payment_form: "03", items });

Lo que necesita saberCopiar enlace a esta sección

• Pruebas y producción. Las llaves fk_test_ timbran gratis en el ambiente de pruebas del SAT; las fk_live_ timbran CFDI reales y usan un timbre cada una. Vea Pruebas y producción.
• Idempotency-Key. Todo lo que timbra la pide. Si la respuesta se pierde, repita la solicitud con la misma: nunca se timbra dos veces. Vea Idempotencia.
• Errores claros. Cada error dice qué campo corregir (param), cómo (message) y, si el SAT lo rechazó, su código (sat_code). Vea Errores.
• Webhooks. Las cancelaciones que el cliente acepta días después, las facturas que el PAC tardó en timbrar y los lotes le llegan como eventos firmados. Vea Webhooks.

Qué puede timbrarCopiar enlace a esta sección

Para agentes y herramientasCopiar enlace a esta sección

• Para que un agente de código (Claude Code, Cursor, Codex…) integre Fiscalisto, conecte el servidor MCP de esta documentación y dele la guía en una página: vea Fiscalisto para agentes de IA.
• El documento OpenAPI 3.1 completo está en https://api.fiscalisto.com/v1/openapi.json, sin llave. Cada campo tiene su descripción y su nombre en el XML del SAT.
• Cada página de estas guías existe también en Markdown: agregue .md a su dirección (por ejemplo /docs/api/idempotencia.md).
• /docs/api/llms.txt es el índice de todas las páginas, y /docs/api/llms-full.txt las guías completas en un solo archivo.