Z-Bombilla API

Resumen

• Tipo: application/x-www-form-urlencoded (form POST)
• Acción: Shipping decodifica envioJson y muestra el formulario con datos precargados.
• Opcional:
  • itemsJson: productos (para pintar tabla ?Productos Marketplace?).
  • alertasMarketplace: lista de avisos (para pintar el bloque de alertas).
  • accessToken: auto-login / autorización (si aplica).
  • order_id: id de pedido del marketplace (ej. Woo) para asociar tracking.
  • combined: indica modo combinado (0/1).

Parámetros

Cómo construir envioJson

Es el JSON de tu EnvioV3DTO codificado en Base64 (UTF-8). En tu UI se genera así al ?Modificar envío actual?:

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). Este JSON termina en window.marketplaceItems y se renderiza con lógica flexible: usa name/title, image/img, sku/sellerSKU, qty/quantity, price/itemPriceAmount.

Campos detectados por el frontend (según tu JS)

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 una lista: ?Alertas del pedido?.

Formatos aceptados (según parseAlertasMarketplace())

Ejemplo JSON (antes de Base64)

[
  "? Este pedido ya consta como ENVIADO (TRK: 1234567890).",
  "? El pedido NO está listo para enviarse porque su estado actual es ?En espera? (wc-on-hold).",
  "Pedido marcado como urgente"
]

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

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

Parámetros del cuerpo (JSON)

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:

• URL del panel de prueba: https://shipping.z-bombilla.com/envio/testVerEtiqueta

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.

POST /apiV2/documentos/facturas

Crea un documento de facturación remoto (Factura / Rectificativa / etc. según la plantilla). Devuelve id, rand y referencia.

Autenticación

Requisitos previos

• El token debe pertenecer a un usuario válido.
• La cuenta debe tener facturación activa (FacturacionUsuarioSettings.activo=true).
• id_plantillasFactura debe existir y pertenecer al rol.

Body (JSON)

Respuesta esperada (HTTP 200)

{
  "success": true,
  "id": 123,
  "rand": 123456789,
  "referencia": "INV-ES-00001",
  "fecha": "2026-01-01",
  "url": "https://finanzas.z-bombilla.com/...",
  "total": 121,
  "iva": 21,
  "neto": 100,
  "irpf": 0,
  "re": 0,
  "message": "Documento creado correctamente."
}

PUT /apiV2/documentos/facturas?id={id}

Edita un documento existente. El id va como query param.

Notas de edición de líneas

• Las líneas con detalles[].id se actualizan.
• Las líneas sin id se crean.
• Las líneas existentes que no se incluyan en detalles se eliminan.

Errores posibles

• 400 Bad Request: validaciones fallidas (plantilla, campos requeridos, etc.).
• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 404 Not Found: documento no encontrado o no pertenece al rol.
• 500 Internal Server Error: error interno.

{
  "success": false,
  "error": "Falta campo obligatorio: id_plantillasFactura"
}

Notas adicionales

• La numeración (referencia) y el rand se generan automáticamente al crear.
• Se recomienda enviar precio con decimales (hasta 3) para minimizar redondeos.

GET /apiV2/documentos

Devuelve un listado paginado de documentos de facturación (según filtros).

Autenticación

Query params

Respuesta (HTTP 200)

Devuelve filas, total y años disponibles para el conjunto actual (tipo/plantilla).

{
  "rows": [
    {
      "id": 123,
      "pagado": false,
      "numero": "INV-ES-00001",
      "fecha": "01/01/2026",
      "cliente": "Cliente SL",
      "total": "121,00 ?",
      "comment": "Revisar",
      "rand": 123456789
    }
  ],
  "total": 1,
  "yearsAvailable": [2026, 2025, 2024]
}

Errores posibles

• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 400 Bad Request: parámetros inválidos (por ejemplo tipo inválido si lo validas).
• 500 Internal Server Error: error interno.

{
  "error": "Usuario no autenticado"
}

Notas

• yearsAvailable está ordenado de más reciente a más antiguo.
• Los campos total y fecha vienen formateados (human friendly). Para cálculos, usa los endpoints de detalle / export si los añades.

GET /apiV2/documentos/years

Devuelve los años disponibles para el conjunto actual de documentos (según tipo y/o idPlantillasFactura).

Autenticación

Query params

Respuesta (HTTP 200)

Lista de años ordenados de más reciente a más antiguo.

{
  "yearsAvailable": [2026, 2025, 2024]
}

Errores posibles

• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 400 Bad Request: parámetros inválidos (por ejemplo tipo inválido si lo validas).
• 500 Internal Server Error: error interno.

{
  "error": "Usuario no autenticado"
}

Notas

• Útil para construir selectores de año en integraciones/ERP.
• Si no hay documentos, puede devolver el año actual como fallback (según implementación).

GET /apiV2/documentos/plantillas

Devuelve las plantillas disponibles (activas) para el rol. Puede filtrar por tipo.

Autenticación

Query params

Respuesta (HTTP 200)

Devuelve un array con id y nombre de cada plantilla.

{
  "success": true,
  "rows": [
    { "id": 12, "nombre": "Factura Nacional" },
    { "id": 13, "nombre": "Factura UE" }
  ]
}

Errores posibles

• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 400 Bad Request: tipo inválido (si lo validas en backend).
• 500 Internal Server Error: error interno.

{
  "error": "Usuario no autenticado"
}

Notas

• Útil para construir selectores de plantilla en integraciones.
• Si no se envía tipo, devuelve todas las plantillas activas del rol.

GET /apiV2/documentos/pendientes/summary

Devuelve un resumen de documentos pendientes (contador y suma de importes) para el rol del token.

Autenticación

Descripción

• El resumen se calcula sobre documentos del rol que cumplan la condición de ?pendiente? según la lógica de tu backend.
• El tipo de documento incluido suele limitarse a plantillas de tipo FACTURA activas (según tu query interna).

Respuesta (HTTP 200)

{
  "count": 5,
  "totalImporte": 1234.56
}

Errores posibles

• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 500 Internal Server Error: error interno.

{
  "error": "Cuenta de facturación no activa"
}

Notas

• totalImporte es un número (no formateado). Útil para dashboards y KPIs.

POST /apiV2/documentos/togglePagado

Alterna el estado de pagado de un documento (true/false) dentro del rol del token.

Autenticación

Parámetros

Respuesta (HTTP 200)

{
  "success": true,
  "pagado": true
}

Errores posibles

• 400 Bad Request: ID inválido o ausente.
• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 404 Not Found: documento no encontrado o fuera del rol.
• 500 Internal Server Error: error interno.

{
  "error": "Factura no encontrada"
}

Notas

• Este endpoint hace ?toggle?: si estaba pagado pasa a pendiente y viceversa.
• Se registra acción en el log del sistema.

POST /apiV2/documentos/updateComment

Actualiza el comentario interno (comment) de un documento dentro del rol del token.

Autenticación

Parámetros

Respuesta (HTTP 200)

{
  "success": true
}

Errores posibles

• 400 Bad Request: ID inválido o ausente.
• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 404 Not Found: documento no encontrado o fuera del rol.
• 500 Internal Server Error: error interno.

{
  "error": "Factura no encontrada"
}

Notas

• Se registra acción en el log del sistema.
• El comentario es interno (no necesariamente visible al cliente final).

POST /apiV2/documentos/delete

Elimina un documento si cumple las validaciones (rol, presentado, numeración posterior, etc.).

Autenticación

Parámetros

Validaciones (resumen)

• El documento debe existir y pertenecer al rol del token.
• Si el documento es de tipo FACTURA o RECTIFICACIONES:
  • No puede estar ?presentado? (según periodoFin en backend).
  • No puede haber documentos posteriores con numeración mayor en el mismo año/plantilla.

Respuesta (HTTP 200)

{
  "success": true
}

Errores posibles

• 400 Bad Request: ID inválido o ausente.
• 401 Unauthorized: token ausente o inválido.
• 403 Forbidden: facturación no activa.
• 404 Not Found: documento no encontrado o fuera del rol.
• 409 Conflict: No se puede eliminar por reglas de negocio (presentado o hay numeración posterior).
• 500 Internal Server Error: error interno.

Ejemplo de error 409

{
  "error": "No se puede eliminar esta factura porque existen facturas con numeración posterior en 2026."
}

Notas

• Se registra acción en el log del sistema cuando la eliminación es correcta.
• Este endpoint elimina también las líneas asociadas al documento.