Z-Bombilla API

Conecta tus sistemas, automatiza procesos y potencia tu logística con nuestra potente API REST.

Ver documentación

Endpoints principales

Consulta rápida a los servicios clave de la API REST

Crear envío

POST /api/envios

Crea un nuevo envío proporcionando remitente, destinatario y bultos.

Consultar envío

GET /api/envios/{id}

Consulta el estado y detalles de un envío existente.

Tarifas disponibles

POST /api/tarifas

Consulta tarifas para un envío antes de confirmarlo.

Autenticación

Accede a la API de forma segura mediante token

Para utilizar la API necesitas un token de acceso.

Solicítalo a través de nuestro equipo de soporte.

Authorization: Bearer {tu_token}

Integraciones disponibles

Compatible con los principales marketplaces y ERPs

Amazon

Amazon

ZBombillaAPI

ZBombillaAPI

Prestashop

Prestashop

POST /envio/calcularEnvio

Calcula las tarifas disponibles para un posible envío, según el país de destino, código postal, valor de la mercancía y los bultos indicados.

Autenticación

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

Parámetros del cuerpo (form-data)

Parámetro Tipo Obligatorio Descripción
tipoPortes string No Valores posibles: Pagados (por defecto), Contrareembolso.
valorMercancia decimal Condicional Opcional si el país es ES, obligatorio y mayor que 0 para otros países.
paisCliente string No Código ISO (ej. ES) o ID del país. Por defecto: ES.
codigoPostal string Sí Código postal de destino.
largo, ancho, alto, peso arrays Sí Debe indicarse al menos un conjunto de medidas. Todos deben tener la misma longitud.

Respuesta esperada (HTTP 200)

Una lista de agencias con tarifas calculadas:

[
  {
    "nombreAgenciaCalculada": "CorreosExpress",
    "precioPorte": 4.52,
    "precioSeguro": 100.00,
    "precioReembolso": 0.00,
    "precioTotal": 4.52,
    "isGood": true,
    "errors": []
  }
]

Detalles importantes

  • precioSeguro: No representa un coste, sino el importe máximo cubierto en caso de pérdida o rotura.
  • isGood: Indica si la agencia puede calcular un precio válido con éxito.

Errores posibles (HTTP 400)

Si hay errores en los parámetros, se devuelve un JSON con la lista de errores detectados:

{
  "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 adicionales

  • Este endpoint solo calcula tarifas. No guarda ni registra el envío.
  • Los campos como nombreCliente, teléfonoCliente, etc., se desecharán y no afectan al resultado del cálculo.
  • Se recomienda validar que isGood sea true antes de usar la tarifa.

GET /codigoPostalLookup

Obtiene la información de una población a partir del código postal. Devuelve datos como la población y la provincia asociadas.

Parámetros de la URL

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

Ejemplo de uso

Se puede llamar directamente mediante una URL como:

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

Respuesta esperada (HTTP 200)

Un array de objetos JSON con la información encontrada. Si no hay resultados, se devuelve un array vacío [].

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

Notas adicionales

  • Este endpoint no requiere autenticación.
  • Devuelve siempre un array JSON, aunque no se encuentren resultados.

POST /api/envio/doEnvio

Genera el envío definitivo, crea el número de seguimiento y devuelve las etiquetas en base64 listas para imprimir.

Autenticación

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

Parámetros del cuerpo (JSON)

Parámetro Tipo Obligatorio Descripción
agencia.nombreAgenciaCalculada string Sí Nombre de la agencia calculada (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 del envío (opcional). Ejemplo el número de pedido.
envio.descripcionEnvio string Condicional Obligatoria si el destino es internacional y la agencia es UPS. Describe el contenido. Ejemplo de la categoría del producto: "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 Código ISO del país. Por defecto ES.
envio.destinatario.provincia string No Provincia del destinatario. No se tendrá en cuenta para envíos a España. Obtenemos la provincia del código Postal.
envio.destinatario.poblacion string No Población del destinatario.
envio.destinatario.codigoPostal string Sí Código postal del destinatario.
envio.destinatario.telefono string No Teléfono de contacto.
envio.destinatario.email string No Email de contacto.
envio.destinatario.observaciones string No Observaciones adicionales.
envio.bultos[] array Sí Listado de bultos. Debe incluir al menos uno.
envio.bultos[].largo decimal Sí Largo en centímetros.
envio.bultos[].ancho decimal Sí Ancho en centímetros.
envio.bultos[].alto decimal Sí Alto en centímetros.
envio.bultos[].peso decimal Sí Peso en kilogramos.
envio.valorMercancia decimal Condicional Obligatorio si el país no es ES (debe ser mayor que 0).
envio.envioConRetorno boolean No Indica si el envío debe ser con recogida del retorno. Solo Envialia, MRW, CorreosExpress.

Respuesta esperada (HTTP 200)

Devuelve un objeto JSON con el número de seguimiento y las etiquetas generadas:

{
  "numSeguimiento": "1234567890",
  "olEtiquetas": [
    "Base64Etiqueta1",
    "Base64Etiqueta2"
  ]
}

Prueba rápida de las etiquetas

Dispones de un panel web para visualizar y probar el resultado de este endpoint. Puedes copiar el JSON de respuesta (numSeguimiento y olEtiquetas) y pegarlo directamente en:

Desde ahí podrás ver, abrir o descargar las etiquetas generadas en formato PDF.

Errores posibles

  • 400 Bad Request: Si falta algún campo obligatorio o hay validaciones fallidas.
  • 401 Unauthorized: Si el token no es válido o no se proporciona.
{
  "error": "Falta campo obligatorio: envio.destinatario.nombre"
}

Notas adicionales

  • El número de seguimiento se genera automáticamente tras completar el envío.
  • Las etiquetas vienen codificadas en Base64 listas para imprimir o generar PDF.
  • Se recomienda verificar que la agencia tenga isGood = true antes de hacer la solicitud.