Facturación: cómo funciona

Facturación cierra la venta. Convierte un carrito en una orden con su total a pagar, recibe el comprobante con el que el cliente dice que pagó y lo deja en una cola para que una persona lo apruebe o lo rechace. Al aprobarlo, la venta se confirma en Productos y la orden queda pagada, lista para despachar.

Por API lo usas para cobrar desde tu propia tienda o tu propio chat, subir los comprobantes que te llegan por otros canales, revisar los pagos desde tu sistema y marcar los pedidos despachados.

También puedes hacerlo desde la consola: en el Estudio de un espacio con el módulo activo, el panel Facturación lista las órdenes y sus comprobantes, enseña cada comprobante y permite aprobarlo o rechazarlo, cancelar la orden o marcarla despachada.

Antes de empezar

• El espacio tiene que tener el módulo Facturación: facturacion sale en sus módulos en GET /api/companies. Si no, cada ruta responde 403 módulo no habilitado para este espacio.
• Leer (las rutas GET) vale con cualquier clave. Crear órdenes, subir y decidir comprobantes, cancelar, despachar y cambiar la configuración piden una clave escribe.
• Las rutas cuelgan de /api/mod/facturacion/{espacio}/, con la misma clave y los mismos límites que el resto de la API. Si el módulo no responde en ese momento, la ruta da 502: reintenta.
• No gasta créditos: ninguna ruta del módulo descuenta de tu bolsa.
• Las órdenes usan el catálogo de Productos: el espacio necesita también ese módulo, con sus variantes y precios.

Una venta, paso a paso

1. Una sola vez: configura las cuentas donde te pagan (Nequi, Bancolombia, efectivo…).
2. Crea la orden con las variantes y cantidades, y el envío si lo cotizaste en Comercial. Responde 201 con el total, el expira_at y las cuentas activas.
3. Dile al cliente cuánto pagar y dónde: el total y las cuentas de la orden.
4. Cuando te mande el comprobante, súbelo. La orden pasa a under_review.
5. Revisa la cola, mira el archivo y apruébalo o recházalo.
6. Si usas datos de despacho, guárdalos y, al enviar el pedido, márcalo despachado.

Las órdenes sin pagar no vencen solas: llama de vez en cuando a vencer órdenes para pasarlas a expired y liberar su stock.

Los estados de una orden

pending_payment → (comprobante) → under_review → (aprobar) → paid → (despachar) → fulfilled
                                 under_review → (rechazar) → rejected → (otro comprobante) → under_review
pending_payment → (vencer órdenes, pasado expira_at) → expired
pending_payment | under_review | rejected → (cancelar) → cancelled

Cada cambio queda en la historia de la orden, con quién lo hizo y por qué. Un cambio que el estado no permite responde 409.

La revisión de los pagos

Un pantallazo de una transferencia no prueba que el dinero llegó: uno falso y uno real pueden verse iguales. Por eso, por defecto, ningún pago se aprueba solo: cada comprobante espera en la cola a que una persona lo mire y decida.

Para ayudar a decidir, a cada comprobante se le hacen cinco comprobaciones, que salen en reglas_json:

Las comprobaciones usan lo que se leyó del comprobante (extraccion_json). Si no se pudo leer (ok: false), las que dependen de lo leído no pasan, nunca se aprueba solo y decides a ojo.

Aprobación automática. Un comprobante se aprueba solo únicamente si pasa las cinco, el total de la orden no supera auto_aprobar_hasta y la configuración tiene requiere_confirmacion_humana_siempre: false. De fábrica, auto_aprobar_hasta es 0 y la confirmación humana está encendida: nunca se aprueba solo.

pending_review → (aprobar) → approved     la orden pasa a paid
               → (rechazar) → rejected   la orden pasa a rejected

Los comprobantes son datos personales del cliente: nombres, números de cuenta, montos. El archivo se sirve sin caché (Cache-Control: private, no-store): pídelo cuando alguien lo vaya a mirar y no lo guardes en otros sistemas.

Los datos de despacho

Si vendes con envío, Facturación puede guardar en la orden lo que necesitas para despachar. Viene apagado; lo enciendes en la configuración con despacho.activo: true.

• Tú decides qué se pide: cada campo (nombre, cedula, telefono, direccion, barrio, ciudad…) se activa y se marca requerido por separado.
• Los datos se van sumando: guárdalos a medida que el cliente los da. Cada orden dice en despacho_status.faltantes qué falta.
• Con bloquea_fulfillment (encendido de fábrica), una orden no se puede marcar despachada hasta tener todos los requeridos: 409 despacho_incompleto.
• Un campo que no pediste no se guarda: el módulo no acepta datos personales que nadie pidió.

Con Productos, Comercial y Ventas

• Productos pone los precios: al crear la orden se le pide la cotización del carrito (con sus promociones) y la orden la congela. Si reservar_stock está encendido, también aparta el stock. Al aprobar el pago, se le confirma la venta: descuenta el stock y cuenta el uso de las promociones.
• Comercial pone el envío y los beneficios. Lo que cotiza entra en la orden como envio (su total_envio), tarifa_version y descuento. El total de la orden es el de Productos, menos ese descuento, más el envío.
• Ventas hace todo esto solo en el chat: cotiza con Productos y Comercial, crea la orden, le da al cliente el total y las cuentas, y sube aquí el comprobante que el cliente le manda. A ti te queda la cola de revisión.
• Contabilidad: con emitir_factura_contable encendido, cada orden pagada envía su factura a tu software contable. Si eso falla, la orden queda pagada igual.

Rutas