# Facturar un pedido o una cotización (timbrar CFDI)

POST https://api.wizerp.com/api/v1/ventas/{clave}/facturar

Convierte en FACTURA un pedido o una cotización que creaste con POST /ventas y pide su CFDI de ingreso al SAT. Es la misma conversión de la pantalla de Ventas: descuenta el inventario, crea la cuenta por cobrar y la póliza, y registra la factura con su folio. NO se puede deshacer borrando: se cancela desde Wizerp.

EL TIMBRADO ES ASÍNCRONO. La respuesta es 202 con la clave de la factura y estado "timbrando"; el UUID llega segundos después. Consúltalo con GET /facturas?venta=<clave de la venta> (o ?clave=<factura>): estatus "vigente" y su uuid cuando quedó timbrada, "error" si el SAT o el PAC la rechazaron (se corrige y se vuelve a timbrar desde Wizerp).

UNA VENTA SE FACTURA UNA SOLA VEZ POR LA API. Si repites la petición —con la misma Idempotency-Key o con otra— no se crea otra factura: responde 200 con la factura ya pedida, su estado al día y ya_solicitada = true.

Sólo se facturan pedidos y cotizaciones creados con POST /ventas (una venta capturada en Wizerp responde 422 venta_no_api), vigentes, no facturados y, si es pedido, sin surtido. Antes de tocar nada se revisa: que tu plan incluya facturación, que el certificado de sello digital esté cargado y vigente, que el cliente tenga RFC válido, régimen fiscal, código postal fiscal y uso de CFDI, que la venta tenga condición, método y forma de pago, y —como en la pantalla— el crédito disponible y los saldos vencidos si es a crédito, o el anticipo mínimo que pida tu configuración si es de contado. Cualquier falla responde 422 con un código claro y no convierte nada; corregido el dato, se puede volver a pedir.

forma_pago_sat, metodo_pago_sat y uso_cfdi sólo COMPLETAN lo que le falte a la venta (como el aviso de campos faltantes de la pantalla): si la venta ya trae otro valor responde 422 dato_ya_capturado. Si la venta ya tiene todo, manda un cuerpo vacío: {}. La serie y el folio salen de la sucursal de la venta; las ventas de POST /ventas son de la matriz (sucursal 0).

Si en ese momento la misma venta se está facturando desde Wizerp, responde 503 reintentable.

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Permiso: facturas:write

## Cuerpo JSON
- `forma_pago_sat` (texto): Forma de pago del SAT (p. ej. "03" transferencia, "99" por definir). Sólo si la venta no la tiene.
- `metodo_pago_sat` (texto): Método de pago del SAT: "PUE" o "PPD". Sólo si la venta no lo tiene.
- `uso_cfdi` (texto): Uso de CFDI del SAT (p. ej. G03), compatible con el régimen y el RFC del cliente. Sólo si la venta no lo tiene; si no lo mandas se usa el del cliente.
- `sucursal` (entero): Sucursal de la venta (0 = matriz, el valor por omisión). Debe coincidir con la de la venta.

https://api.wizerp.com/api/v1/ventas/{clave}/facturar

Convierte en FACTURA un pedido o una cotización que creaste con POST /ventas y pide su CFDI de ingreso al SAT. Es la misma conversión de la pantalla de Ventas: descuenta el inventario, crea la cuenta por cobrar y la póliza, y registra la factura con su folio. NO se puede deshacer borrando: se cancela desde Wizerp.

EL TIMBRADO ES ASÍNCRONO. La respuesta es 202 con la clave de la factura y estado "timbrando"; el UUID llega segundos después. Consúltalo con GET /facturas?venta=<clave de la venta> (o ?clave=<factura>): estatus "vigente" y su uuid cuando quedó timbrada, "error" si el SAT o el PAC la rechazaron (se corrige y se vuelve a timbrar desde Wizerp).

UNA VENTA SE FACTURA UNA SOLA VEZ POR LA API. Si repites la petición —con la misma Idempotency-Key o con otra— no se crea otra factura: responde 200 con la factura ya pedida, su estado al día y ya_solicitada = true.

Sólo se facturan pedidos y cotizaciones creados con POST /ventas (una venta capturada en Wizerp responde 422 venta_no_api), vigentes, no facturados y, si es pedido, sin surtido. Antes de tocar nada se revisa: que tu plan incluya facturación, que el certificado de sello digital esté cargado y vigente, que el cliente tenga RFC válido, régimen fiscal, código postal fiscal y uso de CFDI, que la venta tenga condición, método y forma de pago, y —como en la pantalla— el crédito disponible y los saldos vencidos si es a crédito, o el anticipo mínimo que pida tu configuración si es de contado. Cualquier falla responde 422 con un código claro y no convierte nada; corregido el dato, se puede volver a pedir.

forma_pago_sat, metodo_pago_sat y uso_cfdi sólo COMPLETAN lo que le falte a la venta (como el aviso de campos faltantes de la pantalla): si la venta ya trae otro valor responde 422 dato_ya_capturado. Si la venta ya tiene todo, manda un cuerpo vacío: {}. La serie y el folio salen de la sucursal de la venta; las ventas de POST /ventas son de la matriz (sucursal 0).

Si en ese momento la misma venta se está facturando desde Wizerp, responde 503 reintentable.

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Requiere el permiso facturas:write en la llave · contrato del 2026-10-12

Parámetros de ruta

Cuerpo JSON

Además, toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar.

Respuestas