API Documentación - Home Delivery

🚀 ZEUS COLECTA API

¿Buscas documentación de Zeus Colecta? Accede a la documentación completa de Zeus Colecta API → incluyendo webhooks, tracking y más.

⭐ ACTUALIZACIÓN v2.1 - 2026-05-28

El campo valorDeclarado ahora está disponible a nivel de envío (además de en dinamicouno). Accede directamente con envio.valorDeclarado sin necesidad de parsear JSON. Ver detalles →

Información General

Descripción del servicio

Servicio

Gestión de Planillas

Sistema completo de gestión de planillas de reparto y envíos con seguimiento en tiempo real.

Versión

API v2

Última versión disponible con soporte para múltiples proveedores y integraciones avanzadas.

Ambiente

Production

API disponible en ambiente de producción. Soporte 24/7 para integraciones.

Especificación General

Método HTTP

GET

Base URL

https://lp.logimas.co/Server.Web/dominio/envios/ENThirdPartyLogistic

URL Completa

https://lp.logimas.co/Server.Web/dominio/envios/ENThirdPartyLogistic/v2/planillas-envios

Retorna

Array JSON de Planillas con Envíos

Autenticación

Headers requeridos para todas las solicitudes

ℹ️ Nota: Todos los endpoints requieren autenticación con dos headers específicos. Asegúrate de incluirlos en cada solicitud.

Header 1

Authorization-Token

UUID del token de autenticación. Ejemplo: d5f384dd-e3cd-11ef-808a-000d3a02a8d0

Header 2

Authorization-User

ID del usuario autenticado. Ejemplo: 98D0B0

Endpoints

Listado de endpoints disponibles

Obtener Planillas de Envíos

Método

GET

Path

/v2/planillas-envios

Query Params

codigoCarrier, fecha (YYYY-MM-DD)

Ejemplo

?codigoCarrier=2A6FC2&fecha=2026-05-18

Parámetros de Entrada

Parámetros requeridos para las solicitudes

Parámetro	Tipo	Requerido	Descripción	Ejemplo
codigoCarrier	String	Sí	Código único del carrier/operador	2A6FC2
fecha	String (YYYY-MM-DD)	Sí	Fecha de la planilla a consultar	2026-05-18

✓ Ejemplo de solicitud cURL:

curl -X GET 'https://lp.logimas.co/Server.Web/dominio/envios/ENThirdPartyLogistic/v2/planillas-envios?codigoCarrier=2A6FC2&fecha=2026-05-18' \
  -H 'Authorization-Token: d5f384dd-e3cd-11ef-808a-000d3a02a8d0' \
  -H 'Authorization-User: 98D0B0'

Estructura del Response

Formato de la respuesta JSON

⚠️ Importante: El campo dinamicouno viene como STRING JSON. Debes parsearlo con JSON.parse() (JavaScript) o json.loads() (Python).

[
  {
    "idPlanillaReparto": 482549,
    "estado": "VIG",
    "codigoCarrier": "2A6FC2",
    "fechaCreacion": "2026-05-18T14:17:53",
    "envios": [
      {
        "numero": "240111000010615879",
        "numeroExterno": "3236068144",
        "estadoEnvio": "Entregado",
        "dinamicouno": "{ ... JSON stringificado ... }",
        "dinamicodos": null,
        "dinamicotres": null
      }
    ]
  }
]
            

Diccionario de Campos

Descripción detallada de todos los campos disponibles

Campos a Nivel Planilla

Campo	Tipo	Descripción
idPlanillaReparto	Integer	Identificador único de la planilla de reparto
estado	String	Estado de la planilla (VIG = Vigente)
codigoCarrier	String	Código del carrier/operador logístico
fechaCreacion	DateTime ISO	Fecha y hora de creación de la planilla

Campos a Nivel Envío (Identificación)

Campo	Tipo	Variabilidad	Descripción
numero	String	NO	Número único interno del envío
numeroExterno	String	NO	Número externo o PO del cliente
idEstadoEnvio	String	NO	ID del estado (2, 3, 4, 24)
estadoEnvio	String	NO	Nombre del estado (Entregado, En Reparto, etc)

Campos Dinámicos (dinamicouno) - Variables por Proveedor

Campo	Proveedor	Descripción
SellerId	Falabella/Ibis	ID único del vendedor
parcelNumber	Falabella/Ibis	Número de paquete para tracking (PKG...)
flujo	Marketplace/OPL	Indicador de operador logístico externo ("OPL")
partners	Marketplace/OPL	Canal de venta del partner (ej: "YAPE")
skus	Todos	Array con detalles de productos (peso, dimensiones, descripción)

Contacto (Remitente y Destinatario)

Campo	Tipo	Descripción
remitente / destinatario	String	Nombre completo de la persona o empresa
idTipoDocumento(Rem/Dest)	String	Tipo de documento (CC, CE, NI)
documento(Rem/Dest)	String	Número del documento de identificación
telefono(Rem/Dest)	String	Teléfono de contacto
direccion(Rem/Dest)	String	Dirección física completa
email(Rem/Dest)	String	Correo electrónico de contacto

Ejemplos Completos

Ejemplos reales de respuestas por proveedor

Ejemplo 1: Falabella/Ibis

Este ejemplo muestra un envío de Falabella con información de vendedor, paquete y productos.

{
  "idPlanillaReparto": 482549,
  "estado": "VIG",
  "codigoCarrier": "2A6FC2",
  "fechaCreacion": "2026-05-18T14:17:53",
  "envios": [
    {
      "numero": "240111000010615879",
      "numeroExterno": "3236068144",
      "estadoEnvio": "Entregado",
      "idPoblacionDestino": "150205",
      "nombrePoblacionDestino": "SUPE PUERTO",
      "destinatario": "Farid Taboada Diaz",
      "direccionDest": "Centro Poblado Los Molinos Mz R Lt2",
      "telefonoDest": "972807712",
      "dinamicouno": {
        "SellerId": "SC2C989",
        "parcelNumber": "PKG00000HNVP5",
        "parcelId": "3f5658e2-10e5-4cb5-93fa-ff46565d07b9",
        "skus": [
          {
            "skuDesc": "Audifonos Inalambricos Buds 2 Pro Negro",
            "weight": "0.25",
            "width": "10",
            "height": "5",
            "length": "10"
          }
        ],
        "Valor": 200,
        "valorDeclarado": 200,
        "promesaEntrega": "2026-05-21"
      }
    }
  ]
}
            

Ejemplo 2: Marketplace/OPL

Este ejemplo muestra un envío de Marketplace procesado por un operador logístico externo (OPL).

{
  "idPlanillaReparto": 482549,
  "estado": "VIG",
  "codigoCarrier": "2A6FC2",
  "fechaCreacion": "2026-05-18T14:17:53",
  "envios": [
    {
      "numero": "MKP163233135976901",
      "numeroExterno": "MKP-1632331359769-01",
      "estadoEnvio": "En Reparto",
      "idPoblacionDestino": "250107",
      "nombrePoblacionDestino": "MANANTAY",
      "destinatario": "Lizbet Milagros Paredes",
      "direccionDest": "Jiron Los Mangos 79819",
      "dinamicouno": {
        "flujo": "OPL",
        "partners": "YAPE",
        "Canalventa": "YAPE",
        "skus": [
          {
            "skuDesc": "XIAOMI REDMI 15C 256GB AZUL",
            "weight": "0.25",
            "width": "10.00",
            "height": "10.00",
            "length": "20.00",
            "valorDeclarado": "526.00"
          }
        ],
        "numeroPedido": "MKP-1632331359769-01",
        "fechaCargaOpl": "2026-05-15 17:32:13",
        "promesaEntrega": "2026-05-21"
      }
    }
  ]
}
            

Guía de Integración

Pasos para implementar correctamente la integración

ℹ️ Importante: Sigue estos pasos en orden para una integración exitosa. Cada paso es crítico para el funcionamiento correcto.

Paso 1: Parsear dinamicouno

El campo viene como STRING JSON. Debes convertirlo a objeto:

JavaScript:

const dinamicouno_obj = JSON.parse(envio.dinamicouno);

Python:

import json
dinamicouno_obj = json.loads(envio["dinamicouno"])
                

Paso 2: Detectar el Tipo de Proveedor

Inspecciona el objeto parseado para determinar de qué proveedor es el envío:

if (dinamicouno_obj.flujo === "OPL") {
  // Marketplace / OPL
  console.log("Proveedor: Marketplace/OPL");
  const canal = dinamicouno_obj.partners; // ej: "YAPE"
} else if (dinamicouno_obj.SellerId) {
  // Falabella / Ibis
  console.log("Proveedor: Falabella/Ibis");
  const sellerId = dinamicouno_obj.SellerId;
}
                

Paso 3: Procesar Array SKU

Extrae detalles de cada producto en el array skus:

const skus = dinamicouno_obj.skus || [];
skus.forEach((sku) => {
  const detalles = {
    descripcion: sku.skuDesc,
    peso: parseFloat(sku.weight),
    ancho: parseFloat(sku.width),
    alto: parseFloat(sku.height),
    largo: parseFloat(sku.length)
  };
  // Procesar detalles...
});
                

Paso 4: Normalizar Datos

Atiende casos especiales y normaliza los datos:

codigoProducto puede ser string "None" → convertir a null
Coordenadas pueden ser string "null" → convertir a null
Pesos en OPL siempre son 0 → usar peso de SKU
Dimensiones en envío son 0 → usar dimensiones de SKU

Paso 5: Manejo de Errores

Implementa validaciones para casos especiales:

try {
  const dinamicouno_obj = JSON.parse(envio.dinamicouno);

  if (!dinamicouno_obj) {
    console.error("dinamicouno es null");
    return;
  }

  const skus = dinamicouno_obj.skus || [];
  if (skus.length === 0) {
    console.warn("Sin SKUs en este envío");
  }

} catch (error) {
  console.error("Error parseando dinamicouno:", error);
}
                

Códigos de Estado

Estados HTTP y estados de envío

Códigos HTTP

Código	Estado	Descripción
200	OK	Datos obtenidos exitosamente
400	Bad Request	Parámetros inválidos (codigoCarrier o fecha incorrectos)
401	Unauthorized	Token o usuario de autenticación inválido
403	Forbidden	Sin permisos para acceder a estos datos
404	Not Found	Planilla no existe para los parámetros proporcionados
500	Server Error	Error interno del servidor

Estados de Envío (idEstadoEnvio)

ID	Estado	Descripción
2	En Reparto	Envío en proceso de entrega
3	Entregado	Recibido por el destinatario
4	Excepción	Problema durante la entrega
24	Listo para Retirar	Disponible en punto de retiro

Tipos de Documento

Código	Tipo	Descripción
CC	Cédula	Cédula de Ciudadanía
CE	Extranjería	Cédula de Extranjería
NI	Identificación	NIT/RUC (Identificación Empresarial)

Checklist de Validación

Verificaciones antes de liberar a producción

✓ Parsear dinamicouno correctamente en todas las plataformas
✓ Implementar lógica de detección de proveedor
✓ Validar presencia de campos obligatorios
✓ Procesar correctamente arrays SKU
✓ Normalizar pesos y dimensiones desde SKU
✓ Manejar correctamente campos null y "None"
✓ Implementar manejo robusto de errores
✓ Probar con muestras reales de ambos proveedores

Soporte

Recursos adicionales

Documentación

Especificación Completa

Consulta el documento de integración completo con todas las tablas maestras y ejemplos detallados.

Contacto

Equipo de Integración

Si tienes preguntas o necesitas ayuda, contacta a nuestro equipo de soporte técnico.

Status

API Status

Monitorea el estado de la API y recibe notificaciones de mantenimiento programado.

Planillas de Envíos API v2