API público de Winfra

Winfra API (interfaz de la aplicación) permite acceder a los datos almacenados en la aplicación de Winfra. API esta implementado como servicio REST API con mensajes codificados en el formato JSON. La comunicación se realiza con el protocolo HTTP.

Protocolo HTTP

El API utiliza el protocolo HTTP para toda la comunicación. Métodos que recuperan los datos utilizan las peticiones GET. La creación o actualización de los registros utiliza la petición POST. Hay que controlar los códigos de respuesta de HTTP.

La cantidad de las peticiones a API por minuto puede estar regulada, con valores exactos todavía por decidir.

SSL/TLS y cifrado

El API funciona con simple HTTP o con HTTPS (SSL/TLS). En entorno de producción el HTTPS es obligatorio. Los certificados utilizados son self-signed (no esta firmado por una autoridad de certificación). Permiten el cifrado de la comunicación pero no validan la identidad de los servidores. Hay que tenerlo en cuenta, algunos clientes web avisan o directamente fallan la conexión si no esta controlado.

Formato REST y JSON

El API esta implementado como REST API. El formato de los mensajes es JSON. La representación de los datos esta documentada en la estructura de los datos.

Todos los mensajes están codificados en UTF-8.

Versiones de API

El API de winfra esta desarrollado y mejorado constantemente. El numero de versión mayor forma parte de URL de recurso REST. La versión mayor cambiará solo en caso de cambio completo de API. La versión actual esta visible en pantalla de resumen del API. La versión menor se corresponde a la fecha de publicación de los cambios y es correlativa (número mas grande es mas nuevo).

La mayoría de los cambios esta prevista dentro de la misma versión:

1. Añadir nuevos recursos – no hay ningún problema, clientes que no conocen nuevos recursos no los van a utilizar.
2. Añadir nuevos campos a una petición – todos los campos nuevos añadimos como opcionales para no romper la compatibilidad.
3. Añadir nuevos campos a una respuesta – el cliente tiene que ignorar nuevos campos. Hay que tenerlo en cuenta en la validación de las respuestas.

Código de respuesta y errores

La respuesta utiliza los códigos de estado de HTTP.

Estado	Descripción
200	OK
401	Acceso denegado en caso de error de usuario, contraseña o token.
422	Acceso denegado en caso de error de firma de token.
429	Demasiadas peticiones en caso llegar al limite de peticiones/minuto.
500	Error en la aplicación, esto es error en el servidor de winfra
555	Un error controlado por winfra, por ejemplo fallos de validación de los datos. Este error proporciona información para usuario de la aplicación.

Para los errores con el código 401, 422 y 555 la descripción de error esta en el cuerpo de la respuesta, en formato JSON.

{
    "error": "La contabilidad ha sido cerrada, no se puede modificar."
}

Autenticación y autorización

Winfra API utiliza dos niveles de autenticación y autorización. Primer nivel consiste del servidor de autenticación de winfra. Servidor de autenticación autentica el cliente con usuario y contraseña y genera un token que contiene la autorización. El token se utiliza junto con el usuario y contraseña para validar el acceso a los datos de winfra.

El formato de token es JWT. Utilizamos la infraestructura de clave publica para firmar/validar los tokens. El token es válido durante 30 minutos. No utilizamos refresh tokens, hay que volver a obtener un nuevo token si las operaciones duran mas que el tiempo de validez. El servidor tiene una tolerancia de 5 minutos para evitar problemas con desincronización de los relojes.

Para la autenticación de las peticiones se utiliza la autenticación básica.

Por lo tanto para acceder se requieren dos pares de usuario y contraseña:

1. Primer par para autorizar el acceso. Este usuario/contraseña lo emite WINFRA S.L. y es válido para acceso a todos los dominios y APIs.
2. Segundo par para acceder al dominio de los datos. Este usuario/contraseña lo emite el dueño de los datos.

Ejemplo de la autenticación

POST https://servidor_de_autentificacion/api_token/

Utiliza el primer par de usuario/contraseña. El cuerpo de la petición indica el dominio al que vamos a acceder y el API que se va a utilizar. Es posible indicar varios api separados por punto-coma, el token generado será válido para acceso a todos.

Cabecera de la petición de HTTP:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Petición:

{
    "domain": "empresa_x",
    "api": "contabilidad;maestros"
}

La respuesta del servidor de autenticación incluye un nuevo token:

{
    "WINFRA-API-TOKEN": "IUEWRYTHDBHGKJS.KJHGFKYSGF.YRWEURTEW"
}

Utiliza el token para acceder a los datos. Por ejemplo para obtener los artículos

GET https://servidor_de_la_empresa/winfra3/api_v1/articulos/

Utiliza el segundo par de usuario/contraseña para acceder a los datos e indica el token.

Cabecera de la petición de HTTP:

Authorization: Basic QwxhZGRTYDHKDHKSDKA==
WINFRA-API-TOKEN: IUEWRYTHDBHGKJS.KJHGFKYSGF.YRWEURTEW

La respuesta contiene la lista de los artículos. Véase los servicios disponibles para mas detalles sobre los datos devueltos.

Ademas la pantalla de resumen del API tiene ejemplo de código en Python.