Documentación Polpoo

Documentación de Integración Polpoo

Esta web sustituye la documentación operativa anterior y consolida todos los bloques de integración: envíos, devoluciones, tracking y plantillas.

Novedades

Registro incremental de campos y endpoints incorporados en la integración. Añadir una fila por cada cambio nuevo.

Reglas Globales de Integración

• Codificación de ficheros: UTF-8.
• No incluir un campo opcional si no hay valor real.
• No usar comillas dobles dentro de textos de datos.
• En SFTP, si subes un fichero con el mismo nombre, se sobrescribe.
• Obligatorio si aplica: el campo es obligatorio solo cuando usas ese módulo o caso de negocio (ejemplo: Paquetería, Almacenes o compañía asociada).
• En los bloques API Tester, los campos con fondo resaltado y etiqueta Editable se pueden modificar antes de lanzar la prueba.
• Antes de probar un endpoint API, revisa siempre la URL, el Bearer Token y el JSON Body editable.

Validador de ficheros

Sube un fichero .json y comprueba antes de enviarlo a Polpoo: codificación UTF-8, sintaxis, estructura, campos obligatorios, tipos y reglas (exclusividad isBill/isOrder/isDispatchNote, valores enumerados, etc.).

La validación se ejecuta localmente en tu navegador. El fichero no se sube a ningún servidor.

Autenticación API

Token técnico para llamadas API.

En el API Tester, los campos marcados como Editable son de prueba y puedes sustituirlos por tus credenciales y valores reales antes de ejecutar.

Sin ejecutar

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

Usar cabecera Authorization: Bearer <token>.

API · Envío de Rutas

Existen dos modos de envío con el mismo payload:

• /api/integration_session/delivery_point — acumulativo: todos los envíos del mismo día se agrupan en la misma entrega planificada en Polpoo.
• /api/integration — independiente: cada envío crea una entrega planificada nueva.

Los campos del formulario inferior están preparados para editarse rápido en pruebas manuales. Cambia el token y el JSON antes de enviar a producción o sandbox.

Sin ejecutar

Sin ejecutar

Ejemplo mínimo

{
  "name": "Rutas 2026-04-07",
  "description": "Carga diaria ERP",
  "dateSession": "2026-04-07",
  "deliveryPoints": [
    {
      "id": "CL-1001",
      "name": "Cliente Demo",
      "address": "Calle Mayor 1, Sevilla",
      "deliveryZoneId": "SEV-01",
      "orderNumber": "PED-260407-001",
      "deliveryType": "shipment"
    }
  ]
}

API · Envío de Albaranes

Sin ejecutar

Ejemplo mínimo

{
  "dateDeliveryStart": "2026-04-07",
  "deliveryPoints": [
    {
      "id": "CL-1001",
      "deliveryNotes": [
        {
          "deliveryNoteCode": "ALB-260407-001",
          "deliveryNoteOrderCode": "PED-260407-001",
          "products": [
            {
              "code": "PRD-001",
              "name": "Producto 1",
              "quantity": 2,
              "price": 4.5,
              "taxPercent": 21,
              "measure": "UNITS"
            }
          ]
        }
      ]
    }
  ]
}

API · Envío de Cobros

Sin ejecutar

Ejemplo mínimo

{
  "bills": [
    {
      "deliveryPointId": "CL-1001",
      "code": "FAC-260407-001",
      "total": 145.25,
      "archiveUrl": "https://erp.midominio.com/facturas/FAC-260407-001.pdf",
      "status": 1
    }
  ]
}

API · Envío de Motivos

Sincroniza el catálogo de motivos de incidencia (causas predefinidas que el chófer puede seleccionar en la app al registrar una incidencia o modificación).

Sin ejecutar

No usar comillas dobles dentro del valor de name (rompen el JSON). El resto de caracteres especiales son válidos.

Ejemplo mínimo

{
  "data": [
    {
      "code": "1",
      "name": "Roto",
      "isActive": false
    },
    {
      "code": "2",
      "name": "Mal estado",
      "isActive": true
    }
  ]
}

API · Devolución de Cobros

Sin ejecutar

Debe enviarse al menos uno de los dos filtros: deliveryPointId o code.

Campos de consulta

Campos devueltos

Ejemplo petición

{
  "deliveryPointId": "CL-1001",
  "code": "FAC-260407-001"
}

Ejemplo respuesta

[
  {
    "name": "Cliente Demo",
    "code": "FAC-260407-001",
    "paymentDate": "2026-04-07 10:15:00",
    "paymentType": "Tarjeta de crédito o débito",
    "userChargedBy": "Chofer 01",
    "total": 145.25,
    "billPaymentStatusName": "Cobrado",
    "billPaymentStatusId": 2,
    "vehicle": "1234ABC"
  }
]

API · Devolución Orden de Rutas

Sin ejecutar

Ejemplo petición

{
  "date": "2026-04-07"
}

Ejemplo respuesta

{
  "data": [
    {
      "ruta": "RUTA-1",
      "vehicle": {
        "id": 100,
        "registration": "1234ABC"
      },
      "deliveryPoints": [
        {
          "id": "CL-1001",
          "order": 1,
          "estimatedArrivalTime": 32400,
          "orderNumber": "PED-260407-001"
        }
      ]
    }
  ]
}

API · Seguimiento de Rutas (consulta)

Sin ejecutar

La respuesta es extensa. Campos más usados en integración ERP:

API · Maestro de Clientes (consulta)

Consulta el maestro de clientes de Polpoo. Sin parámetros devuelve la base completa; con id o name filtra el resultado.

Sin ejecutar

Filtros de consulta

Campos devueltos

Ejemplo petición

GET https://v2.restapi.polpoo.com/api/delivery_point_datatables?id=1054

API · Tracking (devolución de estado a Polpoo)

Sin ejecutar

No todos los campos se envían en todos los eventos. La obligatoriedad depende del event.

API · Geolocalización de Chóferes

Devuelve la última posición GPS registrada del chófer durante el reparto, filtrada por número de pedido, nombre o usuario del chófer. Está pensada para consulta puntual del estado, no para tracking continuo.

El endpoint exacto no se publica en la documentación pública — solicítalo a un técnico de Polpoo. Requiere un usuario con rol técnico para generar el token.

Parámetros de petición

Ejemplo petición

{
  "orderNumber": "12345678",
  "name": "Vic",
  "userName": "vicenc.sierra@polpoo.com"
}

Campos devueltos

El chófer debe estar activo y en reparto para que exista posición. Si no, la respuesta vendrá vacía.

SFTP · Envío de Rutas

Fichero: delivery_points.json en la raíz del SFTP de la compañía (./company_X/).

Para verificar la carga: Planificador → + Rutas → Entregas planificadas.

Codificación UTF-8. Si subes un fichero con el mismo nombre, se sobrescribe. Los valores de los campos no pueden contener comillas dobles. Los campos opcionales sin valor deben omitirse (no enviar la clave en el JSON).

Ejemplo

{
  "name": "Lunes",
  "description": "Rutas del lunes",
  "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",
      "demand": 12,
      "volumetric": 0.89,
      "postalCode": "08009",
      "nif": "F62789012",
      "phoneNumber": "34666555666",
      "email": "prueba@empr.com",
      "deliveryType": "shipment",
      "orderNumber": "P-4234",
      "coordinates": { "latitude": 41.3250913, "longitude": 2.0148042 },
      "deliveryNotes": "Pedir llaves"
    }
  ]
}

Conexión SFTP (usuario, contraseña, servidor, puerto): solicítala al equipo técnico de Polpoo. La empresa debe configurar un email de soporte en Configuración > Integraciones.

SFTP · Envío de Albaranes

Fichero: albarans.json en la raíz del SFTP de la compañía (./company_X/).

En un mismo fichero deben venir todos los albaranes del día; si un cliente tiene más de un albarán, se añade como nuevo registro en el array deliveryNotes. Las rutas de los clientes deben estar previamente asignadas en Polpoo antes de cargar el fichero.

Codificación UTF-8. Si subes un fichero con el mismo nombre, se sobrescribe. Los valores de los campos no pueden contener comillas dobles. Los campos opcionales sin valor deben omitirse.

Ejemplo

{
  "deliveryPoints": [
    {
      "id": "119029",
      "deliveryNotes": [
        {
          "deliveryNoteCode": "45466770",
          "kg": 1450.5,
          "volumen": 300.6,
          "package": 2,
          "deliveryNoteObservation": "Observaciones",
          "deliveryNoteOrderCode": "2013",
          "promptPayDiscountPercent": 33,
          "isDevolution": false,
          "products": [
            {
              "code": "PX-34",
              "name": "Manzana Pink Pearl",
              "quantity": 23,
              "price": 0.67,
              "taxPercent": 21,
              "measure": "KGS",
              "lotCode": "11297090",
              "discountPercent": 20
            }
          ]
        }
      ]
    }
  ]
}

Conexión SFTP (usuario, contraseña, servidor, puerto): solicítala al equipo técnico de Polpoo. La empresa debe configurar un email de soporte en Configuración > Integraciones.

SFTP · Envío de Cobros

Fichero: bills.json en la raíz del SFTP de la compañía (./).

Polpoo no almacena el PDF de la factura — únicamente el enlace (archiveUrl) al documento que debe vivir en un servidor accesible del integrador.

Si subes un fichero con el mismo nombre, se sobrescribe. Codificación UTF-8. No incluir comillas dobles ni caracteres especiales dentro del valor de los campos.

Ejemplo

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

Conexión SFTP (usuario, contraseña, servidor, puerto): solicítala al equipo técnico de Polpoo. Cada empresa tiene un directorio propio.

SFTP · Envío de Envases

Fichero: envases.json en la raíz del SFTP.

Ejemplo

[
  {
    "id": "CL-1001",
    "products": [
      {
        "code": "ENV-001",
        "name": "Caja retornable",
        "quantity": 10,
        "import": 0
      }
    ]
  }
]

SFTP · Envío de Clientes

Fichero: clients.json.

Ejemplo mínimo

{
  "deliveryPoints": [
    {
      "id": "CL-1001",
      "name": "Cliente Demo",
      "address": "Calle Mayor 1, Sevilla",
      "serviceTime": 600,
      "demand": 0
    }
  ]
}

SFTP · Devolución de Rutas

Polpoo devuelve planificación y optimización en ficheros:

• evaluation_YYYYMMDD.json
• optimization_YYYYMMDD.json

Ejemplo devolución

{
  "routes": [
    {
      "deliveryZoneId": "RUTA-1",
      "deliveryPoints": [
        {
          "id": "CL-1001",
          "order": 1,
          "estimatedArrivalTime": 32400
        }
      ]
    }
  ]
}

SFTP · Devolución de Albaranes

Fichero: route_NombreDeLaRuta_YYYYMMDD.json en las carpetas de retorno del SFTP.

Polpoo genera el fichero al cerrar la ruta, con la firma, las cajas entregadas/devueltas, las modificaciones de líneas y las incidencias.

Campos clave de devolución

Ejemplo devolución (resumen)

[
  {
    "id": "CL-1001",
    "deliveredBoxes": 3,
    "devolutionBoxes": 1,
    "deliveryNotes": [
      {
        "deliveryNoteCode": "ALB-260407-001",
        "deliveryNoteStatus": 3,
        "signature": "data:image/jpeg;base64,..."
      }
    ]
  }
]

SFTP · Devolución de Cobros

Fichero: bill_XXXX.json (donde XXXX = código de factura) en la carpeta ./bills/ del SFTP.

Polpoo genera el fichero automáticamente cada vez que cambia el estado de cobro de una factura.

Si la factura se devuelve sin cobrar, todos los campos vienen a null excepto code.

Ejemplo devolución

{
  "code": "2261212-122024",
  "paymentDate": "2025-01-10 09:12:55",
  "paymentType": "Efectivo",
  "chargeType": "Comercial",
  "userChargedBy": "Joel Digon Martinez",
  "total": 55.9,
  "billPaymentStatusName": "Cobrado",
  "billPaymentStatusId": 2,
  "vehicle": {
    "id": 1613,
    "name": "iveco daily 2",
    "registration": "1056GKD",
    "idERP": ["2"]
  },
  "deliveryNotes": {
    "documentStore": "2",
    "documentType": "1",
    "documentSeries": "201",
    "documentExercise": "2023"
  },
  "userERP": ["5"]
}

SFTP · Devolución de Envases

Fichero: _YYYY_MM_DD_XXXX.json en la carpeta de retorno del SFTP. Polpoo lo genera al cerrar la ruta con el detalle de envases entregados/recogidos.

Excel · Carga de clientes

Plantilla para alta/actualización del maestro de clientes en Polpoo.

Excel · Envío de rutas

Plantilla para envío puntual de rutas sin pasar por el ERP.

Si usas CSV debe ir separado por ; y codificado en UTF-8.

Excel · Envío de albaranes

Plantilla para envío puntual de albaranes con sus líneas de producto.

Si usas CSV debe ir separado por ; y codificado en UTF-8.

Excel · Carga de productos

Plantilla para alta/actualización del catálogo de productos en Polpoo. Las columnas se importan tal cual están escritas en la cabecera.

Checklist de Producción

1. Validar token técnico y permisos del usuario de integración.
2. Probar envío de rutas (API o SFTP) con casos de ventana horaria y multiviaje.
3. Probar envío de albaranes con productos, con modificaciones y con firma.
4. Probar envío de facturas y consulta/devolución de cobros.
5. Probar tracking en tiempo real (event 10, 11, 1, 2).
6. Probar devolución de rutas a ERP (orden, chofer, ETA).
7. Probar envases y devoluciones si aplica logística retornable.
8. Activar alertas de errores, reintentos y trazabilidad de IDs externos.