API de Despachos — Guía de Integración

Empezando

Introducción

El API de Despachos permite a los sistemas de nuestros clientes integrarse directamente con Aeromensajería: cotizar el valor de un envío antes de generarlo, crear la guía, consultar o anular guías existentes, y rastrear el estado de una entrega.

Flujo típico de integración:

1	Autenticarse en `/connect/token` con su credencial de aplicación y obtener un token Bearer.
2	(Opcional) Cotizar el envío con `/cotizacion` para mostrarle el valor al usuario antes de confirmar.
3	Crear la guía con `POST /guias`.
4	Consultar su estado cuando lo necesite con `POST /rastreo`.

Todos los endpoints descritos aquí (excepto /connect/token) requieren el token Bearer obtenido en el paso 1, y reciben sus parámetros en el cuerpo de la petición — este API no usa query strings ni parámetros de ruta para filtros.

Seguridad

Autenticación

Su integración usa una credencial de aplicación (clientId / clientSecret) que Aeromensajería le entrega por separado para cada ambiente. Con ella obtiene un token JWT de tipo Bearer que debe enviar en cada llamada posterior.

POST /connect/token

Intercambia su credencial de aplicación por un token de acceso.

Request body

{
  "clientId": "empresa-demo",
  "clientSecret": "••••••••••••••••"
}

Response 200

{
  "exito": true,
  "mensaje": "OK",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6ImVtcHJlc2EtZGVtbyIsImN1ZW50YUlkIjoiMTIzIn0...",
    "tokenType": "Bearer",
    "expiresIn": 36000
  },
  "statusCode": 200
}

Posibles errores

401 Credenciales inválidas — clientId o clientSecret incorrectos.
401 La credencial está inactiva.
401 La credencial ha expirado.

Use el token en el encabezado Authorization de cada petición posterior:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

expiresIn indica en segundos cuánto dura el token. Cuando expire, vuelva a llamar /connect/token — no hay endpoint de refresco.

Referencia

Formato de respuesta

Todas las respuestas, exitosas o con error, comparten el mismo sobre:

{
  "exito": true,
  "mensaje": "OK",
  "data": { /* el resultado, o null si hubo error */ },
  "errores": null,
  "statusCode": 200,
  "correlationId": null
}

Campo	Descripción
exito	Booleano. `false` en cualquier respuesta de error.
mensaje	Texto descriptivo, apto para mostrar al usuario final.
data	El objeto o lista solicitada. `null` cuando `exito` es `false`.
errores	Lista de mensajes de validación de campo (solo en errores `400` de validación). `null` en el resto de los casos.
statusCode	Repite el código HTTP de la respuesta.
correlationId	Identificador interno de la petición. Inclúyalo si reporta un problema a Aeromensajería — agiliza encontrar el log correspondiente.

Referencia

Manejo de errores

El API no expone un código de error separado por tipo de falla — identifique el caso por el código HTTP y, si necesita distinguir más, por el texto de mensaje.

HTTP	Cuándo ocurre
400	Datos de la petición inválidos — campos faltantes, fuera de rango, o combinación no permitida (p. ej. indicar ciudad por Id y por nombre a la vez). Revise `errores` para el detalle campo a campo cuando aplica.
401	Token ausente, inválido, expirado, o credencial de aplicación inactiva/expirada.
403	El token es válido pero la operación no está permitida para esa credencial.
404	El recurso solicitado no existe (p. ej. una guía o ciudad que no se encuentra).
409	Conflicto — la operación no puede completarse por el estado actual del recurso.
500	Error interno. Reporte el `correlationId` a Aeromensajería si se repite.

Ejemplo de error de validación (400):

{
  "exito": false,
  "mensaje": "Error de validación.",
  "data": null,
  "errores": [
    "El email del destinatario es obligatorio.",
    "Debe ingresar un valor mayor a 0 para: Peso."
  ],
  "statusCode": 400,
  "correlationId": "0HNNSBV767VD5:00000001"
}

Cotización

Cotizar un envío

Calcula el valor de un envío sin crear la guía — útil para mostrarle el costo al usuario antes de confirmar.

Ambiente de Test: las tarifas configuradas en Test son de prueba y pueden no reflejar la negociación comercial real de su cuenta. Los valores que devuelve este endpoint en Test son solo informativos para validar su integración — el valor real facturado depende de las tarifas vigentes de su cuenta en Producción.

POST /cotizacion Requiere Bearer token

Request body

Campo	Tipo		Descripción
ciudadOrigenId	long?	opcional*	Código DANE de 8 dígitos (código de municipio + 000) del centro poblado de origen. Ej. `11001000` para Bogotá.
ciudadOrigenNombre / departamentoOrigenNombre	string?	opcional*	Alternativa al Id: nombre de ciudad + departamento (recomendado si no tiene el código DANE a mano).
ciudadDestinoId	long?	opcional*	Código DANE de 8 dígitos (código de municipio + 000) del centro poblado de destino. Ej. `05001000` para Medellín (como número JSON se envía sin el cero inicial: `5001000`).
ciudadDestinoNombre / departamentoDestinoNombre	string?	opcional*	Alternativa al Id para el destino.
peso	decimal	requerido	Peso en Kg, mayor a 0.
unidades	int	requerido	Cantidad de unidades, mayor a 0.
valorDeclarado	decimal	requerido	Valor declarado del envío, mayor a 0 y hasta 100,000,000.
servicioId	long	requerido	Ver catálogo de servicios más abajo.
paquetes	array?	condicional	Detalle por bulto (unidades, peso, alto, ancho, largo, valorDeclarado, contenido). Obligatorio para Premier; para Premier y Mercancía de Valores debe traer exactamente 1 paquete con 1 unidad.

* Indique la ciudad por Id o por nombre + departamento, nunca ambos ni ninguno — para origen y destino por separado.

Ejemplo de request (capturado en Test)

{
  "ciudadOrigenNombre": "Bogotá",
  "departamentoOrigenNombre": "Distrito Capital",
  "ciudadDestinoNombre": "Medellín",
  "departamentoDestinoNombre": "Antioquia",
  "peso": 3.5,
  "unidades": 1,
  "valorDeclarado": 150000,
  "servicioId": 30
}

Response 200 (real, ambiente de Test)

{
  "exito": true,
  "mensaje": "OK",
  "data": {
    "vrFlete": 5000,
    "vrManejo": 2000,
    "vrOtros": 0,
    "kilosCobrados": 4,
    "vrKilo": 0,
    "cubrimientoId": 23
  },
  "statusCode": 200
}

El valor total del envío es la suma de vrFlete + vrManejo + vrOtros. También puede indicar la ciudad por ciudadOrigenId/ciudadDestinoId (código DANE de 8 dígitos: código de municipio + 000, ej. 11001000 para Bogotá) en vez de nombre + departamento.

Posibles errores

400 El servicio no admite el peso, valor declarado o unidades enviados (restricciones del servicio).
400 No existe tarifa para la combinación de origen, destino y servicio solicitados.
404 Ciudad de origen o destino no encontrada, o ambigua por nombre.

Catálogo de servicios (servicioId)

Id	Servicio	Notas
30	Carga	Servicio estándar de mensajería/paquetería.
31	Mensajería	Documentos y sobres.
32	Premier	Requiere el detalle de `paquetes` (1 paquete, 1 unidad).
563	Mercancía de Valores	Requiere el detalle de `paquetes` (1 paquete, 1 unidad).

Estos son los servicios más frecuentes. Los servicios habilitados dependen de la negociación de su cuenta — si requiere algún otro servicio, consulte con Aeromensajería los códigos correspondientes.

Guías

Crear, consultar, anular e imprimir guías de envío.

POST /guias Requiere Bearer token

Crear guía

Genera una guía de envío y la liquida (calcula flete/manejo) en el mismo paso.

Campo	Tipo		Descripción
cuentaId	int?	opcional	Solo si su credencial opera sobre varias cuentas (bypass). Si su credencial está fija a una cuenta, no lo envíe.
ciudadOrigenId / ciudadOrigenNombre+departamentoOrigenNombre	—	opcional	Igual que en Cotización: `ciudadOrigenId` es el código DANE de 8 dígitos (código de municipio + `000`). Si se omiten ambos, se usa la ciudad configurada en su cuenta.
ciudadDestinoId / ciudadDestinoNombre+departamentoDestinoNombre	—	requerido*	Uno de los dos, no ambos. `ciudadDestinoId` también es el código DANE de 8 dígitos.
nombreDestinatario, direccionDestinatario, telefonoDestinatario	string	requerido	Máx. 250 / 200 / 50 caracteres respectivamente.
emailDestinatario	string	requerido	Email válido, máx. 100 caracteres.
idDestinatario / tipoIdDestinatario	string / long?	requerido**	Identificación del destinatario, máx. 20 caracteres.
nombreRemitente, direccionRemitente, telefonoRemitente, emailRemitente	string?	opcional	Si se omiten, se usan los datos por defecto de su cuenta.
contenido	string	requerido	Descripción del contenido, máx. 200 caracteres.
unidades, peso, valorDeclarado, servicioId	—	requerido	Igual que en Cotización.
paquetes	array?	condicional	Igual regla que en Cotización según el servicio.
generarCartaporte	bool	opcional	Si es `true`, genera una segunda guía de cartaporte enlazada (retorno).
valorDeclaradoCartaporte / contenidoCartaporte	—	requerido si generarCartaporte	Datos de la guía de cartaporte.

** tipoIdDestinatario es opcional en el DTO pero recomendado para evitar ambigüedad en el tipo de documento.

Ejemplo de request (capturado en Test)

{
  "ciudadOrigenNombre": "Bogotá",
  "departamentoOrigenNombre": "Distrito Capital",
  "ciudadDestinoNombre": "Medellín",
  "departamentoDestinoNombre": "Antioquia",
  "nombreDestinatario": "Juan Perez",
  "direccionDestinatario": "Cra 45 # 12-30",
  "telefonoDestinatario": "3001234567",
  "emailDestinatario": "juan.perez@correo.com",
  "idDestinatario": "1017123456",
  "tipoIdDestinatario": 1,
  "contenido": "Documentos de prueba API",
  "unidades": 1,
  "peso": 3.5,
  "valorDeclarado": 150000,
  "servicioId": 30,
  "generarCartaporte": false
}

Response 201 (real, ambiente de Test)

{
  "exito": true,
  "mensaje": "Creado",
  "data": {
    "consGuia": 3752996232,
    "consGuiaBarCode": 3752996232,
    "consGuiaCartaporte": null,
    "consGuiaBarCodeCartaporte": null,
    "vrFlete": 5000,
    "vrManejo": 2000,
    "vrOtros": 0,
    "pesoCobrado": 4,
    "cubrimientoId": 23,
    "fechaCaptura": "2026-08-17T14:02:39.998"
  },
  "statusCode": 201
}

Posibles errores

400 Validación de campos (ver errores), restricciones del servicio, o sin tarifa para la ruta.
400 No hay consecutivos disponibles para el servicio solicitado.
404 Ciudad de origen/destino no encontrada.

POST /guias/buscar Requiere Bearer token

Buscar guías

Lista guías por rango de fechas, con filtros opcionales.

Campo	Tipo		Descripción
fechaDesde	date	requerido	Formato `YYYY-MM-DD`.
fechaHasta	date	requerido	Igual o posterior a `fechaDesde`. El rango no puede superar 60 días.
estadoId	long?	opcional	Filtra por estado de la guía.
consGuiaBarCode	long?	opcional	Filtra por número de guía puntual.

Ejemplo de request

{
  "fechaDesde": "2026-08-01",
  "fechaHasta": "2026-08-17"
}

Response 200 (real, ambiente de Test)

{
  "exito": true,
  "mensaje": "OK",
  "data": [
    {
      "consGuia": 3752996232,
      "consGuiaBarCode": 3752996232,
      "servicioId": 30,
      "nombreDestinatario": "Juan Perez",
      "direccionDestinatario": "Cra 45 # 12-30",
      "emailDestinatario": "juan.perez@correo.com",
      "unidades": 1,
      "peso": 3.5,
      "valorDeclarado": 150000,
      "valorFlete": 5000,
      "valorCostoManejo": 2000,
      "valorOtros": 0,
      "estadoId": 1,
      "fechaCaptura": "2026-08-17T14:02:39.997"
    }
  ],
  "statusCode": 200
}

Posibles errores

400 Fechas faltantes, rango invertido, o rango mayor a 60 días.

POST /guias/detalle Requiere Bearer token

Detalle de guía

Devuelve la información completa de una guía puntual.

Request body

{
  "consGuiaBarCode": 3752996232
}

Response 200 (real, ambiente de Test)

{
  "exito": true,
  "mensaje": "OK",
  "data": {
    "consGuia": 3752996232,
    "consGuiaBarCode": 3752996232,
    "servicioId": 30,
    "centroPobladoIdOrigen": 11001000,
    "centroPobladoIdDestino": 5001000,
    "nombreRemitente": "CUENTA PARA PRUEBAS",
    "direccionRemitente": "CRA 32A #15-80",
    "telefonoRemitente": "6017428233",
    "nombreDestinatario": "Juan Perez",
    "direccionDestinatario": "Cra 45 # 12-30",
    "telefonoDestinatario": "3001234567",
    "contenido": "Documentos de prueba API",
    "unidades": 1,
    "peso": 3.5,
    "valorDeclarado": 150000,
    "valorFlete": 5000,
    "valorCostoManejo": 2000,
    "valorOtros": 0,
    "estadoId": 1,
    "fechaCaptura": "2026-08-17T14:02:39.997"
  },
  "statusCode": 200
}

Posibles errores

404 La guía no existe, o no pertenece a su cuenta.

PUT /guias/anular Requiere Bearer token

Anular guía

Anula una guía existente. La operación no se puede deshacer.

Request body

{
  "consGuiaBarCode": 3752996232
}

Response 200

{
  "exito": true,
  "mensaje": "Guía anulada.",
  "data": null,
  "statusCode": 200
}

Posibles errores

404 La guía no existe, o no pertenece a su cuenta.
409 La guía ya está anulada o en un estado que no permite anularla.

POST /guias/imprimir Requiere Bearer token

Imprimir guía

Genera el PDF de una o varias guías (etiqueta o formato normal), devuelto en base64.

Campo	Tipo		Descripción
tipoImpresion	string	requerido	`"label"` o `"normal"`.
consGuiaBarCode	long?	requerido*	Para una guía puntual.
fechaDesde / fechaHasta	date?	requerido*	Para imprimir todas las guías del rango.

* Indique consGuiaBarCode o el rango de fechas, no ambos ni ninguno.

Ejemplo de request

{
  "tipoImpresion": "label",
  "consGuiaBarCode": 3752996232
}

Response 200

{
  "exito": true,
  "mensaje": "OK",
  "data": [
    {
      "formato": "label",
      "pdfBase64": "JVBERi0xLjcNCiXi48/TDQo..."
    }
  ],
  "statusCode": 200
}

Al imprimir por rango de fechas, la respuesta trae un elemento por cada guía encontrada — puede ser una lista larga.

Posibles errores

400 Debe indicar consGuiaBarCode o el rango de fechas, no ambos ni ninguno.

Rastreo

Consultar estado de una guía

Devuelve el estado actual del envío y su línea de tiempo de eventos, unificando la información propia de Aeromensajería y la del operador de última milla cuando aplica.

POST /rastreo Requiere Bearer token

Campo	Tipo		Descripción
consGuiaBarCode	long	requerido	Número de guía a rastrear.
incluirImagen	bool	opcional	Si es `true` y la guía fue entregada, incluye la evidencia fotográfica en base64.

Ejemplo de request

{
  "consGuiaBarCode": 3752996232,
  "incluirImagen": false
}

Response 200

{
  "exito": true,
  "mensaje": "OK",
  "data": {
    "consGuiaBarCode": 3752996232,
    "estadoActual": "EN_REPARTO",
    "fechaEstadoActual": "2026-08-18T09:14:00",
    "operador": "Servientrega",
    "operadorDisponible": true,
    "imagenEntregaBase64": null,
    "eventos": [
      { "fecha": "2026-08-17T14:02:39", "estadoEstandar": "GUIA_CREADA", "estadoOriginal": null, "origen": "Local", "observaciones": "GUIA INGRESADA POR CAPTURA WEB" },
      { "fecha": "2026-08-17T18:05:00", "estadoEstandar": "ENTREGADO_A_OPERADOR", "estadoOriginal": "ALISTAMIENTO CLIENTE PARA ENTREGA A RECOLECCIONES", "origen": "Servientrega", "observaciones": null },
      { "fecha": "2026-08-18T09:14:00", "estadoEstandar": "EN_REPARTO", "estadoOriginal": "EN ZONA DE DISTRIBUCION", "origen": "Servientrega", "observaciones": null }
    ]
  },
  "statusCode": 200
}

Los eventos vienen de dos orígenes: "Local" (movimientos propios de Aeromensajería) y el nombre del operador de última milla (p. ej. "Servientrega") cuando la guía pasa a su red. estadoOriginal trae el texto tal cual lo reporta el operador; estadoEstandar es la normalización de Aeromensajería según el catálogo de abajo.

Posibles errores

404 La guía no existe, o no pertenece a su cuenta.

Catálogo de estados (estadoEstandar)

Independientemente del operador que mueva el envío, cada evento se normaliza a uno de estos valores:

Valor	Significado
GUIA_CREADA	La guía fue generada.
RECOLECTADO	El paquete fue recogido en origen.
NOVEDAD_RECOLECCION	No se pudo recolectar; hay una novedad reportada.
ENTREGADO_A_OPERADOR	El paquete pasó a un operador de última milla (p. ej. Servientrega).
EN_TRANSITO	El paquete está en tránsito hacia el destino.
EN_REPARTO	Salió a reparto en la ciudad destino.
ENTREGADO	Entregado al destinatario.
NOVEDAD_ENTREGA	No se pudo entregar; hay una novedad reportada.
NOVEDAD_SOLUCIONADA	Una novedad previa fue resuelta.
DEVUELTO	El paquete inició devolución.
DEVUELTO_A_REMITENTE	El paquete fue devuelto al remitente.
ANULADO	La guía fue anulada.
OTRO_MOVIMIENTO	Movimiento interno sin un estado estándar equivalente.