|   Documentación

Soporte

SFTP

La integración por SFTP se pueden llevar a cabo para cualquier tipo de fichero: CLIENTES, RUTAS, ALBARANES y PRODUCTOS.

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

La conexión SFTP se la creará uno de nuestros propios técnicos y se enviará a la cuenta de correo electrónico que se introdujo en el momento del registro de la empresa en Polpoo. Como ERP, deberéis pedir a la empresa que os otorgue las siguientes credenciales:

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.

También recibiréis la información del directorio de la empresa donde deberéis realizar las integraciones correspondientes.

En cuanto a la configuración, la empresa deberá introducir un correo electrónico de soporte para las integraciones para que, en caso de haber algún tipo de error en alguno de los procesos, el ERP pueda observar cuál ha sido la incidencia. Esto es configurable desde la Configuración de la empresa, en el apartado Integraciones.

Integración de clientes

Un cliente se define como una localización en la que se puede realizar la entrega o recogida 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 (./).

En caso de cargar un fichero en el SFTP con el mismo nombre que un fichero ya existente, este se sobrescribirá.

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

Es importante que la información de los campos no contenga comillas dobles (p.e: "Frutería "El sol""), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial es aceptado.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el fichero .json.

Especificación de los campos

id string - obligatorio
Identificador único del cliente.

name string - obligatorio
Nombre del cliente.

address string obligatorio
Dirección principal de envío del 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 obligatorio
Tiempo estimado para realizar la descarga en el cliente (segundos).

demand integer obligatorio
Espacio que ocupa el pedido de un cliente (se manda 0).

email string
Correo electrónico del cliente.

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

population string
Población del cliente.

addresses.address string
Dirección secundaria del cliente.

addresses.postalCode string
Código postal de la dirección secundaria del cliente.

addresses.province string
Provincia de la dirección secundaria del cliente.

addresses.coordiantes.longitude number
Coordenada de longitud de la dirección secundaria del cliente.

addresses.coordiantes.latitude number
Coordenada de latitud de la dirección secundaria del cliente.

service.code string obligatorio si se envía un servicio
Código de la especificación de servicio.

service.name string obligatorio si se envía un servicio
Nombre de la especificación de servicio.

phones.name string
Nombre del contacto del teléfono secundario.

phones.phone string
Número de teléfono secundario.

showDeliveryNotePrice boolean
Si sus albaranes aparecerán con precios o sin precios.

Ejemplos y descargables

{
    "deliveryPoints": [
    {
        "id": "119029",
        "name": "Empresa Prueba SL",
        "address": "Pg. Sant Joan 6, 08009, Barcelona",
        "deliveryWindow": {
            "start": 14400,
            "end": 39600
        }
        "serviceTime": 600,
        "demand": 0,
        "email": "prueba@empr.com",
        "sendDeliveryNoteEmail": true,
        "population": "Barcelona",
        "addresses": [
        {
            "address": "Calle del Montevideo 3, 08009, Barcelona",
            "postalCode": "08009",
            "province": "Barcelona",
            "coordinates": {
                "longitude": 41.394149,
                "latitude": 2.1087109
            }
        }
        ],
        "service": {
            "code": "0002",
            "name": "Frío"
        }
        "phones": [
        {
            "name": "Administración",
            "phone": "+34666555777"
        }
        ],
        "showDeliveryNotePrice": true
    }
    ]
}

Integración de rutas

Una ruta se define como el conjunto de localizaciones en las que hay que realizar entregas o recogidas.

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 (./).

En caso de cargar un fichero en el SFTP con el mismo nombre que un fichero ya existente, este se sobrescribirá.

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

La plataforma cargará automáticamente los clientes que formen parte de las rutas y podrás encontrarlos en el menú Gestión -> Clientes.

Es importante que la información de los campos no contenga comillas dobles (p.e: "Frutería "El sol""), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial es aceptado.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el fichero .json.

Especificación de los campos

name string - obligatorio
Nombre de la importación.

description string - obligatorio
Descripción de la importación.

dateSession datetime - obligatorio
Fecha de la importación.

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 obligatorio
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.population string
Población del cliente.

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).

deliveryPoints.service.code string obligatorio si se envía un servicio

Código de la especificación de servicio.

deliveryPoints.service.name string obligatorio si se envía un servicio

Nombre de la especificación de servicio.

deliveryPoints.deliveryType string

Tipo de servicio ("shipment" = entrega // "pickup" = recogida). En caso de no enviarse, se marcará como entrega.

deliveryPoints.orderNumber string

Número del pedido referente al punto de entrega.

deliveryPoints.deliveryNotes string

Observaciones acerca de la entrega del pedido.

deliveryPoints.sendDeliveryNoteMail boolean

Si es true, se mandará el albarán por correo electrónico.

Ejemplos y descargables

{
    "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
        },
        "population": "Barcelona",
        "serviceTime": 480,
        "demand": 12,
        "phoneNumber": "34666555666",
        "email": "prueba@empr.com",
        "leadTime": 100,
        "service": {
            "code": "0002",
            "name": "Frío"
        },
        "deliveryType": "shipment",
        "orderNumber": "P-4234",
        "deliveryNotes": "Pedir llaves",
        "sendDeliveryNoteMail": true
        }
      ]
}

Integración de productos

* Hay dos formas de integrar los productos en Polpoo. Es importante conocer las dos formas y estudiarlas antes de empezar cualquier integración de productos. Ambas formas se detallan a continuación.

**El contenido de los ficheros de ambos tipos de integración será el mismo, por lo tanto, sirve la misma especificación de campos para ambos métodos.

Fichero: products.json

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 completo debe llamarse products.json y 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.

En caso de cargar un fichero en el SFTP con el mismo nombre que un fichero ya existente, este se sobrescribirá.

Es importante que la información de los campos no contenga comillas dobles (p.e: "Frutería "El sol""), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial es aceptado.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el fichero .json.

Fichero: productsShortX_XX.json

Fichero:

productsShortX_XX.json

El fichero para la integración de productos productsShort_X.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_X.json, donde X es libre. Este fichero deberá tener un máximo de 100 productos y se ejecutará cada 5 minutos.

El fichero para la integración de productos completo debe llamarse productsShort_X.json y 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.

En caso de cargar un fichero en el SFTP con el mismo nombre que un fichero ya existente, este se sobrescribirá.

Es importante que la información de los campos no contenga comillas dobles (p.e: "Frutería "El sol""), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial es aceptado.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el fichero .json.

Especificación de los campos

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.

Ejemplos y descargables

{
    "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,
              "images": [
                  "data:image/jpeg;base64,/9j/4AA"
              ],
              "subCategory": {
                  "code": "08",
                  "name": "Fresca",
                  "isActive": true,
                  "filters": [{
                      "code": "02",
                      "name": "Manzana",
                      "isActive": false
                    }]
              }
        },
        "images": [
            "data:image/jpeg;base64,/9j/4AA"
        ],
        "productPrices": [{
            "measure": {
                "code": "kg",
                "name": "KG"
            },
            "price": 1.21,
            "quantity": 12,
            "equivalencePercent": 0,
            "taxPercent": 4,
            "isActive": true
        }]
    }
    ]
}

Integración de 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.

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.

En caso de cargar un fichero en el SFTP con el mismo nombre que un fichero ya existente, este se sobrescribirá.

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

Es importante que la información de los campos no contenga comillas dobles (p.e: "Frutería "El sol""), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial es aceptado.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el fichero .json.

Especificación de los campos

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.

Ejemplos y descargables

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

        }]

    }]
}

Integración de 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 del SFTP (./).

En caso de cargar un fichero en el SFTP con el mismo nombre que un fichero ya existente, este se sobrescribirá.

En un mismo fichero tienen que venir toda la información de todos los albaranes.

Si un cliente tiene más de un albarán, se tiene que añadir como nuevo registro en el array "deliveryNotes". Si por ejemplo, se entregan 5 albaranes en un mismo destino, se tiene que añadir un único registro de ese cliente cliente con 5 albaranes.

Es importante que la información de los campos no contenga comillas dobles (p.e: "Frutería "El sol""), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial es aceptado.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el fichero .json.

Especificación de los campos

id string obligatorio
Identificador único del cliente.

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

deliveryNotes.deliveryNoteObservation string
Observaciones del albarán.

deliveryNotes.deliveryNoteOrderCode string
Número del pedido referente al albarán.

deliveryNotes.showDeliveryNotePrice boolean
Si aparecerá el albarán con precios o sin precios.

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

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

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

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

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

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

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

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

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

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

deliveryNotes.products.code string obligatorio
Identificador del producto.

deliveryNotes.products.name string obligatorio
Nombre del producto.

deliveryNotes.products.quantity float obligatorio
Cantidad del producto.

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

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

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

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

deliveryNotes.products.measure string obligatorio
Formato del producto.

deliveryNotes.products.grossMass float
Peso bruto del producto.

deliveryNotes.products.tare float
Tara del producto.

deliveryNotes.products.netMass float
Peso neto del producto.

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

deliveryNotes.products.observation string
Observaciones del producto.

Ejemplos y descargables

{
    "deliveryPoints": [{
        "id": "119029",
        ”deliveryNotes”: [
        {
            "deliveryNoteCode": "45466770",
            "deliveryNoteObservation": "Observaciones",
            "deliveryNoteOrderCode": "2013",
            "showDeliveryNotePrice": true,
            "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,
                "measure": "KGS",
                "grossMass": 0.67,
                "tare": 0.16,
                "netMass": 0.51,
                "lotCode": "11297090",
                "observation": "Observaciones"
            }]
        }
        ]
    }
    ]
}

Integra tus facturas

La integración de facturas 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 enviará a la cuenta de correo electrónico que se introdujo en el momento del registro de la empresa en Polpoo. Como ERP, deberéis pedir a la empresa que os otorgue las siguientes credenciales:

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.

También recibiréis la información del directorio de la empresa donde deberéis realizar las integraciones correspondientes.

En cuanto a la configuración, la empresa deberá introducir un correo electrónico de soporte para las integraciones para que, en caso de haber algún tipo de error en alguno de los procesos, el ERP pueda observar cuál ha sido la incidencia. Esto es configurable desde la Configuración de la empresa, en el apartado Integraciones.

1. Funcionamiento de la integración de facturas

Los clientes que quieran tener a su disposición el módulo de facturación y por lo tanto la integración de facturas activa, deberán almacenar ellos en un servidor propio los documentos necesarios. 

Cada vez que se tenga que mandar una factura, lo que se mandará en el fichero que veremos más adelante es un enlace a ese documento almacenado fuera de Polpoo.

Es importante tener claro este paso ya que Polpoo no tendrá en cuenta otro método de trabajo que no sea este. Dicho de otra manera, Polpoo no almacenará la documentación de las facturas de los clientes.

2. Tipo de documento: bills.json

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

En caso de cargar un fichero en el SFTP con el mismo nombre que un fichero ya existente, este se sobrescribirá.

Es importante que la información de los campos no contenga comillas dobles (p.e: "Frutería "El sol""), ya que los ficheros .json trabajan con comillas dobles para delimitar los campos y la información. En caso de tener algún dato de este estilo, la integración no se realizará correctamente. Cualquier otro símbolo especial tampoco es aceptado.

El campo "archiveUrl" contendrá la URL externa donde se almacena el documento  en pdf de la factura.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el fichero .json.

3. Especificaciones de los campos

deliveryPointId string obligatorio
Identificador único del cliente.

code string – obligatorio
Número o código de la factura.

total float obligatorio
Importe total de la factura.

archiveUrl string obligatorio
Enlace externo del documento de la factura.

status integer obligatorio
Estado de la factura. Si el valor es 1 está por cobrar. Si el valor es 2 está cobrada.

4. Ejemplos y descargables

{
    "bills": [{
        "deliveryPointId": "1054",
        "code": "119029",
        "total": 221.30,
        "archiverUrl": "https://via.placeholder.com/119029.pdf",
        "status": 1
    }
    ]
}

5. ¿Cómo recibo la información en Polpoo?

Partimos de la base que, para que el fichero de facturas pueda ser absorbido y cargado correctamente por Polpoo.

Una vez cargado satisfactoriamente el fichero bills.json en el SFTP, la plataforma lo cargará automáticamente en su correspondiente sección para ser tratado.

Para visualizar las facturas, nos dirigimos al menú Gestión -> Facturación.

Dentro del apartado Facturación, se encontrará todo el registro de facturas por fecha de subida. Mediante los diferentes filtros, se podrá consultar la información que se desee.

6. ¿Cómo devuelvo las facturas a Polpoo?

Para mandar la información de las facturas de vuelta al ERP, tendréis que dirigiros al menú Gestión -> Facturación.

Para mandar la información de las facturas al SFTP, clicamos en el botón derecho Descargar todas situado en la parte superior de la tabla de facturas.

7. Tipo de documento

El envío de facturas de vuelta generará un fichero .json para cada una de las facturas. El fichero se llamará bill_XXXX.json, donde XXXX es el número o código de la factura. Está codificado en UTF-8. Este tipo de fichero se recogerá de la carpeta bills (./bills) dentro del SFTP. Esta carpeta es posible que no esté disponible hasta que se mande un fichero de facturas de vuelta por primera vez.

En caso de devolver una factura que aún no esté cobrada, el valor de todos los campos será null, a excepción del campo "code" (número o código de la factura).

8. Especificaciones de los campos

code string
Número o código de la factura.

paymentDate datetime
Fecha en la que se ha realizado el pago de la factura.

paymentType string
Forma de pago (Efectivo o Tarjeta de crédito o débito).

chargeType string
Canal desde el cual se ha pagado factura (App o Comercial).

userChargedBy string
Usuario que ha cobrado la factura.

9. Ejemplos y descargables

{
    "code": "119029",
    "paymentDate": "2021-10-04 14:54:21",
    "paymentType": "Efectivo",
    "chargeType: "App",
    "userChargedBy": "Pedro Sierra"
}

Integración de pedidos

El fichero para la integración de pedidos es un fichero de recogida de datos, es decir, los pedidos que hayan llegado a Polpoo podrán recogerse en forma de fichero para el tratamiento de la información.

Al tratarse de un fichero que se genera desde la plataforma no tiene un nombre en concreto. Estará codificado en UTF-8.

Este documento se podrá encontrar en el directorio (./companyX/orders), donde X es el número de la compañía que se ha enviado vía mail.

Se definen los campos que pertenecen a este fichero de la siguiente manera:

* La información obligatoria está marcada en rojo. En caso de que no se tenga la información de un campo opcional, no se tiene que añadir la etiqueta en el fichero .json.

Especificación de los campos

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.

Ejemplos y descargables

{
    "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

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.

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/jason

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

{
"client_id": 1,
"client_secret": "tT96kecNtYVf92dvRf
Q1Ikj6sjsx5tKZzaCCpHun"
,
"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

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.

{
"access_token": "eyJ0eXAiOiJKV1QiLC
JhbGciOiJSUzI1NiI"
,
"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.

Especificación de los campos

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.

Ejemplos y descargables

{
    "name": "Rutas Lunes",
    "description": "Rutas de los lunes",
    "dateSession": "2020-03-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.

Especificación de los campos

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 rutasLos 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.

Especificación de los campos

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.