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 los cinco endpoints principales del módulo de integración.

Base URL

https://api.aliclik-dev.com

Auth

Bearer Token

Zona horaria

America/Lima (UTC−05:00)

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 expone cinco endpoints para operar el módulo de integración de Aliclik:

Crear, cancelar y listar pedidos.
Calcular el costo de envío y couriers disponibles.
Consultar el catálogo público con stock virtual por almacén.

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 · Referencia

Endpoints

Cinco endpoints que cubren el ciclo completo de integración: catálogo, cotización de envío, creación, listado y cancelación de pedidos.

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. Auth: Bearer Token

Query parameters

Campo	Tipo	Requerido	Descripción
page	number	—	Página solicitada. Default 1.
limit	number	—	Registros por página. Default 15, máx 100.
search	string	—	Búsqueda parcial por nombre.

Ejemplo de request (http)

GET /integration/product/public?page=1&limit=15&search=laptop
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"
        }
      ]
    }
  ]
}

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.

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

03 · Guía

Flujo recomendado de integración

Orden sugerido para integrar correctamente tu sistema con Aliclik.

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.

04 · 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.

05 · 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.

06 · 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.