Vender por referencias (recomendada)
POST /partners/v1/invoices Ver operación en la Referencia → - No sobrescribe los datos fiscales del cliente: una referencia nunca modifica el registro; con un objeto, cada venta lo reescribe con lo que envías.
- Payloads más pequeños: la venta lleva un texto de 36 caracteres por registro, no el objeto entero.
- Reutilización: el mismo registro sirve a todas las ventas, y lo corriges en un solo lugar.
Paso 1 · Ten las piezas en el catálogo
Cada pieza que cita la venta tiene que existir en el catálogo de tu empresa. El
Mapa del catálogo dice qué pieza va en qué campo de la venta,
y Sincronizar tu catálogo cómo crearla o actualizarla con tu
internalId y guardar su id de Openbox Cloud.
Paso 2 · Crea la venta con referencias
La referencia es el id de Openbox Cloud como texto, en el mismo campo donde iría el objeto (Referencia u objeto). Puedes mezclar: una referencia en un campo y un objeto en otro.
{
"settings": { "notify": "EMAIL", "internalId": "VTA-0002" },
"data": {
"header": {
"documentType": "CCF",
"customer": "0a1b2c3d-1111-9999-0000-123456789abc",
"paymentCondition": "5e6f7a8b-2222-9999-0000-123456789abc",
"invoicesSeller": "9c0d1e2f-3333-9999-0000-123456789abc"
},
"details": [
{ "service": "4b5c6d7e-4444-9999-0000-123456789abc", "product": null, "quantity": 1 }
]
}
}
curl -X POST "$OPENBOX_API_URL/partners/v1/invoices" \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d @venta.json
Los tipos de documento y la respuesta son los mismos de Vender con payload completo; el esquema completo, campo por campo, está en la Referencia.
Dos modos: calculado y precalculado
Lo que envíes en totals decide el modo.
Modo calculado (sin montos)
Omite todos los montos de línea y de totales y Openbox Cloud los calcula con el mismo cálculo de la
aplicación web. Toda línea va por referencia; el price es opcional (sin él, se usa el precio del
catálogo vigente) y el sellingType, si lo envías, debe ser el del catálogo. En totals solo puedes
enviar descuNoSuj, descuExenta, descuGravada e ivaRete1. La FEX solo admite servicios.
Modo precalculado (con montos)
Envías todos los montos y Openbox Cloud los verifica al centavo, con las reglas de Vender con payload completo.
Qué se rechaza antes de escribir
Una venta por referencias nunca modifica el catálogo. Estos cuatro tipos de 400 llegan antes de
escribir nada y de llamar al MH:
- Validación: la petición no cumple el contrato;
messagenombra el campo. REFERENCE_NOT_FOUND: una referencia no existe en tu empresa o fue eliminada;messagenombra el recurso.INSUFFICIENT_DATA_TO_CALCULATE: faltan datos para el modo (por ejemplo, un solo monto entotals, o una línea como objeto en el modo calculado);messagenombra el campo.- Monto que no coincide:
messagenombra el campo, lo que enviaste y el valor correcto.
Crear y anular una venta exigen el módulo Facturación en el perfil de tu llave: ver Permisos por módulo. Si tu integración hoy envía objetos, el paso a paso para cambiar está en Migrar a referencias.