API Selfx para genereación de guías

Entorno de prueba completo para la API de creación de guías.

Flujo Completo de Prueba

Ir a sección "Token API"

Pega el token que el administrador te proporcionó

El token se guarda automáticamente

Se mostrará en el sidebar bajo "JWT Token"

Navega a otros endpoints

Ya tienes JWT, prueba "Crear", "COD" o "Masivo"

¡Listo! El JWT se adjunta automáticamente

Todos los requests llevan el header Authorization

Información Importante

Edita el JSON: Puedes modificar cualquier campo del Request Body en el editor

Console de debugging: Todos los requests y responses aparecen en la consola derecha

JWT automático: Después de login, el token se adjunta a todos los requests

Respuestas completas: Ver estructura exacta de response de cada endpoint

Token API

Proporciona tu JWT token para autenticar todas las solicitudes a la API. El administrador te generará tu token único y válido por 365 días.

🔑 Ingresa tu Token API

Token JWT (Proporcionado por el Administrador)

Solicita tu Token al Administrador

Contacta con el Administrador de la plataforma
Solicita que genere un Token API para tu usuario
Copia el token y pégalo en el campo anterior

Información del Token:

El token es válido por 365 días
Se envía automáticamente en el header Authorization: Bearer {token}
Se usa en TODOS los endpoints (Crear, COD, Masivo)
Si expira, contacta al administrador para generar uno nuevo

Crear Guía Unitaria

Crea una nueva guía individual de envío y la registra automáticamente en PINIT.

📌 POST /api/guias/crear

Headers Requeridos

Content-Type: application/json

Authorization: Bearer {JWT_TOKEN}

Campos Obligatorios

Campo	Tipo	Rango/Formato	Descripción
`remitente_nombre`	string	1-100	Nombre de empresa/persona que envía
`remitente_telefono`	string	7-15 dígitos	Teléfono del remitente
`remitente_direccion`	string	5-200	Dirección completa del remitente
`remitente_ciudad`	string	1-50	Ciudad del remitente
`remitente_departamento`	string	1-50	Departamento del remitente
`destinatario_nombre`	string	1-100	Nombre completo del destinatario
`destinatario_telefono`	string	7-15 dígitos	Teléfono del destinatario
`destinatario_direccion`	string	5-200	Dirección completa del destinatario
`destinatario_ciudad`	string	1-50	Ciudad de destino
`destinatario_departamento`	string	1-50	Departamento de destino
`peso`	number	0.1 - 50 kg	Peso del paquete en kilos
`valor_declarado`	number	1+ COP	Valor declarado en COP
`dimensiones`	string	AxAxP (cm)	Alto x Ancho x Profundidad en cm
`tipo_contenido`	string	Ver opciones →	Documentos, Electrónicos, Ropa, Frágil, Otros

📝 Campos Opcionales

Campo	Tipo	Descripción	Notas
`es_contraentrega`	boolean	Indica si es COD (contraentrega)	true = COD, false = pagada
`documento`	string	Cédula/documento destinatario	⚠️ OBLIGATORIO si es_contraentrega=true

🔄 Campos Calculados Automáticamente (NO ENVIAR)

Campo	Descripción	Cálculo
`fecha_estimada_entrega`	Fecha estimada de entrega	Basada en origen→destino (2-5 días hábiles)
`valor_cobrado`	Dinero a cobrar en destino (COD)	= costo_total si es_contraentrega=true
`id_orden`	ID único del pedido/orden	Generado por servidor: ORD-{timestamp}
`numero_tracking`	Número de tracking en XCargo	Generado por XCargo/PINIT (único)

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 207,
    "tracking_number": "4040789508014807",
    "id_orden": "ORD-1763647196280",
    "index_numero_paquete": 1,
    "estado": "Registrada",
    "remitente": {
      "nombre": "Mi Empresa S.A.",
      "ciudad": "Bogotá"
    },
    "destinatario": {
      "nombre": "Juan Pérez López",
      "ciudad": "Medellín"
    },
    "peso": 2.5,
    "valor_declarado": 150000,
    "fecha_estimada_entrega": "2025-11-22",
    "valor_cobrado": 0,
    "es_contraentrega": false,
    "costos": {
      "costoBase": 15000,
      "costoSeguro": 3000,
      "costoTotal": 18000,
      "tiempoEstimado": "2-5 días hábiles",
      "diasMinimos": 2,
      "diasMaximos": 5
    }
  }
}

Características:

Cálculo automático de costos de envío
Cálculo automático de fecha estimada de entrega
Integración automática con PINIT para tracking
Validación robusta de datos
Soporte para contraentrega (COD)

Guía con Contraentrega (COD)

Crea una guía donde el cliente paga el envío en destino. El dinero se cobra automáticamente al momento de la entrega.

✅ Características de Contraentrega (COD)

El cliente paga en el momento de la entrega

valor_cobrado se calcula automáticamente = costo_total

Campo documento es OBLIGATORIO

El dinero se remite al remitente después de la entrega

Se puede mezclar con guías normales en masivo

📋 Campos Adicionales para COD

Campo	Tipo	Descripción	Requerido
`es_contraentrega`	boolean	Indica que es COD	`true`
`documento`	string	Cédula/documento del destinatario	✓ OBLIGATORIO

Ejemplo de Request (COD)

{
  "remitente_nombre": "Mi Empresa",
  "remitente_telefono": "6018001111",
  "remitente_direccion": "Calle 50 #10-20",
  "remitente_ciudad": "Bogotá",
  "remitente_departamento": "Cundinamarca",

  "destinatario_nombre": "Cliente COD",
  "destinatario_telefono": "3105551111",
  "destinatario_direccion": "Carrera 10 #5-15",
  "destinatario_ciudad": "Cali",
  "destinatario_departamento": "Valle del Cauca",
  "documento": "1234567890",

  "peso": 1.5,
  "valor_declarado": 200000,
  "dimensiones": "25x15x10",
  "tipo_contenido": "Electrónicos",
  "es_contraentrega": true
}

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 208,
    "tracking_number": "5847291034912654",
    "id_orden": "ORD-1763647225242",
    "index_numero_paquete": 1,
    "estado": "Registrada",
    "valor_declarado": 150000,
    "valor_cobrado": 18000,
    "documento": "1234567890",
    "es_contraentrega": true,
    "fecha_estimada_entrega": "2025-11-22",
    "costos": {
      "costoBase": 15000,
      "costoSeguro": 3000,
      "costoTotal": 18000,
      "tiempoEstimado": "2-5 días hábiles"
    }
  }
}

Importante: El campo documento es obligatorio cuando es_contraentrega=true. Sin este campo, la request fallará con error de validación.

Crear Guías Masivas

Crea múltiples guías en una sola request. Perfecto para procesar lotes grandes de envíos de forma eficiente.

📌 POST /api/guias/crear-masivo

Headers Requeridos

Content-Type: application/json

Authorization: Bearer {JWT_TOKEN}

✅ Características del Endpoint Masivo

Característica	Descripción
Mezclar tipos de guías	Enviar guías pagadas y COD en el mismo request
Cálculos independientes	Cada guía se valida y calcula de forma individual
Respuesta detallada	Información de éxito/error para cada guía
Orden común	Todas las guías comparten el mismo ID de orden
Totales automáticos	Suma total de costos, base y seguro
Manejo de errores	Si una guía falla, las demás se procesan normalmente

Estructura del Request (Body)

{
  "guias": [
    {
      // Primera guía - Guía PAGADA (normal)
      "remitente_nombre": "Tienda A",
      "remitente_telefono": "6018001111",
      "remitente_direccion": "Calle 50 #10-20",
      "remitente_ciudad": "Bogotá",
      "remitente_departamento": "Cundinamarca",
      "destinatario_nombre": "Cliente 1",
      "destinatario_telefono": "3105551111",
      "destinatario_direccion": "Carrera 10 #5-15",
      "destinatario_ciudad": "Medellín",
      "destinatario_departamento": "Antioquia",
      "peso": 2.5,
      "valor_declarado": 150000,
      "dimensiones": "30x20x15",
      "tipo_contenido": "Ropa y Accesorios"
    },
    {
      // Segunda guía - Guía COD (Contraentrega)
      "remitente_nombre": "Tienda A",
      "remitente_telefono": "6018001111",
      "remitente_direccion": "Calle 50 #10-20",
      "remitente_ciudad": "Bogotá",
      "remitente_departamento": "Cundinamarca",
      "destinatario_nombre": "Cliente 2 (COD)",
      "destinatario_telefono": "3105552222",
      "destinatario_direccion": "Calle 100 #20-30",
      "destinatario_ciudad": "Cali",
      "destinatario_departamento": "Valle del Cauca",
      "documento": "9876543210",
      "peso": 1.5,
      "valor_declarado": 80000,
      "dimensiones": "25x15x10",
      "tipo_contenido": "Electrónicos",
      "es_contraentrega": true
    }
  ]
}

Response (200 OK)

{
  "success": true,
  "id_orden": "ORD-1763647300000",
  "total_guias": 2,
  "guias_exitosas": 2,
  "guias_fallidas": 0,
  "resultados": [
    {
      "index": 1,
      "numero_tracking": "1234567890123456",
      "success": true,
      "costo_total": 18600,
      "valor_cobrado": 0,
      "es_contraentrega": false,
      "fecha_estimada_entrega": "2025-11-22"
    },
    {
      "index": 2,
      "numero_tracking": "6543210987654321",
      "success": true,
      "costo_total": 18600,
      "valor_cobrado": 18600,
      "es_contraentrega": true,
      "fecha_estimada_entrega": "2025-11-24"
    }
  ],
  "costosTotales": {
    "total": "$37200.00",
    "base": "$30000.00",
    "seguro": "$7200.00"
  }
}

Ventajas:

Una sola request para múltiples envíos
Respuesta detallada con éxito/error por guía
Cálculos totales automáticos
Eficiente para procesamiento por lotes

Notas:

Si una guía falla, las demás se procesan normalmente

Revisa guias_fallidas para identificar problemas

Cada guía debe cumplir validaciones individuales

Códigos de Error

Referencia completa de errores que puede retornar la API y cómo resolverlos.

🔐 Errores de Autenticación (4xx)

Código	HTTP	Descripción	Solución
`AUTH_001`	401	JWT inválido o malformado	Verifica que el token sea válido y completo
`AUTH_002`	401	JWT expirado	Haz login nuevamente para obtener nuevo token
`AUTH_003`	403	Permiso denegado	Verifica permisos del usuario en BD
`AUTH_004`	401	No authorization header	Incluye header `Authorization: Bearer {token}`

⚠️ Errores de Validación (400)

Código	Descripción	Solución
`VALIDATION_ERROR`	Datos inválidos en la request	Revisa el detalle y valida todos los campos
`INVALID_FIELD`	Un campo específico es inválido	Verifica el tipo y formato del campo
`REQUIRED_FIELD`	Falta un campo obligatorio	Verifica tabla de campos obligatorios
`INVALID_JSON`	JSON malformado	Valida el JSON en jsonlint.com

🔗 Errores de Integración (400/5xx)

Código	HTTP	Descripción	Solución
`XCARGO_ERROR`	400	Error en XCargo/PINIT	Verifica que ciudad/departamento sean válidos
`XCARGO_TIMEOUT`	504	XCargo no respondió a tiempo	Reintentar después de unos segundos
`INVALID_CITY`	400	Ciudad no soportada	Verifica que la ciudad esté en lista soportadas
`DB_ERROR`	500	Error en base de datos	Contacta a soporte técnico
`DB_TIMEOUT`	504	Base de datos lenta	Reintentar después

Solución de Problemas

Guía de troubleshooting para los errores más comunes.

❌ JWT inválido o expirado (AUTH_001/AUTH_002)

Causas comunes:

Token no incluido en header
Token incompleto o malformado
Token expirado (aunque duran 365 días)

Solución:

# ✅ CORRECTO
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# ❌ INCORRECTO
curl -H "Authorization: token123456"
curl -H "Authorization: Bearer token123"

Pasos:

Haz login nuevamente: POST /auth/login
Copia el token completo de la respuesta
Incluye en header: Authorization: Bearer {token_completo}
Reintenta la request

❌ Error validando los datos (VALIDATION_ERROR)

Causas comunes:

Faltan campos obligatorios
Tipos de dato incorrectos (string vs number)
Valores fuera de rango

Ejemplo:

// ✅ CORRECTO
{
  "peso": 2.5,              // número
  "valor_declarado": 150000, // número
  "remitente_telefono": "6018001111", // string
  "dimensiones": "30x20x15" // formato AxAxP
}

// ❌ INCORRECTO
{
  "peso": "2.5",              // string en lugar de número
  "valor_declarado": "150000", // string en lugar de número
  "remitente_telefono": 6018001111, // número en lugar de string
  "dimensiones": "30, 20, 15" // formato incorrecto
}

❌ Dimensiones no está nulo

Causa: El campo dimensiones es obligatorio pero no fue incluido.

Solución:

// ✅ CORRECTO - Formato: AnchoxAltoxProfundidad en cm
{
  "dimensiones": "30x20x15"  // Paquete mediano
}

// ✅ OTROS EJEMPLOS
{
  "dimensiones": "25x15x10", // Paquete pequeño
  "dimensiones": "50x40x30", // Paquete grande
  "dimensiones": "100x80x60" // Paquete muy grande
}

❌ Documento requerido para COD

Causa: Cuando es_contraentrega: true, el campo documento es obligatorio.

Solución:

// ✅ CORRECTO para COD
{
  "es_contraentrega": true,
  "documento": "1234567890" // cédula o documento del destinatario
}

// ❌ INCORRECTO para COD
{
  "es_contraentrega": true
  // falta documento
}

❌ No se pudo registrar en XCargo

Causas comunes:

Ciudad no existe en Colombia
Teléfono formato incorrecto
Datos incompletos o mal escritos

Solución:

// ✅ VÁLIDO
{
  "destinatario_ciudad": "Medellín",
  "destinatario_departamento": "Antioquia",
  "destinatario_telefono": "3125556666"
}

// ❌ INVÁLIDO
{
  "destinatario_ciudad": "Ciudad Falsa",
  "destinatario_telefono": "123"
}