Servicio de Creación de Etiquetas - Documentación Técnica

1. Descripción Técnica del Servicio

El servicio permite la generación de una Orden de Transporte (OT) para cada punto de entrega o destinatario, mediante una integración con nuestra API REST. Cada OT puede incluir uno o más productos (SKU) y representa una unidad logística independiente que será gestionada por Urbano desde su recolección hasta su entrega final.

Por cada solicitud al servicio, el sistema de Urbano genera un número único de OT, el cual se devuelve como parte de la respuesta. Este identificador sirve como nexo entre el cliente y Urbano, permitiendo el seguimiento del envío y la trazabilidad completa del proceso.

Para garantizar unicidad y trazabilidad, la OT debe estar vinculada a un código de seguimiento proporcionado por el cliente, como una orden de compra o número de pedido.

El número de OT es un código alfanumérico de hasta 11 caracteres, con un dígito verificador incluido, y se considera el identificador oficial para todas las operaciones logísticas y de tracking posteriores.

La estructura de datos esperada para generar una OT incluye información del contrato, detalles del envío, datos del destinatario, dirección de entrega, productos involucrados, documentos asociados (cedibles), y parámetros logísticos como peso, cantidad de piezas, seguros y ventanas horarias de entrega.

Al final de esta página, puede utilizar el botón "Abrir Formulario de Prueba" para ingresar datos y generar automáticamente ejemplos de código en cURL, PHP, Java y Node listos para usar.

Para consumir el servicio, se debe enviar un payload en formato JSON que contiene todos los datos necesarios para la generación de la OT (detalles del contrato, destinatario, dirección, productos, logística, etc.). Este JSON debe viajar dentro de una variable llamada json, utilizando el formato application/x-www-form-urlencoded, como se ilustra a continuación:


        --header "Content-Type: application/x-www-form-urlencoded"

        --data-urlencode 'json={ ... JSON completo ... }'

Este diseño permite que el servicio pueda integrarse fácilmente desde entornos web, móviles o servidores, manteniendo compatibilidad con sistemas que no permiten el uso de application/json de forma nativa.

2. Endpoint

URL: https://app.urbanoexpress.cl/ws/ue/ge/

Método: POST

Content-Type: application/x-www-form-urlencoded

3. Encabezados HTTP requeridos

user: Usuario autorizado
pass: Contraseña del servicio

4. Parámetros (en el campo `json`)

A. Identificación del Servicio

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`linea`	Numérico	1	Sí	3	Tipo de servicio: 1 (Postal), 2 (Valorados), 3 (Logística)
`id_contrato`	Numérico	9	Sí	1722	Identificador de contrato proporcionado por Urbano

B. Datos del Envío

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`cod_rastreo`	Alfanumérico	20	Sí	5410724479257	Código de rastreo asociado a la compra
`cod_barra`	Alfanumérico	25	No		Código de barras (si se usa el del cliente)
`fech_emi_vent`	Fecha	10	No	13/09/2023	Fecha de emisión de la venta
`nro_o_compra`	Alfanumérico	16	No	1015	Número de orden de compra o pedido
`nro_guia_trans`	Alfanumérico	20	No	1	Número de guía de transporte

C. Datos del Vendedor (Seller)

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`venta_seller`	Alfanumérico	2	No	NO	¿Corresponde a un seller? (SI/NO)
`sell_codigo`	Alfanumérico	12	No		RUT o código del seller
`sell_nombre`	Alfanumérico	80	No		Razón social del seller
`sell_direcc`	Alfanumérico	100	No		Dirección del almacén de recolección
`sell_ubigeo`	Alfanumérico	6	No		Código INE de comuna

D. Datos del Receptor / Cliente

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`cod_cliente`	Alfanumérico	20	Sí	7234047672601	RUT o código del destinatario
`nom_cliente`	Alfanumérico	100	Sí	Hugo Antonio Farfan	Nombre del destinatario
`nom_empresa`	Alfanumérico	80	No	Urbano Chile	Empresa del destinatario
`nro_telf`	Alfanumérico	16	No	null	Teléfono fijo
`nro_telf_mobil`	Alfanumérico	10	No	null	Teléfono móvil (para SMS)
`correo_elec`	Alfanumérico	35	No	[email protected]	Email del destinatario

E. Dirección de Entrega

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`dir_entrega`	Alfanumérico	100	Sí	la punta 1778	Calle o avenida
`nro_via`	Alfanumérico	10	Sí	0	Número exterior
`nro_int`	Alfanumérico	10	Sí	2219	Número interior (dpto, oficina)
`nom_urb`	Alfanumérico	40	No		Nombre de población o villa
`ubi_direc`	Alfanumérico	6	Sí	13128	Código de comuna según INE
`ref_direc`	Alfanumérico	100	No	0	Referencia adicional de ubicación
`id_direc`	Numérico	8	No	0	Identificador validado por API de direcciones UE

F. Datos del Producto a Entregar

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`cod_sku`	Alfanumérico	25	Sí	RC0032L232232	Código del producto
`descr_sku`	Alfanumérico	100	Sí	Caja de CDs	Nombre del producto
`modelo_sku`	Alfanumérico	40	No	CDs R/W	Modelo o referencia
`marca_sku`	Alfanumérico	30	No	Princo	Marca o proveedor
`peso_sku`	Numérico	(10,4)	Sí	5.2	Peso en kilogramos
`valor_sku`	Numérico	(10,4)	No	54990	Valor comercial del producto
`cantidad_sku`	Numérico	(8,2)	Sí	1	Cantidad de unidades
`ancho`	Numérico	4	No	10	Ancho en cm
`alto`	Numérico	4	No	15	Alto en cm
`largo`	Numérico	4	No	20	Largo en cm
`peso_v_sku`	Numérico	(10,4)	No	4.8	Peso volumétrico

G. Cedibles

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`cod_pod`	Alfanumérico	3	No	059	Código del documento (ej. factura)
`descr_pod`	Alfanumérico	20	No	48070604	Número del documento cedible

H. Datos para Despachos

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`peso_total`	Numérico	(12,4)	Sí	12.5	Peso total del envío en kilogramos
`pieza_total`	Numérico	(8,0)	Sí	2	Total de piezas o bultos a despachar
`urgente`	Alfanumérico	2	No	NO	Indica si el servicio es urgente (Premium)
`picking`	Alfanumérico	2	No	NO	Servicio de finishing o alistamiento
`asegurado`	Alfanumérico	2	No	NO	Indica si se toma el seguro
`monto_asegurado`	Numérico	(12,2)	No	12990	Valor asegurado (obligatorio si asegurado=SI)
`via_aereo`	Alfanumérico	2	No	NO	Indica si el envío será por vía aérea

I. Datos para la Entrega

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`fech_pro`	Fecha	10	No	13/09/2023	Fecha programada de entrega
`arco_hor`	Alfanumérico	2	No	PM	Arco horario de entrega: AM o PM
`fech_venc`	Fecha	10	No	13/09/2023	Fecha límite de entrega

J. Datos Autorizados para Entrega

Campo	Tipo	Longitud	Obligatorio	Descripción
`nom_autorizado`	Alfanumérico	80	No	Nombre de persona autorizada a recibir
`nro_doc_autorizado`	Alfanumérico	10	No	Documento/RUT de la persona autorizada
`nom_autorizado_2`	Alfanumérico	80	No	Segunda persona autorizada
`nro_doc_autorizado_2`	Alfanumérico	10	No	Documento de segunda persona

K. Datos para Cobranza

Campo	Tipo	Longitud	Obligatorio	Ejemplo	Descripción
`med_pago`	Alfanumérico	6	No	TARCRE	Método de pago (código)
`descripcion`	Alfanumérico	40	No	Tarjeta de Crédito VISA	Descripción del método de pago
`anotacion`	Alfanumérico	50	No		Comentarios o anotaciones para la cobranza
`moneda`	Alfanumérico	3	No	CLP	Moneda de la transacción (CLP, USD, EUR)
`importe`	Numérico	(10,2)	No	15990	Importe a cobrar
`tipo_empaque`	Alfanumérico	2	No	Paquete	Tipo de bulto (Paquete o Sobre)

📥 Ejemplo con curl

curl --location "https://app.urbanoexpress.cl/ws/ue/ge/" \
--header "user: TU_USUARIO" \
--header "pass: TU_PASSWORD" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode 'json={...}'

📤 Ejemplo de Respuesta Exitosa

Esta es una respuesta típica del servicio cuando la generación de la guía electrónica (GE) ha sido exitosa:

{
  "error": 1,
  "mensaje": "OK",
  "guia": "WB203261446",
  "piezas": [
    { "pieza_barra": "PK245127766SCL" },
    { "pieza_barra": "PK245127774SCL" }
  ],
  "IATA": "SCL",
  "etiqueta": "https://storage.googleapis.com/reportes-ue-cl/etiqueta-WB203261446.pdf",
  "carrier": "URBCL",
  "IATA_ORG": "SCL",
  "etiquetaPOD": "https://storage.googleapis.com/reportes-ue-cl/etiquetaPOD-WB203261446.pdf",
  "cod_destino": "3"
}

📘 Descripción de los campos en la respuesta

Campo	Descripción	Tipo	Ejemplo
`error`	Código de estado de la operación (1 = OK, 0 o negativo = error).	Integer	1
`mensaje`	Mensaje textual del estado del proceso.	String	"OK"
`guia`	Número único de guía electrónica asignado por Urbano.	String	"WB203261446"
`piezas`	Lista de piezas individuales asociadas a la guía, con su código de barra.	Array	[{"pieza_barra": "PK..."}, ...]
`IATA`	Código IATA del destino final.	String	"SCL"
`IATA_ORG`	Código IATA de origen del envío.	String	"SCL"
`cod_destino`	Código interno de destino asignado por Urbano.	String	"3"
`etiqueta`	URL directa para descargar el PDF de la etiqueta logística.	String (URL)	`https://storage.googleapis.com/.../etiqueta-....pdf`
`etiquetaPOD`	URL para descargar el PDF con espacio para firma (Prueba de Entrega).	String (URL)	`https://storage.googleapis.com/.../etiquetaPOD-....pdf`
`carrier`	Identificador del operador logístico asignado.	String	"URBCL"

🌐 Ejemplos de Código

PHP


$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://app.urbanoexpress.cl/ws/ue/ge/",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "user: TU_USUARIO",
        "pass: TU_PASSWORD",
        "Content-Type: application/x-www-form-urlencoded"
    ],
    CURLOPT_POSTFIELDS => http_build_query(["json" => json_encode($data)])
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Java (HttpURLConnection)


URL url = new URL("https://app.urbanoexpress.cl/ws/ue/ge/");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("user", "TU_USUARIO");
conn.setRequestProperty("pass", "TU_PASSWORD");
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setDoOutput(true);
String json = "json=" + URLEncoder.encode(yourJson, "UTF-8");
try (OutputStream os = conn.getOutputStream()) {
    os.write(json.getBytes());
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String line;
while ((line = in.readLine()) != null) System.out.println(line);
in.close();

Node.js (axios)


const axios = require('axios');
const qs = require('qs');

const data = qs.stringify({
  json: JSON.stringify({ ... }) // Tu objeto JSON aquí
});

axios.post('https://app.urbanoexpress.cl/ws/ue/ge/', data, {
  headers: {
    'user': 'TU_USUARIO',
    'pass': 'TU_PASSWORD',
    'Content-Type': 'application/x-www-form-urlencoded'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

🏷️ Diseño de Etiqueta

Si deseas diseñar tu propia etiqueta personalizada, es fundamental incluir tanto los datos básicos del destinatario como los datos técnicos entregados por nuestra API.

📦 Datos mínimos obligatorios para la entrega

Nombre del destinatario
Dirección completa
Comuna
Referencias de ubicación

📋 Datos técnicos requeridos por Urbano

Nuestra etiqueta estándar incluye campos clave que permiten su correcta lectura y trazabilidad por parte del sorter y de nuestros operadores logísticos. Esta información debe estar visible y correctamente posicionada para garantizar su procesamiento sin errores.

A continuación, se muestra un ejemplo real de la etiqueta generada automáticamente por nuestro sistema:

🧾 Ejemplo de JSON de Entrada

A continuación se muestra un ejemplo completo del cuerpo JSON que debe enviarse dentro de la variable json en una llamada POST con Content-Type: application/x-www-form-urlencoded.

{
    "linea": 3,
    "id_contrato": "2362",
    "cod_rastreo": "5410724479257",
    "fech_emi_vent": "13/09/2023",
    "nro_o_compra": "1015",
    "nro_guia_trans": "1",
    "nro_factura": "1",
    "cod_cliente": "7234047672601",
    "nom_cliente": "Fabian Delgado",
    "nom_empresa": "FaceWOD Limitada",
    "nro_telf": "null",
    "nro_telf_mobil": "null",
    "correo_elec": "[email protected]",
    "dir_entrega": "Providencia 119",
    "nro_via": "0",
    "nro_int": "2219",
    "nom_urb": "",
    "ubi_direc": "13128",
    "ref_direc": "0",
    "id_direc": "0",
    "fech_pro": "13/09/2023",
    "arco_hor": "PM",
    "fech_venc": "13/09/2023",
    "nom_autorizado": "",
    "nro_doc_autorizado": "",
    "nom_autorizado_2": "",
    "nro_doc_autorizado_2": "",
    "med_pago": "",
    "descripcion": "",
    "anotacion": "",
    "moneda": "PESO",
    "importe": "630",
    "peso_total": "0",
    "pieza_total": "1",
    "urgente": "NO",
    "picking": "NO",
    "mecanizado": "SI",
    "asegurado": "SI",
    "monto_asegurado": "0630",
    "via_aereo": "NO",
    "venta_seller": "NO",
    "sell_codigo": "",
    "sell_nombre": "",
    "sell_direcc": "",
    "sell_ubigeo": "",
    "productos": [
      {
        "cod_sku": "sku-managed-1",
        "barra_sku": "8414951211289",
        "descr_sku": "The Multi-managed Snowboard",
        "modelo_sku": "",
        "marca_sku": "",
        "peso_sku": "1",
        "peso_v_sku": "0",
        "valor_sku": "630",
        "cantidad_sku": "1",
        "alto": "10",
        "largo": "10",
        "ancho": "10"
      }
    ],
    "cedibles": [
      {
        "cod_pod": "059",
        "descr_pod": "48070604"
      }
    ]
  }

❌ Ejemplos de Respuestas con Error

A continuación se presentan ejemplos de respuestas de error que el servicio puede retornar ante problemas de validación de datos, autenticación o integridad de la información enviada.

🔐 Usuario inválido

[
  {
    "sql_error": "-1",
    "msg_error": "Ocurrio un error al tratar validar el usuario"
  }
]

📄 Falta el `id_contrato` o no coincide con el shipper

{
  "error": -1,
  "mensaje": "Shipper y Contrato no Coinciden, Verificar con Urbano ...",
  "guia": 0
}

📍 Código de comuna inválido (`ubi_direc`)

{
  "error": -1,
  "mensaje": "Codigo ubigeo del Distrito/Localidad no es Valido",
  "guia": 0
}

📦 JSON no enviado o vacío

{
  "error": -1,
  "mensaje": "La variable \"json\" esta vacia",
  "guia": null
}

📘 Descripción de errores comunes

Código/Error	Mensaje	Causa probable	Acción recomendada
`sql_error = -1`	"Ocurrio un error al tratar validar el usuario"	Usuario o contraseña inválidos en autenticación HTTP	Verifica que el `user` y `pass` sean correctos y estén habilitados
`error = -1`	"Shipper y Contrato no Coinciden..."	El `id_contrato` enviado no está asociado al cliente autenticado	Solicita el contrato correcto a tu ejecutivo comercial
`error = -1`	"Codigo ubigeo... no es Valido"	El valor en `ubi_direc` no corresponde a una comuna válida o habilitada	Consulta la tabla de comunas habilitadas por Urbano
`error = -1`	"La variable "json" esta vacia"	No se envió el parámetro `json` o su contenido está en blanco	Asegúrate de enviar un JSON válido usando `--data-urlencode 'json=...'`

📍 Códigos Ubigeo

Para completar correctamente el campo ubi_direc en el JSON, debes utilizar un código de comuna oficial según el INE (Instituto Nacional de Estadísticas de Chile).

Estos códigos corresponden al identificador único de cada comuna, y es fundamental que se mantenga el formato exacto, incluyendo los ceros a la izquierda.

Por ejemplo: 013101 (Santiago), 013128 (Providencia), etc.

📥 Puedes descargar la lista completa de códigos Ubigeo (formato Excel) desde el siguiente enlace:
Descargar archivo de códigos Ubigeo

🧪 Formulario de Prueba Integrado

Para facilitar el proceso de integración y pruebas, hemos incorporado un formulario funcional que te permite probar el servicio de generación de etiquetas directamente desde esta documentación.

Este formulario envía un JSON de ejemplo al endpoint de producción, utilizando autenticación básica y la estructura de datos esperada. El resultado se muestra directamente en pantalla, incluyendo la guía generada y el enlace a la etiqueta PDF.

✅ Ideal para desarrolladores que desean verificar rápidamente el comportamiento del servicio con datos reales.