Recetas

Sincronizar tu catálogo

Crea o actualiza cada registro del catálogo con tu internalId como llave, sin duplicarlo.

Sincronizar deja en Openbox Cloud los registros de tu sistema (clientes, proveedores, servicios, productos, vendedores, zonas y condiciones de pago) para que tus ventas y compras los citen por su id. Se hace registro por registro, con tu internalId como llave.

Antes de empezar conviene leer Tu internalId y los ids y el Mapa del catálogo, que dice qué pieza usa cada documento y en qué campo. Los ejemplos usan clientes; los ocho recursos funcionan igual (tabla al final).

Paso 1 · Busca el registro por tu internalId

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>'

data trae una lista: vacía si el registro no existe, o con el registro y su id de Openbox Cloud.

Paso 2 · Si existe, actualízalo

DisponiblePATCH /partners/v1/customers/{id} Ver operación en la Referencia →

Envía solo los campos que cambian: la actualización cambia el registro en parte y conserva el resto.

Terminal
curl -X PATCH "$OPENBOX_API_URL/partners/v1/customers/<ID_DEL_CLIENTE>" \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"shortName":"Cliente Ejemplo"}'

Paso 3 · Si no existe, créalo con tu internalId

DisponiblePOST /partners/v1/customers Ver operación en la Referencia →
cliente.json (fragmento)
{
  "internalId": "CLI-0001",
  "name": "Cliente Ejemplo, S.A. de C.V.",
  "shortName": "Cliente Ejemplo"
}

El esquema completo, con los campos fiscales y la dirección, está en la Referencia. La respuesta trae el id de Openbox Cloud: guárdalo junto a tu registro, es lo que citarás en cada venta.

Si dos procesos crean el mismo registro

Si otro proceso creó el mismo internalId entre tu búsqueda y tu creación, la respuesta es 409 con el código INTERNAL_ID_DUPLICATED y no se crea nada. No repitas el crear: vuelve al paso 1 y actualiza el registro que ya existe. Ver Errores.

Vendedores y zonas

Cada vendedor pertenece a una zona, así que sincroniza primero las zonas y después los vendedores.

DisponiblePOST /partners/v1/invoices/zones Ver operación en la Referencia →
zona.json
{
  "internalId": "ZON-0001",
  "name": "Zona Ejemplo"
}

La respuesta trae el id de Openbox Cloud de la zona: es el <ID_DE_LA_ZONA> que el vendedor cita en zone.

DisponiblePOST /partners/v1/invoices/sellers Ver operación en la Referencia →
vendedor.json (fragmento)
{
  "internalId": "VEN-0001",
  "name": "Vendedor Ejemplo",
  "zone": "<ID_DE_LA_ZONA>"
}

Si la zona que citas no existe en tu empresa o fue eliminada, la respuesta es 400 con el código REFERENCE_NOT_FOUND y no se crea ni se cambia nada: sincroniza la zona y repite el vendedor. Lo mismo vale al actualizar un vendedor con otra zona.

Una zona que tiene vendedores asignados, activos o inactivos, no se elimina: la respuesta es 409 sin code. Elimina o cambia de zona a sus vendedores antes de eliminarla. Un vendedor responde zone en null cuando no tiene zona asignada o cuando la que tenía fue eliminada: trátalo como vendedor sin zona y asígnale una con un PATCH que envíe zone.

Los ocho recursos

Cada recurso tiene las mismas cinco operaciones: crear, listar (con filtro por internalId), consultar por id, actualizar en parte y eliminar. La insignia de cada una sale del contrato; qué significa cada insignia está en Disponibilidad.

RecursoRutaCrear
Clientes/partners/v1/customersDisponiblePOST /partners/v1/customers Ver operación en la Referencia →
Proveedores/partners/v1/providersDisponiblePOST /partners/v1/providers Ver operación en la Referencia →
Servicios/partners/v1/servicesDisponiblePOST /partners/v1/services Ver operación en la Referencia →
Productos/partners/v1/productsDisponiblePOST /partners/v1/products Ver operación en la Referencia →
Vendedores/partners/v1/invoices/sellersDisponiblePOST /partners/v1/invoices/sellers Ver operación en la Referencia →
Zonas/partners/v1/invoices/zonesDisponiblePOST /partners/v1/invoices/zones Ver operación en la Referencia →
Condiciones de pago de venta/partners/v1/invoices/payment-conditionsDisponiblePOST /partners/v1/invoices/payment-conditions Ver operación en la Referencia →
Condiciones de pago de compra/partners/v1/purchases/payment-conditionsDisponiblePOST /partners/v1/purchases/payment-conditions Ver operación en la Referencia →

Qué módulo del perfil de tu llave exige cada recurso está en Permisos por módulo.

Copyright © 2026