API · v1.0.0 REST JSON

API de Integraciones Aliclik

Documentación oficial para conectar plataformas de terceros con Aliclik. Aquí encontrarás el proceso de alta como integrador, el modelo de autenticación y la referencia completa del módulo de integración para las dos modalidades de pedido: Contraentrega y Por Agencia (Shalom).

Base URL

https://api.aliclik-dev.com

Auth

Bearer Token

Zona horaria

America/Lima (UTC−05:00)

¿Qué modalidad de pedido vas a integrar?

Pedidos Contraentrega

Entrega a domicilio con pago contra entrega. Cotizas el envío con coordenadas, eliges courier y creas el pedido.

POST /integration/order

NUEVO

Pedidos por Agencia (Shalom)

El cliente recoge su pedido en una agencia Shalom. Eliges agencia destino desde el directorio y programas el despacho.

POST /integration/order/agency

Endpoint compartido: ambas modalidades usan el mismo catálogo público (GET /integration/product/public). La única diferencia es el filtro isAgency=true, que restringe el catálogo a almacenes habilitados para envíos por agencia y agrega campos extra por SKU.

01 · Primeros pasos

Introducción

Antes de integrarte, es clave entender el flujo de alta, cómo autenticar tus peticiones y las convenciones que siguen todos los endpoints.

Resumen

La API cubre el módulo de integración de Aliclik en dos modalidades de pedido:

Catálogo compartido: consultar el catálogo público con stock virtual por almacén (con filtro isAgency según modalidad).
Contraentrega: calcular costo de envío y couriers, crear, listar y cancelar pedidos con entrega a domicilio.
Por Agencia (Shalom): consultar el directorio de agencias y tamaños de paquete, crear, listar y anular pedidos con recojo en agencia.

Alta como integrador

Si deseas integrarte con Aliclik, sigue este proceso antes de solicitar tus credenciales de API.

1 Envía un correo con copia (CC)

Destinatarios obligatorios:

Dirección: direccion@aliclik.app
Comercial: comercial@aliclik.app
Operaciones: operaciones@aliclik.app
Sistemas: sistemas@aliclik.app
Jayl Monsalve: jayl.monsalve@aliclik.app

2 Asunto del correo

Solicitud de integración – [Nombre de empresa]

3 Contenido obligatorio del correo

Web y redes sociales de la empresa.
Breve descripción de la empresa.
Servicio que ofrece.
Motivo de integración con Aliclik.
Qué desea integrar o intercambiar (catálogo, pedidos, costos, etc.).
Nombre y teléfono de contacto.

Importante: Solo se evaluarán solicitudes enviadas por este medio. Por correo se enviará más detalle de la integración.

Autenticación

Todos los endpoints están protegidos y requieren un Bearer Token entregado por el equipo de Aliclik.

Cabeceras requeridas (http)

Authorization: Bearer <TU_TOKEN_DE_INTEGRACION>
Content-Type: application/json
x-aliclik-origin: aliclik-web

Respuesta de error 401 (json)

{
  "statusCode": 401,
  "message": "Token de autorización requerido"
}

Código	Mensaje	Causa
401	Token de autorización requerido	No se envió la cabecera Authorization.
401	Token inválido	El token está mal formado, expirado o no pertenece a la integración.

Convenciones generales

Formato de fechas	ISO 8601 (YYYY-MM-DD o YYYY-MM-DDTHH:mm:ssZ)
Zona horaria	America/Lima (UTC−05:00)
Coordenadas	lat y lng como string decimal (ej. -12.04318)
Moneda y país	Se infieren del token (no se envían en el body)
Paginación	page (desde 1) y limit (máx. 100)

02 · Catálogo (compartido)

Este es el único endpoint común a ambas modalidades. El catálogo que consumes es el mismo; el query param isAgency define para qué modalidad lo estás consultando: sin él (o en false) obtienes el catálogo para contraentrega, y con isAgency=true obtienes solo productos despachables por agencia Shalom, con campos adicionales por SKU.

GET /integration/product/public

Listar productos públicos

Devuelve el catálogo público disponible para tu integración, con stock virtual por almacén, paginado y ordenado por ID descendente. El ean de cada SKU es el identificador que usarás en products[].ean al crear pedidos en cualquiera de las dos modalidades. Auth: Bearer Token

Para pedidos por agencia usa siempre isAgency=true: filtra solo SKUs con stock (stockVirtual > 0) en almacenes activos y habilitados para envíos Shalom, y agrega a cada SKU los campos formatTimeAgency (hora de corte del almacén) y shalomOriginIn (agencia Shalom de origen configurada).

Query parameters

Campo	Tipo	Requerido	Descripción
page	number	—	Página solicitada. Default 1; valores menores a 1 se normalizan a 1.
limit	number	—	Registros por página. Default 15, máx 100 (valores mayores se recortan a 100).
search	string	—	Búsqueda parcial por nombre de producto.
categoryId	number	—	Filtra por categoría.
isAgency	boolean	—	`true` restringe el catálogo a almacenes habilitados para envíos Shalom con stock y añade `formatTimeAgency` / `shalomOriginIn` por SKU. Úsalo para el flujo de pedidos por agencia.

Ejemplo de request — contraentrega (http)

GET /integration/product/public?page=1&limit=15&search=laptop
Authorization: Bearer <TU_TOKEN>

Ejemplo de request — pedidos por agencia (http)

GET /integration/product/public?page=1&limit=15&isAgency=true
Authorization: Bearer <TU_TOKEN>

Respuesta 200 OK (json)

{
  "count": 42,
  "page": 1,
  "result": [
    {
      "id": 101,
      "name": "Laptop Acme 14\"",
      "shortDescription": "Laptop ligera para oficina",
      "urlImage": "https://cdn.aliclik.app/products/101.png",
      "category": "Tecnología",
      "skus": [
        {
          "sku": "LAP-ACME-14",
          "ean": "1480110110503",
          "name": "Modelo A",
          "regularPrice": 1499.9,
          "stockVirtual": 12,
          "dropPrice": 12,
          "warehouseId": 210,
          "warehouseName": "Almacén Lima Centro",
          "formatTimeAgency": "13:00",
          "shalomOriginIn": "CHOSICA"
        }
      ]
    }
  ]
}

Notas:
- stockVirtual es el stock disponible para reserva, no el stock físico real.
- El ean devuelto aquí es el que debes usar en products[].ean al crear un pedido (contraentrega o por agencia).
- formatTimeAgency y shalomOriginIn solo se incluyen cuando consultas con isAgency=true; en caso contrario llegan como null o no aplican.

03 · Pedidos Contraentrega

Modalidad de entrega a domicilio con pago contra entrega. El ciclo completo: cotizar el envío con coordenadas del destino, crear el pedido con el courier elegido, hacer seguimiento y cancelar si aplica.

GET /integration/order/shipping/cost

Calcular costo de envío y couriers

Devuelve las transportadoras habilitadas para un almacén y un destino, con el costo de entrega, costo de devolución, días adicionales y horario de corte. Internamente evalúa tarifas premium / VIP si tu integración las tiene habilitadas.
Auth: Bearer Token

Query parameters

Campo	Tipo	Req	Descripción
warehouseId	number	Sí	Id del almacén desde el que se despacha.
lat	string	Sí	Latitud del destino (ej. "-12.04318").
lng	string	Sí	Longitud del destino (ej. "-77.02824").

Lógica de selección de tarifas

Resuelve el ubigeo desde lat y lng.
Obtiene las transportadoras privadas habilitadas para tu empresa + las públicas del país.
Elige la cobertura del nivel más profundo disponible (distrito > provincia > departamento).
Si tu empresa tiene cobertura premium:
- - Premium + VIP → usa deliveryCostVip y returnCostVip.
- - Premium sin VIP → usa deliveryCostPremium y returnCostPremium.
Caso contrario → tarifa estándar del cuadro de cobertura.

Ejemplo de request (http)

GET /integration/order/shipping/cost?warehouseId=123&lat=-12.04318&lng=-77.02824
Authorization: Bearer <TU_TOKEN>

Respuesta 200 OK (json)

{
  "ubigeo": {
    "department": { "name": "Lima" },
    "province":   { "name": "Lima" },
    "district":   { "name": "Miraflores" }
  },
  "couriers": [
    {
      "id": 87,
      "addDays": 1,
      "deliveryCost": 12.5,
      "returnCost": 5,
      "transportId": 4,
      "transportName": "Olva Courier",
      "transportUrlImage": "https://cdn.aliclik.app/transporters/olva.png",
      "flagDeliveryExpress": false,
      "schedule": "16:30",
      "scheduleExpressStart": null,
      "scheduleExpressEnd": null
    },
    {
      "id": 88,
      "addDays": 0,
      "deliveryCost": 18,
      "returnCost": 6,
      "transportId": 15,
      "transportName": "Aliclik Express",
      "transportUrlImage": "https://cdn.aliclik.app/transporters/aliclik-express.png",
      "flagDeliveryExpress": true,
      "schedule": null,
      "scheduleExpressStart": "00:00",
      "scheduleExpressEnd": "11:30"
    }
  ]
}

Tip de integración: El objeto couriers[i] está pensado para usarse directamente como bloque courier del endpoint Crear pedido.

Sin cobertura: Si el almacén no tiene cobertura para el ubigeo destino, la API responde con couriers: [] y un mensaje informativo.

Errores comunes

Código	Mensaje	Causa
400	warehouseId es requerido	Falta el query param.
400	lat y lng son requeridos	Faltan coordenadas.
400	No se pudo resolver el ubigeo...	Coordenadas fuera de territorio.
400	Ubigeo inválido	El ubigeo resuelto no existe.
401	Token inválido	Bearer Token incorrecto.

POST /integration/order

Crear pedido

Crea un pedido a nombre de tu integración. Aliclik resuelve automáticamente el ubigeo a partir de las coordenadas y genera el orderNumber con el prefijo de tu integración. Auth: Bearer Token

Request body (json)

{
  "note": "información adicional del pedido",
  "channel": "WEB",
  "delivery": 14.5,
  "customer": {
    "name": "Gastom",
    "lastName": "Pérez",
    "phone": "51918993266",
    "email": "cliente@gmail.com",
    "address": "Mz Z lote 12 - Piura"
  },
  "shipping": {
    "address1": "Mz Z lote 12 - Piura",
    "address2": "",
    "lat": "-5.18539",
    "lng": "-80.6450045",
    "reference": "Frente al parque"
  },
  "products": [
    {
      "ean": "1480110110503",
      "quantity": 1,
      "price": 10
    }
  ],
  "courier": {
    "addDays": 0,
    "deliveryCost": 14.5,
    "schedule": null,
    "scheduleExpressStart": "00:00",
    "scheduleExpressEnd": "11:30",
    "returnCost": 6,
    "transportId": 15,
    "flagDeliveryExpress": true
  }
}

Respuesta 201 Created (json)

{
  "message": "Orden creada correctamente",
  "orderNumber": "ALC000123456789"
}

Esquema del body (COMPLETO)

Campo	Tipo	Req	Descripción
note	string	—	Nota libre asociada al pedido.
channel	string	—	Canal de origen (ej. WEB, WHATSAPP).
delivery	number	Sí	Costo total de envío cobrado al cliente.
customer.name	string	Sí	Nombre del cliente.
customer.lastName	string	—	Apellido del cliente.
customer.phone	string	Sí	Teléfono con código de país (sin +).
customer.email	string	—	Correo del cliente.
customer.address	string	—	Dirección textual del cliente.
shipping.address1	string	Sí	Dirección principal de envío.
shipping.address2	string	—	Dirección complementaria.
shipping.lat	string	Sí	Latitud del destino.
shipping.lng	string	Sí	Longitud del destino.
shipping.reference	string	—	Referencia visual del lugar.
products[].ean	string	Sí	EAN del producto (*).
products[].quantity	number	Sí	Cantidad solicitada.
products[].price	number	Sí	Precio unitario del producto.
courier.transportId	number	Sí	Id de la transportadora (ver endpoint Calcular envío).
courier.deliveryCost	number	Sí	Costo de entrega devuelto por Calcular envío.
courier.returnCost	number	Sí	Costo de devolución devuelto por Calcular envío.
courier.addDays	number	Sí	Días adicionales devueltos por Calcular envío.
courier.schedule	string \| null	—	Hora de corte (HH:mm) para courier estándar.
courier.scheduleExpressStart	string \| null	—	Inicio de ventana express (HH:mm).
courier.scheduleExpressEnd	string \| null	—	Fin de ventana express (HH:mm).
courier.flagDeliveryExpress	boolean	Sí	true si es entrega express, false si es estándar.

(*) Se requiere al menos uno entre ean o sku por producto.

Reglas de negocio

Ubigeo: Aliclik resuelve department, province y district. Si caen fuera, responde 400.
Cliente: Si el teléfono existe para tu empresa, se actualiza (upsert). Si no, se crea.
Courier express: Si flagDeliveryExpress = true, la hora local de Lima debe estar dentro de [scheduleExpressStart, scheduleExpressEnd].
Courier estándar: La fecha de despacho se calcula contra schedule. Si cae en domingo, se desplaza al lunes.
orderNumber: Lo genera Aliclik. No lo envíes en el request.
Catálogo: El ean debe existir previamente en el catálogo de Aliclik. Si no, se rechaza.
Almacén único: Todos los productos del pedido deben pertenecer al mismo almacén. Múltiples almacenes crean pedidos independientes.
Precio: products[].price es definido por tu plataforma externa; Aliclik no lo sobreescribe.

Errores comunes COMPLETOS

Código	Mensaje	Causa
400	lat y lng son requeridos	Faltan coordenadas.
400	No se pudo resolver ubigeo...	Coordenadas fuera del territorio cubierto.
400	customer.phone es requerido	Teléfono vacío.
400	courier es requerido	No se envió el bloque courier.
400	courier express no disponible para agendar pedidos hoy	Hora actual fuera de la ventana express.
400	El número de pedido ... ya existe.	Colisión interna del orderNumber.
401	Token inválido	Bearer Token incorrecto.

GET /integration/order

Listar pedidos

Devuelve los pedidos de tu integración con filtros y paginación. Auth: Bearer Token

Query parameters

Campo	Tipo	Req	Descripción
page	int ≥ 1	—	Número de página. Default 1.
limit	int 1-100	—	Registros por página. Default 20.
orderNumber	string	—	Búsqueda parcial (contains).
callStatus	enum	—	Filtro por estado de llamada.
status	enum	—	Filtro por estado de entrega.
dispatchStatus	enum	—	Filtro por estado de despacho.
startDate	YYYY-MM-DD	—	Fecha inicial de creación.
endDate	YYYY-MM-DD	—	Fecha final de creación.

callStatus

CONFIRMED
FOLLOW
CALL_LATER
ANNULLED
NOT_RESPOND
DUPLICATE
OUT_OF_STOCK
NO_COVERAGE
FAKE
TESTING
CONTACTED
IMPORTED

status

PENDING_DELIVERY
DELIVERED
RESCHEDULED
REFUSED
NOT_RESPOND
CANCEL
ANNULLED

dispatchStatus

TO_PREPARE
PREPARED
PICKED
TO_RETURN
RETURNED
IN_TRANSIT
IN_AGENCY
LEFT_IN_WAREHOUSE
STORE_CENTRAL
REMAINING_IN_TRANSIT

Ejemplo de request (http)

GET /integration/order?page=1&limit=20&status=PENDING_DELIVERY&startDate=2026-04-01&endDate=2026-04-30
Authorization: Bearer <TU_TOKEN>

Respuesta 200 OK COMPLETADA (json)

{
  "data": [
    {
      "orderNumber": "ALC000123456789",
      "total": 45.5,
      "callStatus": "CONFIRMED",
      "status": "PENDING_DELIVERY",
      "dispatchStatus": "TO_PREPARE",
      "channel": "WEB",
      "productDetail": "Producto X x1",
      "note": "Llamar antes de enviar",
      "createdAt": "2026-04-22T15:30:12.000Z",
      "updatedAt": "2026-04-22T15:31:00.000Z",
      "customer": {
        "name": "Gastom",
        "lastName": "Pérez",
        "phone": "51918993266",
        "email": "cliente@gmail.com"
      },
      "shipping": {
        "address1": "Mz Z lote 12 - Piura",
        "address2": "",
        "reference": "Frente al parque",
        "lat": "-5.18539",
        "lng": "-80.6450045",
        "departmentName": "Piura",
        "provinceName": "Piura",
        "districtName": "Piura"
      },
      "products": [
        { "skuId": 12345, "quantity": 1, "price": 10, "subtotal": 10 }
      ]
    }
  ],
  "pagination": {
    "total": 134,
    "page": 1,
    "limit": 20,
    "totalPages": 7
  }
}

POST /integration/order/cancel

Cancelar pedido

Cancela un pedido de tu integración. La cancelación tiene reglas estrictas según el estado del pedido en Aliclik. Auth: Bearer Token

Request body (json)

{
  "orderNumber": "ALC000123456789"
}

Respuesta 201 Created (json)

{
  "message": "Pedido cancelado correctamente."
}

Reglas de cancelación

Para que un pedido pueda cancelarse deben cumplirse todas estas condiciones:

Campo	Tipo	Requerido	Descripción
orderNumber	string	Sí	Número de pedido devuelto al crearlo.
callStatus	CONFIRMED	Sí	El pedido debe estar confirmado.
status	PENDING_DELIVERY	Sí	El estado de entrega no debe estar finalizado.
dispatchStatus	TO_PREPARE \| PREPARED \| IN_TRANSIT	Sí	El despacho no debe estar en agencia.
isOrderAgency	false	Sí	El pedido no puede ser recogido en agencia.

Pedido aún no confirmado: Si callStatus ≠ CONFIRMED, no se cancela de inmediato: se agrega la nota Cancelar pedido. al pedido y la API responde:
{ "message": "Pedido no confirmado." }.

Errores comunes COMPLETOS

Código	Mensaje	Causa
400	No se puede cancelar un pedido de agencia.	isOrderAgency = true — usa Cancelar pedido por agencia.
400	Pedido esta con estado de entrega Entregado	El pedido ya fue entregado / rechazado / anulado.
400	Pedido ya está en camino a entregar.	dispatchStatus = PICKED o IN_AGENCY.
400	Pedido está retornando al almacén.	dispatchStatus en TO_RETURN, STORE_CENTRAL, REMAINING_IN_TRANSIT.
400	Pedido retornado a almacén.	dispatchStatus en LEFT_IN_WAREHOUSE, RETURNED.
404	Pedido {orderNumber} no encontrado.	El número no existe o no pertenece a tu empresa.
401	Token inválido	Bearer Token incorrecto.

04 · Pedidos por Agencia (Shalom) NUEVO

Modalidad donde el cliente recoge su pedido en una agencia Shalom. En lugar de cotizar envío con coordenadas, eliges una agencia destino desde el directorio y programas la fecha de despacho. El catálogo se consulta con el mismo endpoint compartido, pero siempre con isAgency=true (ver Catálogo).

Novedades 2026-09-24 — Tipo de gestión (managementType)

Crear pedido: nuevo campo opcional managementType (1 = PROPIA, 0 = DROPSHALOM, default 0). Con 1 no se valida ni se reserva stock. Las integraciones que no envíen el campo mantienen el comportamiento anterior.
Cancelar pedido: ahora también anula pedidos de gestión propia (OWN). Antes respondía Pedido no es de tipo de gestión PARTNER. En pedidos OWN la anulación no libera stock.
Listar pedidos: nuevo filtro opcional managementType (1 OWN, 0 PARTNER, vacío = todos) y cada pedido incluye ahora el campo managementType (OWN / PARTNER).

Ver detalle en Tipo de gestión.

GET /integration/order/agencies

Listar agencias Shalom (directorio)

Devuelve el directorio público de agencias Shalom para poblar el selector de agencia destino. La respuesta se sirve desde un cache en memoria del servidor; si el origen Shalom falla, se sirve el último cache disponible (stale). Solo si el origen falla y no existe cache se responde 502. Auth: Bearer Token

Ejemplo de request (http)

GET /integration/order/agencies
Authorization: Bearer <TU_TOKEN>

Respuesta 200 OK (json)

[
  {
    "id": 152,
    "name": "CHOSICA",
    "address": "Av. Lima Sur 123",
    "department": "LIMA",
    "province": "LIMA",
    "district": "LURIGANCHO"
  }
]

Esquema de la respuesta

Campo	Tipo	Descripción
id	number \| string \| null	ID de la agencia en Shalom. Úsalo como `shipping.shalomAgencyId` al crear el pedido (convertido a string).
name	string \| null	Nombre de la agencia. Úsalo como `shipping.shalomAgency`.
address	string \| null	Dirección de la agencia.
department	string \| null	Departamento (ej. LIMA).
province	string \| null	Provincia.
district	string \| null	Distrito.

Errores comunes

Código	Cuándo
401	Bearer Token inválido o ausente.
502	El origen Shalom no respondió y no hay cache disponible. Reintentar más tarde.

GET /integration/order/package-sizes

Listar tamaños de paquete

Devuelve el catálogo de tamaños de paquete disponibles, ordenado por ID ascendente. Útil para poblar un selector en el formulario de creación del pedido. No recibe parámetros. Auth: Bearer Token

Ejemplo de request (http)

GET /integration/order/package-sizes
Authorization: Bearer <TU_TOKEN>

Respuesta 200 OK (json)

[
  { "title": "PAQUETE XXS" },
  { "title": "PAQUETE XS" },
  { "title": "PAQUETE S" }
]

Errores comunes

Código	Cuándo
401	Bearer Token inválido o ausente.

POST /integration/order/agency

Crear pedido por agencia

Crea un pedido con entrega en agencia Shalom (isOrderAgency=true). El tipo de gestión se define con el campo opcional managementType: 1 PROPIA (OWN) o 0 DROPSHALOM (PARTNER, default). El almacén de origen se resuelve automáticamente a partir de los EANs de los productos; tu plataforma no lo envía. Auth: Bearer Token

Tipo de gestión — managementType

Valor API	Nombre	Valor persistido	Stock
0	DROPSHALOM	PARTNER	Se valida stock virtual disponible por EAN y se reserva al crear el pedido. Al anular se libera la reserva.
1	PROPIA	OWN	No se valida ni se reserva stock. Al anular no se genera ningún movimiento de stock.

Si el campo no se envía, o llega vacío, se asume 0 (DROPSHALOM).
Se acepta como número (1) o como string numérico ("1").
Cualquier otro valor devuelve 400 con el mensaje managementType debe ser 1 (PROPIA) o 0 (DROPSHALOM).
En ambos tipos de gestión el almacén se resuelve igual a partir de los EANs, porque se necesita para la hora de corte (scheduleDate) y para la agencia Shalom de origen.

Reglas de negocio aplicadas por el servidor:

Todos los campos de customer son obligatorios. En shipping todos son obligatorios excepto reference.
shalomAgencyId y shalomAgency se obtienen del directorio de agencias (campos id y name).
Todos los EANs deben pertenecer al mismo almacén. No se permiten EANs duplicados en el mismo pedido (consolida las cantidades en una sola línea).
Máximo 6 unidades por producto y 6 unidades en total por pedido.
Con managementType=0 cada EAN debe tener stock virtual suficiente. Con managementType=1 no se revisa stock.
El almacén debe estar activo y habilitado para envíos Shalom (isDropShalom), y tener configurada la agencia Shalom de origen.
shipping.scheduleDate se valida contra la hora de corte del almacén (formatTimeAgency del catálogo): antes del corte el despacho puede ser el mismo día; después del corte pasa al día siguiente. Si la fecha resultante cae domingo, se mueve al lunes. Si la fecha enviada es anterior a la mínima permitida, el servidor la ajusta automáticamente (no falla).
La agencia Shalom de origen se resuelve desde la configuración del almacén contra el directorio de agencias; si no está configurada o no se encuentra, responde 400.
El pedido se crea con callStatus=CONFIRMED, status=PENDING_DELIVERY y trackingStatus=TO_PREPARE.

Request body — gestión DROPSHALOM, valida y reserva stock (json)

{
  "managementType": 0,
  "note": "Pedido de prueba integración",
  "paymentType": "P",
  "customer": {
    "firstName": "Juan",
    "firstLastName": "Pérez",
    "secondLastName": "García",
    "senderPhone": "51990747043",
    "senderDocumentType": "DNI",
    "senderContact": "75059752"
  },
  "shipping": {
    "agencyName": "SHALOM",
    "agencyAddress": "AV. TUPAC AMARU 1105, REFERENCIA: AL COSTADO DEL PARADERO AL CUMBE",
    "reference": "Recoger en agencia",
    "keyCode": "1628",
    "merchandiseShalom": "PAQUETE XXS",
    "scheduleDate": "2026-07-17",
    "shalomAgency": "CAJAMARCA / HUALGAYOC / BAMBAMARCA / BAMBAMARCA",
    "shalomAgencyId": "2"
  },
  "products": [
    { "ean": "1400010310998", "quantity": 2, "price": 60 }
  ]
}

Request body — gestión PROPIA, no considera stock (json)

Mismo body con "managementType": 1. Si el EAN no tiene stock virtual disponible el pedido igual se crea y no se registra reserva ni movimiento de kardex.

{
  "managementType": 1,
  "note": "Pedido gestión propia",
  "paymentType": "P",
  "customer": { "...": "..." },
  "shipping": { "...": "..." },
  "products": [
    { "ean": "1400010310998", "quantity": 2, "price": 60 }
  ]
}

Respuesta 201 Created (json)

{
  "message": "Orden por agencia creada correctamente",
  "orderNumber": "ALC730123456789"
}

orderNumber se genera en el servidor (código de empresa + 12 dígitos). Guárdalo: es la clave para consultar y cancelar el pedido.

Esquema del body — nivel raíz

Campo	Tipo	Req	Descripción
managementType	number \| string numérico	—	`1` = PROPIA (OWN), `0` = DROPSHALOM (PARTNER). Default `0`. Ver Tipo de gestión.
note	string	—	Información adicional del pedido.
paymentType	string	—	Tipo de pago del pedido (P: Parcial / C: Completo).
customer	object	Sí	Datos de quien recoge en agencia. Todos sus campos son requeridos.
shipping	object	Sí	Datos de la agencia destino. Todos sus campos son requeridos excepto `reference`.
products	array	Sí	Mínimo 1 item.

Esquema del body — customer

Campo	Tipo	Req	Descripción
customer.firstName	string	Sí	Nombre de quien recoge en la agencia.
customer.firstLastName	string	Sí	Apellido paterno.
customer.secondLastName	string	Sí	Apellido materno.
customer.senderPhone	string	Sí	Teléfono del remitente con código de país, sin + (ej. 51918993266).
customer.senderDocumentType	string	Sí	Tipo de documento del remitente (ej. DNI).
customer.senderContact	string	Sí	Número de documento del contacto que recoge en la agencia (debe ser válido, ej. 75059752).

Esquema del body — shipping

Campo	Tipo	Req	Descripción
shipping.agencyName	string	Sí	SHALOM
shipping.agencyAddress	string	Sí	Dirección de la agencia destino.
shipping.reference	string	—	Referencia libre (ej. Recoger en agencia).
shipping.keyCode	string	Sí	Clave de recojo del envío.
shipping.merchandiseShalom	string	Sí	Tipo de mercadería Shalom (ej. PAQUETE XXS).
shipping.scheduleDate	string YYYY-MM-DD	Sí	Fecha programada de envío. Formato estricto; el servidor puede ajustarla según hora de corte y domingos.
shipping.shalomAgency	string	Sí	`name` de la agencia elegida del directorio (ej. CAJAMARCA / HUALGAYOC / BAMBAMARCA / BAMBAMARCA).
shipping.shalomAgencyId	string \| number	Sí	`id` de la agencia elegida del directorio. Debe ser un entero positivo (ej. "152").

Esquema del body — products[]

Campo	Tipo	Req	Descripción
products[].ean	string	Sí	EAN del SKU (del catálogo con `isAgency=true`). Todos los EANs deben ser del mismo almacén y no pueden repetirse en el pedido.
products[].quantity	int > 0	Sí	Cantidad. Máximo 6 por producto y 6 en total por pedido.
products[].price	number ≥ 0	Sí	Precio unitario definido por tu plataforma.

Errores comunes (400 — el detalle llega en message)

Mensaje	Causa
managementType debe ser 1 (PROPIA) o 0 (DROPSHALOM)	Valor fuera de `0`/`1`.
customer es requerido / shipping es requerido	Objeto ausente o con formato inválido.
products es requerido y debe tener al menos un item	Array vacío o ausente.
customer.<campo>, shipping.<campo> ... es requerido / son requeridos	Campos requeridos vacíos; el mensaje lista todos los faltantes.
shipping.scheduleDate debe tener formato YYYY-MM-DD	Formato de fecha inválido.
shipping.shalomAgencyId debe ser un entero positivo	ID de agencia inválido.
products[i].ean es requerido / quantity debe ser un entero mayor a 0 / price debe ser un número mayor o igual a 0	Item de producto inválido (incluye el índice).
Uno o más SKUs/EANs no existen en el almacén.	EAN no encontrado en los catálogos de la empresa.
Todos los productos deben pertenecer al mismo warehouse.	EANs de almacenes distintos.
Excede la cantidad de productos por pedido.	Más de 6 unidades (por producto o en total).
No hay stock disponible	Solo con `managementType=0`: stock virtual insuficiente.
El almacén <nombre> no está activo	Almacén resuelto por EAN inactivo.
El almacén <nombre> no está habilitado para envíos por agencia Shalom	Almacén sin habilitación Shalom.
El almacén <nombre> no tiene configurada la agencia Shalom de origen	Configuración faltante en el almacén.
No se encontró en el directorio la agencia de origen ...	La agencia de origen configurada no existe en el directorio.

También puede responder 401 por token inválido o ausente.

GET /integration/order/agency

Listar pedidos por agencia

Devuelve los pedidos por agencia de tu integración, ordenados del más reciente al más antiguo, con filtros por estado de llamada, estado de tracking, tipo de gestión, número de pedido, rango de fechas y paginación. Auth: Bearer Token

Query parameters

Campo	Tipo	Req	Descripción
page	int ≥ 1	—	Número de página. Default 1.
limit	int 1-100	—	Registros por página. Default 20, máx 100.
orderNumber	string	—	Búsqueda parcial (contains) por número de pedido.
callStatus	enum	—	Filtro por estado de llamada.
trackingStatus	enum	—	Filtro por estado de tracking en agencia.
managementType	number	—	`1` = PROPIA (OWN), `0` = DROPSHALOM (PARTNER). Vacío o ausente devuelve todos. Otro valor responde 400.
startDate	YYYY-MM-DD	—	Fecha inicial de creación.
endDate	YYYY-MM-DD	—	Fecha final de creación.

callStatus — Estado de llamada
CONFIRMED	Confirmado — el cliente confirmó el pedido.
FOLLOW	En seguimiento — pendiente de confirmación.
CALL_LATER	Volver a llamar — el cliente pidió ser contactado más tarde.
ANNULLED	Anulado — el pedido fue anulado.
NOT_RESPOND	No contesta — el cliente no respondió las llamadas.
DUPLICATE	Duplicado — pedido repetido de otro existente.
OUT_OF_STOCK	Sin stock — no hay inventario disponible.
NO_COVERAGE	Sin cobertura — no hay reparto en la zona destino.
FAKE	Falso — pedido con datos falsos o malintencionado.
TESTING	Prueba — pedido de prueba, sin efecto comercial.

trackingStatus — Estado de tracking en agencia
TO_PREPARE	Por preparar — el almacén aún no prepara el paquete.
PREPARED	Preparado — paquete listo para despachar a la agencia.
DESTINATION	En destino — el envío llegó a la agencia destino.
LEAVE_IN_AGENCY	Dejado en agencia — disponible para recojo con la clave.
DELIVERED	Entregado — el cliente recogió el pedido en la agencia.
OBSERVED	Observado — el envío tiene una observación o incidencia.
PAID	Pagado — pedido cobrado y liquidado.

Ejemplo de request (http)

GET /integration/order/agency?page=1&limit=20&callStatus=CONFIRMED&startDate=2026-07-01&endDate=2026-07-31
Authorization: Bearer <TU_TOKEN>

Ejemplos de filtro por tipo de gestión (http)

GET /integration/order/agency?managementType=1&page=1&limit=20   -> solo pedidos PROPIA (OWN)
GET /integration/order/agency?managementType=0                   -> solo pedidos DROPSHALOM (PARTNER)
GET /integration/order/agency?managementType=                    -> todos
GET /integration/order/agency                                    -> todos

Respuesta 200 OK (json)

{
  "data": [
    {
      "orderNumber": "ALC730123456789",
      "total": 120,
      "callStatus": "CONFIRMED",
      "trackingStatus": "TO_PREPARE",
      "managementType": "PARTNER",
      "channel": "INTEGRATION",
      "productDetail": "Producto de ejemplo Talla M",
      "note": "Pedido de prueba integración",
      "paymentType": "P",
      "createdAt": "2026-07-16T10:32:15.000Z",
      "shipping": {
        "agencyName": "SHALOM",
        "agencyAddress": "CAJAMARCA / HUALGAYOC / BAMBAMARCA / BAMBAMARCA",
        "keyCode": "1628",
        "merchandiseShalom": "PAQUETE XXS",
        "contactName": "prueba lirio prueba",
        "contactPhone": "51990747043",
        "contactDocumenType": "DNI",
        "contactDocumentNumber": "75059752",
        "scheduleDate": "2026-07-17"
      },
      "products": [
        {
          "skuId": 4521,
          "quantity": 2,
          "product": "Producto de ejemplo Talla M",
          "price": 60,
          "subtotal": 120
        }
      ]
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

createdAt ya viene ajustado a hora de Perú (UTC−5); ignora el sufijo Z. scheduleDate se entrega solo como fecha en formato YYYY-MM-DD. managementType se expone con el valor persistido: OWN (PROPIA) o PARTNER (DROPSHALOM).

Campos de la respuesta

Campo	Tipo	Descripción
orderNumber	string	Número único del pedido.
total	number	Monto total del pedido.
callStatus	string	Estado de llamada (ver enum).
trackingStatus	string \| null	Estado de tracking en agencia (ver enum).
managementType	string	Tipo de gestión: `OWN` (PROPIA) o `PARTNER` (DROPSHALOM).
channel	string \| null	Canal de origen del pedido.
productDetail	string \| null	Detalle resumido de productos.
note	string \| null	Nota del pedido.
paymentType	string \| null	Tipo de pago.
createdAt	string	Fecha de creación en hora de Perú (UTC−5).
shipping	object \| null	Agencia destino, clave de recojo, mercadería, contacto y fecha programada.
products	array	Ítems del pedido: `skuId`, `quantity`, `product` (nombre + variantes), `price`, `subtotal`.
pagination	object	`total`, `page`, `limit`, `totalPages`.

Errores comunes

Código	Cuándo
400	Parámetros de query inválidos (enum o fecha con formato incorrecto).
400	`managementType debe ser 1 (PROPIA) o 0 (DROPSHALOM)` — valor de `managementType` distinto de `0`/`1`.
401	Bearer Token inválido o ausente.

POST /integration/order/agency/cancel

Cancelar pedido por agencia

Anula un pedido por agencia de gestión PROPIA (OWN) o DROPSHALOM (PARTNER) en estado TO_PREPARE. Cambia el callStatus del pedido a ANNULLED. Solo puedes anular pedidos de tu propia integración. Auth: Bearer Token

Condiciones para anular — deben cumplirse todas:

El pedido es por agencia (isOrderAgency = true).
callStatus = CONFIRMED.
managementType = PARTNER (DROPSHALOM) u OWN (PROPIA).
trackingStatus = TO_PREPARE (aún no preparado ni en tránsito).
No tiene un pago Niubiz registrado (si existe pago, la anulación se rechaza).

Efecto según tipo de gestión:

El pedido pasa a callStatus=ANNULLED.
Pedidos PARTNER (DROPSHALOM): se libera la reserva de stock virtual y se registra el movimiento de kardex.
Pedidos OWN (PROPIA): no se toca stock, porque nunca hubo reserva.

Request body (json)

{
  "orderNumber": "ALC000123456789"
}

Respuesta 201 Created (json)

{
  "message": "Pedido por agencia anulado correctamente."
}

Errores comunes COMPLETOS

Código	Mensaje	Causa
404	Pedido <orderNumber> no encontrado.	No existe o no pertenece a tu empresa.
400	El pedido no es un pedido por agencia.	isOrderAgency = false (usa Cancelar pedido contraentrega).
400	Pedido no está confirmado.	callStatus ≠ CONFIRMED.
400	Pedido no es de tipo de gestión PARTNER (DROPSHALOM) ni OWN (PROPIA): <valor>.	Pedido sin tipo de gestión.
400	Pedido no puede cancelarse con estado de tracking: <estado>.	trackingStatus ≠ TO_PREPARE (ya fue preparado, recolectado o entregado).
400	Pedido tiene un pago Niubiz registrado.	Existe pago Niubiz; no se puede anular por esta vía.
401	Token inválido	Bearer Token incorrecto.

05 · Guía

Flujo recomendado — Pedidos Contraentrega

Orden sugerido para integrar la modalidad de entrega a domicilio con pago contra entrega.

Catálogo

Consume GET /product/public para sincronizar productos, EAN y stock.

Cotización

Llama GET /order/shipping/cost con warehouseId, lat y lng antes de cerrar venta.

Creación

Envía POST /order reusando el bloque courier devuelto en el paso 2.

Seguimiento

Consulta GET /order con filtros por fecha y estado periódicamente.

Cancelación

Si el cliente desiste, llama POST /order/cancel respetando las reglas.

Flujo recomendado — Pedidos por Agencia (Shalom)

Orden sugerido para integrar la modalidad de recojo en agencia Shalom.

Catálogo

Consume GET /product/public con isAgency=true. Guarda el ean y precio de cada SKU elegido.

Agencias

Consume GET /order/agencies para el selector de agencia destino. Guarda su id y name.

Paquete

(Opcional) Consume GET /order/package-sizes para mostrar los tamaños de paquete.

Creación

Envía POST /order/agency con los EANs en products[], la agencia elegida como shalomAgencyId / shalomAgency y el managementType (0 DROPSHALOM, 1 PROPIA).

Seguimiento

Consulta GET /order/agency con filtros por fecha, callStatus, trackingStatus y managementType periódicamente.

Anulación

Guarda el orderNumber devuelto. Para anular, llama POST /order/agency/cancel con ese número.

06 · Referencia rápida

Códigos HTTP

200 OK: Consulta exitosa (GET).
201 Created: Operación de escritura exitosa (POST).
400 Bad Request: Datos inválidos o reglas de negocio incumplidas.
401 Unauthorized: Token ausente, mal formado o inválido.
404 Not Found: Recurso no existe o no pertenece a tu integración.
500 Internal: Error inesperado — contactar a sistemas@aliclik.app.
502 Bad Gateway: Solo en el directorio de agencias — origen Shalom sin respuesta y sin cache. Reintentar con backoff.

Formato de error estándar: los errores llegan como { "statusCode": 400, "message": "...", "error": "Bad Request" }. En errores 400 el campo message está en español y es accionable: puedes mostrarlo directamente al usuario.

07 · Eventos

Webhooks (Estados en Tiempo Real)

Debes exponer un endpoint HTTPS en tu plataforma para recibir los cambios de estado de los pedidos. Aliclik enviará notificaciones automáticas a tu sistema con el payload descrito abajo.

POST /webhook/order-status

Payload (json)

{
  "orderNumber": "string",
  "dispatchStatus": "string",
  "status": "string",
  "callStatus": "string",
  "phone": "string"
}

Ejemplo

{
  "orderNumber": "ALC-12345",
  "dispatchStatus": "IN_TRANSIT",
  "status": "PENDING_DELIVERY",
  "callStatus": "CONFIRMED",
  "phone": "51987654321"
}

Esquema del payload

Campo	Tipo	Req	Descripción
orderNumber	string	Sí	Identificador único del pedido en Aliclik.
dispatchStatus	enum	Sí	Estado de despacho actual del pedido.
status	enum	Sí	Estado de entrega actual del pedido.
callStatus	enum	Sí	Estado de la llamada de confirmación.
phone	string	Sí	Número de teléfono del cliente.

Tabla de estados

Estado despacho (dispatchStatus)	Estado entrega (status)	Estado llamada (callStatus)
Por preparar TO_PREPARE	Por entregar PENDING_DELIVERY	Confirmado CONFIRMED
Preparado PREPARED
En tránsito IN_TRANSIT
En agencia IN_AGENCY
Validado PICKED	Entregado DELIVERED
Validado PICKED Por retornar TO_RETURN Retornado RETURNED	Cancelado CANCEL
	Rechazado REFUSED
	No contesta NOT_RESPOND
	Anulado ANNULLED
Por preparar TO_PREPARE	Por entregar PENDING_DELIVERY	No confirmado ≠ CONFIRMED

Consideraciones:

Los estados pueden llegar en desorden.
Un pedido puede recibir múltiples actualizaciones.
Usar orderNumber como identificador único.
Implementar idempotencia para evitar duplicados.

08 · Contacto

Soporte

Para reportes de incidentes técnicos, solicitudes de ampliación de cuotas o nuevas funcionalidades.

Soporte técnico

sistemas@aliclik.app

Operaciones

operaciones@aliclik.app

Teléfono

+51 981 427 212

Al reportar un incidente incluye:

orderNumber (si aplica).
Timestamp en UTC.
Request enviado y respuesta recibida.