# Z-Bombilla Shipping — Tracking API Specification

**Version:** 1.1  
**Base URL:** `https://shipping.z-bombilla.com`  
**Contact:** envios@z-bombilla.com

---

## Overview

Z-Bombilla Shipping is a last-mile carrier operating in Spain (provinces: Alicante 03,
Castellón 12, Murcia 30, Valencia 46). Tracking events are provided in real time from
our logistics partner network.

---

## Tracking Endpoint

### Request

```
GET https://shipping.z-bombilla.com/envio/seguimiento
```

| Parameter        | Type   | Required | Description                            |
|------------------|--------|----------|----------------------------------------|
| `numSeguimiento` | string | **Yes**  | Shipment tracking number               |
| `datos`          | string | No       | Response format. Default: `view`       |

### `datos` values

| Value          | Output                          | Use case                      |
|----------------|---------------------------------|-------------------------------|
| `view`         | HTML page                       | iframe / modal embed          |
| `json`         | JSON array — full event list    | System integration, Amazon    |
| `ultimoestado` | JSON object — current status    | Badge / dashboard widget      |
| `trackingurl`  | HTTP redirect to carrier page   | Quick link                    |

---

## JSON Response — Full Event List (`datos=json`)

Returns an array of tracking events ordered chronologically (most recent first).

```json
[
  {
    "etiqueta": "KC9000072192",
    "tipo": "Canalizado centro logístico",
    "fecha": "2026-07-30T00:00:00+02:00",
    "hora": "PT11H48M43S",
    "base": "CASTELLON",
    "descripcion": "Destinatario ausente",
    "traAccion": "AVI",
    "traTipoLectura": "T",
    "orden": 90
  },
  ...
]
```

### Field Reference

| Field            | Type    | Description                                                              |
|------------------|---------|--------------------------------------------------------------------------|
| `etiqueta`       | string  | Tracking number (matches `numSeguimiento`)                               |
| `tipo`           | string  | Carrier category label                                                   |
| `fecha`          | string  | Event date — ISO 8601 (`2026-07-30T00:00:00+02:00`)                     |
| `hora`           | string  | Event time — ISO 8601 duration (`PT11H48M43S` = 11:48:43)               |
| `base`           | string  | Handling depot name                                                      |
| `descripcion`    | string  | Human-readable event description (Spanish)                               |
| `traAccion`      | string  | **Machine-readable status code** (see table below)                       |
| `traTipoLectura` | string  | Reading type: `P` pickup · `T` transit · `D` delivery                   |
| `orden`          | integer | Carrier internal category code (not chronological order)                 |

> **Time parsing:** `hora` uses ISO 8601 duration notation. `PT11H48M43S` → 11 h 48 m 43 s.
> The `fecha` field carries date information only (time part is always `T00:00:00`).
> Combine `fecha` (date) + `hora` (duration) to reconstruct the full event timestamp.

---

## JSON Response — Current Status (`datos=ultimoestado`)

```json
{
  "estado": "Destinatario ausente",
  "color": "#FF1E1E80"
}
```

| Field    | Type   | Description                          |
|----------|--------|--------------------------------------|
| `estado` | string | Current status label (Spanish)       |
| `color`  | string | RGBA hex color for UI badge rendering |

### Color Legend

| Hex color    | Meaning                          |
|--------------|----------------------------------|
| `#00660080`  | Delivered                        |
| `#FFFF0080`  | In transit / Pending             |
| `#FF1E1E80`  | Issue / Absence / Cancelled      |
| `#0066FF80`  | Return to sender                 |

---

## TraAccion Status Codes

### Delivered ✓ (final state)

| Code  | EN                              | ES                            |
|-------|---------------------------------|-------------------------------|
| `SEF` | Delivered                       | Entregado                     |
| `SEZ` | Delivered                       | Entregado                     |
| `SFD` | Delivered                       | Entregado                     |
| `SFT` | Delivered                       | Entregado                     |
| `SHR` | Delivered                       | Entregado                     |
| `SI`  | Delivered                       | Entregado                     |
| `YES` | Delivered                       | Entregado                     |
| `ZENT`| Delivered                       | Entregado                     |
| `PSI` | Delivered to collection point   | Entregado en Punto Xpress     |

### In Transit

| Code  | EN                              | ES                                    |
|-------|---------------------------------|---------------------------------------|
| `ONB` | Out for delivery                | En Reparto                            |
| `DST` | Out for delivery                | En Reparto                            |
| `SEM` | Out for delivery                | En Reparto                            |
| `TRR` | In transit                      | En tránsito                           |
| `CRZ` | In transit to destination hub   | En tránsito a Base Destino            |
| `ARR` | Routed to destination hub       | Canalizado hacia Base Destino         |

### Hub Processing

| Code  | EN                              | ES                                    |
|-------|---------------------------------|---------------------------------------|
| `FCF` | Channelled to logistics centre  | Canalizado a centro logístico         |
| `FCM` | Channelled to logistics centre  | Canalizado a centro logístico         |
| `FCO` | Channelled to logistics centre  | Canalizado a centro logístico         |
| `FCV` | Channelled to logistics centre  | Canalizado a centro logístico         |
| `RBA` | Received at hub                 | Recepcionado en Base                  |
| `OPE` | Handled by external operator    | Canalizado por operador externo       |
| `CPX` | Received at collection point    | Recepcionado en Punto Xpress          |
| `SPX` | Available at collection point   | Disponible en Punto Xpress            |

### Pickup

| Code  | EN                                        | ES                                          |
|-------|-------------------------------------------|---------------------------------------------|
| `REC` | Collected                                 | Recogido                                    |
| `REF` | Collected                                 | Recogido                                    |
| `ORS` | Pickup order requested                    | Solicitud Orden Recogida                    |
| `PRC` | Collected at collection point             | Recogida en Punto Xpress                    |
| `PXC` | Courier collecting at collection point    | Courier recoge en Punto Xpress              |
| `NP1` | Not ready for pickup                      | Recogida no preparada                       |
| `NP2` | Not ready for pickup — 2nd attempt        | Recogida no preparada — 2º intento          |
| `NRE` | Pickup not found at collection point      | Recogida no existe en Punto Xpress          |

### Absence / Failed Delivery

| Code  | EN                                | ES                                  |
|-------|-----------------------------------|-------------------------------------|
| `AVI` | Recipient absent                  | Destinatario ausente                |
| `AV2` | Recipient absent — 2nd attempt    | Destinatario ausente — 2º intento   |
| `CIT` | Appointment required              | Cita previa necesaria               |
| `ESP` | Excessive wait time               | Espera excesiva                     |
| `VAC` | Closed — holiday                  | Cerrado por vacaciones              |
| `ZCON`| In contact with recipient         | En contacto con el destinatario     |
| `ZCIT`| New delivery appointment          | Nueva entrega concertada            |
| `ZREP`| Delivery rescheduled              | Reparto reprogramado                |

### Incidents

| Code  | EN                                | ES                                  |
|-------|-----------------------------------|-------------------------------------|
| `IND` | Incorrect address                 | Dirección incorrecta                |
| `INP` | Collection point incident         | Incidencia Punto Xpress             |
| `IOR` | Pickup order incident             | Incidencia Orden Recogida           |
| `ROT` | Shipment damaged                  | Rotura del envío                    |
| `ZGES`| Issue being handled               | Incidencia en gestión               |
| `ZRET`| Held at warehouse                 | Retenido en almacén                 |
| `ZEXT`| Lost — investigation open         | Extraviado — investigación abierta  |

### Returns

| Code  | EN                                | ES                                  |
|-------|-----------------------------------|-------------------------------------|
| `RTS` | Return to sender                  | Devolución a remitente              |
| `RTC` | Return to sender — closed         | Devolución a remitente — Cerrado    |
| `RTR` | Return by sender instruction      | Devolución por orden remitente      |
| `PRT` | Return from collection point      | Devolución desde Punto Xpress       |
| `ZDEV`| Return in progress                | Devolución en curso                 |

### Special

| Code          | EN                    | ES                              |
|---------------|-----------------------|---------------------------------|
| `SIN_EVENTOS` | Pending first scan    | Pendiente de primer escaneo     |
| `Anulado` · `ZANU` | Cancelled        | Envío anulado                   |
| `ZNOT`        | Informational note    | Nota informativa                |

---

## `Z`-prefixed code variants

Some states may arrive with a leading `Z` (`ZSFT`, `ZAVI`, `ZRTS`…). This is a
recording variant of **the same state**: it means exactly what the code without
the `Z` means.

> **Integration rule:** if you receive a `traAccion` that is not in the tables
> above and starts with `Z`, strip the leading `Z` and apply the mapping you
> already have for the base code. That way a new code never breaks your
> integration.

On these events `traTipoLectura` may be empty and `orden` is `0`; neither field
is required to determine the state — use `traAccion`.

---

## Error Responses

| HTTP  | Condition                                           |
|-------|-----------------------------------------------------|
| `400` | `numSeguimiento` parameter missing                  |
| `404` | No shipment found with that tracking number         |
| `501` | Carrier tracking not supported for this shipment    |
| `500` | Unexpected server error                             |

---

## Coverage

Z-Bombilla Shipping operates within the following Spanish provinces only.
Shipments with destination postal codes outside these prefixes will not be accepted.

| Province   | Postal code prefix | NUTS code |
|------------|--------------------|-----------|
| Alicante   | 03                 | ES521     |
| Castellón  | 12                 | ES522     |
| Murcia     | 30                 | ES620     |
| Valencia   | 46                 | ES523     |

---

## Rate Limits

| Parameter                  | Value |
|----------------------------|-------|
| Max requests/second (TPS)  | 10    |
| Authentication required    | No    |

---

## Real-World Examples

### Example 1 — Absent recipient

**Tracking number:** `KC9000072192`

```
GET https://shipping.z-bombilla.com/envio/seguimiento?datos=json&numSeguimiento=KC9000072192
```

```json
[
  {
    "etiqueta": "KC9000072192",
    "traAccion": "AVI",
    "descripcion": "Destinatario ausente",
    "fecha": "2026-07-30T00:00:00+02:00",
    "hora": "PT11H48M43S",
    "base": "CASTELLON"
  },
  {
    "etiqueta": "KC9000072192",
    "traAccion": "ONB",
    "descripcion": "En Reparto",
    "fecha": "2026-07-30T00:00:00+02:00",
    "hora": "PT10H9M10S",
    "base": "CASTELLON"
  },
  {
    "etiqueta": "KC9000072192",
    "traAccion": "FCV",
    "descripcion": "Canalizado a centro logístico",
    "fecha": "2026-07-28T00:00:00+02:00",
    "hora": "PT12H22M8S",
    "base": "NOVETLE"
  },
  {
    "etiqueta": "KC9000072192",
    "traAccion": "REC",
    "descripcion": "Recogido",
    "fecha": "2026-07-28T00:00:00+02:00",
    "hora": "PT12H1M43S",
    "base": "NOVETLE"
  }
]
```

**Summary:** Collected 28 July at Novetle hub, loaded for delivery 30 July, recipient absent at 11:48.

---

### Example 2 — Address incident

**Tracking number:** `KC5000073888`

```
GET https://shipping.z-bombilla.com/envio/seguimiento?datos=json&numSeguimiento=KC5000073888
```

```json
[
  {
    "etiqueta": "KC5000073888",
    "traAccion": "IND",
    "descripcion": "Incidencia Dirección Incorrecta",
    "fecha": "2026-08-04T00:00:00+02:00",
    "hora": "PT8H58M50S",
    "base": "CASTELLON"
  },
  {
    "etiqueta": "KC5000073888",
    "traAccion": "ONB",
    "descripcion": "En Reparto",
    "fecha": "2026-08-04T00:00:00+02:00",
    "hora": "PT8H53M54S",
    "base": "CASTELLON"
  },
  {
    "etiqueta": "KC5000073888",
    "traAccion": "FCV",
    "descripcion": "Canalizado a centro logístico",
    "fecha": "2026-07-30T00:00:00+02:00",
    "hora": "PT12H26M56S",
    "base": "NOVETLE"
  },
  {
    "etiqueta": "KC5000073888",
    "traAccion": "REC",
    "descripcion": "Recogido",
    "fecha": "2026-07-30T00:00:00+02:00",
    "hora": "PT12H1M32S",
    "base": "NOVETLE"
  }
]
```

**Summary:** Collected 30 July, out for delivery 4 August at 08:53, incorrect address incident flagged at 08:58.

---

## Current Status — `ultimoestado` examples

```
GET .../envio/seguimiento?datos=ultimoestado&numSeguimiento=KC9000072192
```
```json
{ "estado": "Destinatario ausente", "color": "#FF1E1E80" }
```

```
GET .../envio/seguimiento?datos=ultimoestado&numSeguimiento=KC5000073888
```
```json
{ "estado": "Dirección incorrecta", "color": "#FF1E1E80" }
```

---

## Changelog

| Version | Date    | Notes               |
|---------|---------|---------------------|
| 1.0     | 2026-08 | Initial release     |

---

*Z-Bombilla Spain, S.L. · shipping.z-bombilla.com · envios@z-bombilla.com*