Pruebas y producción

Su cuenta API tiene dos modos que no se mezclan: cada uno tiene sus llaves, sus emisores, sus clientes, sus facturas, sus webhooks y sus eventos. La llave con la que llama decide el modo; cada objeto lo dice en livemode.

PruebasCopiar enlace a esta sección

Al abrir su cuenta API ya tiene un emisor de pruebas y una llave fk_test_: puede timbrar en ese momento. En pruebas se aplican las mismas revisiones del SAT que en producción (catálogos, régimen contra uso, totales, complementos) y el PAC timbra en su ambiente de pruebas, así que una factura que sale bien en pruebas sale bien en producción.

Puede crear emisores de pruebas con cualquier RFC para imitar su configuración real, pero no se suben archivos: el ambiente de pruebas solo acepta el certificado de pruebas del SAT, así que todo se timbra como EKU9003173C9 (el campo stamps_as del emisor lo dice). Los clientes, en cambio, pueden ser reales o de prueba.

Pruebas es gratis, con dos cuidados: una cuenta timbra hasta 1,000 comprobantes de prueba al día (vea Límites), y los correos de las facturas de prueba solo llegan a las personas de su cuenta API, para probar send_email en su propio correo sin escribirle a sus clientes.

Provocar cada rechazo del SATCopiar enlace a esta sección

Para probar cómo responde su sistema cuando el SAT rechaza una factura, use uno de estos RFC como cliente con su llave de pruebas. La API responde 422 con invoice_rejected, el sat_code y el mensaje para su usuario, exactamente como en producción, y le llega invoice.failed a sus webhooks. Los demás datos pueden ser cualquiera; con otros RFC la factura se timbra.

curl https://api.fiscalisto.com/v1/invoices \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Idempotency-Key: prueba-rechazo-1" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "tax_id": "NOM010101FK9", "legal_name": "CLIENTE DE PRUEBA", "tax_system": "601", "zip": "33826" },
    "payment_form": "03",
    "items": [{ "description": "Consultoría", "product_key": "80101500", "unit_price": 1000 }]
  }'

Solo funcionan en pruebas: en producción esos RFC no existen y el SAT los rechaza por eso.

Probar desde la documentaciónCopiar enlace a esta sección

Cada página de la referencia tiene Probar: cambie los campos y pulse Enviar. Si entró a Fiscalisto con su cuenta API abierta (o tiene solo una) no necesita llave: la solicitud corre como esa cuenta, en pruebas, y aparece en Solicitudes como «Documentación». Si no, ponga su llave fk_test_… en Authorization. La solicitud llega a la API de verdad (timbra en pruebas, le manda eventos a sus webhooks de pruebas) y ve la respuesta completa con sus encabezados. La llave se queda solo en su navegador. Ahí no se aceptan llaves fk_live_: lo de producción se llama desde su servidor.

Empezar de ceroCopiar enlace a esta sección

Para que sus pruebas automáticas siempre arranquen igual, reinicie el modo de pruebas: cada emisor de pruebas conserva su RFC y su CSD de pruebas, y se borran sus facturas, clientes, productos, lotes, ligas y descargas, además de los eventos y las solicitudes de pruebas. Las llaves y los webhooks se quedan. Con seed (por omisión) quedan 3 clientes y 3 productos de ejemplo en cada emisor.

curl https://api.fiscalisto.com/v1/test_data/reset \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "seed": true }'

Solo con una llave fk_test_ (con fk_live_ responde test_mode_only) y hasta 20 veces al día. También está en Desarrolladores › Inicio, en Datos de prueba.

Un entorno de prueba para cada personaCopiar enlace a esta sección

Si varias personas o proyectos usan la misma cuenta, dele a cada uno su entorno de prueba: nace con su propio emisor de pruebas del SAT y una llave fk_test_ que solo ve los emisores, facturas, webhooks y eventos de ese entorno. Así el reinicio de una persona no le borra nada a otra, y su webhook no recibe los eventos de los demás. Las llaves de pruebas de la cuenta tampoco ven lo que hay en un entorno.

curl https://api.fiscalisto.com/v1/sandboxes \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ana" }'

La respuesta trae key.secret una sola vez: es la llave del entorno. Con ella, POST /v1/test_data/reset vacía solo ese entorno, y tiene sus propios 20 reinicios al día. Los entornos se crean, listan y borran con una llave de pruebas de la cuenta (una del entorno responde key_in_sandbox), hasta 25 por cuenta. Al borrar uno, sus llaves dejan de funcionar al momento. También están en Desarrolladores › Llaves, en Entornos de prueba.

Adelantar el tiempo con un reloj de pruebaCopiar enlace a esta sección

Una factura recurrente mensual, una cotización que vence o la factura global de los tickets del mes tardan semanas en pasar. Con un reloj de prueba las ve en segundos: el emisor de pruebas vive en la hora del reloj, que solo avanza cuando usted lo adelanta.

Primero el reloj, congelado ahora (o en frozen_time):

curl https://api.fiscalisto.com/v1/issuers/iss_OufpKqnrvx9p/test_clock \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Cree sus facturas recurrentes, cotizaciones o tickets como siempre, y adelántelo, por ejemplo tres meses:

curl https://api.fiscalisto.com/v1/issuers/iss_OufpKqnrvx9p/test_clock/advance \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "frozen_time": "2027-01-25T09:00:00-06:00" }'

Al adelantarlo se hace, día por día, lo que habría pasado: se timbra cada periodo de las facturas recurrentes (con {mes} y {año} de ese periodo), vencen las cotizaciones y salen las facturas globales de tickets, cada cosa con sus webhooks. La respuesta llega cuando terminó, con lo que hizo en advanced, y además llega el evento test_clock.ready.

• Mientras tenga reloj, los procesos diarios no tocan al emisor: nada pasa solo.
• El reloj llega hasta dos años adelante. Cada llamada timbra hasta 25 comprobantes; si toca más, se detiene al final de ese día con stopped_early: true, y otra llamada sigue desde ahí.
• Los CFDI se timbran con la fecha y hora reales, porque el SAT solo acepta las de hoy. El periodo, los vencimientos, amount_due y los eventos sí siguen al reloj.
• Las ligas que abren sus clientes (cotizaciones, autofactura) van con la hora real.
• DELETE /v1/issuers/iss_…/test_clock regresa al emisor a la hora real.

Solo los emisores de prueba tienen reloj, uno cada uno, y se adelanta hasta 50 veces al día.

Pasar a producciónCopiar enlace a esta sección

1. Agregue su emisor con POST /v1/issuers usando una llave de producción, o en el panel en Emisores. Los datos van tal como están en la constancia de situación fiscal.
2. Suba su CSD (certificado de sello digital: .cer, .key y contraseña) con POST /v1/issuers/{id}/certificates.
3. Firme el contrato con el PAC con la e.firma del RFC: POST /v1/issuers/{id}/efirma. Es una sola vez por RFC.
4. Tenga timbres. Al abrir su primera cuenta API recibe 20 de regalo; después compre paquetes en Desarrolladores › Timbres. Consulte los suyos con GET /v1/balance.
5. Cambie la llave de su servidor por una fk_live_ (se crea en Desarrolladores › Llaves y pide verificación en dos pasos).

El emisor está listo cuando su status es active. Mientras no lo esté, requirement dice qué falta. Vea Emisores.

Qué cuesta un timbreCopiar enlace a esta sección

Cada comprobante timbrado en producción usa un timbre: factura, complemento de pago, nota de crédito, anticipo, recibo de nómina o constancia de retenciones. Cancelar un comprobante también usa uno, solo la primera vez que el SAT acepta la solicitud. No usan timbre las solicitudes que no pasan la revisión, las que el SAT o el PAC rechazan ni las repeticiones con la misma Idempotency-Key.

Cuando ya no quedan, la API responde 402 con insufficient_balance y no timbra. Compre un paquete y repita la solicitud con la misma Idempotency-Key.

Para que no lleguen a acabarse: con pocos timbres le llega el evento balance.low a sus webhooks y un correo (la cantidad se elige en Desarrolladores › Timbres, 100 si no la cambia), y otra vez al acabarse. Ahí mismo puede activar la Recarga automática: compramos el paquete que elija con su tarjeta cuando queden los que diga, hasta las veces al mes que diga. GET /v1/balance trae ambas cosas en low_balance_at y auto_recharge. Comprar timbres no se puede con una llave de la API, a propósito: una llave filtrada no puede hacer cargos a su tarjeta.