Errores
Todas las respuestas de error traen statusCode, message y error; algunas agregan un code
estable. Tu sistema decide con statusCode y code. El campo error siempre llega, pero es texto
libre de diagnóstico: su valor puede cambiar sin aviso, así que no lo compares. Por eso los
ejemplos de esta guía lo omiten. La Referencia lista, en cada operación, los códigos
que puede responder.
400 — la petición no es válida
El cuerpo, un parámetro, una referencia o el id de la ruta no cumple el contrato. message es
una lista con el primer problema de cada campo, nombrado con su ruta dentro del cuerpo:
{
"statusCode": 400,
"message": ["data.header.documentType debe ser cualquiera de las siguientes opciones: 'CCF', 'FCF', 'NC', 'FEX'."]
}
Corrige la petición antes de reenviarla: repetirla igual da el mismo 400.
Crear una venta o una compra, y crear o actualizar un vendedor, responden además 400 propios.
Cada uno trae message como un solo texto (no una lista) y un code estable con el que tu
sistema distingue el caso:
REFERENCE_NOT_FOUND(venta, compra y vendedor): un registro del catálogo que citas por su UUID no existe en tu empresa o fue eliminado;messagenombra el recurso y no se escribe nada. En una compra, también lo recibes si envías como objeto el proveedor o la condición de pago con elidde un registro que tu empresa eliminó. En un vendedor, lo recibes cuando la zona que citas enzoneno existe en tu empresa o fue eliminada.INSUFFICIENT_DATA_TO_CALCULATE(venta): a la venta le faltan datos para su modo, o trae alguno que ese modo no admite;messagenombra el campo.AMOUNT_OUT_OF_TOLERANCE(venta): un monto enviado no coincide al centavo con el que corresponde;messagenombra el campo, lo que enviaste y el valor correcto.
{
"statusCode": 400,
"message": "El proveedor indicado no existe o fue eliminado.",
"code": "REFERENCE_NOT_FOUND"
}
{
"statusCode": 400,
"message": "totals.totalPagar: se envió 7789.89; el valor correcto es 7720.95.",
"code": "AMOUNT_OUT_OF_TOLERANCE"
}
Crear una compra puede responder también un 400 sin code cuando el documento no pasa la
validación electrónica: message es un solo texto con el motivo. Si el motivo es la configuración
de facturación electrónica de tu empresa (certificado o contraseñas), corregir la petición no
basta: pide al equipo de Openbox Cloud que la revise. Ese 400 llega después de crear o actualizar
el proveedor o la condición de pago que enviaste como objeto.
Consultar y anular una venta responden también 400 cuando la venta no existe en tu empresa.
Anular responde además 400 cuando el estado de la venta no permite anularla (por ejemplo, ya
anulada, pagada o en contingencia).
401 — sin sesión válida
Falta el token, venció o fue revocado por un inicio de sesión posterior con la misma llave. Inicia
sesión una vez y repite la petición (Autenticación). Al iniciar sesión, el 401 significa que la llave o
el secreto no son válidos.
403 — sin permiso
Tiene dos causas:
- El token no corresponde a una llave de API de Partners.
- La llave no tiene acceso al módulo del recurso (clientes, proveedores, servicios, inventarios, facturación o compras), o no tiene perfil o empresa asignados.
No se resuelve reintentando: pide al equipo de Openbox Cloud que revise el perfil de tu llave. Qué módulo exige cada recurso está en Permisos por módulo.
404 — el registro no existe
El registro que pides no existe en tu empresa. Lo responden consultar, actualizar y eliminar en los
ocho recursos del catálogo y consultar una compra. Consultar o anular una venta responden 400 en
ese caso (ver arriba).
409 — conflicto con un registro existente
El 409 llega con code o sin él, y la causa cambia. Ninguno se resuelve repitiendo la petición
igual.
Con code: INTERNAL_ID_DUPLICATED
{
"statusCode": 409,
"message": "Ya existe un registro activo con el internalId indicado.",
"code": "INTERNAL_ID_DUPLICATED"
}
message siempre habla del internalId, pero el 409 tiene tres causas y en ninguna se escribe nada:
- Otro registro activo de tu empresa ya usa ese
internalId(al crear o actualizar en el catálogo): búscalo por tuinternalIdy actualízalo. - El
idque enviaste al crear en el catálogo ya existe: consulta el registro por eseid. Si lo encuentras, es tuyo: actualízalo. Si responde404, es de otra empresa o lo eliminaste: créalo sinidy Openbox Cloud genera uno. - Una venta o una compra lleva un registro como objeto con un
idde otra empresa: no se crea ni el registro ni el documento. Envía ese registro sinido cita por referencia uno de tu empresa.
Sin code
Crear una venta o una compra responde 409 sin code cuando ya existe una con el mismo
internalId en un estado que impide recrearla. Consúltala por tu internalId y usa la que ya
existe: Reintentos explica cómo con una venta y con una compra.
Eliminar una zona que tiene vendedores asignados, activos o inactivos, responde 409 sin code y
la zona sigue igual. message nombra la zona. Elimina o cambia de zona a sus vendedores antes de
eliminarla:
{
"statusCode": 409,
"message": "No se puede eliminar la zona \"Zona Central\" porque tiene vendedores asociados"
}
501 — NOT_AVAILABLE_YET
La operación, o la forma de la petición que enviaste, está declarada en el contrato y responde así mientras su insignia no cambie. No crea ni cambia nada.
{
"statusCode": 501,
"message": "Esta operación aún no está disponible. Se habilitará cuando su funcionalidad se publique.",
"code": "NOT_AVAILABLE_YET"
}
No es reintentable: qué significa cada insignia y cuándo deja de responder 501 está en
Disponibilidad.