Recetas

Vender por referencias (recomendada)

Crea primero el catálogo y luego vende citando cada registro por su UUID de Openbox Cloud.
DisponiblePOST /partners/v1/invoices Ver operación en la Referencia →
Esta es la forma recomendada. Registras una sola vez el cliente, los servicios o productos, la condición de pago, el vendedor y la zona en el catálogo, y cada venta los cita por su id de Openbox Cloud en lugar de enviarlos completos.
  • 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.

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.

venta.json (fragmento)
{
  "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 }
    ]
  }
}
Terminal
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:

  1. Validación: la petición no cumple el contrato; message nombra el campo.
  2. REFERENCE_NOT_FOUND: una referencia no existe en tu empresa o fue eliminada; message nombra el recurso.
  3. INSUFFICIENT_DATA_TO_CALCULATE: faltan datos para el modo (por ejemplo, un solo monto en totals, o una línea como objeto en el modo calculado); message nombra el campo.
  4. Monto que no coincide: message nombra 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.

Copyright © 2026