Referencia u objeto: qué hace cada forma
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:
| Forma | Qué envías | Qué hace con el registro |
|---|---|---|
| Referencia | El id de Openbox Cloud del registro, como texto | Lo usa tal cual; nunca lo modifica |
| Objeto | El registro completo | Lo 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 → {
"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.