API

La API de BoxHero permite a los desarrolladores integrar nuestras capacidades de gestión de inventario con aplicaciones externas para una recuperación e interacción eficientes de datos.

BoxHero’s API: A Simple Way to Integrate Your Inventory DataBoxHero Blog

---

Referencia de la API

Para obtener documentación detallada de los endpoints, visite: https://rest.boxhero-app.com/docs/api

---

Endpoint

Todas las solicitudes de la API deben dirigirse a la siguiente URL base: https://rest.boxhero-app.com

Autenticación

Todas las solicitudes de la API deben incluir un Authorization encabezado con un token Bearer:

Authorization: Bearer {API_TOKEN}

Para obtener un token de API:

1. Inicie sesión en su cuenta de BoxHero en Desktop (Web).

2. Vaya a Configuración > Integraciones.

3. Genere un nuevo token de API.

Realización de solicitudes

Aquí hay una solicitud de API de ejemplo para recuperar productos.

curl -X 'GET' \
  'https://rest.boxhero-app.com/v1/items?location_ids=12345&location_ids=34567&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer test-api-token-123'

Límites de tasa

Para garantizar la estabilidad del sistema, imponemos los siguientes límites de tasa:

• 5 consultas por segundo para cada endpoint.

Una vez que alcance el límite de tasa, verá un mensaje de error con lo siguiente:

• X-Ratelimit-Limit - Máximo de consultas por minuto

• X-Ratelimit-Remaining - Consultas restantes

• X-Ratelimit-Reset - Tiempo (en segundos) restante hasta el reinicio del conteo de consultas

---

Respuestas

Éxito

Las respuestas con códigos de estado HTTP en el rango 200 indican que el procesamiento de la API fue exitoso.

Error

Los códigos de estado en el rango 400 o 500 indican fallos en la solicitud de la API:

• Rango 400: error del lado del cliente debido a la información proporcionada con la solicitud (por ejemplo, faltan parámetros obligatorios).

• Rango 500: error del lado del servidor.

Ejemplo de respuesta de error:

{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "El token de autenticación no es válido. Proporcione un token válido.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}

• id : Un ID único para identificar el error.

• type : Un código en forma de URL que identifica el tipo de error.

• title : Proporciona el contenido del error en un formato legible para humanos.

• correlation_id : Apunta al ID de la solicitud asociada con el error.

• otros : Se pueden incluir campos adicionales para proporcionar información adicional, como "given" en el ejemplo.

Tipos de error comunes

Tipo	Descripción
/errors/not-found	Recurso solicitado no encontrado (por ejemplo, no existe un elemento con un ID específico).
/errors/invalid-request	Parámetros no válidos en la solicitud.
/errors/invalid-team-mode	La consulta solicitada no se puede procesar en el modo de equipo actual (por ejemplo, usando la ubicación API de búsqueda en Modo básico).
/errors/tokens/required	Falta el token de API.
/errors/tokens/invalid	Token de API no válido (por ejemplo, el token de API ha expirado).
/errors/too-many-requests	Se ha superado el límite de tasa.
/errors/unhandled	Error del lado del servidor sin resolver.
/errors/core/usage-limit-exceeded	Se alcanzó el límite de uso. Se requiere actualizar el plan.

Paginación

Para los endpoints que devuelven grandes conjuntos de datos (por ejemplo, listas de artículos, listas de transacciones), la API de vista de lista limita la cantidad de elementos devueltos en una sola solicitud mediante paginación. Usamos paginación basada en cursor:

Para determinar si se requiere paginación, verifique si hay parámetros relacionados con la paginación presentes en el cuerpo de la solicitud del endpoint en la documentación de la API.

Parámetros de paginación

• has_more : Un valor booleano que indica si existen más datos más allá de la página actual.

• cursor : Proporciona el valor del cursor para recuperar la siguiente página.

Recuperación de la siguiente página

• Verifique si has_more es true. Significa que hay otra página disponible.

• Si true, envíe otra solicitud incluyendo cursor={valor del cursor recibido} en los parámetros. Esto devolverá los datos siguientes.

• Repita hasta que has_more es false para recuperar la lista completa.

---

Soporte y comentarios

Si encuentra problemas o necesita funcionalidad adicional de la API, comuníquese con nuestro equipo de soporte. Agradecemos sus comentarios para mejorar la API y nuevas solicitudes de funciones.