Autorización

Para poder realizar una venta, reimpresión o cancelación es necesario primero solicitar la autorización a los servicios mediante una consulta al servidor y obtener un token de acceso o access_token. El servicio de autorización empleado es OAuth 2.0, el cuál permite autorizar una aplicación de manera estándar, fácil y segura.
 

Para obtener un access_token es necesario contar con los siguientes datos:  

  • {{Auth_string}} : Cadena de texto codificado enviado en los headers de la petición.
  • {{grant_type}} : Es la manera en la que una aplicación obtiene un access_token.
  • {{username}} : usuario para solicitar un access_token.
  • {{password}} : contraseña para solicitar un access_token.
     

Ver: Obtener datos de acceso para OAuth

Cosas a tener en cuenta

  • El access_token se debe solicitar solo la primera vez que se desea autorizar la aplicación, las siguientes veces se debe emplear el refresh_token
  • El access_token tiene una duración de 12 horas (43199 segundos). Después de que expire, se debe solicitar un nuevo access_token como se menciona en el punto anterior.
  • Las credenciales generadas deben mantenerse seguras en todo momento para evitar que alguien haga mal uso de tu cuenta. No compartas tus credenciales en lugares públicos ni por medios poco seguros.

Ambientes

SANDBOX URL BASE:
http://nubeqa.netpay.com.mx:3334

PRODUCCIÓN URL BASE:
https://suite.netpay.com.mx/

Estructura de una petición

POST /oauth-service/oauth/token

Headers

  • Content-Type: application/x-www-form-urlencoded
  • Authorization: Basic {{Auth_string}}

Body

  • grant_type={{grant_type}}&username={{username}}&password={{password}}

Ejemplo de solicitud / respuesta

A continuación, se muestra un ejemplo de una petición para solicitar el access_token por primera vez, la renovación mediante el refresh_token y los diferentes mensajes de respuesta.

Solicitud por primera vez

curl -L -X POST 'http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic {{Auth_string}}' \
--data-urlencode 'grant_type={{grant_type}}' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

var client = new RestClient("http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddHeader("Authorization", "Basic {{Auth_string}}");
request.AddParameter("grant_type", "{{grant_type}}");
request.AddParameter("username", "{{username}}");
request.AddParameter("password", "{{password}}");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type={{grant_type}}&username={{username}}&password={{password}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded",
    "Authorization: Basic {{Auth_string}}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type={{grant_type}}&username={{username}}&password={{password}}");
Request request = new Request.Builder()
  .url("http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Authorization", "Basic {{Auth_string}}")
  .build();
Response response = client.newCall(request).execute();
import requests

url = "http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token"

payload = 'grant_type={{grant_type}}&username={{username}}&password={{password}}'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Authorization': 'Basic {{Auth_string}}'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

Respuestas

  • SUCCESS: Se obtendrá la siguiente respuesta con un access_token y refresh_token válido si las credenciales enviadas han sido las correctas.
  • UNAUTHORIZED: Se obtendrá la siguiente respuesta si el {Auth_string} enviado está incorrecto o ha sido deshabilitado.
  • MISSING GRANT TYPE: Se obtendrá la siguiente respuesta si el {grant_type} no se ha enviado en la petición.
  • UNSUPPORTED GRANT TYPE: Se obtendrá la siguiente respuesta si el {grant_type} enviado en la petición es incorrecto.
  • INVALID USERNAME OR PASSWORD: Se obtendrá la siguiente respuesta si el {username} o {password} enviado en la petición es incorrecto.

 

NOTA: el access_token y refresh_token se han recortado para efectos ilustrativos. En la práctica ambos tokens son de una longitud mayor variable.

 

{
    "access_token": "CI6IkpXVCJ9wianReyJhdWQiOlsib2F1dGgyX2lkIl0sInVzZX",
    "token_type": "bearer",
    "refresh_token": "mlkLnJtei45NUBnbWFpbC5jb20iLCJzY6ImRhd_3yghIRLnew",
    "expires_in": 43199,
    "scope": "read write",
    "jti": "32116378-023b-9331-0920-ff1e2e200601"
}
{
    "timestamp": "2020-02-19T15:21:21.347+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/oauth/token"
}
{
    "error": "invalid_request",
    "error_description": "Missing grant type"
}
{
    "error": "unsupported_grant_type",
    "error_description": "Unsupported grant type: example"
}
{
    "error": "unauthorized",
    "error_description": "Invalid username or password."
}

Actualización de token vencido

Una vez el primer access_token generado ha llegado a su vida útil, es necesario solicitar uno nuevo. Para ello, se debe solicitar un nuevo access_tokenválido mediante el refresh_token.

Ahora, en el {grant_type} se debe enviar el valor refresh_token de la petición.

curl -L -X POST 'http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic {{Auth_string}}' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={{refresh_token}}'
var client = new RestClient("http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddHeader("Authorization", "Basic {{Auth_string}}");
request.AddParameter("grant_type", "refresh_token");
request.AddParameter("refresh_token", "{{refresh_token}}");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type=refresh_token&refresh_token={{refresh_token}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded",
    "Authorization: Basic {{Auth_string}}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=refresh_token&refresh_token={{refresh_token}}");
Request request = new Request.Builder()
  .url("http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Authorization", "Basic {{Auth_string}}")
  .build();
Response response = client.newCall(request).execute();
import requests

url = "http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token"

payload = 'grant_type=refresh_token&refresh_token={{refresh_token}}'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Authorization': 'Basic {{Auth_string}}'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

 

NOTA: Es importante que el {{Auth_string}}, {{grant_type}}, {{username}}, {{password}}, URL BASE y PATH queden configurables dentro de algún menú de configuración o un archivo externo dado que pueden cambiar en el ambiente de producción.

← Terminal punto de venta SmartRealizando una venta →