Vender con payload completo
POST /partners/v1/invoices Ver operación en la Referencia → POST /partners/v1/invoices crea la venta, la presenta al MH y devuelve su estado. Esta página
describe la forma con payload completo, la que usan hoy las integraciones existentes: cada
venta lleva todos sus registros como objeto y todos sus montos calculados por ti.
Tipos de documento
data.header.documentType acepta:
| Valor | Documento |
|---|---|
CCF | Comprobante de crédito fiscal |
FCF | Factura de consumidor final |
NC | Nota de crédito (usa creditFor con el documento que corrige) |
FEX | Factura de exportación |
Cada registro como objeto
El cliente, la condición de pago, el vendedor (y su zona) y el servicio o producto de cada línea aceptan un objeto o una referencia en el mismo campo (Referencia u objeto). En esta forma todos van como objeto: cada venta reescribe el registro con lo que envías, así que si tu sistema manda un dato fiscal del cliente desactualizado, ese es el que queda.
Modo precalculado: tus montos, verificados al centavo
Cuando totals trae al menos uno de sus montos (totalNoSuj, totalExenta, totalGravada,
subTotalVentas, subTotal, reteRenta, montoTotalOperacion, totalIva o totalPagar), la venta
está en modo precalculado. Los descuentos (descuNoSuj, descuExenta, descuGravada) e
ivaRete1 no cuentan: con solo ellos la venta sigue en modo calculado. En modo precalculado envías los
13 campos de totals (con ivaRete1, en 0 si no hay retención) y los siete montos de cada línea, y
Openbox Cloud los verifica al centavo antes de crear nada. reteRenta y montoTotalOperacion
siguen siendo obligatorios por compatibilidad, pero Openbox Cloud no los verifica ni los guarda.
- Cada línea: cantidad × precio unitario = monto de la línea, y el monto va solo en la columna de su tipo de venta. En una FCF también vale la forma con IVA: cantidad × (precio + IVA unitario) = monto + IVA de la línea.
- Las líneas suman los totales por categoría (no sujeto, exento, gravado).
subTotalVentases esa suma ysubTotalessubTotalVentasmenos los descuentos.totalIvaes la suma del IVA de las líneas o el 13 % del gravado tras descuento (FEX: 0). Una línea exenta o no sujeta lleva IVA 0. El IVA de una línea gravada es el 13 % de su monto, el 13 % de su monto tras su parte proporcional del descuento gravado o, en una FCF, el de la forma con IVA. Se verifica siempre en FCF; en CCF y NC, solo cuandototalIvaes la suma del IVA de las líneas y no el 13 % del gravado tras descuento (sitotalIvaes ese 13 %, el IVA de cada línea no se verifica). En FEX no se verifica.ivaRete1es 0 o el 1 % del gravado tras descuento (FEX: 0).totalPagar=subTotal+totalIva−ivaRete1.
Si un monto no coincide, la respuesta es 400 y su message nombra el campo, lo que enviaste y el
valor correcto, por ejemplo totals.totalPagar: se envió 7789.89; el valor correcto es 7720.95. No
se escribe nada ni se llama al MH. Si prefieres no calcular, omite los montos y usa el modo calculado
de Vender por referencias.
La operación exige el módulo Facturación en el perfil de tu llave; sin él responde 403
(Permisos por módulo).
curl -X POST "$OPENBOX_API_URL/partners/v1/invoices" \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d @venta.json
venta.json lleva settings (notify: EMAIL o NONE, y tu internalId de la venta) y data
(header, details, totals). Un ejemplo en modo precalculado, con el cliente abreviado: la línea
va como objeto, así que lleva price, incIva, chargeDescription y sellingType (1 no sujeto,
2 exento, 3 gravado), además de sus siete montos; totals lleva sus 13 campos.
{
"settings": { "notify": "EMAIL", "internalId": "VTA-0001" },
"data": {
"header": {
"documentType": "CCF",
"customer": {
"name": "Cliente Ejemplo, S.A. de C.V.",
"svFields": { "nit": "…", "nrc": "…" }
},
"paymentCondition": { "name": "Contado", "cashPayment": true },
"invoicesSeller": { "name": "Vendedor 1", "zone": { "name": "Zona Central" } }
},
"details": [
{
"service": { "name": "Consulta" },
"quantity": 2,
"price": 25,
"incIva": false,
"chargeDescription": "Consulta",
"sellingType": 3,
"unitPrice": 25,
"ivaPrice": 3.25,
"ventaPrice": 50,
"totalNoSuj": 0,
"totalExenta": 0,
"totalGravada": 50,
"totalIvaPrice": 6.5
}
],
"totals": {
"totalNoSuj": 0,
"totalExenta": 0,
"totalGravada": 50,
"subTotalVentas": 50,
"descuNoSuj": 0,
"descuExenta": 0,
"descuGravada": 0,
"subTotal": 50,
"ivaRete1": 0,
"reteRenta": 0,
"montoTotalOperacion": 56.5,
"totalIva": 6.5,
"totalPagar": 56.5
}
}
}
El esquema completo, campo por campo, está en la Referencia.
Respuesta
La venta responde con su id de Openbox Cloud, los enlaces pdfURL y jsonURL, su status
(EMITIDA, PRESENTADA, ANULADA o CONTINGENCIA) y haciendaResponse, la respuesta del MH.
Guarda el id: con él la consultas y la
anulas.
internalId en settings. Si una petición se corta, con él compruebas si la
venta ya existe antes de volver a enviarla (Reintentos).