> For the complete documentation index, see [llms.txt](https://docs.zipnova.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zipnova.com/rutas/conceptos.md).

# Conceptos

## Organizaciones

Una organización es el núcleo del sistema — representa una empresa operadora (carrier) o remitente (shipper), o ambas. Cada organización tiene un `subdomain` único que determina qué API endpoints son accesibles. A través del endpoint `GET /organizations/my` podés obtener los datos de tu propia organización: nombre, zona horaria, moneda, tipo de servicio por defecto, y configuraciones visuales. También podés consultar tus **contratos** (relaciones con otras organizaciones) y tus **lugares** (direcciones guardadas).

## Envíos

Un envío representa un paquete o conjunto de paquetes que necesita ser movido de un origen a un destino. Tiene:

* **Referencias**: `control_number` (generado automáticamente, 5 chars), `external_reference` (tu referencia interna)
* **Partes**: `shipper` (quien envía), `carrier` (quien opera), `origin` y `destination` (direcciones)
* **Contenido**: packages con peso, volumen, y `declared_value` para seguros
* **Ciclo de vida** — estados progresivos:

| Estado               | Descripción            |
| -------------------- | ---------------------- |
| `pending`            | Creado, sin procesar   |
| `shipped`            | En tránsito            |
| `picked_up`          | Retirado               |
| `in_facility`        | En depósito/hub        |
| `out_for_delivery`   | En camino a destino    |
| `attempted_delivery` | Intento fallido        |
| `delivered`          | Entregado exitosamente |
| `not_delivered`      | No se pudo entregar    |
| `cancelled`          | Cancelado              |

Los estados de envío se pueden personalizar en cada organización.

También soporta **tracking** individual y bulk, etiquetas, adjuntos, y cotizaciones previas a la creación.<br>

## Workflows

Los **Blueprints** son plantillas reutilizables que definen cómo se ejecuta un proceso logístico. Cada Blueprint tiene una serie de **Steps** (pasos) que configuran:

* Qué tipo de tarea se crea en ese paso (pickup, delivery, etc.)
* Qué requisitos deben cumplirse para iniciar, completar o fallar
* Qué **acciones** se ejecutan automáticamente al completar/fallar el paso: crear la siguiente tarea, cancelar tareas restantes, disparar un evento, iniciar otro workflow, etc.

Un **Workflow** es una instancia de un Blueprint para un caso concreto. Al crear un workflow se le pasa `data` (origen, destino, paquetes, etc.) y él se encarga de generar las tareas necesarias siguiendo los pasos del Blueprint.

{% code overflow="wrap" %}

```
Blueprint (plantilla) → Steps (pasos configurados)Workflow (instancia)  → Tasks (tareas ejecutadas)
```

{% endcode %}

Estados del workflow: `new` → `scheduled` / `cancelled`

## Tareas

Una tarea es la unidad ejecutable del sistema — lo que un repartidor o operario realmente realiza. Puede ser un retiro, una entrega, una inspección, etc. Cada tarea:

* Pertenece a un **Workflow** y a un **Step** específico del blueprint
* Puede estar asociada a un **Envío** (o no, si es una tarea standalone)
* Tiene una **dirección** de ejecución
* Puede asignarse a un **usuario**
* Soporta **dependencias** entre tareas (una tarea espera a que otra termine)
* Tiene **ventanas horarias** (`time_windows`) y restricciones de tiempo
* Registra **firma** del receptor (`signed_by`) y **adjuntos**

#### Estados de la tarea

| Estado      | Descripción                                                     |
| ----------- | --------------------------------------------------------------- |
| `pending`   | Pendiente de ejecución                                          |
| `started`   | En camino / iniciada                                            |
| `arrived`   | En el lugar                                                     |
| `complete`  | Completada exitosamente                                         |
| `failed`    | Falló (con razón: `no_answer`, `bad_address`, `rejected`, etc.) |
| `cancelled` | Cancelada                                                       |

## Rutas

Una rutaagrupa un conjunto de tareas para ser ejecutadas por un conductor con un vehículo, en una fecha determinada (`shift_date`). Permite:

* **Publicar** la ruta para que el conductor la vea (`POST /routes/{id}/publish`)
* **Agregar / quitar tareas** dinámicamente
* Controlar **capacidad** del vehículo (peso, volumen, cantidad de paquetes)
* Trackear el progreso en tiempo real

#### Estados de la ruta

| Estado      | Descripción            |
| ----------- | ---------------------- |
| `draft`     | En planificación       |
| `published` | Publicada al conductor |
| `blocked`   | Bloqueada              |
| `started`   | En ejecución           |
| `finished`  | Finalizada             |

<br>