Recetas

Vender con payload completo

La venta lleva el cliente, las líneas y los totales completos, cada registro como objeto.
DisponiblePOST /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.

Hay una segunda forma, por referencias, que es la recomendada para integraciones nuevas: ve a Vender por referencias. Para pasar de una a otra, ver Migrar a referencias.

Tipos de documento

data.header.documentType acepta:

ValorDocumento
CCFComprobante de crédito fiscal
FCFFactura de consumidor final
NCNota de crédito (usa creditFor con el documento que corrige)
FEXFactura 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.

  1. 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.
  2. Las líneas suman los totales por categoría (no sujeto, exento, gravado).
  3. subTotalVentas es esa suma y subTotal es subTotalVentas menos los descuentos.
  4. totalIva es 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 cuando totalIva es la suma del IVA de las líneas y no el 13 % del gravado tras descuento (si totalIva es ese 13 %, el IVA de cada línea no se verifica). En FEX no se verifica.
  5. ivaRete1 es 0 o el 1 % del gravado tras descuento (FEX: 0).
  6. 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).

Terminal
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.

venta.json
{
  "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.

Envía siempre tu internalId en settings. Si una petición se corta, con él compruebas si la venta ya existe antes de volver a enviarla (Reintentos).
Copyright © 2026