Conceptos

Tu internalId y los ids de Openbox Cloud

Tu identificador en cada registro del catálogo, el id de Openbox Cloud y cómo pasar de uno a otro.

Cada registro del catálogo tiene dos identificadores: el id de Openbox Cloud, que la API asigna, y tu internalId, el identificador de tu sistema (no es el código ni el código de barras del producto). El catálogo son ocho recursos: clientes, proveedores, servicios, productos, vendedores, zonas y las condiciones de pago de venta y de compra. Todos comparten estas reglas.

Tu identificador: internalId

  • Es opcional, y único por empresa entre los registros no eliminados cuando lo envías.
  • Al crear puedes enviar el id de Openbox Cloud, el internalId, ambos o ninguno; si no envías id, Openbox Cloud lo genera.
  • Un internalId repetido se rechaza con 409 y el código INTERNAL_ID_DUPLICATED: los cambios van por actualización (PATCH), no por un segundo "crear". Actualizar un registro con un internalId que ya usa otro registro activo responde el mismo 409.
  • El borrado es lógico y libera el internalId: puedes volver a usarlo. El id de Openbox Cloud nunca se reutiliza.

Del internalId al id de Openbox Cloud

Todo listado del catálogo se filtra por internalId: así recuperas el id de Openbox Cloud de un registro que solo conoces por tu identificador.

DisponibleGET /partners/v1/customers Ver operación en la Referencia →
Terminal
curl "$OPENBOX_API_URL/partners/v1/customers?internalId=CLI-0001" \
  -H 'Authorization: Bearer <TOKEN>'

Ese id es el que citas en una venta o una compra (Referencia u objeto). Ventas y compras también llevan tu internalId (en settings), y se consultan por él (Consultar y conciliar).

El paso a paso para mantener el catálogo al día está en Sincronizar tu catálogo.

Copyright © 2026