Sincronizar tu catálogo
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 → 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.
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 → {
"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 → {
"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.
POST /partners/v1/invoices/sellers Ver operación en la Referencia → {
"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.
| Recurso | Ruta | Crear |
|---|---|---|
| Clientes | /partners/v1/customers | DisponiblePOST /partners/v1/customers Ver operación en la Referencia → |
| Proveedores | /partners/v1/providers | DisponiblePOST /partners/v1/providers Ver operación en la Referencia → |
| Servicios | /partners/v1/services | DisponiblePOST /partners/v1/services Ver operación en la Referencia → |
| Productos | /partners/v1/products | DisponiblePOST /partners/v1/products Ver operación en la Referencia → |
| Vendedores | /partners/v1/invoices/sellers | DisponiblePOST /partners/v1/invoices/sellers Ver operación en la Referencia → |
| Zonas | /partners/v1/invoices/zones | DisponiblePOST /partners/v1/invoices/zones Ver operación en la Referencia → |
| Condiciones de pago de venta | /partners/v1/invoices/payment-conditions | DisponiblePOST /partners/v1/invoices/payment-conditions Ver operación en la Referencia → |
| Condiciones de pago de compra | /partners/v1/purchases/payment-conditions | DisponiblePOST /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.