Ten en cuenta que para poder comenzar a probar/usar las APIs debes estar registrado y haber iniciado sesión. A partir de ahí, estos son los pasos que debes seguir
Registrar una Aplicación en el portal:
Puedes registrar una Aplicación desde tu zona de usuario. Solamente es necesario proporcionar un nombre y una descripción. En cuanto lo hagas, anota las credenciales para esa Aplicación, que te serán asignadas nada más realizar el alta (client_id y client_secret). Éstas serán necesarias en los próximos pasos para poder utilizar la API de autorización y poder, posteriormente, invocar a la API concreta que quieras probar. Además, puedes necesitar las credenciales de usuario del entorno (en sandbox se puede indicar cualquier valor). Es muy importante hacerlo en este momento puesto que el client_secret nunca más se presentará como texto plano.
1. Suscribir una Aplicación a los Productos que contengan las APIs que desees probar
Una vez creada la Aplicación, ésta deberá estar suscrita a los Productos que contengan las APIs que quieras probar/usar. Para eso, accede al Producto que desees probar dentro del Catálogo y pulsa en el botón Suscribirme
En ese momento, pasarás a la siguiente pantalla, donde se te permitirá indicar cuál de las Aplicaciones que tienes registradas es la que deseas suscribir a este Producto.
2. Suscribir la misma Aplicación al Producto OAuth2-provider, que contiene la API que permite autorizar la aplicación con el portal
Además de suscribir la Aplicación a aquellos Productos que quieras probar, deberás, siguiendo los mismos pasos, suscribirla al producto OAuth2-provider, que contiene la API que te permitirá autorizar a tu Aplicación en este entorno sandbox. Así, todas las Aplicaciones que crees tendrán que estar suscritas a los productos que quieras probar/usar con dicha Aplicación y al Producto OAuth2-provider.
Invocar a la API OAuth2-provider para conseguir el token de acceso
La API OAuth2-provider del Producto con el mismo nombre tiene un par de operaciones para realizar la autorización de tu aplicación: una te proporcionará el token de acceso necesario para poder invocar a las APIs y otra te proporcionará un token de refresco que evitará que tengas que volver a enviar tus credenciales username y password cuando el primer token caduque.
Obtener el token de acceso
Para obtener el token de acceso deberás invocar al endpoint POST /token de la API OAuth2-provider. Necesitarás enviar los siguientes campos:
grant_type: Se indicará el valor password
client_id: Se debe proporcionar el client_id de la aplicación
client_secret: Se debe proporcionar el client_secret de la aplicación
username: Usuario del entorno (indicar un valor cualquiera para el entorno de sandbox)
password: Contraseña del entorno (indicar un valor cualquiera para el entorno sandbox)
scope: Indicar tantos scopes como sea necesario. Los posibles valores son: read, update, delete, create. Se pueden indicar varios al mismo tiempo, separándolos por espacios
Se obtendrá una respuesta como la siguiente:
{
"token_type": "Bearer",
"access_token": "Jksjwhwh. . . .",
"expires_in": 3600,
"consented_on": 1605085323,
"scope": "create read update delete",
"refresh_token": "AKJiogjd. . .",
"refresh_token_expires_in": 2592000
}
La propiedad access_token es el token de acceso que deberemos utilizar en la cabecera Authorization para invocar a la API. Es un token de corta duración.
La propiedad refresh_token es un token que nos permitirá conseguir un nuevo token de acceso cuando el access_token haya caducado, puesto que el primero es de larga duración.
Refrescar el token
A la hora de refrescar el token ya no es necesario enviar el usuario/contraseña (username y password) del entorno. Se envía la siguiente información:
grant_type: Se indicará el valor refresh_token
client_id: Se debe proporcionar el client_id de la aplicación
client_secret: Se debe proporcionar el client_secret de la aplicación
refresh_token: Se debe indicar el valor de la propiedad refresh_token que devolvió la invocación con la que se solicitó el token de acceso
Se obtiene una respuesta similar a la de la solicitud del token, con la que tendrás un nuevo access_token y también un nuevo refresh_token para usar cuando necesites de nuevo refrescarlo el token de acceso.
En cualquier caso, puedes encontrar información más detallada en este portal, en la Documentación de esta API.
Utilizando el token de acceso conseguido en el paso anterior, invocar a la API que quieras probar
Una vez obtenido el token invocando a la API OAuth2-provider, éste debe ser incluido en cada una de las invocaciones a la API que hagas en la cabecera Authorization. Recuerda que es un token Bearer, por lo que tendrás que indicarlo precediendo al valor del token en esta cabecera. Si tu token de acceso es token123, la cabecera Authorization quedará:
Authorization: Bearer token123
El resto de campos de entrada dependerán ya de cada uno de los endpoints de las APIs y del caso concreto de uso que quieras probar. Recuerda que puedes consultar en el portal toda la información técnica necesaria para conocer los detalles de estos campos, los casos de uso e incluso ejemplos en diferentes lenguajes de programación. Lo tienes disponible en la sección Documentación de cada una de las APIs publicadas.
Para integrar las APIs en tu ERP, puedes encontrar información relativa al proceso de dicha integración en las webs de los diferentes proveedores. A continuación listamos algunos de los más utilizados con sus referencias hacia la gestión de integraciones via APIs:
- Epicor
- Geinfor
- Netsuite
- Sage