OrderProvider (endpoints antiguos)

{warning} Rutas deprecadas de asignaciones repartidor–orden, conservadas por compatibilidad porque varias apps aún no migran. Para integraciones nuevas usa OrderProvider. El modelo y las reglas de negocio son los mismos; cambian las rutas.

La asignación de una Order a un Provider. Una misma orden de supermercado puede tener dos OrderProvider a la vez: uno para el shopper y otro para el repartidor; unique_code los distingue (0 = shopper, 1 = repartidor) e is_shopping_mode marca el del shopper.

Ciclo de vida

assigned_at / unassigned_at los marca la asignación / desasignación. El proveedor avanza la asignación con estos endpoints, cada uno registra su timestamp:

  • set-running → started_at (el proveedor arrancó).
  • set-in-destination → in_destination_at (llegó al punto de recolección).
  • set-collected → picked_up_at (recolectó la orden).
  • set-working → working_at (servicios: empezó a trabajar).
  • set-arrived → arrived_at (llegó al destino).
  • set-completed → finished_at (terminó la asignación).

provider_status es el código entero del estado de la asignación; status (string) es la etiqueta derivada de provider_status y los timestamps. tracking es el rastro de ubicaciones del proveedor (oculto); tracking_statistics resume distancia y tiempos. snapshots guarda copias congeladas de datos usados en el cálculo de pagos.

Estructura de Datos

Atributo Tipo Descripción
id int
provider_status int Código entero del estado de la asignación (ver status para la etiqueta)
scheduled_at datetime\|null Fecha/hora programada de la orden asignada
assigned_at datetime Momento en que el proveedor fue asignado
unassigned_at datetime\|null Momento en que el proveedor fue desasignado
started_at datetime\|null El proveedor arrancó la asignación (set-running)
picked_up_at datetime\|null El proveedor recolectó la orden (set-collected)
arrived_at datetime\|null El proveedor llegó al destino (set-arrived)
working_at datetime\|null El proveedor empezó a trabajar el servicio (set-working)
finished_at datetime\|null El proveedor terminó la asignación (set-completed)
tracking array Rastro de ubicaciones del proveedor durante la asignación (oculto)
provider_fee_e2 int\|null Monto a pagar al proveedor por esta asignación (× 100)
created_at datetime\|null
updated_at datetime\|null
order_id int {@link Order} asignada
provider_id int {@link Provider} asignado
client_id int Cliente de la orden
client_rating_id int\|null Calificación que el cliente dejó al proveedor
provider_rating_id int\|null Calificación que el proveedor dejó al cliente
company_id int Company de la orden
in_destination_at datetime\|null El proveedor llegó al punto de recolección (set-in-destination)
tracking_statistics array\|null Resumen de distancia y tiempos de la asignación
is_shopping_mode bool La asignación corresponde al shopper (no al repartidor)
snapshots array\|null Copias congeladas de datos para el cálculo de pagos
unique_code int\|null 0 = asignación de shopper, 1 = asignación de repartidor (oculto)
allLogs ApiLog>
assignments OrderProviderService> Servicios/ítems concretos asignados dentro de la orden
client Client
clientRating ClientRating\|null
company Company
histories OrderProviderHistory> Historial de estados de la asignación
logs ApiLog>
order Order
provider Provider
providerRating ProviderRating\|null
status string Etiqueta de estado de la asignación, derivada de provider_status y los timestamps 
{
    "id": 847,
    "provider_status": 179336,
    "scheduled_at": null,
    "assigned_at": "2020-04-30 23:45:57",
    "unassigned_at": null,
    "started_at": "2020-05-06 19:09:55",
    "picked_up_at": null,
    "arrived_at": "2020-05-06 19:23:38",
    "working_at": null,
    "finished_at": "2020-05-06 19:23:52",
    "provider_fee_e2": 0,
    "created_at": "2020-04-30 23:45:57",
    "updated_at": "2020-05-06 19:23:52",
    "order_id": 1531,
    "provider_id": 36,
    "client_id": 39,
    "client_rating_id": null,
    "provider_rating_id": null,
    "company_id": 116,
    "in_destination_at": null,
    "tracking_statistics": {
        "version": 1,
        "branch_order_distance": 287603,
        "total_run_distance": 0
    },
    "is_shopping_mode": false,
    "snapshots": null,
    "status": "DELIVERED",
    "status_info": {
        "status_assigned": true,
        "status_started": true,
        "status_destination_reached": false,
        "status_picked_up": false,
        "status_running": false,
        "status_working": false,
        "status_arrived": true,
        "status_finished": true
    },
    "assignments": [
        {
            "id": 1008,
            "order_id": 1531,
            "provider_id": 36,
            "order_provider_id": 847,
            "ordered_good_id": 1744,
            "is_successful": true,
            "completed_at": "2020-05-06 19:23:52",
            "provider_fee_e2": 0,
            "created_at": "2020-04-30 23:45:57",
            "updated_at": "2020-05-06 19:23:52"
        }
    ]
}

Endpoints

Listar OrderProvider

Listar asignaciones de una orden

{info} Soporta: Paginación Filters Carga dinámica

Devuelve los OrderProvider de la orden (una por shopper y otra por repartidor, si aplica).

Método URI Cabeceras
GET /companies/{companyId}/orders/{orderId}/order-providers Authorization

Listar asignaciones de un proveedor

{info} Soporta: Paginación Filters

Lista los OrderProvider (asignaciones de órdenes) del proveedor indicado.

Método URI Cabeceras
GET /companies/{companyId}/providers/{providerId}/order-providers Authorization

Asignaciones activas de un proveedor

{info} Soporta: Paginación

Lista los OrderProvider del proveedor cuya orden todavía está en curso.

Método URI Cabeceras
GET /companies/{companyId}/providers/{providerId}/order-providers/active Authorization

Asignaciones de hoy de un proveedor

{info} Soporta: Paginación Filters

Lista los OrderProvider del proveedor asignados en el día actual (hora local).

Método URI Cabeceras
GET /companies/{companyId}/providers/{providerId}/order-providers/today Authorization

Productos asignados de una asignación

Lista los OrderProviderService (productos concretos de la orden) que le tocan al proveedor de este OrderProvider.

Método URI Cabeceras
GET /companies/{companyId}/order-providers/{orderProviderId}/ordered-goods Authorization

Mostrar OrderProvider

Mostrar asignación

{info} Soporta: Carga dinámica

Devuelve el OrderProvider por su id: la asignación de una orden a un proveedor, con sus timestamps de ciclo de vida.

Método URI Cabeceras
GET /companies/{companyId}/order-providers/{orderProviderId} Authorization

Acciones de OrderProvider

Iniciar asignación (proveedor arrancó)

El proveedor marca que arrancó la asignación (OrderProvider); registra started_at. Requiere que la orden esté confirmada y con método de pago definido.

Método URI Cabeceras
POST /companies/{companyId}/order-providers/{orderProviderId}/set-running Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC310 400 El proveedor ya había iniciado esta asignación.
EC306 400 El proveedor ya completó esta asignación.
EC116 400 La orden ya está finalizada.
EC102 400 La orden no está confirmada.
EC104 400 La orden no tiene método de pago definido.

Proveedor llegó al punto de recolección

El proveedor marca que llegó al origen (comercio / punto de recogida) del OrderProvider; registra in_destination_at. Verifica que esté dentro del radio de recolección configurado por la company.

Método URI Cabeceras
POST /companies/{companyId}/order-providers/{orderProviderId}/set-in-destination Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC303 400 El proveedor no está asignado a la orden.
EC312 400 El proveedor ya había marcado que llegó al punto de recolección.
EC309 400 El proveedor no inició la asignación.
EC306 400 El proveedor ya completó esta asignación.
EC319 400 El proveedor está demasiado lejos del punto de recolección.

Proveedor recolectó la orden

El proveedor marca que recogió la orden del OrderProvider; registra picked_up_at. Requiere haber llegado antes al punto de recolección.

Método URI Cabeceras
POST /companies/{companyId}/order-providers/{orderProviderId}/set-collected Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC303 400 El proveedor no está asignado a la orden.
EC311 400 El proveedor no había marcado que llegó al punto de recolección.
EC314 400 El proveedor ya había recolectado la orden.
EC309 400 El proveedor no inició la asignación.
EC306 400 El proveedor ya completó esta asignación.

Proveedor empezó a trabajar (servicios)

En órdenes de servicio, el proveedor marca que empezó a prestar el servicio del OrderProvider; registra working_at. Requiere haber llegado al sitio.

Método URI Cabeceras
POST /companies/{companyId}/order-providers/{orderProviderId}/set-working Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC316 400 El proveedor ya había marcado que está trabajando.
EC306 400 El proveedor ya completó esta asignación.
EC307 400 El proveedor no ha llegado al sitio.
EC116 400 La orden ya está finalizada.
EC102 400 La orden no está confirmada.
EC104 400 La orden no tiene método de pago definido.

Proveedor llegó al destino

El proveedor marca que llegó al punto de entrega del OrderProvider; registra arrived_at. Requiere haber iniciado la asignación.

Método URI Cabeceras
POST /companies/{companyId}/order-providers/{orderProviderId}/set-arrived Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC306 400 El proveedor ya completó esta asignación.
EC309 400 El proveedor no inició la asignación.
EC104 400 La orden no tiene método de pago definido.

Completar asignación

El proveedor da por terminada su asignación (OrderProvider); registra finished_at. En órdenes que no son de servicio, adjunta la prueba de entrega (POD). Puede completar la orden si es la última asignación pendiente.

Método URI Cabeceras
POST /companies/{companyId}/order-providers/{orderProviderId}/set-completed Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC306 400 El proveedor ya completó esta asignación.
EC104 400 La orden no está pagada (órdenes de servicio).

Asignar un proveedor a una orden

Asigna el Provider indicado a la orden, creando un OrderProvider. Según quién llame (admin, cliente o el propio proveedor auto-asignándose) se validan las preferencias de pool de la company y que el proveedor esté disponible.

Método URI Cabeceras
PUT /companies/{companyId}/orders/{orderId}/providers/{providerId} Authorization 
[
    "integer"
]

Errores de negocio

Código HTTP Cuándo ocurre
EA109 400 La preferencia de pool que habilita esta asignación no está activada en la company.
ED200 400 El proveedor está ocupado.
EC104 400 La orden no tiene método de pago definido.

Desasignar un proveedor de una orden

Quita al Provider de la orden (marca unassigned_at en su OrderProvider). Si lo hace el propio proveedor, requiere que la company permita renunciar a asignaciones.

Método URI Cabeceras
DELETE /companies/{companyId}/orders/{orderId}/providers/{providerId} Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EA109 400 La company no permite que los repartidores renuncien a una asignación.
EC306 400 El proveedor ya completó esta asignación.
EC308 400 El proveedor ya había llegado; no se puede desasignar.
EC100 400 La orden queda sin repartidor y no es reasignable en su estado actual.

Asignar proveedores por producto/servicio

Asigna varios Provider a una misma orden, uno por producto o servicio (para órdenes con múltiples servicios). Cada proveedor debe tener acceso al comercio o a la company.

Método URI Cabeceras
PUT /companies/{companyId}/orders/{orderId}/providers Authorization 
[
    {
        "ordered_good_id": "integer",
        "provider_id": "integer"
    }
]

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC102 400 La orden no está confirmada.
EC100 400 La orden no admite repartidor.
EC318 400 El proveedor no tiene acceso al comercio ni a la company de la orden.

Productos asignados a un proveedor en una orden (por order_id + provider_id)

Lista los OrderProviderService (productos concretos de la orden) que le tocan al proveedor indicado.

Método URI Cabeceras
GET /companies/{companyId}/orders/{orderId}/providers/{providerId}/ordered-goods Authorization

Relaciones