¡Bienvenido a la REST API de Easypromos!

Si quieres puedes explorar las posibilidades de la REST API sin tener que programar una línea de código. Simplemente obtén un accessToken y testea las diferentes funciones desde la página de referencia de la API con el botón de Try It.

Sigue los pasos de esta guía para obtener un access token.

¿Quién puede utilizar la REST API?

• La REST API solamente está disponible para clientes con un plan Marca Blanca o Corporate
• La REST API no permite obtener datos de promociones Premium o Básicas. 
• La REST API no aplica a sorteos de comentarios en redes sociales (Instagram, Facebook, Twitter, Multired), ni tampoco a Sorteos de un Listado o Sorteos en un evento.

Los casos de uso habituales de la REST API son integraciones con sistemas externos para automatizar procesos. Ejemplos:

• Importar los usuarios registrados en las promociones a las bases de datos propias del clientes o a un sistema de gestión de usuarios.
• Importar el listado de ganadores y premios a un sistema de gestión de proceso y envío de premios. 
• Permitir que usuarios de un sistema externo (aplicación móvil, sitio de membresía, programas de fidelización) participen en una promoción saltándose el sistema de registro propio de Easypromos. Descubre todas las posibilidades de la solución de Autologin.
• Conectar la promoción a Bots de Mensajería instantánea. Por ejemplo: validar códigos promocional a través de un Bot de Whatsapp para ganar premios directos por instante ganador.
• Mostrar datos de la promoción en un sitio externo. Por ejemplo: pintar el ranking de usuarios de un juego en tu propia web y en tu propio formato.
• Actualizar el saldo de monedas virtuales de un usuario para sincronizarlo con un sistema externo de fidelización.
• Enviar las transacciones de monedas virtuales para premiar a un usuario por acciones realizadas en un sistema de fidelización externo.
• Enviar las transacciones de monedas virtuales para dar participaciones adicionales en promociones para un usuario.

Nota: Si tu objetivo es recoger los datos de los nuevos usuarios registrados en tiempo real o bien obtener los ganadores de premios en tiempo real, considera utilizar el sistema de Webhooks.

Índice de contenidos:

• Url base de la API y versiones

• Autorización

• Métodos

• Modelos e ítems

• Colecciones y paginación

• Fechas

• Límite de peticiones (Rate limit)

• Errores

• Documentación de referencia de la API

• Reportar un error

Url base de la API y versiones

La versión actual de la REST API de Easypromos es 2.0 (Abril 2022)

La Url base de la API para todas las llamadas es:

https://api.easypromosapp.com/v2

Cabe recordar que la última parte de la url base (v2 en este caso) es el número de versión de nuestra API. Si en el futuro añadimos cambios que sean incompatibles con versiones previas, incrementaremos el número de versión para dar tiempo a la migración. Siempre se dará un tiempo antes de descatalogar una versión, para que se pueda migrar.

Noticia de versión obsoleta

Hemos marcado todas las llamadas a la url https://wl.easypromosapp.com/api/ como obsoletas. Esta url corresponde a la versión 1.0 de la API REST de Easypromos.

Todas las llamadas a la versión 1.0 dejarán de funcionar a partir del 1 de Abril del 2023.

¿Qué tienes que hacer?

Si utilizas las versión 1.0, debes adaptar las llamadas a la nueva versión 2.0. 

Autorización

Todas las llamadas a la API necesitan autenticarse a través de un token de acceso. Puedes obtener el token desde tu cuenta de Easypromos, en el menú Utilidades. Instrucciones para obtener un token de acceso a la API.

Para autenticar la llamada incluye la siguiente Cabecera HTTP Authorization: Bearer access_token 

Ejemplo de una llamada a la API con la cabecera HTTP de Autorización mediante CURL:

curl -i -X GET \
'https://api.easypromosapp.com/v2/promotions' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Si no incluyen un token de acceso válido recibirás un error 401 (Unauthorized).

Métodos

Es una API REST. Quiere decir que todas las llamadas siguen las reglas REST en términos de nomenclatura del path de la url, el uso del método HTTP como descripción de la acción a realizar, y el uso de cabeceras HTTP para información adicional.

Aceptamos 2 métodos: GET y POST.

GET es para obtener información. Solo se permiten parámetros en la URL y en el path. Se ignorará cualquier parámetro enviado en el cuerpo de la llamada. Las llamadas GET no modifican nada.

POST es para añadir nueva información o modificar información existente. Todas las llamadas POST deben tener la cabecera Content-Type. Actualmente para la versión 2.0, únicamente se acepta application/json como Content-Type.

Modelos e ítems

La información la presentamos en formato JSON. La información que devuelve una llamada GET de la API se denomina "ítem" de un "modelo". Cada url de una llamada (path) de nuestra API representa un "modelo". Cada ítem tiene su identificador propio único (ID). La nomenclatura es fácil: el ID de una promoción le llamamos promotion_id. Cuando haces la llamada GET /promotions/1234 devolveremos una respuesta en formato JSON que tendrá un ítem del modelo "promotion" con el ID "1234".

Los modelos actuales de la API son:

La especificación de los campos de cada modelo está definida en la documentación de referencia de la API.

Colecciones y paginación

Cuando haces la llamada GET /promotions te devolveremos como respuesta una Colección de ítems. Una Colección es simplemente un lista de ítems presentada como un array JSON. En las colecciones podemos omitir algún campo del modelo. Debes tratar los ítems de la colección como resúmenes del modelo que representan. Si necesitas obtener toda la información de un ítem de la colección, podrás hacer una nueva llamada GET, con el ID del ítem, por ejemplo: GET /promotions/1234 

Una Colección incluye un máximo de 100 ítems por página.

Una llamada GET que devuelve una Colección siempre incluirá la lista de items y la información de paging para poder obtener la siguiente página de ítems.

Ejemplo para obtener el listado de marcas organizadoras para la página 1 y página 2

GET /organizing_brands  (page 1)
{
  "items": [
     {
       "id": 1,
       "name": "My organizing brand 1"
     }
     ....
     {
       "id": 100,
       "name": "My organizing brand 100"
    }
  ],
  "paging": {
    "next_cursor": 1234,
    "items_page": 100
  }
}

Si el campo next_cursor del elemento paging existe y es mayor de 0, entonces puedes obtener la siguiente página de ítems de la Colección realizando la llamada GET pasando el valor de next_cursor como parámetro en la url: 

GET /organizing_brands?next_cursor=1234 (page 2)
{
  "items": [
    {
      "id": 101,
      "name": "My organizing brand 101"
    }
    ....
    {
      "id": 109,
      "name": "My organizing brand 109"
    }
  ],
  "paging": {
    "items_page": 9
  }
}

Cuando no hay el campo next_cursor en el elemento pagingentonces es ya la última página de la Colección.

Fechas

Todas las fechas se presentan en formato ISO-8601 y zona horaria UTC. Por ejemplo, 2022-04-08T12:52:36+00:00. 

La zona horaria de todas las fechas que se presentan en la API es UTC

Límite de peticiones (Rate limit)

El límite de peticiones es de 200 llamadas por minuto por cuenta.

Si se excede el límite de peticiones, todas las siguientes llamadas recibirán como respuesta un código de error 429 (Too many requests) hasta que se llegue al siguiente minuto.

Errores

Si la API responde correctamente con un ítem o con una colección de ítems, siempre devolverá OK con el código HTTP  200 .

Si no responderá con un código HTTP de error:

Cuando la API responde con un código HTTP  400, el cuerpo del mensaje incluirá la razón del error en formato JSON. Aquí tienes un ejemplo:

{
  "code": 42,
  "message": "Promotion is not open"
}

Este es el listado de errores cuando recibes un error HTTP 400:

Documentación de referencia de la API

La definición de la API sigue el estándar Openapi 3.1.0. 

Ir a la documentación de referencia de la API.

Reportar errores de la API

Si detectas algún error en la API por favor envía un email a support@easypromosapp.com.