Recetas

Migrar de payload completo a referencias

Pasa una integración que envía objetos a citar el catálogo por id, campo por campo y sin cortar la facturación.
DisponiblePOST /partners/v1/invoices Ver operación en la Referencia →

Esta receta es para una integración con payload completo: cada venta envía el cliente, las líneas y la condición de pago como objetos. Al migrar, cada venta cita esos registros por su id de Openbox Cloud y deja de reescribirlos (Referencia u objeto). La migración es gradual: la venta acepta una referencia en un campo y un objeto en otro.

Paso 1 · Sincroniza el catálogo con tu internalId

Registra cada cliente, servicio, producto, vendedor, zona y condición de pago con tu internalId, como en Sincronizar tu catálogo. Si un registro ya existe en Openbox Cloud porque tus ventas lo crearon como objeto, búscalo y asígnale tu internalId con una actualización.

DisponibleGET /partners/v1/customers Ver operación en la Referencia →

Paso 2 · Guarda los ids de Openbox Cloud

Guarda en tu sistema el id de Openbox Cloud de cada registro, junto a tu propio identificador. Es lo que vas a enviar en la venta: una referencia es ese id como texto.

Paso 3 · Cambia campo a campo

Empieza por el campo que más se repite (por ejemplo, el cliente) y cambia el objeto por su id:

venta.json (fragmento)
{
  "data": {
    "header": {
      "customer": "0a1b2c3d-1111-9999-0000-123456789abc",
      "paymentCondition": { "name": "Contado", "cashPayment": true }
    }
  }
}

El Mapa del catálogo dice qué campo lleva cada pieza. Cuando una referencia no existe en tu empresa, la venta responde 400 REFERENCE_NOT_FOUND sin escribir nada: corrige el id y reenvía.

Paso 4 · Si quieres, deja de calcular montos

Con todas las líneas por referencia, puedes omitir los montos y usar el modo calculado: Openbox Cloud calcula la venta con el mismo cálculo de la aplicación web (Vender por referencias). Si prefieres seguir enviando montos, el modo precalculado los verifica al centavo.

Copyright © 2026