Introducción al API CostoNet

Introducción

Este manual está dirigido a programadores que deseen crear aplicaciones que puedan interactuar con los servicios de CostoNet. Aquí se explican conceptos básicos para utilizar la API de CostoNet.

Tecnologías

El programador deberá estar familiarizado con las siguientes tecnologías:

REST: REST es un interfaz entre sistemas que utiliza directamente HTTP para obtener datos o indicar la ejecución de operaciones sobre los datos.
OAuth: OAuth es un estándar abierto que permite flujos simples de autorización para sitios web o aplicaciones informáticas.
JSON: JSON es un formato de texto ligero para el intercambio de datos.

Inicio

Antes de comenzar es necesario completar los siguientes pasos:

Registrarse en CostoNet: Deberá crear una cuenta de usuario accediendo a Registro a CostoNet, despúes de realizar el registro recibirá un correo de confirmación, confirme su correo para completar su registro.
Crear un Cliente: El cliente es un identificador y su respectiva contraseña que se utilizan para hacer llamadas al API, para obtener un cliente debera entrar en el panel de control y hacer clic en la sección Crear aplicación o ingrese directamente a crear aplicación para generar su cliente.

Roles

En esta sección mostraremos los roles principales que interactuan en el proceso

Dueño del recurso | Usuario: Es el dueño de los recursos (catálogos, productos, su perfil) y quien autoriza o desautoriza a la cliente | aplicación para acceder a su cuenta y limita el alcance del acceso.
Cliente | Aplicación: El cliente es la aplicación que desea acceder a la cuenta del dueño de los recursos | usuario y utilizar sus recursos, previamente debe ser autorizado por el dueño de los recursos | usuario y verificado por el Servidor de recursos | API.
Servidor de recursos | API: Es el servidor donde se encuentra los recursos del usuario y que el cliente | aplicación desea acceder.
Servidor de autorizaciones: Es el servidor que gestiona las llaves (tokens) para autorizar al cliente | aplicación que el dueño de los recursos | usuario permitió el uso de sus recursos.

Autorización a los propios recursos

flujo de autorizacion de propios recursos

Como se muestra en el diagrama, este flujo se utiliza cuando el Dueño del recurso | Usuario y el Cliente | Aplicación son los mismos, es decir el dueño de los recursos desea acceder a sus propios recursos.

El usuario solicita al Servidor de autorizaciones un token usando la función accesstoken.
Si el cliente (idClient) y la contraseña (idSecret) son válidas obtiene un Access token.
El Access token se utiliza para hacer llamadas desde las distintas funciones disponibles y acceder a sus recursos en el servidor de recursos.
Si el token es válido y no ha caducado el servidor de recursos devuelve el recurso solicitado.
Si es el token ha caducado deberá solicitar uno nuevo desde el paso 1.

Ejemplo

    	 			
curl 'https://www.costonet.com.mx/api/v1/oauth/accesstoken' --header 'Content-Type: application/x-www-form-urlencoded' --header "Accept: text/json" -d 'client_id=xxxxx&client_secret=xxxxx&grant_type=client_credentias'

Respuesta

    	 			
    	 			
HTTP/1.1 200 OK
Date: Thu, 20 Sep 2018 18:19:09 GMT
Server: Apache
X-Frame-Options: SAMEORIGIN
X-Powered-By: PHP/7.1.14
Cache-Control: no-cache, private
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
Vary: Accept-Encoding
Content-Length: 1213
Content-Type: text/json; charset=UTF-8

{"issued_at":1537467551,
"scope":"READ",
"application_name":"http:\/\/www.costonet.com.mx",
"organization_name":"CostoNet",
"status":"approved",
"api_product_list":"[InsumosAPI]",
"expires_in":3800,
"developer_email":"info@costonet.com.mx",
"organization_id":"0","token_type":"BearerToken",
"client_id":"xxxxx",
"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE1Mzc0Njc1NTEsImp0aSI6InVxYmtsRmZxTm5lYVB0NnJkakZFZEJXQWpwWEhOTVpTZFUxeEFWdnRDR1k9IiwiaXNzIjoiaHR0cDpcL1wvd3d3LmNvc3RvbmV0LmNvbS5teCIsIm5iZiI6MTUzNzQ2NzU2MSwiZXhwIjoxNTM3NDcxMTYxLCJkYXRhIjp7InVzZXIiOiJiZW5qYW1pbiIsImNsaWVudF9pZCI6IjEyMzQ1In19.8ACUnRwF1wF-ZaUL4gTNvfcNQENgE_7yi0Hl7rWRWaxffB-cherMO2cBsYM3uIwrAHksrhghvpey4welO394Og",
"refresh_token_status":"approved",
"refresh_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE1Mzc0Njc1NTEsImp0aSI6InVxYmtsRmZxTm5lYVB0NnJkakZFZEJXQWpwWEhOTVpTZFUxeEFWdnRDR1k9IiwiaXNzIjoiaHR0cDpcL1wvd3d3LmNvc3RvbmV0LmNvbS5teCIsIm5iZiI6MTUzNzQ2NzU2MSwiZXhwIjoxNTM3NDcxMTYxLCJkYXRhIjp7InVzZXIiOiJiZW5qYW1pbiIsImNsaWVudF9pZCI6IjEyMzQ1In19.8ACUnRwF1wF-ZaUL4gTNvfcNQENgE_7yi0Hl7rWRWaxffB-cherMO2cBsYM3uIwrAHksrhghvpey4welO394Og",
"refresh_token_expires_in":86399,
"refresh_token_issued_at":1537557560,
"refresh_count":0}

Autorización a recursos de terceros

Como se muestra en el diagrama, la Autorización de usuario se utiliza cuando el Cliente | Aplicación pretende tener acceso en nombre del Dueño del recurso | Usuario, es decir el dueño de los recursos delega a la aplicación el uso de sus propios recursos.

El Cliente | Aplicación solicita al Servidor de autorizaciones autorización para utilizar los recursos del Dueño del recurso | Usuario, utiliza la función authorize.
Si el Cliente (idClient) es válido el Servidor de autorizaciones solicita al Dueño del recurso | Usuario a través de su navegador que autorice a la Cliente | Aplicación para utilizar sus datos.
Si el usuario aprueba el uso de sus datos el sistema redirige a la url establecida por la Cliente | Aplicación y agrega en los parámetros un código (code) que podrá utiliza para acceder a sus recursos en el servidor de recursos.
La Cliente | Aplicación envía a través de la función accesstoken, el código (code), el ClientId y el secret para obtener un token de acceso.
Si el token es válido y no ha caducado el servidor de recursos devuelve el recurso solicitado.
Si es el token ha caducado deberá solicitar uno nuevo desde el paso 1.

Ejemplo

    	 			
https://www.costonet.com.mx/api/v1/oauth/authorize/?response_type=code&client_id=xxxxx&redirect_uri=http%3A%2F%2Fwww.trendtacion.com%2F&scope=read

Respuesta

    	 			
 http://trendtacion.com/?code=oJ2808JQn1USgdn

Petición de recursos

Una vez que se tiene un token el Cliente | Aplicación podrá realizar peticiones al servidor de recursos a través de las funciones disponibles de CostoNet.

El Cliente | Aplicación solicita al Servidor de recursos un recurso usando alguna de las funciones del API de CostoNet por ejemplo: Producto.
Las peticiones son envíadas vía HTTP por REST y es importante que se envíe un Access token válido en el encabezado (Header) Authorization: Bearer.
Según la petición y la función el Método HTTP puede ser POST, GET, DELETE.
Si el token es válido y no ha caducado el servidor de recursos devuelve el recurso solicitado, usualmente en formato JSON.
Si es el token ha caducado deberá solicitar uno nuevo.

Ejemplo

    	 			
curl "https://www.costonet.com.mx/api.proyecto.insumos/ACEREF00265" --header "Accept: text/json" --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE1Mzc1MDg0MTcsImp0aSI6Im45SFk5QmNRQ0pReVd0dFFKOEZjc21JVmJJTHZQeU5uIiwiaXNzIjoiaHR0cDpcL1wvd3d3LmNvc3RvbmV0LmNvbS5teCIsIm5iZiI6MTUzNzUwODQyNywiZXhwIjoxNTM3NTEyMDI3LCJkYXRhIjp7InVzZXIiOiJiZW5qYW1pbiIsImNsaWVudF9pZCI6IjEyMzQ1In19.UVTFfFOETJqJRB5EOfAyON_Oozs02p32aWPWYZdNzEAsU2OCCvkSiWnCzwaAmbnIOj9XTQki7CDswqRJ5ebyRg"

Respuesta

    	 			
    	 			
{"producto":
	{"Clave":"ACEREF00265",
	 "Familia":"ACE",
	 "Descripcion":"VARILLA No. 3 (3\/8\")",
	 "Unidad":"Kg.",
	 "Fecha":null,
	 "Accesos":"126282",
	 "ultimo":"2018-09-21 00:21:47",
	 "mayor":18.94,
	 "menor":3.75,
	 "promedio":12.90
	 }
}