# API

{% embed url="<https://www.boxhero.io/en/blog/boxhero-open-api-integrate-inventory-data>" %}

***

## **Referencia de la API**

Para la documentación detallada de los endpoints, visita: <https://rest.boxhero.io/docs/api>

***

## Endpoint

Todas las solicitudes de la API deben dirigirse a la siguiente URL base:\ <mark style="color:azul;"><https://rest.boxhero-app.com></mark>

## **Autenticación**

Todas las solicitudes de la API deben incluir un <mark style="color:azul;">**Authorization**</mark> encabezado con un <mark style="color:azul;">**token Bearer**</mark>:

```
Authorization: Bearer {API_TOKEN}
```

Para obtener un token de API:

1. Inicia sesión en tu cuenta de BoxHero en el escritorio (web).
2. Navega a <mark style="color:azul;">**`Configuración`**</mark> > <mark style="color:azul;">**`Integraciones`**</mark>.
3. Genera un nuevo token de API.

## **Realización de solicitudes**

Aquí tienes un ejemplo de solicitud de API para recuperar productos.

```bash
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 frecuencia

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

* 5 consultas por segundo para cada endpoint.

Una vez que se te limite la frecuencia, verás 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 un procesamiento exitoso de la API.

### 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 (p. ej., parámetros obligatorios faltantes).
* Rango 500: error del lado del servidor.

**Ejemplo de respuesta de error:**

```json
{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "El token de autenticación no es válido. Proporciona 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 por 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

<table><thead><tr><th width="252">Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Recurso solicitado no encontrado (p. ej., el elemento con un ID específico no existe).</td></tr><tr><td>/errors/invalid-request</td><td>Parámetros no válidos en la solicitud.</td></tr><tr><td>/errors/invalid-team-mode</td><td>La consulta solicitada no puede procesarse en el modo de equipo actual (p. ej., usar la API de búsqueda de <em>location</em> en <em>Modo Básico</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Falta el token de API.</td></tr><tr><td>/errors/tokens/invalid</td><td>Token de API no válido (p. ej., el token de API ha expirado).</td></tr><tr><td>/errors/too-many-requests</td><td>Se ha superado el límite de frecuencia.</td></tr><tr><td>/errors/unhandled</td><td>Error no resuelto del lado del servidor.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Se alcanzó el límite de uso. Se requiere una actualización del plan.</td></tr></tbody></table>

## Paginación

Para los endpoints que devuelven grandes conjuntos de datos (p. ej., listas de elementos, listas de transacciones), la API de vista de lista limita el número de elementos devueltos en una sola solicitud mediante paginación. Usamos paginación basada en cursor:

{% hint style="info" %}
Para determinar si se requiere paginación, comprueba 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.
{% endhint %}

#### **Parámetros de paginación**

* `has_more` : Un 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.

#### **Recuperar la siguiente página**

* Comprueba si `has_more` es `true`. Significa que hay otra página disponible.
* Si `true`, envía otra solicitud incluyendo `cursor={received cursor value}` en los parámetros. Esto devolverá los datos siguientes.
* Repite hasta `has_more` es `false` para recuperar la lista completa.

***

## Soporte y comentarios

Si encuentras problemas o necesitas funcionalidad adicional de la API, contacta con nuestro [equipo de soporte](https://docs-en.boxhero.io/etc/contact). Agradecemos tus comentarios para mejorar la API y nuevas solicitudes de funciones.