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 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
Daniel Vargas: daniel.vargas@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).

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, managementType=PARTNER). 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

Reglas de negocio aplicadas por el servidor:

Todos los EANs deben pertenecer al mismo almacén, con stock disponible y un máximo de 6 unidades en total por pedido.
El almacén debe estar activo y habilitado para envíos Shalom.
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.

Request body (json)

{
  "note": "información adicional del pedido",
  "paymentType": "CONTADO",
  "customer": {
    "firstName": "Juan",
    "firstLastName": "Pérez",
    "secondLastName": "García",
    "senderPhone": "51918993266",
    "senderDocumentType": "DNI",
    "senderContact": "María López"
  },
  "shipping": {
    "agencyName": "Agencia Central Huancayo",
    "agencyAddress": "Av. Ferrocarril 146, Huancayo",
    "reference": "Recoger en agencia",
    "keyCode": "A1B2C3",
    "merchandiseShalom": "PAQUETE S",
    "scheduleDate": "2026-07-20",
    "shalomAgency": "CHOSICA",
    "shalomAgencyId": "152"
  },
  "products": [
    { "ean": "7750243063648", "quantity": 2, "price": 49.9 }
  ]
}

Respuesta 201 Created (json)

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

Esquema del body — nivel raíz

Campo	Tipo	Req	Descripció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 documente del remitente (ser válido)

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	Sí	`id` de la agencia elegida del directorio, como string (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.
products[].quantity	int > 0	Sí	Cantidad. La suma total del pedido no debe exceder 6 unidades.
products[].price	number ≥ 0	Sí	Precio unitario definido por tu plataforma.

Errores comunes (400 — el detalle llega en message)

Mensaje	Causa
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.
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).
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.
Errores de stock / almacén distinto / máx. 6 unidades	Validaciones de productos por EAN.

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

POST /integration/order/agency/cancel

Cancelar pedido por agencia

Anula un pedido por agencia. Si procede, el servidor devuelve el stock reservado y 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.
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).

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.	managementType ≠ PARTNER.
400	Pedido no puede cancelarse con estado de tracking: <estado>.	trackingStatus ≠ TO_PREPARE.
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[] y la agencia elegida como shalomAgencyId / shalomAgency.

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

Ejemplo

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

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.

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.