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.

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.

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

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