01 · Auth
Autenticación
Las APIs de integración usan JWT Bearer. Primero debes obtener un token con un usuario que tenga el rol IntegrationApi y los permisos integration.shipments.write y integration.tracking.read.
POST
https://api.helpcourierexpress.cl/api/v1/auth/integration-login
Request
{
"tenantCode": "DEMO",
"userNameOrEmail": "integracion@cliente.cl",
"password": "tu-clave"
}| Campo | Tipo | Largo máximo | Obligatorio | Descripción |
|---|---|---|---|---|
tenantCode | string | 50 | Sí | Código del courier/tenant entregado para la integración. |
userNameOrEmail | string | 80 si es usuario, 200 si es email | Sí | Usuario o correo del usuario API. |
password | string | Según política de clave | Sí | Clave del usuario API. |
Response
{
"tenantCode": "DEMO",
"tenantName": "Courier Demo",
"accessToken": "eyJhbGciOi...",
"refreshToken": "token-refresh",
"accessTokenExpiresAtUtc": "2026-04-22T20:30:00Z"
}En los siguientes llamados agrega el header:
Authorization: Bearer {{accessToken}}
Content-Type: application/jsonRenovar token
POST
https://api.helpcourierexpress.cl/api/v1/auth/integration-refresh
{
"tenantCode": "DEMO",
"refreshToken": "{{refreshToken}}"
}02 · Shipments
Crear encomienda
POST
https://api.helpcourierexpress.cl/api/v1/integrations/shipments
Centro de costo opcional:
si no envías
centroCosto, la encomienda queda asociada automáticamente al centro de costo principal del cliente. También puedes indicar centroCosto a nivel de encomienda o por cada bulto.
| Campo | Tipo | Largo máximo | Obligatorio | Descripción |
|---|---|---|---|---|
codigoCliente | string | 40 | Sí | Código del cliente/seller registrado en la plataforma. |
centroCosto | number | No aplica | No | Código numérico del centro de costo. Si viene vacío usa el principal. |
tipoServicio | string | 40 si es código, 120 si es nombre | No | Código o nombre del tipo de servicio. Si viene vacío usa el primer servicio activo disponible. |
fechaCompromisoUtc | datetime | No aplica | No | Fecha compromiso en UTC, formato ISO 8601. Puede ir null. |
destinatario | object | No aplica | Sí | Datos de entrega. Nombre, dirección y comuna son obligatorios. |
informacionAdicional | object | No aplica | No | Código externo, referencias y observaciones de la encomienda. |
cantidadBultos | number | No aplica | No | Debe coincidir con la cantidad de objetos enviados en bultos si se informa. |
bultos | array | Máximo 200 ítems | Sí | Uno o más bultos. Ver detalle de campos más abajo. |
Detalle de destinatario
| Campo | Tipo | Largo máximo | Obligatorio | Descripción |
|---|---|---|---|---|
nombre | string | 180 recomendado | Sí | Nombre de quien recibe. |
identificacion | string | 40 recomendado | No | RUT, DNI u otra identificación. |
email | string | 200 recomendado | No | Correo del destinatario. |
telefono | string | 40 recomendado | No | Teléfono del destinatario. |
direccion | string | 200 | Sí | Calle, número y dirección base de entrega. |
complemento | string | 200 | No | Depto, oficina, block u otra segunda línea de dirección. |
comuna | string | 120 | Sí | Comuna destino. Debe existir en la plataforma. |
ciudad | string | 120 | No | Si viene vacía, se usa la comuna como ciudad. |
region | string | 120 | No | Ayuda a desambiguar comunas con nombres repetidos. |
codigoPostal | string | 20 | No | Código postal de destino. |
referencia | string | 250 | No | Referencia para encontrar la dirección. |
latitud | decimal | 10,6 | No | Latitud con hasta 6 decimales. |
longitud | decimal | 10,6 | No | Longitud con hasta 6 decimales. |
Detalle de informacionAdicional
| Campo | Tipo | Largo máximo | Obligatorio | Descripción |
|---|---|---|---|---|
codigoExterno | string | 60 | No | Código externo de la encomienda. Debe ser único por cliente. La API recorta a 60 caracteres. |
referencia | string | 200 recomendado | No | Primera referencia comercial. |
referencia2 | string | 200 recomendado | No | Segunda referencia comercial. |
observaciones | string | 300 recomendado | No | Observación general de la encomienda. Si referencia2 viene vacía, se usa como segunda referencia. |
Detalle de bultos[]
| Campo | Tipo | Largo máximo | Obligatorio | Descripción / regla |
|---|---|---|---|---|
centroCosto | number | No aplica | No | Código numérico del centro de costo para este bulto. Si viene vacío, hereda el centro de costo de la encomienda; si la encomienda tampoco trae, usa el principal. |
codigoExterno | string | 60 | No | Código externo del bulto. La API recorta a 60 caracteres. |
referencia | string | 200 recomendado | No | Primera referencia del bulto. |
referencia2 | string | 200 recomendado | No | Segunda referencia del bulto. |
descripcion | string | 200 recomendado | No | Descripción del contenido o embalaje. Si viene vacía, se registra como Bulto. |
pesoKg | decimal | 18,3 | Sí | Debe ser mayor a 0. Ejemplo: 1.5. |
largoCm | decimal | 18,2 | Sí | Debe ser mayor a 0. Largo en centímetros. |
anchoCm | decimal | 18,2 | Sí | Debe ser mayor a 0. Ancho en centímetros. |
altoCm | decimal | 18,2 | Sí | Debe ser mayor a 0. Alto en centímetros. |
valorDeclarado | decimal | 18,2 | No | Valor declarado del bulto. |
observaciones | string | 300 recomendado | No | Observación específica del bulto. |
Nota de largos:
los campos marcados como "recomendado" no tienen una validación estricta de largo en el contrato actual, pero se documentan con un máximo operativo para evitar textos excesivos en etiquetas, reportes y pantallas. Los campos de código opcional se normalizan y recortan a 60 caracteres.
Ejemplo: crear encomienda con 1 bulto
{
"codigoCliente": "100",
"centroCosto": null,
"tipoServicio": "Same day",
"fechaCompromisoUtc": null,
"cantidadBultos": 1,
"destinatario": {
"nombre": "Juan Pérez",
"identificacion": "11111111-1",
"email": "juan.perez@correo.cl",
"telefono": "+56912345678",
"direccion": "Avenida Apoquindo 4500",
"complemento": "Depto 1204",
"comuna": "Las Condes",
"ciudad": "Las Condes",
"region": "Metropolitana",
"codigoPostal": null,
"referencia": "Recepción del edificio",
"latitud": null,
"longitud": null
},
"informacionAdicional": {
"codigoExterno": "OC-10001",
"referencia": "Pedido web 10001",
"referencia2": "Canal ecommerce",
"observaciones": "Entregar en horario oficina"
},
"bultos": [
{
"centroCosto": null,
"codigoExterno": "BULTO-10001-1",
"referencia": "SKU-A",
"referencia2": null,
"descripcion": "Caja pequeña",
"pesoKg": 1.5,
"largoCm": 30,
"anchoCm": 20,
"altoCm": 15,
"valorDeclarado": 25000,
"observaciones": "Frágil"
}
]
}Ejemplo: crear encomienda con más de 1 bulto
{
"codigoCliente": "100",
"centroCosto": 101,
"tipoServicio": "Same day",
"fechaCompromisoUtc": null,
"cantidadBultos": 2,
"destinatario": {
"nombre": "María González",
"identificacion": "22222222-2",
"email": "maria.gonzalez@correo.cl",
"telefono": "+56987654321",
"direccion": "Los Militares 5900",
"complemento": "Oficina 802",
"comuna": "Las Condes",
"ciudad": "Las Condes",
"region": "Metropolitana",
"codigoPostal": null,
"referencia": "Torre norte",
"latitud": null,
"longitud": null
},
"informacionAdicional": {
"codigoExterno": "OC-10002",
"referencia": "Pedido web 10002",
"referencia2": "Marketplace",
"observaciones": "Llamar antes de entregar"
},
"bultos": [
{
"centroCosto": 101,
"codigoExterno": "BULTO-10002-1",
"referencia": "SKU-B",
"referencia2": null,
"descripcion": "Caja 1",
"pesoKg": 2.3,
"largoCm": 40,
"anchoCm": 30,
"altoCm": 20,
"valorDeclarado": 40000,
"observaciones": null
},
{
"centroCosto": 102,
"codigoExterno": "BULTO-10002-2",
"referencia": "SKU-C",
"referencia2": null,
"descripcion": "Caja 2",
"pesoKg": 3.1,
"largoCm": 45,
"anchoCm": 35,
"altoCm": 25,
"valorDeclarado": 55000,
"observaciones": "Mantener vertical"
}
]
}Response de creación
{
"mensaje": "Registro exitoso.",
"codigoEncomienda": "ENV2604221830451234",
"codigoExterno": "OC-10001",
"etiquetaFormato": "ZPL_BASE64",
"etiquetaBase64": "Xlha...",
"bultos": [
{
"codigoBulto": "PKG2604221830450015678",
"trackingNumber": "PKG2604221830450015678",
"etiquetaBase64": "Xlha..."
}
]
}03 · Tracking
Consultar estado y tracking
El código puede ser código de encomienda, código externo de encomienda, tracking del bulto, código interno PKG o código externo del bulto.
GET
https://api.helpcourierexpress.cl/api/v1/integrations/tracking/{codigo}
Ejemplo
GET https://api.helpcourierexpress.cl/api/v1/integrations/tracking/PKG2604221830450015678Response
{
"codigoEncomienda": "ENV2604221830451234",
"codigoExterno": "OC-10001",
"cliente": "Cliente demo",
"destinatario": "Juan Pérez",
"destino": "Avenida Apoquindo 4500, Las Condes, Metropolitana",
"fechaRegistroUtc": "2026-04-22T18:30:45Z",
"totalBultos": 1,
"bultos": [
{
"codigoBulto": "PKG2604221830450015678",
"trackingNumber": "PKG2604221830450015678",
"codigoExterno": "BULTO-10001-1",
"estado": "PickupPending",
"estadoDescripcion": "Pendiente de retiro",
"pesoKg": 1.5,
"eventos": [
{
"tipo": "Created",
"titulo": "Creación de bulto",
"descripcion": "Encomienda registrada por integración.",
"fechaUtc": "2026-04-22T18:30:45Z"
}
]
}
]
}04 · Estados
Códigos de estado frecuentes
| Estado técnico | Descripción |
|---|---|
LabelGenerated | Etiqueta generada |
PickupPending | Pendiente de retiro |
PickedUp | Retirado |
AdmittedAtOriginHub | Admitido en origen |
InLinehaul | En troncal |
OutForDelivery | En reparto |
Delivered | Entregado |
Incidented | Incidentado |
05 · Errores
Errores comunes
| Código HTTP | Causa común |
|---|---|
400 | Faltan campos obligatorios, comuna no reconocida, centro de costo inexistente o dimensiones inválidas. |
401 | Token ausente, vencido o usuario sin rol de integración. |
403 | Usuario sin permiso para crear encomiendas o consultar tracking. |
404 | No se encontró tracking para el código consultado. |
409 | Código externo de encomienda duplicado para el mismo cliente. |
06 · Postman
Colección Postman
Importar colección:
importa el archivo
helpcourier-integracion-api.postman_collection.json, ajusta las variables tenantCode, username, password, codigoCliente y centroCostoPrincipal, ejecuta primero Obtener token y luego los ejemplos de creación/tracking.
Documento generado para la API de integración HelpCourier Express. Base URL: https://api.helpcourierexpress.cl.