Documentación Shipping

Tarifas, creación y gestión de envíos: endpoints, parámetros y ejemplos listos para usar.

Volver a Documentación Ver endpoints
POST

/nuevoEnvio Pasarela de creación de envío

Abre Shipping con datos precargados (envío + destinatario + bultos) y, opcionalmente, productos y alertas del pedido.

itemsJson alertasMarketplace

Resumen

Content-Type: application/x-www-form-urlencoded Entrada: envioJson (Base64 JSON) Opcionales: itemsJson, alertasMarketplace, accessToken, order_id, combined
Qué hace: Shipping decodifica envioJson y muestra el formulario con los datos precargados.

Autenticación

Si tu integración utiliza token, puedes enviar accessToken para auto-login/autorización (según tu flujo).

Parámetros

Nombre Tipo Oblig. Descripción
envioJson string (Base64 JSON) Sí Base64 del JSON de EnvioV3DTO (UTF-8). Es el payload principal.
idExpedicion number No Si se envía, Shipping carga una expedición existente y precarga el formulario (editar/duplicar).
marketplaceName string No Nombre del marketplace para rotular el bloque de productos (ej. WooCommerce).
itemsJson string (Base64 JSON) No Lista de productos/líneas del pedido. Ver detalle
alertasMarketplace string (JSON/Base64) No Lista de alertas del pedido. Ver detalle
order_id string No ID de pedido del marketplace (para asociar tracking u operaciones posteriores).
combined 0/1 No Si 1, Shipping pinta productos por pedido (modo combinado).
accessToken string No Token para auto-login/autorización (si tu integración lo soporta).
Nota: normalmente envías envioJson. Si envías idExpedicion, puede no ser necesario envioJson (dependiendo del flujo).

Cómo construir envioJson

JSON de EnvioV3DTO codificado en Base64 (UTF-8).

const codificado = btoa(unescape(encodeURIComponent(JSON.stringify(envio))));

Ejemplo de JSON (antes de Base64)

{
  "refEnvio":"WC-12345",
  "tipoPortes":"Pagados",
  "valorTotal":59.90,
  "destinatario":{
    "nombre":"Cliente SL",
    "direccion":"Calle Falsa 123",
    "numero":"1",
    "codigoPostal":"28001",
    "poblacion":"Madrid",
    "provincia":"Madrid",
    "pais":{"isoCode":"ES"},
    "telefono":"600000000",
    "email":"cliente@email.com",
    "observaciones":""
  },
  "olBultos":[{"largo":30,"ancho":20,"alto":10,"peso":1.2}]
}
itemsJson ? productos del pedido

Si envías itemsJson, Shipping podrá pintar el bloque Productos Marketplace (tabla). El frontend es flexible: usa name/title, image/img, sku/sellerSKU, qty/quantity y price/itemPriceAmount.

Formato recomendado: Base64 de un JSON array (UTF-8), enviado por form-urlencoded.

Campos detectados por el frontend

UsoCampos aceptados
Títuloname o title
Imagenimage o img
SKUsku / sku_id / sellerSKU
Cantidadqty / quantity / quantityOrdered
Precioprice o itemPriceAmount
Link productoidProduct + linkProduct (si existen)
Fila gastos envíoisShippingFee = true + name + price

Ejemplo JSON (antes de Base64)

[
  {"name":"Producto 1","sku":"REF1","qty":2,"price":8.264,"image":"https://tuweb/img1.jpg"},
  {"isShippingFee":true,"name":"Gastos de envío","price":4.95}
]
alertasMarketplace ? alertas del pedido

Si envías alertasMarketplace, Shipping lo convierte a List<String> y lo pinta como lista en ?Alertas del pedido?.

Este parámetro es tolerante: acepta JSON array, JSON string con array dentro o Base64 del JSON.

Formatos aceptados

TipoEjemploRecomendación
JSON array ["Este pedido ya consta como ENVIADO (TRK: 123...)", "El pedido está en espera"] Mejor opción si controlas el body
JSON string con array "[\"Mensaje 1\",\"Mensaje 2\"]" Evitar si puedes (solo compatibilidad)
Base64 del JSON array WyJFbCBwZWRpZG8uLi4iLCJPay4uLiJd Recomendado en form-urlencoded

Ejemplo JSON (antes de Base64)

[
  "Este pedido ya consta como ENVIADO (TRK: 1234567890).",
  "El pedido no está listo porque su estado actual es En espera (wc-on-hold).",
  "Pedido marcado como urgente"
]
Fallback: si no se puede parsear, se muestra un único aviso con el texto recibido.
POST

/envio/calcularEnvio Tarificación

Calcula las tarifas disponibles para un envío según destino, código postal, valor de mercancía y bultos.

x-www-form-urlencoded Bultos repetibles Devuelve lista de agencias

Resumen

Content-Type: application/x-www-form-urlencoded Auth: Bearer token
Qué hace: devuelve una lista de agencias con precios calculados (isGood indica si la tarifa es válida).

Autenticación

Incluye el token en cabecera:

Authorization: Bearer {accessToken}

Cabeceras

Cabecera Valor Obligatorio
Authorization Bearer {accessToken} Sí
Content-Type application/x-www-form-urlencoded Sí

Parámetros

Parámetro Tipo Oblig. Descripción
codigoPostal string Sí Código postal de destino.
paisCliente string No Código ISO (ej. ES) o ID del país. Por defecto: ES.
tipoPortes string No Pagados (por defecto) o Contrareembolso.
valorMercancia decimal Cond. Opcional si el país es ES. Obligatorio y > 0 para otros países.
largo, ancho, alto, peso repetible Sí Los bultos se envían repitiendo la misma clave en application/x-www-form-urlencoded.
Importante: todas las listas deben tener el mismo número de valores (mismo nº de bultos).

Ejemplo (1 bulto):
largo=20&ancho=30&alto=40&peso=5

Ejemplo (2 bultos):
largo=20&ancho=30&alto=40&peso=5&largo=25&ancho=35&alto=45&peso=7

Respuesta (HTTP 200)

Lista de agencias con tarifas calculadas:

[
  {
    "nombreAgenciaCalculada": "CorreosExpress",
    "precioPorte": 4.52,
    "precioSeguro": 100.00,
    "precioReembolso": 0.00,
    "precioTotal": 4.52,
    "isGood": true,
    "errors": []
  }
]
  • precioSeguro: no es un coste, es el importe máximo cubierto en caso de incidencia.
  • isGood: valida que la agencia puede calcular la tarifa correctamente.

Errores (HTTP 400)

Si faltan campos o hay validaciones, se devuelve un JSON con errores:

{
  "errores": [
    "codigoPostal es obligatorio",
    "valorMercancia debe ser mayor que 0 para envíos fuera de España",
    "Debe especificar al menos un bulto (largo, ancho, alto, peso)"
  ]
}

Notas

  • Este endpoint solo calcula tarifas (no registra el envío).
  • Valida isGood antes de usar la tarifa.
GET

/codigoPostalLookup Lookup CP

Obtiene población y provincia a partir de un código postal.

Sin autenticación Devuelve array JSON
Ejemplo Respuesta

Resumen

Qué hace: devuelve un array con las coincidencias encontradas (si no hay resultados: []).

Autenticación

No requiere token.

Parámetros (query)

Parámetro Tipo Oblig. Descripción
codigoPostal string Sí Código postal del que obtener población y provincia.

Ejemplo

GET https://shipping.z-bombilla.com/codigoPostalLookup?codigoPostal=03500

Respuesta (HTTP 200)

[
  {
    "poblacion": "Benidorm",
    "codigoPostal": "03501",
    "provincia": "Alicante"
  }
]

Notas

  • Devuelve siempre un array JSON.
  • Si no hay coincidencias: [].
POST

/api/envio/doEnvio Confirmar envío

Genera el envío definitivo, crea el tracking y devuelve las etiquetas en Base64.

application/json Devuelve numSeguimiento Etiquetas Base64
Body Respuesta Errores

Resumen

Content-Type: application/json Auth: Bearer token
Qué hace: confirma el envío con la agencia elegida (de Calcular Envío), genera tracking y produce etiquetas.

Autenticación

Incluye el token:

Authorization: Bearer {accessToken}

Cabeceras

Cabecera Valor Obligatorio
Authorization Bearer {accessToken} Sí
Content-Type application/json Sí

Parámetros del body (JSON)

Campo Tipo Oblig. Descripción
agencia.nombreAgenciaCalculada string Sí Nombre de la agencia (obtenido desde Calcular Envío).
agencia.precioPorte decimal Sí Precio confirmado del porte (obtenido desde Calcular Envío).
envio.tipoPortes string No Pagados (por defecto) o Contrareembolso.
envio.refEnvio string No Referencia interna (por ejemplo nº de pedido).
envio.descripcionEnvio string Cond. Obligatoria si el destino es internacional y la agencia es UPS. Describe el contenido (ej. "Papel Secamanos").
envio.destinatario.nombre string Sí Nombre del destinatario.
envio.destinatario.direccion string Sí Dirección del destinatario.
envio.destinatario.numero string No Número de dirección (opcional).
envio.destinatario.paisISO string No ISO país. Por defecto ES.
envio.destinatario.provincia string No Para envíos a España no se tendrá en cuenta (la provincia se obtiene del CP).
envio.destinatario.poblacion string No Población del destinatario.
envio.destinatario.codigoPostal string Sí Código postal.
envio.destinatario.telefono string No Teléfono de contacto.
envio.destinatario.email string No Email de contacto.
envio.destinatario.observaciones string No Observaciones.
envio.bultos[] array Sí Listado de bultos (mínimo 1).
envio.bultos[].largo decimal Sí Largo (cm).
envio.bultos[].ancho decimal Sí Ancho (cm).
envio.bultos[].alto decimal Sí Alto (cm).
envio.bultos[].peso decimal Sí Peso (kg).
envio.valorMercancia decimal Cond. Obligatorio si el país no es ES (debe ser > 0).
envio.envioConRetorno boolean No Solo Envialia, MRW, CorreosExpress. Indica retorno.

Respuesta (HTTP 200)

{
  "numSeguimiento": "1234567890",
  "olEtiquetas": [
    "Base64Etiqueta1",
    "Base64Etiqueta2"
  ]
}
Panel de prueba: puedes pegar el JSON de respuesta y previsualizar etiquetas en: https://shipping.z-bombilla.com/envio/testVerEtiqueta

Errores

  • 400 Bad Request: validación / faltan campos.
  • 401 Unauthorized: token inválido o no enviado.
{
  "error": "Falta campo obligatorio: envio.destinatario.nombre"
}

Notas

  • El tracking se genera al confirmar el envío.
  • Las etiquetas vienen en Base64 listas para imprimir o convertir a PDF.
  • Se recomienda usar agencia con isGood = true desde Calcular Envío.