SFTP

Las importaciones por STFP se pueden llevar a cabo para cualquier tipo de fichero: CLIENTES, RUTAS, ALBARANES, PRODUCTOS y PEDIDOS.

Requiere de una conexión particular de cada cliente a nuestro servidor SFTP. Esta conexión se la creará uno de nuestros propios técnicos y se os enviará a vuestra cuenta de correo electrónico de contacto en el momento del inicio de la integración.

Los ficheros deben estar codificados en UTF-8.

Conexión SFTP

Las credenciales las encontraréis en el correo electrónico de contacto.

  • Usuario: Nombre de usuario.
  • Contraseña: Contraseña del usuario.
  • Servidor: Dirección a la que conectarse.
  • Puerto: Puerto por el cual se conectará el cliente a nuestro servidor.

Hay dos tipos de directorios en el sftp:

  • Directorio de envío de ficheros: El cliente dejará aquí sus ficheros JSON para cargarlos en Polpoo.
  • Directorio de recogida de ficheros: El cliente recogerá aquí sus ficheros JSON generados desde Polpoo.

Integración clientes

Hay dos formas de realizar la integración de clientes: la primera de ellas es la carga del fichero clients.json con la información de estos; la segunda es la carga de las rutas con el fichero delivery_points.json, que automáticamente cargará los nuevos clientes de estas en la plataforma.

En cualquiera de los dos casos, el fichero debe estar codificado en UTF-8.

Clientes

Un cliente se define como una localización en la que hay que realizar la entrega de un pedido.

El fichero para la integración de clientes debe llamarse clients.json y debe estar codificado en UTF-8. Se dejará en el directorio raíz (./).

La plataforma cargará los nuevos clientes y podrás encontrarlos en el menú Gestión -> Clientes.

id string
Identificador único del cliente.

name string - obligatorio
Nombre del cliente.

address string obligatorio
Dirección de envío del cliente.

deliveryZoneId string
Zona de reparto a la que pertenece el cliente.

deliveryWindow.start integer
Hora en la que se puede empezar a repartir en un cliente (segundos).

deliveryWindow.end integer
Hora en la que ya no se puede repartir en un cliente (segundos).

serviceTime integer
Tiempo estimado para realizar la descarga en el cliente (segundos).

demand integer
Espacio que ocupa el pedido de un cliente.

email string
Correo electrónico del cliente.

sendDeliveryNoteMail boolean
Si el cliente recibirá o no un email cuando se le haya entregado el pedido.

clients.json

{
"deliveryPoints": [ 
{
"id": "119029",
"name": "Empresa Prueba SL",
"address": "Pg. Sant Joan 6, 08009, Barcelona",
"deliveryZoneId": "BCN-02",
"deliveryWindow": {
"start": 14400,
"end": 39600
}
"serviceTime": 600,
"demand": 0,
"email": "prueba@empr.com",
"sendDeliveryNoteEmail": true,
}
]
}

Clientes mediante la carga de rutas

Un cliente se define como una localización en la que hay que realizar la entrega de un pedido.

El fichero para la integración de clientes debe llamarse delivery_points.json y debe estar codificado en UTF-8. Para cargar los clientes nos dirigimos al Planificador de rutas -> + Rutas -> Seleccionar archivos.

La plataforma cargará automáticamente los nuevos clientes y podrás encontrarlos en el menú Gestión -> Clientes.

id string obligatorio
Identificador único del cliente.

address string obligatorio
Dirección de envío del cliente.

coordinates.latitude number
Coordenada de latitud de cliente.

coordinates.longitude number
Coordenada de longitud del cliente.

name string - obligatorio
Nombre del cliente.

deliveryZoneId string - obligatorio
Zona de reparto a la que pertenece el cliente.

deliveryWindow.start integer
Hora en la que se puede empezar a repartir en un cliente (segundos).

deliveryWindow.end integer
Hora en la que ya no se puede repartir en un cliente (segundos)

demand integer
Espacio que ocupa el pedido de un cliente.

serviceTime integer
Tiempo estimado para realizar la descarga en el cliente.

requiredSignature boolean
Indica si se podrá firmar el pedido por la app.

email string
Correo electrónico del cliente.

phone string
Número de teléfono del cliente.

agentUserMail string
Correo electrónico del comercial que lleva el cliente.

orderId integer
Identificador (id) de la orden para poder vincularla con el cliente.

useBillingAddress boolean
Indica si se puede añadir una dirección de facturación.

billingAddress string obligatorio si useBillingAddress es true
Dirección de facturación del cliente.

delivery_points.json

{
"deliveryPoints": [ 
{
"id": "119029",
"address": "Pg. Sant Joan 6, 08009, Barcelona",
"coordinates": {
"latitude": 41.3971593,
"longitude": 2.1726474
}
"name": "Empresa Prueba SL",
"deliveryZoneId": "BCN-02",
"deliveryWindow": {
"start": 14400,
"end": 39600
}
"demand": 0,
"serviceTime": 600,
"requiredSignature": true,
"email": "prueba@empr.com",
"phone": "34666555666",
"agentUserMail": "com@empr.com",
"orderId": 120,
"useBillingAddress": true,
"billingAddress": "C. Piu I 58, 08009, Barcelona"
}
]
}

Integración rutas

El fichero para la integración de rutas debe llamarse delivery_points.json y debe estar codificado en UTF-8. Se dejará en el directorio raíz (./).

La plataforma cargará las nuevas rutas y podrás encontrarlas desde el Planificador de rutas, importando desde el Planificador de Entregas.

Rutas

Una ruta se define como un conjunto de clientes a los que hay que realizar la entrega de un pedido.

name string - obligatorio
Nombre de la ruta.

description string
Descripción de la ruta.

dataSession datetime - obligatorio
Fecha de a ruta.

deliveryPoints.id string - obligatorio
Identificador único del cliente.

deliveryPoints.name string - obligatorio
Nombre del cliente.

deliveryPoints.address string obligatorio
Dirección del cliente.

deliveryZoneId string
Zona de reparto a la que pertenece el cliente.

deliveryPoints.deliveryWindow.start integer
Hora en la que se puede empezar a repartir en un cliente (segundos).

deliveryPoints.deliveryWindow.end integer
Hora en la que ya no se puede repartir en un cliente (segundos).

deliveryPoints.serviceTime integer
Tiempo estimado para realizar la descarga en el cliente (segundos).

deliveryPoints.demand integer
Espacio que ocupa el pedido de un cliente.

deliveryPoints.phoneNumber string
Número de teléfono del cliente.

deliveryPoints.email string
Correo electrónico del cliente.

deliveryPoints.leadTime integer
Tiempo de entrega antes de la hora de apertura del cliente (segundos).

delivery_points.json

{
"name": "RutaXX",
"description": "Ruta de farmacias",
"dateSession": "2020-11-9",
"deliveryPoints": [{
"id": "119029",
"name": "Empresa SL",
"address": "Pg. Sant Joan 6, 08009, Barcelona",
"deliveryZoneId": "BCN-02",
"deliveryWindow": {
"start": 17700,
"end": 28000
},
"serviceTime": 480,
"demand": 12,
"phoneNumber": "34666555666",
"email": "prueba@empr.com",
"leadTime": 100
}
]
}

Integración productos

Hay dos formas de realizar la integración de productos: la primera de ellas es la carga del fichero products.json con la información de todos los productos que se quiera; la segunda es la carga de los productos con el fichero productsShort_XX.json, que cargará hasta un máximo de 100 productos.

El fichero para la integración de productos products.json se utilizará para la carga inicial de productos, pudiendo enviar todo tu catálogo en un sólo fichero para hacer una carga masiva. Para llevar a cabo este tipo de integración, deberá ponerse en contacto con uno de nuestros técnicos, ya que debe realizarse de forma manual para controlar en todo momento la subida.

El fichero para la integración de productos productsShort_XX.json se utilizará para la carga de actualizaciones o de creación de nuevos productos del día a día, pudiendo enviar tantos ficheros como se quiera. El nombre del fichero deberá ser productsShort_XX.json, donde X es libre. Este fichero deberá tener un máximo de 100 productos y se ejecutará cada 5 minutos.

En cualquiera de los dos casos, el fichero debe estar codificado en UTF-8. Se dejará en el directorio ./companyX/products, donde la X es el número de la compañía que se os ha enviado vía mail. Los campos que lo conforman son los detallados a continuación.

Productos

Un producto se define como un objeto con un identificador único que una empresa ofrece a sus clientes.

code string - obligatorio
Código del producto.

name string obligatorio
Nombre del producto.

description string
Descripción del producto.

origin string
Origen del producto.

estimatedWeightPerUnit float
Peso medio por unidad (KG).

freeField string
Campo de información libre.

isActive boolean
Si el producto está activo o no. Por defecto estará activo.

showInApp boolean
Si el producto es visible desde la aplicación o no.

promotion boolean
Si el producto tiene una promoción o no.

startPromotionDate datetime obligatorio si promotion es true
Fecha de inicio de la promoción.

endPromotionDate datetime obligatorio si promotion es true
Fecha de finalización de la promoción.

highlight boolean
Si el producto está destacado en la aplicación o no.

valoration float
La valoración del producto. Indica su posición en la app.

category.code string obligatorio
Código de la categoría del producto.

category.name string obligatorio
Nombre de la categoría del producto.

category.isActive boolean
Si la categoría está activa o no. Por defecto estará activa.

category.images base64
Imagen de la categoría.

category.subCategory.name string
Código de la subcategoría del producto.

category.subCategory.name string
Nombre de la subcategoría del producto.

category.subCategory.isActive boolean
Si la subcategoría está activa o no. Por defecto estará activa.

category.subCategory.filters.code string
Código del filtro del producto.

category.subCategory.filters.name string
Nombre del filtro del producto.

category.subCategory.filters.isActive boolean
Si el filtro está activo o no. Por defecto estará activo.

images base64
Imagen/es del producto.

productPrices.measure.code string obligatorio
Código de la medida del producto.

productPrice.measure.name string obligatorio
Nombre de la medida del producto.

productPrices.price float obligatorio
Precio por medida del producto.

productPrices.quantity float obligatorio
Cantidad por medida del producto.

productPrices.equivalencePercent float
Porcentaje del recargo de equivalencia del producto.

productPrices.taxPercent float
Impuesto sobre el Valor Añadido (IVA) del producto.

productPrices.isActive boolean
Si el formato está activo o no. Por defecto estará activo.

products.json

{
"products": [
{
"code": "034",
"name": "Manzana Pink Pearl",
"description": "Buena manzana",
"origin": "Valencia",
"estimatedWeightPerUnit": 0.67,
"freeField": "Buena manzana.",
"isActive": true,
"showInApp": true,
"promotion": true,
"startPromotionDate": "2021-01-20",
"endPromotionDate": "2021-01-25",
"highlight": true,
"valoration": 1.5,
"category": {
"code": "03",
"name": "Fruta",
"isActive": true,
"subCategory": {
"code": "08",
"name": "Fresca",
"isActive": true,
"filters": [{
"code": "02",
"name": "Manzana",
"isActive": false
}]
}
},
"productPrices": [{
"measure": {
"code": "kg",
"name": "KG"
},
"price": 1.21,
"quantity": 12,
"equivalencePercent": 0,
"taxPercent": 4,
"isActive": true
}]
}
]
}

Integración productos no entregados

El fichero para la integración de productos no entregados no tiene un nombre en concreto; por ejemplo undeliveredProducts.json y debe estar codificado en UTF-8. Se dejará en el directorio ./orders/undeliveredProducts.

Este fichero incluirá los productos de cada pedido que no se han entregado.

Productos no entregados

Un producto no entregado se define como un objeto con un identificador único que durante un pedido no ha podido ser entregado.

code string - obligatorio
Código del albarán.

undeliveredProducts.code string obligatorio
Código del producto.

measure.undeliveredProducts.code string obligatorio
Código de la medida del producto.

undeliveredProducts.json

{
"orders": [{
"code": "2321343",
"undeliveredProducts": [{
"code": "0056",
"measure": {
"code": "003"
}
} ]
} ]
}

Integración albaranes

El fichero para la integración de albaranes debe llamarse albarans.json y debe estar codificado en UTF-8. Se dejará en el directorio raíz (./).

Cuando se tenga una ruta asignada, se podrán cargar los albaranes desde el menú de Rutas -> Rutas asignadas y clicando en el botón Agregar Productos -> Importar desde nube.

Albaranes

Un albarán se define como un documento que se entrega a cada cliente con el listado de todos los productos de un pedido.

id string - obligatorio
Identificador único del cliente.

deliveryNoteCode string obligatorio
Número o código del albarán.

deliveryNoteObservation string
Observaciones del albarán.

deliveryPayDiscuntPercent float
Porcentaje de descuento a aplicar en el precio total del albarán.

companyAssociated.code string obligatorio si factura compañía asociada
Código de la compañía asociada

companyAssociated.name string obligatorio si factura compañía asociada
Nombre de la compañía asociada

companyAssociated.nif string obligatorio si factura compañía asociada
NIF de la compañía asociada

companyAssociated.streetAddress string obligatorio si factura compañía asociada
Dirección de la compañía asociada

companyAssociated.city string obligatorio si factura compañía asociada
Ciudad de la compañía asociada

companyAssociated.province string obligatorio si factura compañía asociada
Provincia de la compañía asociada

companyAssociated.zipCode string obligatorio si factura compañía asociada
Código postal de la compañía asociada

companyAssociated.phone string obligatorio si factura compañía asociada
Número de teléfono de la compañía asociada

companyAssociated.billingAddress string obligatorio si factura compañía asociada
Correo de facturación de la compañía asociada

products.code string - obligatorio
Identificador del producto.

products.name string - obligatorio
Nombre del producto.

products.quantity float - obligatorio
Cantidad del producto.

products.price float - obligatorio
Precio del producto por medida.

products.measureQuantity float
Cantidad del producto referente a la medida.

products.taxPercent integer - obligatorio
Impuesto sobre el Valor Añadido (IVA) del producto.

products.equivalencePercent float
Porcentaje del recargo de equivalencia del producto.

products.lotCode string
Identificador del lote al que pertenece el producto.

products.observation string
Observaciones del producto.

albarans.json

{
"deliveryPoints": [
{
"id": "119029",
"deliveryNoteCode": "45466770",
"deliveryNoteObservation": "Observaciones",
"deliveryPayDiscountPercent": 21,
"companyAssociated":{
"code": "0023",
"name": "Empresa Asociada SL",
"nif": "B78902232",
"streetAddress": "Pg. Sant Joan 21, 08009, Barcelona",
"city": "Barcelona",
"province": "Barcelona",
"zipCode": "08009",
"phone": "+346162666112",
"billingEmail": "asociada@empr.com"
},
"products": [{
"code": "PX-34",
"name": "Manzana Pink Pearl",
"quantity": 23,
"price": 0.67,
"measureQuantity": 2,
"taxPercent": 21,
"equivalencePercent": 5.2,
"lotCode": "11297090",
"observation": "Observaciones"
}]
}
]
}

Integración pedidos

El fichero para la integración de pedidos no tiene un nombre en concreto ya que depende del nombre del pedido; por ejemplo order_companyX_20200115.json y debe estar codificado en UTF-8.

Este es un fichero de recogida de datos, es decir, se generará desde la plataforma y se enviará a vuestro SFTP para su recogida y tratamiento. Se podrán obtener del fichero todos los campos que sean necesarios.

Para enviar este tipo de fichero al SFTP, desde el menú de Pedidos clicamos en el botón Enviar Pedidos.

Pedidos

Un pedido se define como un conjunto de productos solicitados por un cliente.
id string
Identificador del pedido.

code string
Código del pedido.

orderDate datetime
Fecha de entrega del pedido.

observations string
Observaciones del pedido.

fromApp boolean
Si el pedido proviene de la app o no.

statusOrderId integer
Estado en el que se encuentra el pedido.

deliveryPointId integer
Identificador del cliente.

name string
Nombre del cliente.

address string
Dirección del cliente.

phoneNumber string
Número de teléfono del cliente.

orderProducts.quantity float
Cantidad del producto.

orderProducts.price float
Precio del producto.

orderProducts.taxPercent integer
Impuesto sobre el Valor Añadido (IVA) del producto.

orderProducts.equivalencePercent float
Porcentaje del recargo de equivalencia del producto.

orderProducts.tax float
Precio del producto con el IVA.

orderProducts.equivalence float
Precio del producto con el recargo de equivalencia.

orderProducts.subTotal float
Precio total del producto sin IVA y/o recargo de equivalencia.

orderProducts.total float
Precio total del producto con IVA y/o recargo de equivalencia.

orderProducts.product.id integer
Identificador del producto.

orderProducts.product.code string
Código del producto.

orderProducts.product.name string
Nombre del producto.

orderProducts.measure.id integer
Identificador de la medida del producto.

orderProducts.measure.name string
Nombre de la medida del producto.

status.id integer
Identificador del estado del pedido.

status.name string
Nombre del estado del pedido.

order_companyX_20200115.json

{
"orders": [ 
{
"id": "119029",
"code": "45466770",
"orderDate": "2020-01-20",
"observations": "Observaciones",
"fromApp": true,
"statusOrderId": 1,
"deliveryPointId": 21,
"name": "Empresa Prueba SL",
"address": "PG. Sant Joan 6, 08009, Barcelona",
"phoneNumber": "34666555666",
"orderProducts": [{
"quantity": 7,
"price": 0.89,
"taxPercent": 21,
"equivalencePercent": 5.2,
"tax": 1.07,
"equivalence": 0.94,
"subTotal": 6.23,
"total": 7.49,
"product": {
"id": "12",
"code": "PX-34",
"name": "Manzana Pink Pearl"
},
"measure": {
"id": "4",
"name": "KG"
},
}],
"status": {
"id": "1",
"name": "En proceso"
}
}
]
}

API

La importación de contenido mediante API requiere de la creación por parte del usuario de un token de acceso. Este token es un string que identifica a un usuario dentro de una aplicación o servicio, para realizar llamadas a la API.

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. Debe estar codificado en UTF-8.

Creación del token

Para obtener este token de acceso tendrá que tener un usuario creado en nuestra plataforma con el rol de técnico. En el momento de la creación de la cuenta en Polpoo se creará automáticamente un usuario técnico. Las credenciales de dicho usuario serán enviadas en el correo de bienvenida. En caso de querer crear otra cuenta de usuario de tipo técnico, hay que ir a la sección de Gestión y en la pestaña de Usuarios clicar en Añadir usuario y rellenar todos los campos; indicando el rol de usuario como técnico.

Los parámetros de conexión de la conexión API son los siguientes:

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

Para obtener el token de acceso se deberá hacer una petición 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 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

Integración de clientes 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.polpoo.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. Solo se incluyen tres campos nuevos (automáticamente) que únicamente sirven para diferenciar las diferentes integraciones hechas vía API.

Junto con estos nuevos tres campos, y como ya se ha dicho, hay que añadir los campos anteriormente especificados en la Integración de Rutas.

name string
Nombre de la integración.

description string
Observaciones de la integración.

dateSession datetime
Fecha de la integración.

** Los campos del deliveryPoints son los mismos
que los de la integración de rutas por SFTP.

delivery_points.json

{
name: "Rutas Lunes",
description: "Es la ruta de los lunes",
dateSession: "2020-3-22",
"deliveryPoints": [
{
.....
.....
},
{
...
...
}
]
}

EXCEL

La integración por fichero Excel, está única y exclusivamente disponible para la integración de clientes.

El fichero para la integración de clientes por Excel no necesita tener un nombre en concreto.

Para cargarlo en la plataforma tendremos que ir al menú Gestión -> Clientes i clicar en el botón Importar.

Modelo Excel

id string - obligatorio
Identificador único del cliente.

name string - obligatorio
Nombre del cliente.

nif string - obligatorio
Número de identificación fiscal.

address string - obligatorio
Dirección de envío del cliente.

coordinatesLatitude number
Coordenada de latitud de cliente.

coordinatesLongitude number
Coordenada de longitud del cliente.

postalCode integer
Código postal del cliente.

province string
Provincia del cliente.

email string
Correo electrónico del cliente.

phoneNumber string
Teléfono del cliente.

deliveryZoneId string - obligatorio
Zona de reparto a la que pertenece el cliente.

deliveryWindowStart integer
Hora en la que se puede empezar a repartir a un cliente (segundos).

deliveryWindowEnd integer
Hora en la que ya no se puede repartir a un cliente (segundos).

serviceTime integer
Tiempo estimado para realizar la descarga en el cliente (segundos).

demand integer
Espacio que ocupa el pedido de un cliente.

requiredSignature boolean
Indica si se podrá firmar el pedido por la app.

leadTime string
Tiempo de entrega antes de la hora de apertura del cliente (segundos).

delayTime string
Retraso permitido en la entrega al cliente (segundos).

sendDeliveryNoteMail boolean
Si el cliente recibirá o no un email cuando se le haya entregado el pedido.

CSV

La integración por fichero CSV, está única y exclusivamente disponible para la carga de rutas en el
planificador de rutas
Los clientes de estas rutas que no estén registrados en nuestra base de datos
serán almacenados, y se podrá ver toda su información desde el menú de Gestión -> Clientes.

El fichero para la integración de clientes por CSV no necesita tener un nombre en concreto. Los campos
deberán ir separados por comas.

Para cargarlo en la plataforma tendremos que ir al menú Planificador de rutas -> + Rutas i clicar en el
botón Subir archivo. La plataforma cargará automáticamente los nuevos clientes y ya podrás encontrarlos
en el menú Gestión -> Clientes.

Modelo CSV

id string - obligatorio
Identificador único del cliente.

address string - obligatorio
Dirección de envío del cliente.

coordinates.latitude number
Coordenada de latitud de cliente.

coordinates.longitude number
Coordenada de longitud del cliente.

name string - obligatorio
Nombre del cliente.

deliveryZoneId string - obligatorio
Zona de reparto a la que pertenece el cliente.

deliveryWindow.start integer
Hora en la que se puede empezar a repartir a un cliente (segundos).

deliveryWindow.end integer
Hora en la que ya no se puede repartir a un cliente (segundos).

demand integer
Espacio que ocupa el pedido de un cliente.

serviceTime integer
Tiempo estimado para realizar la descarga en el cliente (segundos).

requiredSignature boolean
Indica si se podrá firmar el pedido por la app.

email string
Correo electrónico del cliente.

phoneNumber string
Número de teléfono del cliente.

Logo de Polpoo

Icono de YouTube    Icono de LinkedIn    Icono de Instagram    Icono de Facebook

Horario de Atención

Lunes - Viernes de 9:30 - 18:00

+34 931 097 523

info@polpoo.com

Logo de Polpoo

Icono de YouTube    Icono de LinkedIn    Icono de Instagram    Icono de Facebook

Horario de Atención

Lunes - Viernes de 9:30 - 18:00

+34 931 097 523

info@polpoo.com