Autorización con oAuth

Aprende como integrarte a Zippin utilizando oAuth para la conexión a una cuenta Zipnova.

Cuándo utilizar la autenticación por oAuth

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 credenciales simples de cuenta.

Utiliza oAuth cuando tu integración se reutilice con múltiples cuentas Zipnova.

Requisitos

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 formulario de alta.

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

Procedimiento

Paso 1: Solicitar código de autorización

Como primer paso, deberás redirigir al usuario a la siguiente URL, para que pueda autorizar el acceso a la aplicación.

Obtención del código de autorizació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.

Revisa que la porción del host de la URL corresponda con la del país de Zipnova correcto.

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.

Parámetros de la URL de autorización

Name	Type	Description
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	Se deben indicar explícitamente los permisos requeridos (separados por espacios). Ver permisos disponibles
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

Paso 2: Validar la autorización y canjear el código por un token

Valida el state

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.

Obtención del access token

POST /oauth/token (No lleva el prefijo v2 en este endpoint)

Canjear un código de autorización por un access token

Query Parameters

Name	Type	Description
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.

Request Ejemplo

curl --request POST \
  --url https://api.zippin.xx/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
	"grant_type": "authorization_code",
	"code": "def502000854851...",
	"client_id": "9c8f-f139-4cfe-9be1-6e799",
	"client_secret": "Qzxs7u9WN3GsE24BwNJrWx8VVcvhjZ",
	"redirect_uri": "https://misitio.com/zipnova/callback"
}'

Respuesta Ejemplo

{
	"token_type": "Bearer",
	"expires_in": 31536000,
	"access_token": "eyJ0eXAiOiJ2329scsd9bGciOiJSUzI1NiJ9.eyJhdWQiOiI5YzVkMzQwskdm399OTAxNWUzOTkiLCJqdGkiOiJjNTliOWE5NG",
	"refresh_token": "def502005b186b4a8762ee98bd64aff4aab2a2ee6c8917777d5d5e5733e36fcc2989eae43f38d12c6b19b0f0ac97aa218"
}

Paso 3: Utilizar el token para los requests a la API

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.

curl -X GET \
https://api.zipnova.com.xx/v2/shipments \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {access_token}'

Paso 4: Refrescar el token

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.

Refrescar access token

POST /oauth/token (No lleva el prefijo v2 en este endpoint)

Canjear un código de autorización por un access token

Body Parameters

Name	Type	Description
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.

Request Ejemplo

curl --request POST \
  --url https://api.zipnova.xx/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
	"grant_type": "refresh_token",
	"refresh_token": "def502000854851...",
	"client_id": "9c8f-f139-4cfe-9be1-6e799",
	"client_secret": "Qzxs7u9WN3GsE24BwNJrWx8VVcvhjZ"
}'

Respuesta Ejemplo

{
	"token_type": "Bearer",
	"expires_in": 31536000,
	"access_token": "eyJ0eXAiOiJ2329scsd9bGciOiJSUzI1NiJ9.eyJhdWQiOiI5YzVkMzQwskdm399OTAxNWUzOTkiLCJqdGkiOiJjNTliOWE5NG",
	"refresh_token": "def502005b186b4a8762ee98bd64aff4aab2a2ee6c8917777d5d5e5733e36fcc2989eae43f38d12c6b19b0f0ac97aa218"
}

Permisos disponibles para solicitar en scope

Recuerda que puedes solicitar múltiples permisos, para ello deberás separar cada uno con un espacio en la URL inicial.

Permiso	Descripción
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