Tickets
Un ticket es una venta ya pagada que tu punto de venta registra en Fiscalapi para Auto CFDI. Al registrarlo recibes un código y la URL de su QR, que imprimes en el comprobante de la venta: con ellos tu cliente genera su factura en el portal de autofactura. Lo que tus clientes no facturan lo incluyes en la factura global de tickets.
Registrar un ticket exige Auto CFDI en tu suscripción y consume 1 crédito de ticket de la persona autenticada, aunque el ticket nunca se facture. Consultar tus tickets no exige Auto CFDI: si das de baja el módulo, sigues viendo los que registraste.
Cada ticket pertenece a una persona emisora de tu cuenta y guarda los conceptos e impuestos de la venta con los mismos nombres que Crear factura. Fiscalapi valida su estructura, los catálogos del SAT y que el total cuadre al centavo; los impuestos que declaras son tu responsabilidad.
Estados del ticket
El estado de un ticket viaja como texto en camelCase en el campo status. Solo un ticket en estado pending se autofactura, entra a una factura global o se cancela.
| Estado | Qué significa |
|---|---|
pending | Sin factura: tu cliente lo puede autofacturar o tú lo incluyes en una global. |
invoicing | Tu cliente lo está timbrando en el portal. |
invoiced | Tiene su factura individual, en invoiceId. |
globalizing | Una factura global lo está timbrando. |
globalized | Está en una factura global, en globalInvoiceId. |
cancelled | Lo cancelaste antes de facturarlo. Es final y libera su serie y folio. |
Pueden aparecer estados nuevos: trata un valor desconocido como un ticket que no puedes facturar todavía.
Modelo ticket
El modelo ticket (Ticket) es el que devuelven Listar tickets y Obtener ticket por ID. Los conceptos solo vienen con details=true, y la historia, solo en el detalle.
Propiedades
- Name
id- Type
- string?
- Description
ID del ticket asignado por Fiscalapi.
- Name
personId- Type
- string?
- Description
ID de la persona emisora del ticket.
- Name
folio- Type
- string?
- Description
Folio del punto de venta. No es el folio del CFDI: en la factura global va como
itemSku(NoIdentificacion).
- Name
series- Type
- string?
- Description
Serie del punto de venta, o
nullsi el ticket no tiene serie.
- Name
paymentDate- Type
- string?
- Description
Fecha y hora del pago en hora civil de México, sin zona, tal como la envió el punto de venta.
- Name
paymentFormCode- Type
- string?
- Description
Forma de pago. Catálogo del SAT
c_FormaPago.
- Name
currencyCode- Type
- string?
- Description
Moneda de la venta. Catálogo del SAT
c_Moneda.
- Name
exchangeRate- Type
- number | decimal?
- Description
Tipo de cambio de la venta, o
nullen una venta en MXN.
- Name
expeditionZipCode- Type
- string?
- Description
Código postal del lugar de expedición.
- Name
subtotal- Type
- number | decimal?
- Description
Subtotal calculado por Fiscalapi.
- Name
totalTransferredTaxes- Type
- number | decimal?
- Description
Total de impuestos trasladados calculado por Fiscalapi.
- Name
totalWithheldTaxes- Type
- number | decimal?
- Description
Total de impuestos retenidos calculado por Fiscalapi.
- Name
total- Type
- number | decimal?
- Description
Total de la venta. Cuadra al centavo con el calculado.
- Name
status- Type
- string?
- expandible
- Description
Estado del ticket. Ver Estados del ticket.
- Type
- enum:
- Values
- "pending""invoicing""invoiced"
- Name
selfInvoiceEligible- Type
- boolean?
- Description
truesi hoy tu cliente puede autofacturarlo: el ticket está enpendingy su ventana de autofactura sigue abierta. Se calcula al consultar, con la configuración vigente.
- Name
eligibleUntil- Type
- string?
- Description
Último momento de la ventana de autofactura, o
nullsi la ventana no cierra. Se calcula al consultar.
- Name
invoiceId- Type
- string?
- Description
ID de la factura individual del ticket, o
null.
- Name
globalInvoiceId- Type
- string?
- Description
ID de la factura global que ampara el ticket, o
null.
- Name
createdAt- Type
- string?
- Description
Fecha y hora en que se registró el ticket.
- Name
items- Type
- array of objects (TicketItem)?
Conceptos de la venta con sus impuestos. Solo con
details=true.- Name
itemCode- Type
- string?
- Description
Clave del producto o servicio. Catálogo del SAT
c_ClaveProdServ.
- Name
itemSku- Type
- string?
- Description
Identificador del producto en tu punto de venta.
- Name
quantity- Type
- number | decimal?
- Description
Cantidad vendida.
- Name
unitOfMeasurementCode- Type
- string?
- Description
Unidad de medida. Catálogo del SAT
c_ClaveUnidad.
- Name
description- Type
- string?
- Description
Descripción del producto o servicio.
- Name
unitPrice- Type
- number | decimal?
- Description
Valor unitario sin impuestos.
- Name
discount- Type
- number | decimal?
- Description
Descuento del concepto.
- Name
taxObjectCode- Type
- string?
- Description
Objeto de impuesto. Catálogo del SAT
c_ObjetoImp.
- Name
itemTaxes- Type
- array of objects (TicketItemTax)?
Impuestos del concepto.
- Name
taxCode- Type
- string?
- Description
Impuesto. Catálogo del SAT
c_Impuesto.
- Name
taxTypeCode- Type
- string?
- Description
Tipo de factor: Tasa, Cuota o Exento.
- Name
taxRate- Type
- number | decimal?
- Description
Tasa o cuota del impuesto.
- Name
taxFlagCode- Type
- string?
- Description
Traslado (T) o retención (R).
- Name
events- Type
- array of objects (TicketEvent)?
Historia del ticket en orden. Solo en Obtener ticket por ID con
details=true.- Name
type- Type
- string?
- Description
Hecho registrado; por ejemplo,
ingested,invoicedocancelled. Pueden aparecer tipos nuevos.
- Name
occurredAt- Type
- string?
- Description
Fecha y hora del hecho.
- Name
actorType- Type
- string?
- Description
Quién lo provocó:
tenant(tu cuenta),portal(tu cliente en el portal) osystem(un proceso de Fiscalapi).
- Name
invoiceId- Type
- string?
- Description
ID de la factura del hecho, o
null.
Crear ticket
Este endpoint registra una venta pagada y consume 1 crédito de ticket de la persona autenticada. Responde 201 con el código del ticket y la URL de su QR. El CFDI que facture el ticket es versión 4.0, de ingreso, con método de pago PUE y sin exportación.
Antes de cobrar, Fiscalapi revisa que la persona emisora sea de tu cuenta, que tenga completos sus datos fiscales, un CSD vigente y timbres, porque cada autofactura consume un timbre de su saldo. También revisa que el pago no sea posterior a ahora por más de 5 minutos y que el total cuadre al centavo con el calculado.
Encabezado Idempotency-Key
El encabezado Idempotency-Key es opcional. Con la misma llave de idempotencia y el mismo cuerpo, el endpoint no registra otro ticket ni cobra otra vez: devuelve la respuesta original con el encabezado Idempotent-Replayed en true. Las reglas son las de Solicitudes idempotentes.
El emisor solo puede tener un ticket activo con la misma serie y folio: un duplicado responde 409 con el ticket que ya los tiene en data.existingTicketId, sin cobrar. Para volver a registrar ese folio, cancela el ticket existente y regístralo de nuevo con otra llave de idempotencia, lo que consume otro crédito.
Modelo
- Name
issuer- Type
- object (TicketIssuer)
- required
Persona emisora, por referencia.
- Name
id- Type
- string
- required
- Description
ID de la persona emisora de tu cuenta que facturará el ticket.
- Name
folio- Type
- string
- required
- Description
Folio del punto de venta, de 1 a 40 caracteres y sin el carácter de barra vertical.
- Name
series- Type
- string?
- Description
Serie del punto de venta, de 1 a 25 caracteres y sin el carácter de barra vertical. Si la omites, el ticket queda sin serie.
- Name
paymentDate- Type
- string
- required
- Description
Fecha y hora del pago con el formato yyyy-MM-ddTHH:mm:ss, en hora civil de México. Este campo no usa el encabezado
X-TIME-ZONE.
- Name
paymentFormCode- Type
- string
- required
- Description
Forma de pago con la que se liquidó la venta. Catálogo del SAT
c_FormaPago. No admite"99"(por definir).
- Name
currencyCode- Type
- string?
- Description
Moneda de la venta. Catálogo del SAT
c_Moneda. No admite"XXX".Default:MXN
- Name
exchangeRate- Type
- number | decimal?
- Description
Tipo de cambio de la venta. Con MXN se omite o se envía
null; con otra moneda es obligatorio y mayor que 0.
- Name
expeditionZipCode- Type
- string?
- Description
Código postal de expedición, de 5 dígitos. Si lo omites, se usa el de la persona emisora.
- Name
total- Type
- number | decimal
- required
- Description
Total que cobró el punto de venta. Debe cuadrar al centavo con el total calculado de los conceptos e impuestos.
- Name
items- Type
- array of objects (TicketItem)
- required
Conceptos de la venta, de 1 a 1,500.
- Name
itemCode- Type
- string
- required
- Description
Clave del producto o servicio, de 8 caracteres. Catálogo del SAT
c_ClaveProdServ.
- Name
itemSku- Type
- string
- required
- Description
Identificador del producto en tu punto de venta.
- Name
quantity- Type
- number | decimal
- required
- Description
Cantidad vendida, mayor que 0 y con hasta 6 decimales.
- Name
unitOfMeasurementCode- Type
- string
- required
- Description
Unidad de medida. Catálogo del SAT
c_ClaveUnidad.
- Name
description- Type
- string
- required
- Description
Descripción, de 1 a 1000 caracteres y sin el carácter de barra vertical.
- Name
unitPrice- Type
- number | decimal
- required
- Description
Valor unitario sin impuestos, con hasta 6 decimales.
- Name
discount- Type
- number | decimal?
- Description
Descuento del concepto, con hasta 6 decimales.
Default:0
- Name
taxObjectCode- Type
- string
- required
- Description
Objeto de impuesto. Catálogo del SAT
c_ObjetoImp. Con 02 el concepto lleva al menos un impuesto; con 01, 03, 04 o 05 no lleva impuestos.
- Name
itemTaxes- Type
- array of objects (TicketItemTax)?
Impuestos del concepto, con los mismos campos que los de una factura. Si el concepto no lleva impuestos, omítelo o envía una lista vacía.
- Name
taxCode- Type
- string
- required
- Description
Impuesto. Catálogo del SAT
c_Impuesto.
- Name
taxTypeCode- Type
- string
- required
- Description
Tipo de factor: Tasa, Cuota o Exento.
- Name
taxRate- Type
- number | decimal
- required
- Description
Tasa o cuota del impuesto; por ejemplo,
"0.160000".
- Name
taxFlagCode- Type
- string
- required
- Description
Traslado (T) o retención (R).
Respuesta
Una repetición con la misma llave de idempotencia devuelve el mismo cuerpo y el mismo 201, con el encabezado Idempotent-Replayed.
- Name
id- Type
- string?
- Description
ID del ticket.
- Name
ticketCode- Type
- string?
- Description
Código del ticket sin guiones, de 12 caracteres. Imprímelo en grupos de 4 separados por guiones; el portal acepta ambas formas.
- Name
qrUrl- Type
- string?
- Description
URL del portal que abre el ticket. Imprímela como código QR en el comprobante de la venta. Ver Código y QR.
- Name
status- Type
- string?
- Description
Estado del ticket; al registrarlo,
pending.
- Name
selfInvoiceEligible- Type
- boolean?
- Description
truesi hoy tu cliente puede autofacturarlo.
- Name
eligibleUntil- Type
- string?
- Description
Último momento de la ventana de autofactura, o
nullsi la ventana no cierra.
- Name
subtotal- Type
- number | decimal?
- Description
Subtotal calculado.
- Name
totalTransferredTaxes- Type
- number | decimal?
- Description
Total de impuestos trasladados calculado.
- Name
totalWithheldTaxes- Type
- number | decimal?
- Description
Total de impuestos retenidos calculado.
- Name
total- Type
- number | decimal?
- Description
Total calculado, igual al enviado.
Errores
Las fallas de validación llegan en ValidationFailure con el campo que falló, antes de cobrar. En los mensajes, <dato> es el dato fiscal que le falta a la persona emisora, n es el saldo disponible y m la cantidad requerida.
| Estado | Cuándo ocurre | Mensaje |
|---|---|---|
| 400 | Falta el emisor o su id. | 'issuer.id' es obligatorio: la persona emisora del tenant que facturará el ticket. |
| 400 | El folio falta o no cumple su formato. | 'folio' es obligatorio y debe tener de 1 a 40 caracteres sin el carácter '|'. |
| 400 | La serie no cumple su formato. | 'series' debe tener de 1 a 25 caracteres sin el carácter '|'; si se omite, el ticket queda sin serie. |
| 400 | La forma de pago es 99. | 'paymentFormCode' no puede ser 99 (por definir): un ticket es una venta ya pagada; usa la forma con la que se pagó. |
| 400 | La moneda es XXX. | 'currencyCode' no puede ser XXX: un ticket es una venta con importes. |
| 400 | Hay tipo de cambio con MXN. | 'exchangeRate' no aplica con la moneda MXN (también es MXN si se omite 'currencyCode'): omítelo o envíalo null. |
| 400 | Falta el tipo de cambio con otra moneda, o no es mayor que 0. | 'exchangeRate' es obligatorio con una moneda distinta de MXN y debe ser mayor que 0. |
| 400 | No hay conceptos. | 'items' debe tener al menos un concepto. |
| 400 | Hay más de 1,500 conceptos. | Un ticket admite como máximo 1500 conceptos (items). |
| 400 | Un concepto con objeto de impuesto 02 no trae impuestos. | 'itemTaxes' es obligatorio con taxObjectCode 02 (sí objeto de impuesto): agrega al menos un impuesto. |
| 400 | Un concepto con objeto de impuesto 01, 03, 04 o 05 trae impuestos. | 'itemTaxes' debe ir vacío con taxObjectCode 01, 03, 04 o 05: esos conceptos no desglosan impuestos. |
| 400 | La llave de idempotencia está vacía, pasa de 64 caracteres o tiene espacios o caracteres fuera de ASCII. | El encabezado Idempotency-Key debe tener de 1 a 64 caracteres ASCII visibles, sin espacios. |
| 403 | La persona autenticada no tiene créditos de ticket suficientes. | Saldo insuficiente. Disponible: n, Requerido: m |
| 403 | Tu suscripción no incluye Auto CFDI. Ver Permisos y suscripción. | Para ingerir tickets tu suscripción debe incluir: Auto CFDI. |
| 409 | El emisor ya tiene un ticket activo con esa serie y folio. El id va en data.existingTicketId. | Ya hay un ticket activo con esa serie y folio para el emisor: 'data.existingTicketId' es el ticket que lo tiene. Para volver a ingerirlo, cancela ese ticket primero. |
| 409 | Otro registro con la misma serie y folio cambió al mismo tiempo. Repite la solicitud. | Otro ticket con la misma serie y folio cambió mientras se ingería este. Intenta de nuevo. |
| 409 | Otra solicitud con la misma llave de idempotencia sigue en proceso. Reintenta después de los segundos que indica el encabezado Retry-After. | Otra petición con esta Idempotency-Key sigue en proceso. Reintenta en unos segundos; si continúa, consulta el recurso y usa una Idempotency-Key nueva. |
| 422 | La llave de idempotencia ya se usó con otra solicitud. | Esta Idempotency-Key ya se usó con otra petición. Usa una Idempotency-Key nueva para cada operación distinta. |
| 422 | El total no cuadra al centavo. El enviado va en data.expectedTotal y el calculado en data.computedTotal. | 'total' no cuadra al centavo con el total calculado de los conceptos e impuestos: 'data.expectedTotal' es el enviado y 'data.computedTotal' el calculado. |
| 422 | El pago es posterior a ahora por más de 5 minutos. | 'paymentDate' no puede ser posterior a ahora por más de 5 minutos: revisa el reloj del punto de venta. |
| 422 | La persona emisora no es de tu cuenta. | 'issuer.id' no es una persona de tu organización. |
| 422 | A la persona emisora le falta un dato fiscal. | La persona emisora no tiene <dato>: complétalo en sus datos fiscales para ingerir tickets. |
| 422 | La persona emisora no tiene un CSD vigente. | La persona emisora no tiene un CSD vigente (certificado y llave privada): cárgalo para ingerir tickets. |
| 422 | La persona emisora no tiene timbres. | La persona emisora no tiene timbres: cada autofactura consume uno de su saldo. Transfiérele timbres para ingerir tickets. |
Las claves de catálogo y los decimales usan los mismos mensajes que la emisión: consulta Claves de catálogo del SAT y Decimales de importes, cantidades y tasas.
Request
curl --location 'https://test.fiscalapi.com/api/v4/tickets' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
--data-raw '{
"issuer": { "id": "<person_id>" },
"folio": "F-1001",
"series": "A",
"paymentDate": "2026-10-10T12:30:00",
"paymentFormCode": "01",
"total": 116.00,
"items": [
{
"itemCode": "50202306",
"itemSku": "SKU-1",
"quantity": 1,
"unitOfMeasurementCode": "H87",
"description": "Refresco",
"unitPrice": 100.00,
"taxObjectCode": "02",
"itemTaxes": [
{ "taxCode": "002", "taxTypeCode": "Tasa", "taxRate": "0.160000", "taxFlagCode": "T" }
]
}
]
}'
Response
{
"data": {
"id": "9f8e7d6c-1b2a-4c3d-8e9f-0a1b2c3d4e5f",
"ticketCode": "K7M2Q9X4TB3H",
"qrUrl": "https://test.factura.fiscalapi.com/t/K7M2Q9X4TB3H",
"status": "pending",
"selfInvoiceEligible": true,
"eligibleUntil": "2026-10-31T23:59:59.000",
"subtotal": 100,
"totalTransferredTaxes": 16,
"totalWithheldTaxes": 0,
"total": 116
},
"succeeded": true,
"message": "",
"details": "",
"httpStatusCode": 201
}
Listar tickets
Este endpoint devuelve los tickets de tu cuenta paginados y ordenados por fecha de pago. Cada filtro aplica solo si lo envías. Con él juntas los tickets pendientes de un periodo para armar tu factura global de tickets.
Para una grid, GET /api/v4/tickets/load devuelve los tickets de tu cuenta con las opciones de carga de DevExtreme (filtro, orden, paginación y agrupación) y responde su LoadResult, sin el sobre de la respuesta. Valida sus parámetros como las demás consultas load; ver ValidationFailure.
Query parameters
- Name
status- Type
- string?
- Description
Uno o más estados en camelCase. Para varios, repite el parámetro; por ejemplo,
status=pending&status=invoiced.
- Name
personId- Type
- string?
- Description
ID de la persona emisora. Una persona de otra cuenta deja la lista vacía.
- Name
globalInvoiceId- Type
- string?
- Description
ID de la factura global que ampara los tickets. Una factura de otra cuenta deja la lista vacía.
- Name
from- Type
- string?
- Description
Primer día del pago, incluido, como fecha civil de México con el formato YYYY-MM-DD. Va junto con
to.
- Name
to- Type
- string?
- Description
Último día del pago, incluido, como fecha civil de México con el formato YYYY-MM-DD. Va junto con
from.
- Name
details- Type
- boolean?
- Description
Con
true, cada ticket trae sus conceptos con sus impuestos.Default:false
- Name
pageNumber- Type
- integer | number?
- Description
Número de página, desde 1.
Default:1
- Name
pageSize- Type
- integer | number?
- Description
Tickets por página, de 1 a 50.
Default:10
Errores
Cada falla llega como falla de validación en el parámetro. En los mensajes, <valor> es el valor recibido.
| Estado | Cuándo ocurre | Mensaje |
|---|---|---|
| 400 | Un estado no existe. | 'status' no admite '<valor>': usa pending, invoicing, invoiced, globalizing, globalized, cancelled (repite 'status' para varios). |
| 400 | Solo llega uno de los dos límites del periodo. | 'from' y 'to' van juntos: envía ambos (fechas YYYY-MM-DD de México) o ninguno. |
| 400 | La fecha de from no tiene el formato YYYY-MM-DD. | 'from' debe ser una fecha YYYY-MM-DD. |
| 400 | La fecha de to no tiene el formato YYYY-MM-DD. | 'to' debe ser una fecha YYYY-MM-DD. |
| 400 | El inicio del periodo es posterior al fin. | 'from' no puede ser posterior a 'to'. |
| 400 | El tamaño de página no está entre 1 y 50. | 'pageSize' debe estar entre 1 y 50. |
Request
curl --location 'https://test.fiscalapi.com/api/v4/tickets?status=pending&personId=<person_id>&from=2026-10-01&to=2026-10-31&pageNumber=1&pageSize=50' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'
Response
{
"data": {
"items": [
{
"id": "9f8e7d6c-1b2a-4c3d-8e9f-0a1b2c3d4e5f",
"personId": "4b1c2d3e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
"folio": "F-1001",
"series": "A",
"paymentDate": "2026-10-10T12:30:00.000",
"paymentFormCode": "01",
"currencyCode": "MXN",
"exchangeRate": null,
"expeditionZipCode": "42501",
"subtotal": 100,
"totalTransferredTaxes": 16,
"totalWithheldTaxes": 0,
"total": 116,
"status": "pending",
"selfInvoiceEligible": true,
"eligibleUntil": "2026-10-31T23:59:59.000",
"invoiceId": null,
"globalInvoiceId": null,
"createdAt": "2026-10-10T12:31:00.000"
}
],
"pageNumber": 1,
"totalPages": 1,
"totalCount": 1,
"hasPreviousPage": false,
"hasNextPage": false
},
"succeeded": true,
"message": "",
"details": "",
"httpStatusCode": 200
}
Obtener ticket por ID
Este endpoint obtiene un ticket con su estado, sus facturas y su vigencia de autofactura. Con details=true trae además sus conceptos con sus impuestos y su historia.
Query parameters
- Name
details- Type
- boolean?
- Description
Con
true, trae los conceptos y la historia del ticket.Default:false
Errores
En el mensaje, que llega en details, <id> es el id del ticket.
| Estado | Cuándo ocurre | Mensaje |
|---|---|---|
| 404 | El ticket no existe o pertenece a otra cuenta. | No such resource for the given Id: <id> |
Request
curl --location 'https://test.fiscalapi.com/api/v4/tickets/<ticket_id>?details=true' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'
Response
{
"data": {
"id": "9f8e7d6c-1b2a-4c3d-8e9f-0a1b2c3d4e5f",
"personId": "4b1c2d3e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
"folio": "F-1001",
"series": "A",
"paymentDate": "2026-10-10T12:30:00.000",
"paymentFormCode": "01",
"currencyCode": "MXN",
"exchangeRate": null,
"expeditionZipCode": "42501",
"subtotal": 100,
"totalTransferredTaxes": 16,
"totalWithheldTaxes": 0,
"total": 116,
"status": "pending",
"selfInvoiceEligible": true,
"eligibleUntil": "2026-10-31T23:59:59.000",
"invoiceId": null,
"globalInvoiceId": null,
"createdAt": "2026-10-10T12:31:00.000",
"items": [
{
"itemCode": "50202306",
"itemSku": "SKU-1",
"quantity": 1,
"unitOfMeasurementCode": "H87",
"description": "Refresco",
"unitPrice": 100,
"discount": 0,
"taxObjectCode": "02",
"itemTaxes": [
{ "taxCode": "002", "taxTypeCode": "Tasa", "taxRate": 0.16, "taxFlagCode": "T" }
]
}
],
"events": [
{ "type": "ingested", "occurredAt": "2026-10-10T12:31:00.000", "actorType": "tenant", "invoiceId": null }
]
},
"succeeded": true,
"message": "",
"details": "",
"httpStatusCode": 200
}
Obtener código de ticket
Este endpoint devuelve el código del ticket y la URL de su QR, los mismos que respondió Crear ticket. Úsalo para reimprimir el comprobante de una venta.
Errores
En el mensaje, que llega en details, <id> es el id del ticket.
| Estado | Cuándo ocurre | Mensaje |
|---|---|---|
| 404 | El ticket no existe o pertenece a otra cuenta. | No such resource for the given Id: <id> |
Request
curl --location 'https://test.fiscalapi.com/api/v4/tickets/<ticket_id>/code' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'
Response
{
"data": {
"ticketCode": "K7M2Q9X4TB3H",
"qrUrl": "https://test.factura.fiscalapi.com/t/K7M2Q9X4TB3H"
},
"succeeded": true,
"message": "",
"details": "",
"httpStatusCode": 200
}
Cancelar ticket
Este endpoint cancela un ticket en estado pending y libera su serie y folio para volver a registrarlo. El crédito de ticket que consumió el registro no se devuelve. Exige Auto CFDI en tu suscripción.
Un ticket que ya se facturó no se cancela aquí: cancela su factura. Al confirmarse la cancelación de su factura individual con motivo 02 o 03, el ticket vuelve a pending. Con motivo 01, queda ligado a la sustituta si esta relaciona a la original con tipo 04. Para la factura global, consulta Sustituir una factura global de tickets.
Errores
En los mensajes, <id> es el id del ticket y <estado> su estado actual.
| Estado | Cuándo ocurre | Mensaje |
|---|---|---|
| 403 | Tu suscripción no incluye Auto CFDI. Ver Permisos y suscripción. | Para cancelar tickets tu suscripción debe incluir: Auto CFDI. |
| 404 | El ticket no existe o pertenece a otra cuenta. | No such resource for the given Id: <id> |
| 409 | El ticket no está en pending. | Solo se cancela un ticket en estado pending y este está en <estado>: ya se facturó, se está facturando o ya estaba cancelado. El crédito de ticket de la ingesta no se devuelve. |
| 409 | El ticket cambió de estado mientras se cancelaba. Repite la solicitud. | El ticket cambió de estado mientras se cancelaba (alguien lo estaba facturando). Intenta de nuevo. |
Request
curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/tickets/<ticket_id>' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'
Response
{
"data": true,
"succeeded": true,
"message": "",
"details": "",
"httpStatusCode": 200
}
Crear factura global de tickets
Este endpoint timbra la factura global con la petición estándar de Crear factura. Con ticketId, Fiscalapi reserva los tickets antes de cobrar el timbre: todos o ninguno. Al guardar el CFDI, los tickets pasan a globalized con el ID de la factura en globalInvoiceId. Si el PAC rechaza el CFDI, los tickets vuelven a su estado anterior y el timbre se reembolsa.
El ejemplo ampara el ticket F-1002, una venta de 166.00 con un refresco de 100.00 al 16 % de IVA y agua natural de 50.00 al 0 %. Sus dos grupos de impuestos van en dos conceptos con el mismo ticketId, y cada concepto suma lo que el ticket guardó en su grupo. Cómo armar los conceptos y el comprobante está en Factura global de tickets.
Reglas de ticketId
El campo items[].ticketId es opcional. Sin él, la factura se emite igual que siempre.
| Regla | Qué pasa si no se cumple |
|---|---|
Solo va en una factura global de ingreso, con typeCode I y globalInformation. | 400 en el ticketId del concepto. |
| La global lleva el emisor por referencia. | 400 en Issuer.Id. |
| El ticket es de tu cuenta, de la misma persona emisora y en la misma moneda que la global. | 400 en el ticketId del concepto. |
| Los conceptos del ticket reflejan el ticket guardado. | 400 en el ticketId del primer concepto del ticket. |
El ticket está en pending, o en globalized en la global que sustituyes. | 409 con data.unavailableTickets, sin cobrar ni tomar tickets. |
Reintentos
Un 400 o un 409 no cobran el timbre ni dejan tickets tomados. Ante un 409, data.unavailableTickets trae el id y el estado de cada ticket que ya no estaba disponible: vuelve a consultar los tickets pendientes y arma la global otra vez. No reintentes la misma petición sin cambios.
Si el PAC no responde o responde un error de su servidor sin código de rechazo, el resultado es incierto porque el CFDI pudo timbrarse. Fiscalapi responde el error inesperado y conserva el timbre, el folio y los tickets tomados para revisarlos. No emitas otra global con esos tickets: consulta tus facturas y los tickets, y si siguen en globalizing, escribe a soporte con el traceIdentifier de la respuesta.
Errores
Las fallas llegan como falla de validación, con el campo en PascalCase; por ejemplo, Items[0].TicketId. En los mensajes, i es la posición del concepto, desde 0.
| Estado | Cuándo ocurre | Mensaje |
|---|---|---|
| 400 | Un concepto trae ticketId y la factura no es una global de ingreso. | 'items[i].ticketId' solo aplica en una factura global de ingreso: 'typeCode' I con 'globalInformation'. Quita el ticketId o emite la factura global. |
| 400 | El ticketId va vacío o pasa de 36 caracteres. | 'items[i].ticketId' debe tener de 1 a 36 caracteres: el id del ticket. |
| 400 | La global con tickets lleva el emisor por valores. Llega en Issuer.Id. | La factura global con tickets requiere el emisor por referencia ('issuer.id'): la persona emisora de los tickets. |
| 400 | El ticket no existe o es de otra cuenta. | 'items[i].ticketId' no es un ticket de tu organización. |
| 400 | El ticket es de otra persona emisora. | 'items[i].ticketId' es un ticket de otra persona emisora: la factura global lleva solo tickets de su emisor, indicado por referencia ('issuer.id'). |
| 400 | El ticket está en otra moneda. | 'items[i].ticketId' es un ticket en otra moneda: la factura global lleva solo tickets de su moneda ('currencyCode'). |
| 400 | Los conceptos del ticket no reflejan el ticket guardado. | Los conceptos con el ticket de 'items[i].ticketId' (<conceptos>) no reflejan ese ticket: la suma de sus importes (quantity × unitPrice), la de sus descuentos y la de sus impuestos por impuesto, tipo de factor y tasa deben ser las de los conceptos del ticket. Un ticket con impuestos distintos va en un concepto por cada grupo de impuestos, todos con el mismo ticketId. |
| 409 | Un ticket ya no está disponible. Los tickets y su estado van en data.unavailableTickets. | Uno o más tickets ya no están disponibles para la factura global (solo entra un ticket en estado pending): 'data.unavailableTickets' dice cuáles y su estado. No se cobró el timbre ni quedó tomado ningún ticket. |
En el mensaje de conceptos que no reflejan el ticket, <conceptos> es la lista de los conceptos con ese ticket; por ejemplo, items[0], items[1]. Los demás errores de la factura son los de Crear factura global.
Request
curl --location 'https://test.fiscalapi.com/api/v4/invoices' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data-raw '{
"versionCode": "4.0",
"series": "G",
"date": "2026-11-01T10:00:00",
"paymentFormCode": "01",
"paymentMethodCode": "PUE",
"currencyCode": "MXN",
"exchangeRate": 1,
"typeCode": "I",
"expeditionZipCode": "42501",
"exportCode": "01",
"globalInformation": {
"periodicityCode": "04",
"monthCode": "10",
"year": 2026
},
"issuer": { "id": "<person_id>" },
"recipient": {
"tin": "XAXX010101000",
"legalName": "PUBLICO EN GENERAL",
"zipCode": "42501",
"taxRegimeCode": "616",
"cfdiUseCode": "S01"
},
"items": [
{
"ticketId": "<ticket_id>",
"itemCode": "01010101",
"itemSku": "F-1002",
"quantity": 1,
"unitOfMeasurementCode": "ACT",
"description": "Venta",
"unitPrice": 100.000000,
"discount": 0,
"taxObjectCode": "02",
"itemTaxes": [
{ "taxCode": "002", "taxTypeCode": "Tasa", "taxRate": "0.160000", "taxFlagCode": "T" }
]
},
{
"ticketId": "<ticket_id>",
"itemCode": "01010101",
"itemSku": "F-1002",
"quantity": 1,
"unitOfMeasurementCode": "ACT",
"description": "Venta",
"unitPrice": 50.000000,
"discount": 0,
"taxObjectCode": "02",
"itemTaxes": [
{ "taxCode": "002", "taxTypeCode": "Tasa", "taxRate": "0.000000", "taxFlagCode": "T" }
]
}
]
}'
Response 409
{
"data": {
"unavailableTickets": [
{ "ticketId": "9f8e7d6c-1b2a-4c3d-8e9f-0a1b2c3d4e5f", "status": "invoiced" }
]
},
"succeeded": false,
"message": "Sorry, it's not me, it's you.",
"details": "Uno o más tickets ya no están disponibles para la factura global (solo entra un ticket en estado pending): 'data.unavailableTickets' dice cuáles y su estado. No se cobró el timbre ni quedó tomado ningún ticket.",
"httpStatusCode": 409
}