Resumen #

En este documento se describe cómo integrar datos con SAWA.

Las especificaciones en este documento se deben utilizar cuando una organización envía datos a SAWA y la forma de enviarlos es de forma estructurada vía HTTP.

Para eso, SAWA provee una API documentada, con ejemplos y un sandbox de prueba para el desarrollo de sus clientes.

Servidores #

Existen 2 servidores para integraciones externas de SAWA

• api.ext.sawa.cl: Servidor de producción
• api-sandbox.ext.sawa.cl: Servidor sandbox de desarrollo

El flujo de desarrollo de un programa típicamente consistirá en el uso inicial de la API sandbox, de modo que los desarrolladores se puedan familiarizar con los formatos de requests y responses de la API y una vez que ambas partes estén contentas, se pone en marcha el programa apuntando las solicitudes a api.ext.sawa.cl.

Endpoints y documentación de schemas #

La API SAWA está documentada para todos sus schemas de requests y responses y tiene interfaces para ser probada antes de usarlas con datos reales. En su sandbox se puede ver la documentación

La API tiene 2 endpoints que están descritos en la misma API, pero brevemente son los siguientes:

• transactions: transacciones de los participantes. Por ejemplo: ventas o respuestas de encuestas
• metrics: datos agregados de todos los participantes. Por ejemplo: ventas totales a la fecha o ventas mensuales de un determinado producto

Para mayor detalle, se puede consultar la documentación

Esquema de autentificación #

No cualquier persona ni institución puede acceder a los recursos de la API. Cada llamado a la API debe estar contener datos de autentificación.

La autentificación de cada request se hace usando el estandar jwt. Para ello, SAWA le hará llegar un token oportunamente, que deberá usar en cada request que se haga a la API. Para describir brevemente la seguridad de este método, se trata de un mensaje firmado que contiene datos no sensibles. El secreto que genera la firma está siempre en posesión de SAWA y la autentificación se basa en que cada request contiene un mensaje del siguiente estilo:

SAWA me dijo los siguientes datos y ésta es la firma.

En fin, no es propósito de este documento probar las propiedades criptográficas del estándar, pero sí mencionar que el esquema es seguro bajo supuestos razonables.

Con el token recibido, cualquier request HTTP debe contener un header Authorization con el formato Bearer <jwt> en que <jwt> debe reemplazarse por el token antes mencionado. De no incluirlo en cada request, se devolverá un mensaje con código HTTP 403.

Pruebas con swagger #

En la ruta /docs de cualquier servidor (producción, sandbox) está disponible una interfaz que permite probar el servicio de forma amigable y rápida. Si bien esto también puede usarse para producción, su principal objetivo es que sirva para familiarizarse con la API y sus tipos. La interfaz que se muestra se llama Swagger y utiliza el estándar OpenAPI.

Servers #

Hay un selector que permite elegir el servidor para los requests

Con este se puede elegir cuál servidor va a recibir los requests de prueba realizados usando esta interfaz. Si bien están disponibles el de producción y el de sandbox, no se pueden cruzar el dominio contra el servidor del request:

• api-sandbox.ext.sawa.cl no puede hacer requests al server de producción
• api.ext.sawa.cl no puede hacer requests al server de sandbox

Esta limitación sólo cuenta en swagger y no tiene nada que ver con la operación normal. Seleccione siempre el servidor que es apropiado

Schemas #

En la parte de abajo se muestran los schemas

Estos muestran la estructura de los datos a consultar. Usualmente esta sección es sólo de consulta.

Endpoints #

Los endpoints muestran las consultas que es posible realizar al servicio

Es la parte central de la interacción con Swagger. En la imagen se muestran los 2 endpoints que ofrece la aplicación

Hacer un request #

Para hacer un request hay que hacer clic en un endpoint

La imagen muestra la descripción de lo que hace el endpoint y un valor de ejemplo que puede usarse para mandarle requests al servidor. El botón Try it out permite probar el endpoint para ver qué responde.

La imagen muestra un esquema de ejemplo que es válido para hacer un request y el botón Execute sirve para mandar el request al servidor.

En la respuesta (abajo) se muestran 3 secciones

• Curl: el request equivalente para curl
• Request URL: A qué URL se hizo el request
• Server response: La respuesta del servidor, el código y el mensaje

En este caso la respuesta tiene status 403 (Forbidden), se puede ver el cuerpo de la respuesta:

{
    "detail": "Not authenticated"
}

Y debajo se pueden ver los headers http.

La razón del 403 se explica abajo, en Autentificación.

Autentificación #

Como se explicaba anteriormente, el esquema de autentificación es via JWT, y para poder ocupar la interfaz correctamente, se necesita autentificar cada request. La interfaz ofrece directamente esa opción con el botón de la imagen

Dándole clic al botón se abre la siguiente ventana

Que pide el token entregado, no debe anteponerse Bearer al token, sólo debe ingresarse el token. Una vez ingresado el token, todos los requests subsiguientes llevarán el token. Si se vuelve a hacer clic en el botón, se puede eliminar la autentificación si fuera necesario.

Uso en producción #

En producción se deben seguir los mismos pasos que los indicados durante todo este documento, pero las con las siguientes excepciones y consideraciones que están a continuación.

Servidor de producción #

Recuerde siempre hacerle requests a https://api.ext.sawa.cl y no al sandbox. Cualquier error http con status entre 400 y 499 (inclusive) será del mismo formato que el sandbox. Sin embargo, los errores con status http mayor a 500 puede que difieran. Estos errores los monitorea SAWA y siempre serán arreglados a la brevedad.

Consideraciones de seguridad #

• El JWT de producción difiere del del sandbox. Si se confunden los tokens, la respuesta resultará en un error 403.
• Eso implica que para producción les entregaremos otro token
• No comparta su JWT con nadie ni de ninguna forma. Si se pierde, le podemos entregar uno nuevo, pero en principio, los tokens viejos no se pueden invalidar.