Saltar a contenido

APIs Tienda Online

Esta sección describe las APIs públicas disponibles para la Tienda Online (Shop).

Introducción

La Tienda Online (Shop) ofrece un conjunto de APIs públicas que permiten a los desarrolladores integrar sus aplicaciones y servicios con la plataforma. Estas APIs están diseñadas para ser fáciles de usar y están documentadas exhaustivamente mediante OpenApi.

Principios de diseño de la API

La API HTTP de la plataforma proporciona una interfaz para el acceso a los datos y servicios de la TOL. Esta API se rige por los siguientes principios de diseño:

  • Las API deben ser simples . No se deben exponer la complejidad interna.
  • Las API deben ser flexibles . Un pequeño cambio, como agregar un filtro, no debe suponer un cambio de API.
  • Las API deben ser versionadas . Siempre hay que evitar cambios que rompan la compatibilidad de la API, pero si no hay otra opción los servicios deben estar versionados.

Por tanto, los clientes que se integren con la API deben ser flexibles para aceptar cambios en la API:

  • Nuevos parámetros opcionales en la Query o el Header
  • Nuevos parámetros en JSON en las request (POST)
  • Nuevos parámetros en JSON en las response

Seguridad

Todo el acceso API es a través de HTTPS.

La autorización API usa Tokens de portador OAuth2. Para autenticarse en la aplicación usamos el protocolo OpenID Connect[1] (Para login y refresh token). El token que intercambia la aplicación y la API usa el formato JWT[2].

Todas las peticiones a la API se realicen agregando el token como parámetro en el header de la llamada.

Documentación de la API

Todas las APIs de la TOL están documentadas mediante OpenAPI[3].

La documentacion identifica de manera inequivoca cada uno de los servicios con un ID propio. Por ejemplo: SHOP.FORM.003 - Form Validate

Además del Swagger está disponible la documentación adicional que incluye:

  • Taxonomías de tipos de datos usados y los servicios a los que pertenecen.
  • Flujos de llamadas para procesos complejos.

Características generales de la API REST

La API de la Tol se rige por unas características que aplican a todos los servicios que de exponen.

Métodos HTTP soportados

Método Descripción
GET Obtener objetos \ listas de objetos
POST Agregar nuevos objetos \ Ejecución de acciones
DELETE Borrar objeto
PUT Actualizar objeto

Definición de las URI

La API de servicios de la TOL estará disponible en una dirección con el siguiente formato.

https://{URI_API}/{system-name}/{version}/{resourcepath}["?"{query-string}]

HTTP status codes

Para evitar complejidades en la implementación de los clientes, se ha limitado el número de códigos de respuesta HTTP diferentes que la API puede devolver.

A continuación listamos los diferentes códigos de respuesta que pueden devolver los servicios de la Tol. Como buena practica solo definimos un subset de posibles códigos (No deben agregarse más a la lista, debemos usar siempre los existentes):

Tipos Código Descripción Usos
2XX 200 OK (respuesta standard) Para los GET Respuesta correcta, suele incluir datos en "data"
Peticiones correctas 201 Created (Ok resultado en la creación de un nuevo recurso) Usado para PUT / POST Respuesta del CREATE Lanzar procesos en segundo plano Lanzar cargas batch
Errores del cliente 400 Bad Request La resquest está invocada con parametros incorrectos
4xx 401 Unauthorized Usuario no identificado
403 Forbidden Usuario identificado pero sin permisos
404 Not found Recurso no existe
500 Internal Server Error Error no controlado en la aplicación
5xx Generic REST API error response
Errores de servidor 503 Service Unavailable Método no Implementado Timeout o fallo en acceso a gateway remoto

Clasificación interna de respuesta del servicio (errorType)

Para obtener más información de la respuesta de un servicio en nuestra respuesta incluimos un código de información adicional, el campo errorType. Estos códigos tienen el formato XX siempre numérico.

Cada servicio puede definir el código de error que quieran, pero los 59 primeros están reservados para usar siempre los mismos. Estos códigos reservados son:

Tipos errorType HTTP Code Descripción Usos
0X Errores genericos
4X Errores de request 40 400 Missing required data Faltan datos requeridos en la request
41 400 Invalid data input Datos enviados a la aplicación no son válidos
43 403 Forbidden No tienen permiso para acceder
44 404 Generic Not found Error generico de recurso no encontrado
5X Errores de servidor 50 500 Undefined error Error no contemplado
51 503 Método no implementado La instalación no soporta este método
52 503 Bad Gateway Error en servicio remoto
53 503 Service Unavailable Servicio remoto no disponible
54 503 Timeout Timeout en el servicio remoto
6X Errores especificos de 6X XXX Son propios de cada servicio y pueden ser definidos especificamente

Intercambio de datos

Los datos entrada y salida de la API están gestionados de manera que toda la API trabaje de la misma manera. En esta sección describimos las maneras de obtener y pasar información a la API. Todos los objetos y nombres de las variables de la API estarán en inglés.

Parametros de Header Request

El header de cada llamada se usará para enviar los siguientes datos:

Parámetro Descripción
X-TOL-LOCALE Idioma
X-TOL-CHANNEL Canal
X-TOL-ZONE Zona
X-TOL-SHIPPING-ZONE Zona de envío
X-TOL-CURRENCY Moneda
X-TOL-USERID Id Usuario
X-TOL-APP Indica la aplicacion que accede a la API. Por defecto tol
Authorization: Bearer Token del usuario

Parametros de Header Response

El header de la response del servidor puede contener los siguientes datos:

  • Datos de auditoria (Información de la versión, servidor, tiempo de procesamiento, etc)

Parametros de query

Los servicios que devuelven un listado de elementos permiten pasar los siguientes filtros.

Filtros de colección

Filtro Descripción
from Filtro 'desde' para fechas
to Filtro 'hasta' para fechas
Id Permite indicar un Id de atributo por el que filtraremos, por ejemplo, categoryId.

Filtros de ordenación

Filtro Descripción Ejemplo
sort Indica el orden en que aparecerán los elementos. Cada servicio puede soportar órdenes diferentes. sort=key1:asc,key2:desc,key3

Filtros de paginación

En la API Tol permitimos al cliente especificar el número de elementos que obtendrá, así como hacer paginación.

Filtro Descripción
limit Número de resultado a devolver
offset Número desde el que se empiezan a devolver resultados

Objeto de request

En las peticiones POST es posible enviar un objeto JSON con parámetros al servicio.

Payload de respuestas correctas

Todos los servicios devuelven una respuesta JSON de la siguiente forma:

{ 
  "meta": {
      "code": 200,
      "errorType": null ,
      "errorMessages": null
    },
  "data": null 
}
  • Las respuestas del servicio siempre serán en formato JSON.
  • Si un campo tiene un valor nulo, no debe ser agregado con otro valor.
  • Los campos de fecha deben incorporar la fecha completa y la zona horaria en un formato standard de JSON.
  • La implementación del cliente no debe fallar si el orden de los campos varía.
  • La implementación del cliente no debe fallar si se agregan nuevos campos.

Payload de respuestas erróneas

En caso de error la API debe devolver siempre un formato de error standard. En nuestro caso usamos siempre el siguiente formato:

{ 
  "meta": {
    "code": 500, // Código HTTP 
    "errorType": 23, //Código interno del error
    "errorMessages": null , //Listado de errores
  }
}

Este objeto tiene los siguientes hijos:

  • Meta: Son datos adicionales que nos ayudan a ver la salida del servicio. Este objeto incluye los siguientes hijos:
  • Code: Es el código HTTP de la respuesta. Algunas aplicaciones no tienen acceso al código de HTTP directamente, por eso preferimos repetirlo en la respuesta.
  • errorType: Campo de texto que nos permite poner el tipo de error que se ha producido. Cada servicio devolverá códigos de error específicos.
  • errorMessages: Es un listado de los mensajes que puede proveer el servicio al cliente. Puede informarnos de los mensajes de error, warnings o infos.

En caso de llamadas PUT o POST hace falta listar los diferentes errores o warnings relacionándolos con el campo original. Por ejemplo:

  • [1] http://openid.net/connect/
  • [2] https://jwt.io/
  • [3] https://swagger.io/