Autorización con oAuth
Aprende como integrarte a Zippin utilizando oAuth para la conexión a una cuenta Zipnova.
Última actualización
Aprende como integrarte a Zippin utilizando oAuth para la conexión a una cuenta Zipnova.
Última actualización
Recomendamos el uso de oAuth cuando tu integración sirva para conectar múltiples cuentas de Zipnova de diferentes clientes.
Si la integración que estás realizando es entre un sistema propio y una única cuenta Zipnova, te recomendamos usar .
Antes de avanzar con el proceso de autorización, deberás tener una aplicación dada de alta en Zipnova. Para obtener tu aplicación, completa el .
Deberás informarnos la o las URLs que quieras dar de alta para el callback del proceso de autorización
Una vez que demos de alta la aplicación, te proveeremos de los siguientes datos:
client_id
client_secret
Como primer paso, deberás redirigir al usuario a la siguiente URL, para que pueda autorizar el acceso a la aplicación.
Redirige al usuario a la URL https://api.zipnova.pais/oauth/authorize?response_type=code&state=XX&client_id=ID&scope=...&redirect_uri=URL (ver a continuación cómo armarla), para que pueda dar a tu aplicación permiso de acceder a su cuenta.
En caso que el usuario autorice a tu aplicación a acceder a la cuenta, lo redirigiremos a tu URL de redirección con un código de autorización en la URL, necesario para canjear luego por un token.
response_type*
String
Debe ser code
client_id*
String
El client_id de la app del marketplace
redirect_uri*
String
La URL de redirección, debe estar habilitada previamente en la aplicación al darla de alta.
scope*
String
state*
String
String generado en el momento que luego podrás usar para validar el código. Se recomienda guardarlo en la sesión del usuario.
Ejemplo:
https://api.zipnova.com.ar/oauth/authorize?response_type=code&client_id=9c5nd3-dxd3d-er3gfre43-e2e2e&scope=shipments.quote shipments.create&state=32323231&redirect_uri=https://misitio.com/zipnova/callback
Si el usuario autorizó el acceso, volverá a la URL especificada como redirect_uri, incluyendo un code en el query string, por ejemplo: https://misitio.com/zippin/callback?code=def502000854851...&state=32323231
Ese paso no es obligatorio, pero es aconsejable para dar mas seguridad al proceso.
Antes de canjear el código recibido por un token, deberías validar que el state recibido en la URL coincida con el que habías enviado en el paso anterior. Si no coincide, deberías anular el flujo.
POST /oauth/token (No lleva el prefijo v2 en este endpoint)
Canjear un código de autorización por un access token
grant_type*
String
Debe ser authorization_code
client_id*
String
El client_id de la app
redirect_uri*
String
La URL de callback, debe estar autorizada previamente
code*
String
Envía el código obtenido previamente.
client_secret*
String
El client_secret de la app
Como resultado del request anterior obtendrás un json conteniendo un access_token, un refresh_token y un atributo expires_in, que expresa la cantidad de segundos hasta que expire el token recibido.
Todos los llamados que se hagan a la API de Zippin deben estar autenticados. Para ello se deberá enviar un header Authorization, tipo Bearer, con el access token obtenido en el flujo de autorización.
Si bien los tokens tienen una larga duración, tienen un vencimiento (un año, inicialmente), lo que implica que será necesario refrescarlos periódicamente para obtener un nuevo token.
POST /oauth/token (No lleva el prefijo v2 en este endpoint)
Canjear un código de autorización por un access token
grant_type*
String
Debe ser refresh_token
client_id*
String
El client_id de la app
refresh_token*
String
Envía el refresh_token recibido previamente.
client_secret*
String
El client_secret de la app
Como resultado del request anterior volverás a obtener un json conteniendo un nuevo access_token, un refresh_token y un atributo expires_in, que expresa la cantidad de segundos hasta que expire el token recibido.
scopeRecuerda que puedes solicitar múltiples permisos, para ello deberás separar cada uno con un espacio en la URL inicial.
Envíos
shipments.quote
Cotizar envíos
shipments.create
Crear/Actualizar envíos
shipment_documentation.download
Descargar documentación del envío
shipments.show
Buscar/ver envíos
shipments.update
Actualizar estados de envíos
Ordenes
orders.view
Ver Ordenes
orders.create
Crear ordenes
orders.update
Actualizar Ordenes
Cuenta y Orígenes
accounts.show
Ver info de la cuenta
addresses.show
Ver orígenes
addresses.create
Crear origen
addresses.destroy
Eliminar origenes
Fulfillment
stocks.read
Ver stocks
Revisa que la porción del host de .
Se deben indicar explícitamente los permisos requeridos (separados por espacios).