> 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>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zipnova.com/rutas/conceptos.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.