👋🏻 ¡Bienvenido a la guía de integración de Handy!

Si no eres desarrollador o no tienes idea de qué es una API y solo deseas iniciar sesión en tu cuenta de Handy, puedes hacerlo aquí

Esto es lo primero que debes leer.

En esta guía, te mostramos cómo iniciar con nuestra API para integrar tu sistema administrativo o ERP.

La API es REST, utiliza el formato de datos JSON y está protegida con HTTPS y un Bearer Token.

---

1. Crea una cuenta gratuita en Handy

Puedes hacerlo aquí.

No necesitas una tarjeta de crédito. Obtendrás el producto completo durante 14 días.

En caso de que necesites más tiempo para efectos de una integración, escríbenos en el chat.

2. Crea un token de API.

Ve a editar tu usuario y presione el botón verde para crear tu token de API personal.

3. Prueba tu token.

Esta prueba requiere que tengas instalado cURL en tu terminal

Abre una ventana de terminal y ejecute esto:

curl -H "Authorization: Bearer API_TOKEN" https://hub.handy.la/api/v2/user

Deberías obtener una respuesta como esta:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "pagination": {
        "totalCount": 50,
        "totalPages": 5,
        "currentPage": "https://hub.handy.la/api/v2/user?page=1",
        "nextPage": "https://hub.handy.la/api/v2/user?page=2",
        "prevPage": null,
        "firstPage": "https://hub.handy.la/api/v2/user?page=1",
        "lastPage": "https://hub.handy.la/api/v2/user?page=5"
    },
    "users": [
        {
            "id": 1153,
            "username": "enrique@gmail.com",
            ...
        }
    ]
}

🥳 ¡Eso es todo! acabas de recibir una lista de tus usuarios en formato JSON a través de la API 🥳

---

Algunos detalles importantes

Estas son algunas otras consideraciones técnicas importantes con respecto a la API que encontrarás en la referencia completa:

• Hay límites de uso (rate limit) que debes tener en cuenta, especialmente si haces llamadas en paralelo. El límite es relativamente alto, por lo que solo incurrirás en él si hay un patrón de abuso. El límite es de 500 solicitudes por minuto.

  Puedes guiarte de los siguientes encabezados en las respuestas de la API para manejar el límite de uso:

  • X-RateLimit-Limit: límite establecido por la API
  • X-RateLimit-Reset: Unix timestamp (numérico) del momento en el que el límite se va a resetear
  • X-RateLimit-Remaining: cantidad de solicitudes que quedan para el periodo actual

• Utiliza el formato dd/MM/aaaa HH:mm:ss para especificar fechas. No olvides codificarlo si es un parámetro de consulta de URL. Cuando especificas una fecha y hora, la zona horaria que se tomará será la del usuario al que corresponde el token de API.

• Las fechas que despliega en los resultados la API están en formato yyyy-MM-dd'T'HH:mm:ss'Z' y son en la zona horaria UTC.

• Los resultados están paginados. Estás en la última página cuando nextPage es nulo.

• Las llamadas API tienen un tiempo de espera máximo de 30 segundos.

• Los parámetros y atributos de tipo String que no especifican su tamaño máximo, se consideran con un tamaño límite de 255 caracteres. Si el límite se excede, se recortará la cadena a 255 caracteres, no se generarán errores.

• Cuando se hace polling de pedidos, es recomendado utilizar el campo de fecha dateCreated en lugar de mobileDateCreated (default) para que no se pierdan pedidos que se crearon en la app móvil estando offline y que no se han sincronizado a los servidores.

• Handy puede entrar en ventanas de mantenimiento los sábados de las 22:00 horas a las 01:00 del domingo, hora del Centro de México (Ciudad de México). Te recomendamos no correr procesos importantes en ese horario.

Puedes continuar explorando en el artículo sobre cómo integrar los pedidos a tu ERP o sistema administrativo, que ahí te mostramos cómo manejar estos detalles.