Facturación CFDI

Winal timbra CFDI 4.0 contra un PAC (hoy: Finkok o Facturama, el que tú elijas) — base e IVA se calculan exactos a partir del total en centavos, nunca con redondeo de punto flotante. Facturas lo que vendiste, haya pasado o no por un cobro de Winal: el mostrador que cobró en efectivo emite su CFDI igual que quien cobró con nuestra API. Y para el grueso de un mostrador — las ventas de las que nadie pidió comprobante — está la factura global periódica: la obligación mensual que agrupa todo eso en un solo CFDI.

¿Cuál de los caminos es el tuyo?

Elige por si tu cliente te dio su RFC — eso decide más que cómo cobraste. En un mostrador, la mayoría no lo da: esas ventas son el primer caso de la tabla, y son casi siempre el grueso del mes.

Si el PAC no contesta: el único error que NO significa "no se timbró"

Vale para las cuatro rutas de emisión (POST /v1/invoices, /pue, /ppd y /global) y también para el REP y la nota de crédito. Casi todos los rechazos de esta página son firmes: el PAC miró tu comprobante y dijo que no. Dos no lo son, y confundirlos con los demás es lo que emite un segundo CFDI por la misma venta.

Venta con RFC: facturar sin cobro

POST /v1/invoices/pue emite un CFDI de ingreso, método de pago PUE (una sola exhibición), por una venta que ya está pagada y que no pasó por ningún cobro de Winal. Es el caso de la farmacia que vende en el mostrador, cobra en efectivo, y ese cliente sí te dio su RFC y quiere su factura nominativa. Si no lo dio, esa venta no pasa por aquí: se ampara en la factura global del período.

Como no hay payment_intent del cual deducirla, tú declaras la forma de pago del catálogo c_FormaPago del SAT. Es el único campo que esta ruta pide de más frente a las otras.

Cuerpo

Ejemplo

curl -s https://api.winal.com.mx/v1/invoices/pue \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "total_minor": 23200,
    "currency": "MXN",
    "forma_pago": "01",
    "receptor": {
      "rfc": "EKU9003173C9",
      "nombre": "ESCUELA KEMPER URGATE",
      "uso_cfdi": "G03",
      "regimen_fiscal": "601",
      "cp": "45050"
    },
    "descripcion": "Venta de mostrador",
    "serie": "CAJA-2",
    "folio": "00981"
  }'

$232.00 cobrados en efectivo: Winal desglosa 200.00 de base y 32.00 de IVA, exactos al centavo. El receptor de arriba es un RFC de ejemplo —usa el real de tu cliente—; los cinco campos siguen siendo obligatorios (ver la regla completa del receptor si tu cliente sí opera con el genérico de residente extranjero XEXX010101000, que es el único genérico que esta ruta todavía acepta). serie/folio son opcionales —omítelos y no pasa nada— pero un POS con varias cajas normalmente sí los manda.

{
  "id": "5cee05bd-de0c-4961-98eb-e0cacfc6aae8",
  "object": "invoice",
  "status": "stamped",
  "uuid_fiscal": "...",
  "serie": "CAJA-2",
  "folio": "00981",
  "total_minor": 23200,
  "base_minor": 20000,
  "iva_minor": 3200,
  "currency": "MXN",
  "receptor": { "...": "..." },
  "pac": "finkok",
  "metodo_pago": "PUE",
  "parcialidades": 0,
  "created_at": "...",
  "updated_at": "..."
}

No verás payment_intent_id (no hay cobro que colgar) ni saldo_insoluto_minor (una PUE nace liquidada): Winal omite los campos nulos en vez de devolverlos en null. serie es la del request si la mandaste, si no la de tu perfil fiscal, o se omite si ninguna de las dos aplica; folio es el que mandaste, o se omite (ver Serie y folio para límites y qué rutas los aceptan). Después puedes descargar el XML y el PDF con el id.

La forma de pago: catálogo c_FormaPago del SAT

La clave viaja verbatim al PAC y de ahí al SAT, así que Winal la valida contra el catálogo real antes de gastar un timbre: una cadena inventada ("efectivo", "1", "07") se rechaza en milisegundos con invoice.invalid_forma_pago y sin consumir folio.

Winal acepta además el resto de claves vigentes del catálogo —12, 13, 14, 15, 17, 23, 24, 25, 26 y 27, las formas de extinción de obligaciones— y las manda tal cual; su definición exacta está en el Anexo 20. Lo que no existe son los huecos del catálogo: 07, 09, 10, 11, 16 y 18–22 no son claves válidas, por eso la validación es una lista blanca y no un rango.

Idempotencia: obligatoria, y aquí más que en ningún lado

Errores propios de esta ruta

Facturar un cobro que procesó Winal

El caso "te cobro Y te facturo": un CFDI de ingreso, método de pago PUE, sobre un payment_intent ya succeeded — de un cliente que sí te dio su RFC al pagar. Aquí no mandas forma_pago: Winal la deriva del método real del cobro — tarjeta (incluidos MSI y card-present) → 04, SPEI/DiMo/CoDi → 03, OXXO/Paynet/efectivo → 01.

curl -s https://api.winal.com.mx/v1/invoices \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "a55fc12f-0af3-4858-ba84-52a3e7240f52",
    "receptor": {
      "rfc": "EKU9003173C9",
      "nombre": "ESCUELA KEMPER URGATE",
      "uso_cfdi": "G03",
      "regimen_fiscal": "601",
      "cp": "45050"
    },
    "serie": "CAJA-2",
    "folio": "00981"
  }'

El monto sale del cobro, no del cuerpo: por construcción no puedes facturar por un importe distinto del que cobraste. Si el intent no existe responde invoice.intent_not_found; si todavía no está liquidado, invoice.intent_not_succeeded; y si ese cobro ya tiene un CFDI vivo, invoice.already_exists — ese sí es un backstop de unicidad, porque aquí sí hay un cobro del cual colgarse. Si el timbrado tiene éxito, la respuesta es un invoice stamped con uuid_fiscal, serie y folio —serie/folio son opcionales, ver Serie y folio; shape completo en Referencia de API → Facturas.

Serie y folio: tu propia numeración

El Anexo 20 deja Serie y Folio como atributos opcionales del comprobante — el identificador fiscal único de un CFDI es el uuid_fiscal del timbre, no estos dos. En la práctica sirven de control interno: el POS de tu mostrador ya lleva su propia numeración de tickets ("caja 2, folio 981"), y Winal te deja escribirla tal cual en el comprobante en vez de obligarte a correlacionarla por fuera.

Los dos límites son los del XSD del SAT (cfdv40.xsd), no un número que nos inventamos; y ninguno de los dos puede llevar el carácter | — es el separador de la cadena original que se firma, así que aparecer ahí desplazaría el resto del comprobante. Un valor que se pasa de largo o trae | se rechaza EN LA PUERTA, antes de reservar tu Idempotency-Key o intentar nada, con invoice.cfdi_field_invalid y el nombre del campo (Serie o Folio) en el mensaje.

Conceptos con IVA mezclado (retail: 0%, exento, 8% frontera)

Por default un CFDI se timbra como un único concepto a la tasa general del 16%. Un ticket de RETAIL casi nunca es así de simple: en el mismo ticket conviven productos gravados al 16%, alimentos/medicinas a tasa 0% (sí gravados, IVA en cero), servicios exentos (sí objeto de impuesto pero SIN traslado de IVA — fiscalmente distinto de tasa 0%) y, si el emisor opera en la región fronteriza, líneas al 8% (estímulo fiscal). El campo opcional conceptos[] — disponible en las cuatro rutas de emisión (POST /v1/invoices, POST /v1/invoices/pue, POST /v1/invoices/ppd y POST /v1/invoices/global) — declara el tratamiento de IVA por línea en vez de forzar una sola tasa a todo el comprobante. En la factura global, además, cada línea puede llevar no_identificacion (el folio del ticket que ampara) — detalle abajo.

curl -s https://api.winal.com.mx/v1/invoices/pue \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "total_minor": 15600,
    "forma_pago": "01",
    "receptor": {
      "rfc": "EKU9003173C9",
      "nombre": "ESCUELA KEMPER URGATE",
      "uso_cfdi": "G03",
      "regimen_fiscal": "601",
      "cp": "45050"
    },
    "conceptos": [
      { "importe_minor": 11600, "treatment": "tasa16", "descripcion": "Artículos de perfumería" },
      { "importe_minor": 4000,  "treatment": "exento", "descripcion": "Medicamento de patente" }
    ]
  }'

$156.00 de ticket: 116.00 gravados al 16% y 40.00 exentos. El comprobante queda con base_minor 14000 (los 100.00 gravados más los 40.00 exentos) e iva_minor 1600 — la línea exenta no traslada IVA, que es justo lo que la distingue de una de tasa 0%.

Cada elemento de conceptos[] es un CfdiConceptoDto:

conceptos es completamente opcional: si se omite (o se manda vacío), Winal sigue emitiendo el concepto único de tasa 16% de siempre — nada cambia para quien ya integró antes de que existiera este campo.

Cantidad y valor unitario: que la factura diga lo mismo que el ticket

Sin declararlos, cada concepto sale del comprobante como una unidad del valor de la línea: una farmacia que vende 3 cajas a $45 emite un CFDI que dice «1 unidad de $135». Es válido ante el SAT, pero describe mal la venta — y eso es lo que el cliente lee. Con cantidad_micro y valor_unitario_micro el comprobante dice lo mismo que el papel que el cliente tiene en la mano.

"conceptos": [
  {
    "importe_minor": 15660,
    "treatment": "tasa16",
    "descripcion": "Caja de analgésico 500 mg",
    "clave_unidad": "H87",
    "cantidad_micro": 3000000,
    "valor_unitario_micro": 45000000
  },
  {
    "importe_minor": 4640,
    "treatment": "tasa16",
    "descripcion": "Producto a granel",
    "clave_unidad": "KGM",
    "cantidad_micro": 500000,
    "valor_unitario_micro": 80000000
  }
]

Eso es lo que queda escrito en el concepto del CFDI: Cantidad y ValorUnitario con los seis decimales de cantidad_micro/valor_unitario_micro, e Importe con los dos decimales de siempre — es la BASE de la línea, sin IVA (135.00, no los 156.60 con IVA de importe_minor: 16% de 135.00 son los 21.60 que faltan). Importe no pasa a seis decimales con esta capacidad; solo lo hacen los dos atributos nuevos.

Las dos cifras van en millonésimas —seis decimales, los que admite el Anexo 20 en ambos atributos— y como enteros, igual que el resto de la API. La cantidad, en millonésimas de unidad: 3 piezas son 3000000, medio kilo 500000. El valor unitario, en millonésimas de peso: $45.00 son 45000000. No es capricho: el litro de gasolina se vende a 23.459 pesos, y con centavos ese precio no se puede escribir.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invoice.pac_error",
    "message": "El PAC rechazó el timbrado (CFDI a0182936-9b76-4989-9ff2-581f78a9240f quedó en 'error'): Finkok CFDI40167: El valor del campo Importe no se encuentra entre el limite inferior y superior permitido. (El valor del atributo Conceptos/Concepto:Importe:130.00 del Concepto con ClaveProdServ:01010101 y NoIdentificacion:, es menor al limite inferior:134.99 o es mayor al limite superior:135.01) — el importe de un concepto no coincide con cantidad × valor unitario. El SAT tolera un centavo arriba o abajo; el mensaje del PAC dice los límites exactos que esperaba. Winal escribe los tres números tal como se los manda, sin corregirlos: revise cuál de los tres está mal en el ticket. Dos causas típicas: (a) el valor unitario va CON impuestos —el 'ValorUnitario' y el 'Importe' del concepto son la BASE, sin IVA ni IEPS—, o (b) 'valor_unitario_micro' se mandó en centavos: va en millonésimas de peso ($45.00 son 45000000). Corregirlo es emitir un comprobante NUEVO: el reintento reexpide este mismo XML.",
    "doc_url": "https://winal.com.mx/docs/errores.html#err-invoice.pac_error",
    "request_id": "0HNMSIOBNVS9K:00000001"
  }
}

Reconócelo por invoice.pac_error (400) y por los nombres de los tres atributos (Importe, Cantidad, ValorUnitario) en el texto — el mensaje exacto depende de tu PAC, éste es de Finkok. El propio mensaje te dice la salida: emite un comprobante nuevo con los números corregidos. POST /retry no sirve aquí —reexpide TAL CUAL los mismos tres números, así que fallaría exactamente igual—, y por eso en este caso el mensaje NO te ofrece esa ruta, a diferencia de los rechazos que sí se resuelven reintentando. (Respuesta real, capturada el 2026-09-04 emitiendo a propósito un trío incoherente contra el PAC: 3 × $45.00 declarado como $130.00. De ahí sale también la tolerancia, que no la inventamos: el SAT admite un centavo arriba o abajo de cantidad × valor unitario —el propio mensaje dice «límite inferior 134.99, superior 135.01»—, así que un redondeo normal de tu punto de venta no te va a rebotar.)

Los dos campos van juntos o ninguno: con solo uno, Winal tendría que dividir para inventar el que falta, y ese número redondeado ya no sería el del ticket (invoice.cantidad_incompleta). Omitir los dos deja el comportamiento de siempre, intacto para quien ya factura.

Si declaras cantidad, conviene mandar también la clave_unidad que corresponda: sin ella el comprobante dirá «3 Actividad» —la clave genérica de ACT que Winal usa por defecto—, que es justo la descripción confusa que estos campos vienen a eliminar. Winal no la exige —rechazar por eso dejaría sin facturar a un comercio cuyo catálogo no las tiene—. Las más usadas del catálogo c_ClaveUnidad del SAT para retail:

Con IEPS por cuota conviven sin estorbarse: la cantidad_micro del concepto es cuántas piezas se venden y la cantidad_micro del ieps es la cantidad gravada por la cuota (litros, cigarros). Coinciden a veces y difieren a menudo — dos botellas de 1 L son cantidad 2 y base 2 L; una de medio litro es cantidad 1 y base 0.5 —, así que se declaran por separado y Winal no las cruza.

La nota de crédito total hereda la cantidad de las líneas de la factura que acredita: si la venta dijo «3 cajas a $45», la devolución dice lo mismo.

Descuentos por línea (promociones, 3+1)

Una promoción de mostrador se documenta con descuento_minor en la línea. Va en centavos y con impuestos incluidos, igual que importe_minor: es como lo ve una caja («le quité cincuenta pesos»), y Winal deriva de ahí lo que el CFDI necesita.

En el comprobante, la línea sale con su valor de lista en ValorUnitario e Importe, el descuento en su propio atributo, y el impuesto se traslada sobre lo que de verdad se cobra (Base = Importe − Descuento). El total del comprobante sigue siendo lo que paga el cliente.

"conceptos": [
  { "importe_minor": 46400, "descuento_minor": 11600, "treatment": "tasa16",
    "descripcion": "Antibiótico 500 mg — promoción 3+1 (4 cajas)" },
  { "importe_minor": 11600, "treatment": "tasa16", "descripcion": "Analgésico" }
]

En ese ejemplo el comprobante sale con SubTotal 500.00, Descuento 100.00, IVA 64.00 y Total 464.00 — que es lo que el cliente paga.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invoice.conceptos_sum_mismatch",
    "message": "La suma de los conceptos (27000) debe igualar el total del comprobante (28000), en centavos.",
    "doc_url": "https://winal.com.mx/docs/errores.html#err-invoice.conceptos_sum_mismatch",
    "request_id": "0HNMSIOBNVS9K:00000001"
  }
}

IEPS por concepto: botanas, bebidas azucaradas, cigarros

El IEPS (Impuesto Especial sobre Producción y Servicios, clave 003 del catálogo del SAT) es OPCIONAL y va dentro de un concepto (conceptos[], arriba): agrega el campo ieps a cualquier línea que lo lleve. Pocos productos de mostrador lo traen, pero en una farmacia SÍ existen y hasta ahora no eran facturables: botanas, chocolates y dulces, bebidas energizantes, bebidas saborizadas con azúcares añadidos y cigarros. Una línea sin ieps se comporta EXACTAMENTE como antes — el campo es aditivo.

Dos formas, mutuamente excluyentes, y las dos en ENTEROS

El SAT traslada el IEPS de dos maneras, y un concepto usa una de las dos, nunca las dos ni ninguna: mandar ambas, o media forma, se rechaza. Igual que el resto de la API, ninguna cifra viaja como decimal (regla 1) — la convención de la casa es la de millonésimas, los seis decimales que el Anexo 20 admite en el atributo TasaOCuota.

Nota el nombre: cantidad_micro son litros (o piezas) en millonésimas, no mililitros — el error clásico. Media botella de 500 ml son 0.5 litros, o sea 500000; mandar 500000000 (interpretando mililitros) declararía 500,000 litros gravados y el IEPS se comería el precio entero.

Las trece tasas del catálogo c_TasaOCuota (impuesto 003)

Una tasa "razonable" que no esté en esta lista (16% de IEPS, por ejemplo) se rechaza con 400 invoice.invalid_ieps — nunca se manda al PAC para que la rechace él.

El orden de cálculo: el IVA grava el valor MÁS el IEPS

Es la regla que casi todo el mundo se salta, y no es una preferencia de Winal: la Ley del IVA (arts. 12, 18 y 23) manda que la base del IVA sea la contraprestación más las cantidades que se carguen por otros impuestos — el IEPS es uno de ellos. Un precio de mostrador ya trae todo dentro, así que Winal desglosa hacia atrás en ese mismo orden: primero sale el IVA (sobre valor + IEPS), y de lo que queda sale el IEPS (sobre el valor solo). Hacerlo al revés —IVA sobre el valor pelado, IEPS aparte— da un IVA de menos y un comprobante que no cuadra contra el que emite Winal.

Un ticket real de farmacia, con las tres líneas que motivaron el campo — botana con IEPS de tasa, bebida con IEPS de cuota, y una medicina sin IEPS, $241.00 en total:

curl -s https://api.winal.com.mx/v1/invoices/pue \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "total_minor": 24100,
    "forma_pago": "01",
    "receptor": {
      "rfc": "EKU9003173C9",
      "nombre": "ESCUELA KEMPER URGATE",
      "uso_cfdi": "G03",
      "regimen_fiscal": "601",
      "cp": "45050"
    },
    "conceptos": [
      { "importe_minor": 10000, "treatment": "tasa16", "descripcion": "Botana",
        "ieps": { "tasa_bps": 800 } },
      { "importe_minor": 2500, "treatment": "tasa16", "descripcion": "Bebida saborizada 500 ml",
        "ieps": { "cuota_micro": 3081800, "cantidad_micro": 500000 } },
      { "importe_minor": 11600, "treatment": "tasa16", "descripcion": "Medicina de patente" }
    ]
  }'

Nota la botana: sobre $100.00 con 8% de IEPS y 16% de IVA, el reparto es $79.82 de valor + $6.39 de IEPS + $13.79 de IVA. El IVA (13.79) es 16% de $86.21 (valor + IEPS), no de $79.82 — 16% de 79.82 serían apenas $12.77, un peso de menos. Cuadra tu sistema contra estos números si integras el cálculo por tu cuenta antes de mandarnos el importe.

{
  "id": "...",
  "object": "invoice",
  "status": "stamped",
  "total_minor": 24100,
  "base_minor": 19983,
  "ieps_minor": 793,
  "iva_minor": 3324,
  "currency": "MXN",
  "...": "..."
}

ieps_minor es un campo nuevo en la respuesta de cualquier factura — 0, y presente igual, si ningún concepto lo lleva (no se omite como los campos null). base_minor sigue siendo el valor SIN impuestos —el SubTotal del CFDI—; no incluye el IEPS.

Límites, sin adornos

PPD: factura por un monto acordado, cóbralo después en partes

Para servicios/proyectos que se liquidan en parcialidades sin un cobro previo, con un cliente que sí te dio su RFC: emites un CFDI método de pago PPD (pago en parcialidades o diferido) por el total acordado, y cada cobro real que llega después genera su propio complemento de pagos 2.0 (REP) — un CFDI adicional que documenta esa parcialidad ante el SAT.

Lo que una PPD no admite, y por qué se te dice ANTES de timbrar

Emitir una PPD es firmar una promesa: cuando tu cliente pague, la ley te obliga a emitir el REP de esa parcialidad. Por eso POST /v1/invoices/ppd rechaza en la puerta las facturas cuyo REP no podría emitirse — antes de gastar un timbre. El comprobante contrario ya no tendría salida: timbrado ante el SAT, obligado a cerrarse, e imposible de cerrar.

POST /v1/invoices/ppd

curl -s https://api.winal.com.mx/v1/invoices/ppd \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "total_minor": 348000,
    "currency": "MXN",
    "receptor": {
      "rfc": "EKU9003173C9",
      "nombre": "ESCUELA KEMPER URGATE",
      "uso_cfdi": "G03",
      "regimen_fiscal": "601",
      "cp": "45050"
    },
    "descripcion": "Servicios profesionales - anticipo PPD",
    "serie": "PPD-A",
    "folio": "500"
  }'

total_minor (centavos, incluye IVA) es el único campo nuevo frente a la ruta con cobro; currency y descripcion son opcionales (MXN y una descripción genérica por default). No lleva forma_pago: en un PPD el SAT exige forzosamente 99 "Por definir", y Winal la pone por ti. serie/folio son opcionales, igual que en el resto de rutas de emisión (ver Serie y folio); el REP que después liquide esta factura puede llevar SU PROPIA serie/folio, sin relación con los de aquí (ver abajo).

{
  "id": "5cee05bd-de0c-4961-98eb-e0cacfc6aae8",
  "object": "invoice",
  "status": "stamped",
  "total_minor": 348000,
  "base_minor": 300000,
  "iva_minor": 48000,
  "currency": "MXN",
  "receptor": { "...": "..." },
  "pac": "facturama",
  "metodo_pago": "PPD",
  "saldo_insoluto_minor": 348000,
  "parcialidades": 0,
  "created_at": "2026-07-07T23:02:30Z",
  "updated_at": "2026-07-07T23:02:31Z"
}

saldo_insoluto_minor arranca igual al total_minor (nada pagado todavía) y baja con cada REP; parcialidades cuenta cuántos REP ya se timbraron contra esta factura.

POST /v1/invoices/{id}/payments — registra un pago (REP)

Cuando llega un pago que liquida (parte de) el saldo insoluto. Winal calcula la parcialidad, el saldo anterior/nuevo y timbra el REP. Hay dos variantes, y eliges una según quién cobró:

• Cobró Winal — mandas payment_intent_id (un cobro ya succeeded, tuyo, correlacionado por ti con la factura PPD que corresponde) y nada más: el importe, la forma de pago y la fecha se LEEN del cobro.
• Cobraste tú, por fuera — efectivo en el mostrador, tu propia terminal, una transferencia que llegó directo a tu banco. Omites payment_intent_id y declaras amount_minor y forma_pago. Ver abajo.

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-.../payments \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "a55fc12f-0af3-4858-ba84-52a3e7240f52",
    "serie": "REP-A",
    "folio": "9001"
  }'

{
  "id": "...",
  "object": "invoice_payment",
  "invoice_id": "5cee05bd-de0c-4961-98eb-e0cacfc6aae8",
  "payment_intent_id": "a55fc12f-0af3-4858-ba84-52a3e7240f52",
  "parcialidad": 1,
  "monto_minor": 55000,
  "saldo_anterior_minor": 348000,
  "saldo_insoluto_minor": 293000,
  "currency": "MXN",
  "status": "stamped",
  "rep_uuid": "...",
  "created_at": "...",
  "updated_at": "..."
}

El mismo endpoint, sin cobro de Winal: pago en efectivo o con tu propia terminal

Es el caso del POS que cobra por fuera y solo usa Winal para facturar. La ley te obliga a timbrar el REP en cuanto recibes el pago de una PPD, así que la puerta no puede exigirte un payment_intent que en tu flujo no existe. Declaras lo que aquí no se puede deducir de nada —cuánto, cómo y, si no fue hoy, cuándo— y el resto del trámite fiscal es idéntico: mismo armador, misma parcialidad, mismos tres saldos absolutos, mismo XML.

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-.../payments \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": 55000,
    "forma_pago": "01",
    "serie": "REP-A",
    "folio": "9001"
  }'

POST /v1/invoices/{id}/payments/{pid}/retry — cuando el timbrado del REP falla

La SALIDA de un complemento que quedó en error, espejo exacto de POST /v1/invoices/{id}/retry. Sin cuerpo: todo lo que determina el comprobante ya está guardado en su fila, y reintentar es reenviar exactamente eso. Devuelve 200 con el REP (ya stamped) o explica por qué no se puede (invoice.payment_not_retryable).

curl -s -X POST https://api.winal.com.mx/v1/invoices/5cee05bd-.../payments/8f2a1c7e-.../retry \
  -H "Authorization: Bearer $SK"

GET /v1/invoices/{id}/payments — lista los REP de una factura

{ "object": "list", "data": [] }

GET /v1/invoices/{id}/payments/{pid}/xml — descarga el XML del REP

Devuelve application/xml con Content-Disposition: attachment; filename="rep-{pid}.xml". Mismo 404/409 que el resto de descargas de CFDI si el REP no existe o aún no está timbrado.

Factura global: el CFDI periódico a público en general

POST /v1/invoices/global es el caso principal de un mostrador, no un extra: el comprobante periódico que agrupa TODAS las ventas del período de las que nadie pidió factura. Es una obligación fiscal, no una comodidad, para quien vende al público en general — y hasta ahora Winal no la emitía.

Cuerpo

Lo que no mandas: receptor y total_minor. El receptor lo fija el SAT y lo construye Winal —con el CP de tu perfil fiscal como domicilio del receptor, por la regla CFDI40149— y el total sale de sumar los conceptos, así que no puede discrepar del desglose de IVA.

Ejemplo

curl -s https://api.winal.com.mx/v1/invoices/global \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "periodicidad": "04",
    "meses": "07",
    "anio": 2026,
    "forma_pago": "01",
    "conceptos": [
      { "importe_minor": 116000, "treatment": "tasa16", "descripcion": "Ventas gravadas del período" },
      { "importe_minor": 96500,  "treatment": "exento", "descripcion": "Medicinas de patente" }
    ],
    "serie": "G",
    "folio": "0007"
  }'

{
  "id": "5cee05bd-de0c-4961-98eb-e0cacfc6aae8",
  "object": "invoice",
  "status": "stamped",
  "uuid_fiscal": "...",
  "serie": "G",
  "folio": "0007",
  "total_minor": 212500,
  "base_minor": 196500,
  "iva_minor": 16000,
  "currency": "MXN",
  "receptor": {
    "rfc": "XAXX010101000",
    "nombre": "PUBLICO EN GENERAL",
    "uso_cfdi": "S01",
    "regimen_fiscal": "616",
    "cp": "06600"
  },
  "pac": "finkok",
  "metodo_pago": "PUE",
  "parcialidades": 0,
  "created_at": "...",
  "updated_at": "...",
  "informacion_global": { "periodicidad": "04", "meses": "07", "anio": 2026 }
}

$2,125.00 del mes: $1,160.00 gravados al 16% ($1,000.00 de base + $160.00 de IVA) y $965.00 exentos. El cp del receptor de arriba es ilustrativo — en tu cuenta es SIEMPRE el mismo que el lugar de expedición de tu perfil fiscal, nunca uno que tú mandes. metodo_pago es siempre PUE (las operaciones del período ya se cobraron) y no verás payment_intent_id ni saldo_insoluto_minor: una global no nace de ningún cobro de Winal. serie/folio son los de ESTE comprobante (ver Serie y folio); omítelos y se comportan como en cualquier otra ruta de emisión. informacion_global y sustituye_uuid son justamente lo que distingue a una global de cualquier otra factura: en un CFDI ordinario ambos viajan null (por eso se omiten del JSON).

El folio del ticket, por línea

Cada elemento de conceptos[] admite no_identificacion (texto libre, hasta 100 caracteres): el folio del ticket de mostrador que esa línea ampara. Es el hilo que la guía del SAT pide entre el comprobante global y las operaciones que agrupa. Quien puede detallar ticket por ticket lo hace; quien no, agrupa por tasa como en el ejemplo de arriba — las dos formas son la misma ruta.

"conceptos": [
  { "importe_minor": 5000, "treatment": "tasa16", "no_identificacion": "TICKET-00417" },
  { "importe_minor": 5000, "treatment": "tasa16", "no_identificacion": "TICKET-00418" }
]

Corregir una global ya timbrada

Una global mal capturada no se borra ni se retimbra sola: el SAT exige el mismo orden que para cualquier CFDI con relacionados vivos — primero se emite el comprobante que la sustituye (relación 04), y solo después se cancela la original con motivo 01 apuntando al nuevo folio fiscal.

1. Emite la global correcta con sustituye_uuid = el uuid_fiscal de la que estás corrigiendo, para el mismo período (periodicidad/meses/año idénticos).
2. Con el uuid_fiscal que te devuelve esa emisión, cancela la original — POST /v1/invoices/{id}/cancel con motive: "01" y substitution_uuid apuntando al nuevo folio (contrato completo, con el aviso de la demora del SAT para reconocer el UUID recién timbrado, en Cancelar un CFDI ya timbrado más abajo).

Entre esos dos pasos existen, LEGÍTIMAMENTE, dos globales vivas del mismo período: si el índice único las prohibiera, la corrección no tendría ninguna primera jugada posible. Mientras no sustituyas, solo puede haber una global viva por (ambiente + periodicidad mensual o bimestral + meses + año) — un segundo intento del mismo período responde invoice.global_already_exists con el id de la que ya existe.

Errores propios de esta ruta

Las de configuración de cuenta de siempre — invoice.fiscal_profile_missing, invoice.pac_credentials_missing— aplican igual que en el resto de rutas de facturación.

Cancelar un CFDI ya timbrado

POST /v1/invoices/{id}/cancel cancela ante el SAT cualquier CFDI de ingreso que hayas timbrado por esta API — PUE, PPD o factura global — con los cuatro motivos del Anexo 20. Es idempotente: cancelar una factura que ya está canceled devuelve éxito sin volver a llamar al PAC. El uuid_fiscal del timbre no cambia: es terminal, la cancelación no lo reemplaza (regla 4 — estados terminales inmutables).

Cuerpo

Authorization y Idempotency-Key son requeridos, igual que en todo POST bajo /v1/invoices* (regla 8): cancelar mueve el estado FISCAL de un comprobante ante el SAT tanto como emitirlo.

Ejemplo

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-de0c-4961-98eb-e0cacfc6aae8/cancel \
  -X POST \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Un cuerpo vacío es válido: motive cae al 02 por defecto. Para cancelar con sustitución (motivo 01 — el caso de corregir una global):

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-de0c-4961-98eb-e0cacfc6aae8/cancel \
  -X POST \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "motive": "01",
    "substitution_uuid": "5b21f6a0-7e3c-4a1e-9b3d-8f9c6d2a1234"
  }'

{
  "object": "invoice",
  "id": "5cee05bd-de0c-4961-98eb-e0cacfc6aae8",
  "status": "canceled",
  "uuid_fiscal": "..."
}

Nota que esta respuesta es más chica que el invoice completo de las rutas de emisión (sin total_minor, receptor, etc.): solo lo que confirma la cancelación. Para el resto de los datos del CFDI, consulta GET /v1/invoices/{id}.

Errores propios de esta ruta

Descarga del CFDI (PUE, PPD o GLOBAL) — con tu llave, no confundir con Autofactura

Estas dos rutas descargan cualquier CFDI de tu cuenta ya timbrado — el que timbraste con POST /v1/invoices, /pue, /ppd o /global — y exigen tu Authorization, igual que el resto de /v1/*.

Ambos requieren que el CFDI esté stamped — si no, 400 invoice.not_stamped.

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-de0c-4961-98eb-e0cacfc6aae8/xml \
  -H "Authorization: Bearer $SK" -o factura.xml
curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-de0c-4961-98eb-e0cacfc6aae8/pdf \
  -H "Authorization: Bearer $SK" -o factura.pdf

Autofactura: que el cliente facture su propio ticket

Para el mostrador que no captura el RFC en el momento del cobro, pero deja la puerta abierta a facturar después: cada cobro trae un receipt_code corto (formato W-XXXXX) desde que se crea el payment_intent — es el dato que le pides al cliente para que facture su propio ticket sin tu intervención, si al final sí quiere su factura con RFC.

{
  "id": "5cb2d99f-a290-45fc-81c5-acb5aa4b0d79",
  "object": "payment_intent",
  "amount_minor": 900,
  "currency": "MXN",
  "status": "requires_payment_method",
  "client_secret": "pi_secret_TD3ZDUAfULIGL2N-...",
  "receipt_code": "W-EMU7K",
  "livemode": false,
  "created_at": "2026-07-08T02:19:32.63073+00:00",
  "updated_at": "2026-07-08T02:19:32.63073+00:00"
}

Imprímelo en el ticket físico (o mándalo por SMS/WhatsApp) junto con la URL pública de autofactura de tu comercio: https://winal.com.mx/factura/{slug} — el slug es el mismo identificador corto de tu tenant que se configura en portal → Facturación → Autofactura (junto con el interruptor de habilitarla).

POST /public/autofactura/{slug}/invoices — sin Authorization

El cliente captura su RFC y datos fiscales en la página pública; ésta llama este endpoint sin ninguna clave — la combinación de receipt_code + rfc es la única llave. Los mismos cinco campos de receptor que en PUE/PPD, más el receipt_code del ticket:

curl -s https://api.winal.com.mx/public/autofactura/antech/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_code": "W-EMU7K",
    "rfc": "EKU9003173C9",
    "nombre": "ESCUELA KEMPER URGATE",
    "uso_cfdi": "G03",
    "regimen_fiscal": "601",
    "cp": "45050"
  }'

{
  "error": {
    "type": "invalid_request_error",
    "code": "autofactura.generic_rfc_not_allowed",
    "message": "Para facturar a nombre de 'público en general' ya no se emite un comprobante individual: el SAT lo prohíbe. No tienes que hacer nada — tu compra queda amparada en la factura global que el comercio emite por todas las ventas del período. Si necesitas la factura a tu nombre, captura tu propio RFC.",
    "doc_url": "https://winal.com.mx/docs/errores.html#err-autofactura.generic_rfc_not_allowed",
    "request_id": "0HNMSIOBNVS9K:00000001"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invoice.pac_error",
    "message": "El PAC rechazó el timbrado (CFDI 492400bb-969b-413b-97b8-93789f34ddb4 quedó en 'error'): ",
    "doc_url": "https://winal.com.mx/docs/errores.html#err-invoice.pac_error",
    "request_id": "0HNMSIOBNVS9K:00000001"
  }
}

Descargas: receipt_code + rfc como llave

Nota la ruta: pública, bajo /public/autofactura/{slug}/..., sin Authorization — la llave es el par receipt_code+rfc del cliente final. Es una ruta distinta de GET /v1/invoices/{id}/xml/pdf (privada, con tu llave, para cualquier CFDI de tu cuenta) — ver el aviso en Descarga del CFDI arriba si no tienes claro cuál te toca.

curl -s "https://api.winal.com.mx/public/autofactura/antech/invoices/{id}/xml?receipt_code=W-EMU7K&rfc=EKU9003173C9"
curl -s "https://api.winal.com.mx/public/autofactura/antech/invoices/{id}/pdf?receipt_code=W-EMU7K&rfc=EKU9003173C9"

Ambos parámetros deben coincidir con el CFDI ya timbrado — igual que el resto de descargas de esta página, 400 invoice.not_stamped si el CFDI aún no timbra.

Anti-enumeración, en dos capas

Igual que el client_secret de checkout público, autofactura nunca revela cuál dato falló:

Lo que todavía NO existe

Sin adornos, para que no lo descubras en tu primer cierre de mes:

Lo que YA no está en esta lista: la factura global (arriba) y el cruce CP del receptor genérico contra tu lugar de expedición, que la global satisface por construcción —Winal arma ese receptor, tú no lo mandas—. Las otras tres rutas ya no aceptan en absoluto el RFC genérico nacional (ver CFDI40130), así que ese cruce dejó de ser un caso posible ahí también.

La cancelación de un CFDI SÍ existe como endpoint — POST /v1/invoices/{id}/cancel, documentado arriba con su cuerpo, respuesta y la demora real del SAT para reconocer un timbre recién emitido— y las notas de crédito también, con su ciclo completo (crear —por reembolso de Winal o, sin él, declarando el monto— listar, consultar, descargar y cancelar): ver Nota de crédito más abajo.

Nota de crédito: el CFDI de egreso que cierra una devolución

Cuando devuelves dinero de una factura ya timbrada, el CFDI de ingreso original NO se toca —los estados terminales de un CFDI son inmutables (regla 4)— así que el reembolso se documenta con un comprobante nuevo: la nota de crédito, un CFDI 4.0 de tipo Egreso (E). Sin ella, el ingreso original queda vivo ante el SAT sin contraparte: IVA de más acreditado, ingresos inflados.

POST /v1/invoices/{id}/credit-notes — emitir por un reembolso de Winal

Hay un tercer detalle, menos visible pero igual de importante: el monto fiscal sale del reembolso REAL, no de lo que mandes en el cuerpo. refund_id tiene que apuntar a un refund tuyo que ya esté succeeded, y amount_minor/ currency son solo una confirmación: si no coinciden EXACTO con el monto y la moneda de ese reembolso, la API rechaza la nota — así nunca se puede timbrar un egreso por un monto distinto del que de verdad salió de tu cuenta.

curl -s https://api.winal.com.mx/v1/invoices/f47e2b91-6a3d-4c8e-9b2a-1d5e8f3c6a97/credit-notes \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_id": "b3f6a1c2-8e4d-4a9b-9c1e-2f6a8b0d5e17",
    "amount_minor": 23200,
    "forma_pago": "01",
    "motivo": "Devolución de mercancía",
    "serie": "NC",
    "folio": "0007"
  }'

{
  "object": "credit_note",
  "id": "7a2e4c1b-9f3d-4b6e-8a2c-1d5f9e3b7c4a",
  "invoice_id": "f47e2b91-6a3d-4c8e-9b2a-1d5e8f3c6a97",
  "refund_id": "b3f6a1c2-8e4d-4a9b-9c1e-2f6a8b0d5e17",
  "status": "stamped",
  "uuid_fiscal": "...",
  "related_uuid": "...",
  "serie": "NC",
  "folio": "0007",
  "total_minor": 23200,
  "base_minor": 20000,
  "iva_minor": 3200,
  "currency": "MXN",
  "motivo": "Devolución de mercancía"
}

related_uuid es el uuid_fiscal de la factura de ingreso que esta nota acredita — la relación 01 del Anexo 20, la que Winal arma por ti. Nota que este shape NO trae ieps_minor: hoy una nota de crédito nunca lo lleva — ver el límite en IEPS por concepto.

Acreditar el TOTAL exacto de la factura (nada acreditado antes) reexpide sus MISMAS líneas, con sus mismos impuestos ya timbrados. Por eso la nota total sí se emite sobre una factura de tasas mezcladas (perfumería al 16%, medicina exenta) y también sobre una con IEPS (el refresco y la botana del mismo ticket): cada línea conserva su tratamiento y su traslado del 003, así que el impuesto devuelto es al centavo el que se trasladó, sin recalcular nada.

Acreditar solo una PARTE es otro problema y sigue sin soportarse en esos dos casos — invoice.mixed_rate_unsupported con tasas mezcladas, invoice.ieps_breakdown_unsupported con IEPS—. El motivo cabe en una línea: repartir un importe entre tasas (o entre impuestos) exige saber qué línea se devolvió, y eso solo lo sabe quien recibió la devolución; repartirlo "a prorrata" inventaría un IVA o un IEPS que nadie trasladó. La salida es cancelar el comprobante y reexpedirlo por lo que sí queda vendido. Ver Límites en IEPS por concepto.

Errores propios de esta ruta

Todos los 400 salvo dos: invoice.not_found y invoice.refund_not_found responden 404 — el resto, incluidos los que documentan un conflicto de estado (invoice.not_stamped), responde 400 (misma regla de mapeo por subcadena que el resto de la Api; ver Errores).

POST /v1/invoices/{id}/credit-notes/pue — emitir SIN reembolso de Winal

El equivalente exacto de POST /v1/invoices/pue pero para el EGRESO: la devolución de mostrador de una venta que Winal nunca cobró —el caso central de una farmacia, y el que motivó esta ruta— no tiene refund_id del cual leer el monto, así que lo declaras tú, junto con forma_pago (con qué DEVOLVISTE el dinero). Por lo demás es el MISMO trámite fiscal que la ruta de arriba: mismo tope agregado por factura, misma relación CfdiRelacionados tipoRelacion 01 que Winal arma por ti, mismo importe SIEMPRE positivo, mismo sellador de egreso — lo único que cambia es de dónde sale el monto.

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-de0c-4961-98eb-e0cacfc6aae8/credit-notes/pue \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": 23200,
    "forma_pago": "01",
    "motivo": "Devolución de mercancía en el mostrador",
    "serie": "NC",
    "folio": "0008"
  }'

Misma respuesta 200 que la ruta por reembolso, con refund_id: null:

{
  "object": "credit_note",
  "id": "3c8a7d1e-5b2f-4e9a-8c6d-0f1a3b7c9e42",
  "invoice_id": "5cee05bd-de0c-4961-98eb-e0cacfc6aae8",
  "refund_id": null,
  "status": "stamped",
  "uuid_fiscal": "...",
  "related_uuid": "...",
  "serie": "NC",
  "folio": "0008",
  "total_minor": 23200,
  "base_minor": 20000,
  "iva_minor": 3200,
  "currency": "MXN",
  "motivo": "Devolución de mercancía en el mostrador"
}

Errores propios de esta ruta

Idempotencia: esta ruta NO tiene refund_id del cual deduplicar, así que reintentarla con una Idempotency-Key DISTINTA crea una nota nueva — es tu responsabilidad no reenviar la misma devolución dos veces con llaves diferentes. Con la MISMA llave, el protocolo de idempotencia de la API (header obligatorio en todo POST /v1/invoices*) sí te protege del reintento por timeout.

GET /v1/invoices/{id}/credit-notes — listar

Todas las notas de crédito (en cualquier estado) de una factura, del más nuevo al más viejo.

{ "object": "list", "data": [] }

GET /v1/invoices/{id}/credit-notes/{creditNoteId} — consultar

Devuelve el mismo shape credit_note de arriba. La nota tiene que pertenecer a la factura {id} de la ruta: una nota de OTRA factura del mismo tenant se ve como invoice.credit_note_not_found (404) — no un 403, para no confirmar que el id existe en otro lado.

GET /v1/invoices/{id}/credit-notes/{creditNoteId}/xml · /pdf — descargar

Mismo patrón que la descarga de una factura: application/xml o application/pdf, con tu Authorization. La diferencia es que aquí SÍ puedes descargar una nota ya canceled —el comprobante existió y su XML es justo lo que hay que conservar cinco años—; lo único que no se descarga es una que nunca llegó a timbrarse (400 invoice.credit_note_not_stamped).

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-.../credit-notes/7a2e4c1b-.../xml \
  -H "Authorization: Bearer $SK" -o nota-credito.xml

POST /v1/invoices/{id}/credit-notes/{creditNoteId}/retry — reintentar

La salida de una nota que quedó en error, espejo de POST /v1/invoices/{id}/retry. No emite otra nota: vuelve a mandar EL MISMO comprobante —mismos importes, mismas líneas, misma serie/folio, misma forma de pago y la misma fecha de expedición—, marcado como reintento, así que un PAC que sabe recuperar el timbre devuelve el folio anterior en vez de emitir uno nuevo. Sin cuerpo: todo lo que determina el comprobante ya quedó guardado antes de la primera llamada al PAC.

Es importante que uses ESTA ruta y no emitas una nota nueva cuando el PAC no respondió: dos CFDI de egreso vivos por la misma devolución acreditan el IVA dos veces, y no se borran — se cancelan, dejando rastro fiscal de los dos. (Por eso, además, una nota con desenlace incierto sigue ocupando su parte del tope acreditable de la factura hasta que se aclare.)

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-.../credit-notes/7a2e4c1b-.../retry \
  -X POST \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)"

Devuelve el credit_note ya stamped. Si la nota ya estaba timbrada (o cancelada) el reintento es un no-op exitoso: te la devuelve sin llamar al PAC. Y si no se puede reintentar —tiene un intento EN CURSO, otro reintento se adelantó, o se emitió antes de que Winal guardara lo que la hace reproducible— responde invoice.credit_note_not_retryable con la salida en el mensaje.

POST /v1/invoices/{id}/credit-notes/{creditNoteId}/cancel — cancelar

Mismo contrato que POST /v1/invoices/{id}/cancel — los cuatro motivos del SAT, motive: "01" exige substitution_uuid, idempotente (cancelar una nota ya canceled es éxito sin llamar de nuevo al PAC), y la misma demora real del SAT para reconocer un timbre recién emitido. La diferencia frente a la cancelación de una factura: la respuesta aquí es el credit_note completo (no un shape recortado).

curl -s https://api.winal.com.mx/v1/invoices/5cee05bd-.../credit-notes/7a2e4c1b-.../cancel \
  -X POST \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Errores propios: invoice.invalid_cancel_motive, invoice.cancel_substitution_required, invoice.credit_note_not_stamped (solo se cancela lo que sí timbró), invoice.no_provider_ref y invoice.pac_cancel_error — el mismo cuarteto que la cancelación de una factura, sobre la nota de crédito en vez del CFDI de ingreso.

Siguiente paso