Conceptos

Referencia u objeto: qué hace cada forma

Cada registro del catálogo que lleva una venta o una compra va como referencia o como objeto, en el mismo campo.

Donde una venta o una compra pide un registro del catálogo (el cliente o el proveedor, la condición de pago, el vendedor y su zona, el servicio o el producto de cada línea), el mismo campo acepta dos formas:

FormaQué envíasQué hace con el registro
ReferenciaEl id de Openbox Cloud del registro, como textoLo usa tal cual; nunca lo modifica
ObjetoEl registro completoLo crea o lo reescribe con lo que envías

Puedes mezclar: una referencia en un campo y un objeto en otro, dentro de la misma venta.

DisponiblePOST /partners/v1/invoices Ver operación en la Referencia → DisponiblePOST /partners/v1/purchases Ver operación en la Referencia →
fragmento
{
  "customer": "0a1b2c3d-1111-9999-0000-123456789abc",
  "paymentCondition": { "name": "Contado", "cashPayment": true }
}

La referencia, por forma

Una referencia se valida por forma: 8-4-4-4-12 caracteres hexadecimales (0a1b2c3d-1111-9999-0000-123456789abc), sin exigir la versión RFC. El OpenAPI publicado lo describe con un pattern, no con format: uuid, para que tu validador o tu cliente generado lo acepte. Una referencia que no existe en tu empresa, o que fue eliminada, responde 400 con el código REFERENCE_NOT_FOUND y no se escribe nada.

Cuál conviene

  • Referencia cuando el registro ya está en el catálogo: la venta no reescribe los datos fiscales del cliente y el payload es más pequeño. Es la forma de Vender por referencias.
  • Objeto cuando tu sistema no guarda el id de Openbox Cloud: cada venta lleva el registro completo, como en Vender con payload completo.

Para pasar de una a otra sin cortar la facturación, ver Migrar a referencias. Qué campo lleva cada pieza está en el Mapa del catálogo.

Copyright © 2026