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.

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.

EstadoQué significa
pendingSin factura: tu cliente lo puede autofacturar o tú lo incluyes en una global.
invoicingTu cliente lo está timbrando en el portal.
invoicedTiene su factura individual, en invoiceId.
globalizingUna factura global lo está timbrando.
globalizedEstá en una factura global, en globalInvoiceId.
cancelledLo 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 null si 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 null en 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

    true si hoy tu cliente puede autofacturarlo: el ticket está en pending y 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 null si 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, invoiced o cancelled. 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) o system (un proceso de Fiscalapi).

  • Name
    invoiceId
    Type
    string?
    Description

    ID de la factura del hecho, o null.


POST/api/v4/tickets

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

    true si hoy tu cliente puede autofacturarlo.

  • Name
    eligibleUntil
    Type
    string?
    Description

    Último momento de la ventana de autofactura, o null si 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.

EstadoCuándo ocurreMensaje
400Falta el emisor o su id.'issuer.id' es obligatorio: la persona emisora del tenant que facturará el ticket.
400El folio falta o no cumple su formato.'folio' es obligatorio y debe tener de 1 a 40 caracteres sin el carácter '|'.
400La 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.
400La 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ó.
400La moneda es XXX.'currencyCode' no puede ser XXX: un ticket es una venta con importes.
400Hay 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.
400Falta 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.
400No hay conceptos.'items' debe tener al menos un concepto.
400Hay más de 1,500 conceptos.Un ticket admite como máximo 1500 conceptos (items).
400Un concepto con objeto de impuesto 02 no trae impuestos.'itemTaxes' es obligatorio con taxObjectCode 02 (sí objeto de impuesto): agrega al menos un impuesto.
400Un 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.
400La 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.
403La persona autenticada no tiene créditos de ticket suficientes.Saldo insuficiente. Disponible: n, Requerido: m
403Tu suscripción no incluye Auto CFDI. Ver Permisos y suscripción.Para ingerir tickets tu suscripción debe incluir: Auto CFDI.
409El 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.
409Otro 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.
409Otra 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.
422La 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.
422El 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.
422El 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.
422La persona emisora no es de tu cuenta.'issuer.id' no es una persona de tu organización.
422A la persona emisora le falta un dato fiscal.La persona emisora no tiene <dato>: complétalo en sus datos fiscales para ingerir tickets.
422La persona emisora no tiene un CSD vigente.La persona emisora no tiene un CSD vigente (certificado y llave privada): cárgalo para ingerir tickets.
422La 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

POST
/api/v4/tickets
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
}

GET/api/v4/tickets

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.

EstadoCuándo ocurreMensaje
400Un estado no existe.'status' no admite '<valor>': usa pending, invoicing, invoiced, globalizing, globalized, cancelled (repite 'status' para varios).
400Solo 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.
400La fecha de from no tiene el formato YYYY-MM-DD.'from' debe ser una fecha YYYY-MM-DD.
400La fecha de to no tiene el formato YYYY-MM-DD.'to' debe ser una fecha YYYY-MM-DD.
400El inicio del periodo es posterior al fin.'from' no puede ser posterior a 'to'.
400El tamaño de página no está entre 1 y 50.'pageSize' debe estar entre 1 y 50.

Request

GET
/api/v4/tickets?status=pending&personId=<id>&from=2026-10-01&to=2026-10-31
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
}

GET/api/v4/tickets/<id>

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.

EstadoCuándo ocurreMensaje
404El ticket no existe o pertenece a otra cuenta.No such resource for the given Id: <id>

Request

GET
/api/v4/tickets/<id>?details=true
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
}

GET/api/v4/tickets/<id>/code

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.

EstadoCuándo ocurreMensaje
404El ticket no existe o pertenece a otra cuenta.No such resource for the given Id: <id>

Request

GET
/api/v4/tickets/<id>/code
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
}

DELETE/api/v4/tickets/<id>

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.

EstadoCuándo ocurreMensaje
403Tu suscripción no incluye Auto CFDI. Ver Permisos y suscripción.Para cancelar tickets tu suscripción debe incluir: Auto CFDI.
404El ticket no existe o pertenece a otra cuenta.No such resource for the given Id: <id>
409El 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.
409El 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

DELETE
/api/v4/tickets/<id>
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
}

POST/api/v4/invoices

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.

ReglaQué 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.

EstadoCuándo ocurreMensaje
400Un 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.
400El ticketId va vacío o pasa de 36 caracteres.'items[i].ticketId' debe tener de 1 a 36 caracteres: el id del ticket.
400La 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.
400El ticket no existe o es de otra cuenta.'items[i].ticketId' no es un ticket de tu organización.
400El 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').
400El ticket está en otra moneda.'items[i].ticketId' es un ticket en otra moneda: la factura global lleva solo tickets de su moneda ('currencyCode').
400Los 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.
409Un 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

POST
/api/v4/invoices
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
}

¿Le resultó útil esta página?