Integración SFTP-API

Encuentra toda la informacion que necesitas para poder integrarte en función a tus necesidades con nuestro software.
  • SFTP
  • API
1. Importación mediate SFTP

«Las importaciones por STFP se pueden llevar a cabo para cualquier tipo de fichero: PUNTOS DE ENTREGA, RUTAS, PRODUCTOS y ALBARANES»

La importación mediante SFTP requiere de una conexión particular de cada cliente a nuestro servidor SFTP. Este usuario se lo creará uno de nuestros propios técnicos y se os enviará a vuestra cuenta de correo de contacto en el momento del inicio de la integración. Hay que decir que esta opción necesita de varios ficheros JSON como los que se han detallado en su correspondiente apartado, y que se tendrán que cargar con la conexión SFTP indicada a continuación.

La codificación de caracteres del fichero debe ser UTF-8. Cualquier otra codificación puede causar problemas de representación o de error en la carga del fichero a la plataforma.

1.1.Datos para la conexión SFTP

Las credenciales necesarias para la integración mediante SFTP son las siguientes:

• USUARIO: Usuario creado por nuestros técnicos.

• CONTRASEÑA: Contraseña del usuario creada por nuestros técnicos.

• SERVIDOR: Dirección a la que conectarse con el usuario asignado.

• PUERTO: Puerto por el cual se conectará el cliente a nuestro servidor.

Nuestro técnico se encargara de crear toda la estructura de directorios personalizada que se explica a continuación. Antes de eso, se debe tener claro que hay dos tipos de directorio dentro del SFTP de OptimManage.

• Directorio raíz (envío de fichero): Este directorio será el que el cliente utilizará para cargar sus propios JSON a nuestra plataforma (importaciones).

• Directorios de recogida de ficheros: Estos directorios serán los que el cliente utilizará para recoger los ficheros descargados desde nuestra plataforma (recuperaciones).

Es muy importante tener esto claro, ya que sino pueden ocurrir errores a la hora de cargar ficheros a nuestra plataforma o, en el caso de los clientes, de leer los datos de forma equivocada.

Una vez vista esta distinción, vamos a especificar los directorios en cada uno de los dos casos nombrados.

.

ENVÍO DE FICHEROS

.

Directorio raíz (./) (Envío de ficheros): En esta carpeta el cliente dejará sus ficheros JSON de los puntos de entrega, albaranes, rutas a cargar en nuestra plataforma.

• En el caso de tratarse de un fichero de puntos de entrega el nombre del fichero será: delivery_points.json.

• En el caso de tratarse de un fichero de albaranes el nombre del fichero será: albarans.json

• En el caso de tratarse de un fichero de rutas el nombre del fichero se será: route_MAD-1_20200304.json (por ejemplo, ya que depende del nombre de la ruta).

• En el caso de tratarse de un fichero de productos, se deberá dejar en el directorio (./company_1/products/). El nombre del fichero será: products.json. 

.

RECOGIDA DE FICHEROS

.

• Directorio de históricos (./routes/) (Recogida de ficheros): En esta carpeta el cliente recogerá los ficheros JSON descargados desde nuestra plataforma con el histórico de las rutas. Se podrán descargar, o una ruta en concreto como por ejemplo: route_MAD-1_20200304.json, donde MAD-1 es el identificador de la ruta, o el archivo general con todas las rutas, como por ejemplo routes_20200304.json.

• Directorio de optimizaciones (./optimizations/) (Recogida de ficheros): En esta carpeta el cliente recogerá los ficheros JSON descargados desde nuestra plataforma con las optimizaciones de las rutas. El fichero se llamará: optimization_20200227.json

• Directorio de evaluaciones (./evaluations/) (Recogida de ficheros): En esta carpeta el cliente recogerá los ficheros JSON descargados desde nuestra plataforma con las evaluaciones de las rutas. El fichero se llamará: evaluation_20200227.json

• Directorio de albaranes (./deliveryNotes/) (Recogida de ficheros): En esta carpeta el cliente recogerá los ficheros JSON descargados desde nuestra plataforma con las firmas de los albaranes de los sus clientes en PDF. El fichero se llamará: deliveryNote_2_1_20200301.json, donde el 2 es el id de la empresa, el 1 es el id del punto de entrega y los siguientes números son al fecha.

• Directorio de órdenes (./orders/) (Recogida de ficheros): En esta carpeta el cliente recogerá los ficheros JSON descargados desde nuestra plataforma con las diferentes órdenes. El fichero se llamará: orders_company_1_20200707155700.json, donde company_1 es la empresa y el 20200707155700 es el identificador único de la orden; dónde 2020 es el año, 07 es el mes, 07 es el día, 15 es la hora, 57 son los minutos y 00 son los segundos.

1. Importación mediante API

«La importación por API única y exclusivamente se llevará a cabo para los ficheros de RUTAS»

La importación mediante API requiere de la generación por parte del usuario de un token. Este token contiene la información de los puntos de entrega en un día concreto o de los productos a repartir en los diferentes puntos de entrega. Hay que decir que esta opción nos creará un fichero JSON como el que hemos detallado en su correspondiente apartado, y que tendremos que cargar en la plataforma.

Es importante remarcar, que la importación mediante API, única y exclusivamente se llevará a cabo para las rutas.

La codificación de caracteres de los fichero deben ser UTF-8. Cualquier otra codificación puede causar problemas de representación o de error en la carga del fichero a la plataforma.

1.1. Creación del AccessToken

Para la integración de cualquier contenido vía API se necesitará la creación de un token de acceso. Este token es una string aleatorio que identifica a un usuario dentro de una aplicación o servicio, para realizar llamadas a la API.

Para los que no estén familiarizados con el término, una API es un conjunto de funciones que se usan para que una aplicación pueda usar otro software por encima. Hablando concretamente de OptimManage, se debe crear un token de acceso para conectar vuestro propio software con nuestra API para poder utilizar nuestro servicio sin modificar en ningún momento el vuestro propio.

Para obtener este token de acceso tendrá que tener un usuario creado en nuestra plataforma con el perfil de técnico. Este primer usuario se lo creará uno de nuestros propios técnicos y se os enviará a vuestra cuenta de correo de contacto en el momento del inicio de la integración. En caso de querer crear otra cuenta de usuario de tipo técnico, debes dirigiros a la sección de Gestión y en la pestaña de Usuarios clicar en Agregar usuario y rellenar todos los campos; indicando el tipo de usuario como técnico. Las siguiente imágenes muestran estos pasos gráficamente:

https://www.optimmanage.com/wp-content/uploads/2020/05/API01-1.png

Una vez se tenga el usuario o usuarios de perfil técnico, llega el momento de conectarse a nuestra API para realizar el envío de los datos. Los parámetros de la conexión son los siguientes:

• URL: https://restapi.optimroute.com/api/oauth/token_integrator
• MÉTODO: POST
• CONTENIDO: application/json

Para obtener el token de acceso se deberá hacer una petición a la API con el siguiente esquema de código:

Petición a la API

{
 “client_id”: 1,
 “client_secret”: “tT96kecNtYVf92dvRfQ1Ikj6sjsx5tKZzaCCpHun”,
 “username”: “integration@company.com”,
 “password”: “secret_password”,
 “grant_type”: “password”
}

Los campos client_id, client_secret y grant_type son constantes, es decir, no deben modificarse en ningún caso. Por otra parte, los campos username y password sí que son modificables, y deberán rellenarse con los datos del usuario creado anteriormente como técnico.

Una vez establecida la conexión y hecha la petición a la API, se recibirá la respuesta por parte de nuestro sistema con el token de acceso.

Respuesta de la petición a la API

{
 “access_token”: “eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiI”,
 “refresh_token”: “def50200388a50a45925d65”,
 “expires_in”: 86400,
 “token_type”: “Bearer”,
 “username”: “integration@company.com”
}

La parte más importante de esta respuesta es el valor del token de acceso (access_token), que es lo que se tendrá que usar para la integración de los datos que veremos a continuación.

1.2. Creación de puntos de entrega por API

Una vez se tenga el usuario o usuarios de perfil técnico, y el token de acceso para la conexión a la API, ya se podrá cargar las datos en la plataforma. Los parámetros de la conexión para la carga de datos son los siguientes

• URL: https://restapi.optimroute.com/api/integration
• MÉTODO: POST
• CONTENIDO: application/json

El esquema de código el mismo que se usa para integración de los datos mediante JSON o CSV. Sólo se incluyen tres campos nuevos (automáticamente) que únicamente sirven para diferenciar las diferentes integraciones hechas vía API, así como información adicional acerca de ésta. A continuación se especifica para cada uno de los tres campos su definición y sus restricciones. Los campos marcados con el símbolo indicarán la obligatoriedad del mismo. Por el contrario, los campos que no lleven dicho símbolo serán tratados como información opcional. En caso de tener dependencia entre campos, se indicará en cada una de las especificaciones; así como los campos a los que se debe esa dependencia (obligatoriedad).

1. Nombre de la integración [name] ():

• Identificador: name
• Descripción: Nombre de la integración que se está llevando a cabo. No hace falta que sea único, es decir, puede haber dos integraciones diferentes con el mismo nombre pero con diferente fecha de creación.
• Restricciones: Cadena de caracteres (string). Valor máximo: 100 caracteres.
• Ejemplos:
• Prueba0012
• X1266
• BCN_int003

2. Observaciones sobre la integración [description]:

• Identificador: description
• Descripción: Este campo permite indicar las observaciones o comentarios respecto a la integración que se está llevando. cabo.
• Restricciones: Cadena de caracteres (string). Valor máximo: 255 caracteres.
• Ejemplos:
• Todo correto

3. Fecha de la integración [dateSession] ():

• Identificador: dateSession
• Descripción: Indica la fecha en la que se lleva a cabo la integración.
• Restricciones: Fecha (datetime). Formato: YYYY-MM-DD
• Ejemplos:
• 2020-01-12
• 2020-01-25
• 2020-02-01

Junto con estos nuevos tres campos, y como ya se ha dicho, hay que añadir los campos anteriormente especificados en su apartado.

Punto de entrega vía API

{
 “name”: string,
 “description”: string,
 “dateSession”: datetime,
 “deliveryPoints”: [
 {
 “id”: string,
 “address”: string,
 “coordinates”: {
 “latitude”: float,
 “longitude”: float
 },
 “name”: string,
 “deliveryZoneId”: string,
 “deliveryWindow”: {
 “start”: int,
 “end”: int
 },
 “demand”: int,
 “serviceTime”: int,
 “requiredSignature”: boolean,
 “email”: string,
 “phone”: string
 }
 ]
}
Ejemplo – Punto de entrega vía API

{
 “name”: “MAD-00123”,
 “dateSession”: ”2020-11-24”,
 “deliveryPoints”: [
 {
 “id”: “1",
 “address”: ”Carrer Mallorca, 591 08026
Barcelona”,
 “name”: “Farmacia Anna”,
 “deliveryZoneId”: ”BCN”,
 “deliveryWindow”: {
 “start”: 28800,
 “end”: 36000
 },
 “demand”: 12,
 “serviceTime”: 480,
 “requiredSignature”: false,
 “phone”: “638901266”
 }
 ]
}
https://www.optimmanage.com/wp-content/uploads/2020/05/stitelogo-1.png
Optimmanage nace del sector logístico, tras 20 años de experiencia decidimos poner fin a la gran mayoría de los problemas que vivimos, desarrollando una solución funcional multiplataforma apta para todo tipo de negocio.

CONTÁCTANOS

Horario Comercial de Lunes – Viernes

de 10 – 14 y de 16 – 19

+34 930 08 52 41

© 2019 Copyright – All Rights Reserved. Project by booleanwork.com

ContáctanosBienvenidos a OptimManage

Horario de atención
Lunes a Viernes de 09:00 a 18:00

Teléfono
+34 930085241