Order (endpoints antiguos)

{warning} Rutas deprecadas de órdenes, conservadas por compatibilidad porque varias apps aún no migran. Para integraciones nuevas usa Order. El modelo y las reglas de negocio son los mismos; cambian las rutas y algún endpoint auxiliar.

Representa una orden o pedido de un cliente dentro de una company.

Una orden puede ser de productos (asociada a un comercio vía branch_id) o de envío directo / servicio (sin branch_id). El ciclo de vida se controla con el bitmask status; los flags booleanos derivados (is_status_confirmed, is_payment_confirmed, is_provider_assigned, is_status_being_prepared, is_status_prepared, is_provider_collected, is_status_arrived, is_status_completed, is_status_completed_ok, is_status_canceled, is_status_expired, …) se definen en onInitializeBitMaskBags().

Ciclo de vida

Hitos con timestamp (se registran para estadísticas de tiempos de entrega): paid_at → being_prepared_at → prepared_at → collected_at → arrived_at → completed_at.

Duraciones autocalculadas en segundos (OrderHandler::onSaving()):

  • preparation_time: prepared_at − being_prepared_at.
  • total_preparation_time: prepared_at − paid_at en órdenes inmediatas; prepared_at − being_prepared_at en programadas.
  • collection_time: collected_at − prepared_at.
  • arrival_time: arrived_at − paid_at (solo órdenes inmediatas).

Al cierre del día (00:00 hora local) las órdenes finalizadas se archivan: se asigna deleted_at (soft delete = archivado, no borrado físico).

Estados por audiencia

status_for_clients, status_for_shoppers, status_for_providers, status_for_company_admins, status_for_branch_admins, status_for_partners, status_for_payment son códigos de texto estables (constantes, no localizados). Valen N/A cuando la audiencia no aplica a la orden (p. ej. status_for_shoppers en una orden sin shopper); no debería ocurrir en apps reales. latest_status es el valor de status inmediatamente anterior al actual. status_data es solo para depurar los bitmasks; se mantiene por retrocompatibilidad y no debe usarse en integraciones nuevas.

Montos

Todos los montos usan sufijo _e2 (entero = monto × 100). Definiciones:

  • subtotal_original_e2: total de productos, sin descuentos.
  • subtotal_e2: subtotal_original_e2 tras aplicar descuentos de precio base.
  • tax_e2: suma de la lista taxes (envío, servicio de app, shopper, descuentos, tarifas extra…).
  • total_e2: monto final. Equivale a subtotal_e2 + tax_e2.
  • branch_subtotal_e2: monto de cara al comercio. subtotal_original_e2 − branch_discounts_e2 (descuentos asumidos por el comercio).
  • delivery_fee_e2: costo del envío de la orden.
  • delivery_fee_e2_paid_for_client: cuánto de ese envío pagó el cliente (0 si hay promo de envío gratis; total o parcial según promociones).
  • delivery_fee_to_pay_e2: cuánto se le debe pagar al repartidor por el envío.

Orden de cálculo: se suma subtotal_original_e2 → se aplican descuentos de base_price (subtotal_e2) → se calculan y registran en taxes: descuentos de subtotal, servicio de app (service_fee_e2), envío y sus descuentos, shopper y sus descuentos, tarifas adicionales (config global + comercio) → tax_e2 = suma de taxes → total_e2 = subtotal_e2 + tax_e2. Si el método de pago aplica comisión, se cobra total_e2 + payment_fee_e2 sin alterar los montos de la orden (payment_fee_e2 vive en Payment).

Notas y gotchas

  • Pickup: en órdenes con branch_id el punto de recolección es la ubicación del comercio (pickup_*_e6 no se usan). En órdenes sin branch_id se usan pickup_latitude_e6, pickup_longitude_e6 y pickup_address.
  • number: correlativo desde 1 por branch_id; en órdenes sin comercio, correlativo por company_id.
  • uid: identificador legible para el usuario. Con comercio: "<número de comercio>-<número de orden>". Sin comercio: prefijo L + secuencia global de la company (ej. L001-0000001).
  • Dirección de entrega: client_address (string plano) está deprecado en favor de client_address_data (país, address_line_1/2, postal_code, …). Coexisten por retrocompatibilidad.
  • Ubicaciones: client_*_e6 y pickup_*_e6 están siendo reemplazados por locations (lista de OrderLocation), que soporta multiparada e incluye started_at, arrived_at y notes por parada.
  • source: null en órdenes nativas; el nombre del origen (Ridery, WhatsApp, Square, …) cuando la creó una integración externa.
  • Snapshots (currency_snapshot, company_currency_snapshot, shopper_snapshot, order_provider_snapshot): copias congeladas al crear la orden; cambios posteriores en el origen (moneda por defecto de la company, teléfono/vehículo del repartidor…) no la afectan.
  • Shopper vs repartidor: el shopper (solo supermercados) selecciona los productos y se los entrega al repartidor, que hace el reparto al cliente. Una orden puede tener ambos.

Estructura de Datos

Atributo Tipo Descripción
id int
number int\|null Número correlativo de la orden (por branch_id, o por company_id si no hay comercio)
status int Bitmask de estado; ver flags is_* y onInitializeBitMaskBags()
subtotal_e2 int Total de productos tras descuentos de precio base (× 100)
total_e2 int Monto final de la orden. Equivale a subtotal_e2 + tax_e2 (× 100)
tax_e2 int Suma de la lista taxes: envío, servicio de app, shopper, descuentos, tarifas extra (× 100)
notes string\|null Notas de entrega escritas por el cliente
scheduled_at datetime\|null Fecha/hora de entrega solicitada (órdenes programadas); null = inmediata
client_latitude_e6 int Latitud del punto de entrega (× 1e6)
client_longitude_e6 int Longitud del punto de entrega (× 1e6)
client_address_data array\|null Dirección de entrega estructurada (país, address_line_1/2, postal_code…)
pickup_latitude_e6 int Latitud del punto de recolección; solo órdenes sin branch_id (× 1e6)
pickup_longitude_e6 int Longitud del punto de recolección; solo órdenes sin branch_id (× 1e6)
pickup_address string\|null Dirección de recolección; solo órdenes sin branch_id
completed_at datetime\|null Momento de finalización de la orden (entrega o cancelación)
deleted_at datetime\|null Momento de archivado (soft delete al cierre del día en hora local)
created_at datetime\|null
updated_at datetime\|null
company_id int Company dueña de la orden
client_id int\|null Cliente dueño de la orden
creator_id int\|null Admin que creó la orden en nombre del cliente; null si la creó el propio cliente
branch_id int\|null Comercio (sucursal) de la orden; null en envío directo / servicio
uid string\|null Identificador legible: "<comercio>-<orden>" con comercio, o "<code de company>-<secuencia>" con prefijo L sin comercio (ej. L001-0000001)
receiver_name string\|null Nombre de quien recibe
receiver_phone string\|null Teléfono de quien recibe
is_gift bool\|null La recibe otra persona distinta a quien creó la orden
shopper_id int\|null Repartidor que actúa de shopper (selecciona los productos); solo supermercados
currency_iso string\|null Moneda en la que paga el cliente esta orden
branch_group_id int\|null Comercio (marca, no sucursal) al que pertenece; usado en reportes por comercio
subtotal_original_e2 int\|null Total de productos sin descuentos (× 100)
branch_rating_id int\|null Calificación que el cliente dejó al comercio por esta orden
paid_at datetime\|null Momento del hito de pago (FLAG_PAID / FLAG_POST_PAYMENT; no se sobreescribe)
being_prepared_at datetime\|null Momento en que el comercio/shopper inició la preparación
prepared_at datetime\|null Momento en que la orden quedó lista
collected_at datetime\|null Momento en que el repartidor recolectó la orden
arrived_at datetime\|null Momento de llegada del repartidor al punto de entrega
preparation_time int\|null Segundos de preparación: prepared_at − being_prepared_at
total_preparation_time int\|null Segundos totales de preparación: desde paid_at (inmediatas) o desde being_prepared_at (programadas)
collection_time int\|null Segundos entre orden lista y recolección: collected_at − prepared_at
arrival_time int\|null Segundos desde el pago hasta la llegada al destino; solo órdenes inmediatas
fleet_association_id int\|null Asociación/tarifa de envío elegida para la orden (aunque aún no haya repartidor asignado)
source string\|null Origen externo de la orden (Ridery, WhatsApp, Square…); null en órdenes nativas
city_id int\|null Ciudad de la orden (del comercio, o del destino si no hay comercio); define visibilidad para admins de ciudad
client_address string\|null Dirección de entrega en texto plano (deprecado: usar client_address_data)
locations array\|null Paradas de la entrega (lista de {@link OrderLocation}); reemplaza a client_*_e6 / pickup_*_e6 y soporta multiparada
order_edit_data OrderEditData\|null Datos de la edición de la orden en curso (cambios de ítems pendientes de confirmar)
ordered_goods array\|null Lista de productos de la orden (snapshot)
is_service bool BitMask (({@link self::status} & 0x1) !== 0)
is_pickup_enabled bool BitMask (({@link self::status} & 0x2) !== 0)
is_type_digital bool BitMask (({@link self::status} & 0x4) !== 0)
is_delivery bool BitMask (({@link self::status} & 0x8) !== 0)
is_bid_waiting_client bool BitMask (({@link self::status} & 0x10) !== 0)
is_bid_waiting_admin bool BitMask (({@link self::status} & 0x20) !== 0)
is_bid_waiting_provider bool BitMask (({@link self::status} & 0x40) !== 0)
is_asap bool BitMask (({@link self::status} & 0x80) !== 0)
is_status_unconfirmed bool BitMask (({@link self::status} & 0x100) !== 0)
is_payment_waiting_confirmation bool BitMask (({@link self::status} & 0x200) !== 0)
is_payment_confirmed bool BitMask (({@link self::status} & 0x400) !== 0)
is_provider_assigned bool BitMask (({@link self::status} & 0x800) !== 0)
is_provider_started bool BitMask (({@link self::status} & 0x1000) !== 0)
is_status_arrived bool BitMask (({@link self::status} & 0x2000) !== 0)
is_provider_working bool BitMask (({@link self::status} & 0x4000) !== 0)
is_status_completed bool BitMask (({@link self::status} & 0x8000) !== 0)
is_status_canceled bool BitMask (({@link self::status} & 0x10000) !== 0)
is_status_completed_ok bool BitMask (({@link self::status} & 0x20000) !== 0)
is_refund_applied bool BitMask (({@link self::status} & 0x40000) !== 0)
is_refund_pending bool BitMask (({@link self::status} & 0x80000) !== 0)
is_payment_later bool BitMask (({@link self::status} & 0x100000) !== 0)
is_status_being_prepared bool BitMask (({@link self::status} & 0x200000) !== 0)
is_status_prepared bool BitMask (({@link self::status} & 0x400000) !== 0)
is_provider_arrived bool BitMask (({@link self::status} & 0x800000) !== 0)
is_provider_collected bool BitMask (({@link self::status} & 0x1000000) !== 0)
is_status_expired bool BitMask (({@link self::status} & 0x2000000) !== 0)
is_shopper_allowed bool BitMask (({@link self::status} & 0x4000000) !== 0)
is_shopper_assigned bool BitMask (({@link self::status} & 0x8000000) !== 0)
is_pool_private bool BitMask (({@link self::status} & 0x10000000) !== 0)
is_invoice_allowed bool BitMask (({@link self::status} & 0x20000000) !== 0)
is_for_shipping bool BitMask (({@link self::status} & 0x40000000) !== 0)
has_item_updates bool BitMask (({@link self::status} & 0x80000000) !== 0)
is_sent_to_pool bool BitMask (({@link self::status} & 0x100000000) !== 0)
is_trip bool BitMask (({@link self::status} & 0x200000000) !== 0)
is_trip_locked bool BitMask (({@link self::status} & 0x400000000) !== 0)
is_bot_attempting bool BitMask (({@link self::status} & 0x800000000) !== 0)
is_no_provider_dispatch bool BitMask (({@link self::status} & 0x1000000000) !== 0)
is_dispatched_without_provider bool BitMask (({@link self::status} & 0x2000000000) !== 0)
is_payment_later_required bool BitMask (({@link self::status} & 0x4000000000) !== 0)
is_type_good bool BitMask (({@link self::status} & 0x1) === 0)
is_scheduled bool BitMask (({@link self::status} & 0x80) === 0)
is_status_confirmed bool BitMask (({@link self::status} & 0x100) === 0)
is_no_bid_waiting bool BitMask ((({@link self::status} & 0x70) >> 4) === 0)
additional_delivery_fee_e2 int
admin_url string
administrator_notes Collection Notas de administración registradas ante incidencias
allLogs ApiLog>
allOrderedGoodItems OrderedGood>
allPayments Payment>
amount_for_debugging Money\|null
applied_taxes array
assignedOrderProviders OrderProvider>
assigning_bot_status string\|null
balance OrderBalance
base_delivery_fee_e2 int
base_price_e2 int
bids Bid>
bids_snapshot array
branch Branch\|null
branch_group BranchGroup\|null
branchPendingFee BranchPendingFee\|null
branchRating BranchRating\|null
branch_subtotal_e2 int Monto de cara al comercio: subtotal_original_e2 − branch_discounts_e2 (× 100)
cancellationReason OrderCancellationReason\|null
cashback_e2 int
cashbacks CouponUsage>
charges_e2 int
client Client\|null
client_debt_e2 int
client_payment_e2 int
clientRating ClientRating\|null
client_rating_e2 int Calificación que el cliente dejó al comercio, × 100 (ej. 450 = 4.5)
clientRatings ClientRating>
company Company
companyActiveOrder CompanyActiveOrder\|null
company_currency_snapshot Currency\|null Moneda por defecto de la company al momento de crear la orden (snapshot)
creator Admin\|null
currency_rates array
currency_snapshot Currency\|null Moneda del comercio al momento de crear la orden (snapshot; puede tener tasa distinta a la de la company)
current_delay_in_seconds int
delivery_eta_in_seconds int Tiempo estimado del delivery desde que se recolecta la orden (segundos)
delivery_fee_e2 int Costo del envío de la orden (× 100)
delivery_fee_e2_paid_for_client int Cuánto del envío pagó el cliente: 0 con promo de envío gratis, total, o parcial según promos (× 100)
delivery_fee_to_pay_e2 int Cuánto se le debe pagar al repartidor por el envío (× 100)
delivery_notes string
desired_pickup_at datetime\|null
destination_city City\|null
device array\|null Metadatos del dispositivo que creó la orden
discount_e2 int
discounts CouponUsage>
discountsAndCashbacks CouponUsage>
driver_assigning_delay_in_seconds int
effective_discount_e2 int
effective_service_fee_e2 int
estimated_max_weight int
estimated_route DirectionsEstimated\|null Ruta del trayecto de delivery calculada por el servicio externo de rutas (distancia y tiempo)
estimated_route_for_assigned_provider DirectionsEstimated\|null
external_id string\|null
external_source string\|null
fleet Fleet\|null
fleet_association FleetAssociation\|null
fleet_association_shipment_action string\|null
full_delivery_eta_in_seconds int Tiempo estimado total de la orden (segundos)
full_preparation_eta_in_seconds int
generalInvoiceItems GeneralInvoiceItem>
gmv_e2 int
goodRatings GoodRating>
goods Good>
google_maps_url string\|null
gross_total_e2 int
histories OrderHistory>
initial_eta datetime
invoiceDocumentItems InvoiceDocumentItem>
is_arriving_for_pickup bool
is_expiration_allowed bool
is_provider_chat_allowed bool El cliente puede chatear con el repartidor de esta orden
is_provider_dial_allowed bool El cliente puede llamar al repartidor de esta orden
items_quantity int
last_status_change int
latest_status string Valor de status inmediatamente anterior al actual
local_date datetime
logs ApiLog>
notifications Notification>
order_location_history Collection
orderProviderServices OrderProviderService>
order_provider_snapshot OrderProvider\|null Datos congelados del repartidor asignado a la orden
orderProviders OrderProvider>
orderedGoodItems OrderedGood>
orderedGoodItemsWithPromo OrderedGood>
ordered_goods_history Collection
package_content string\|null
package_description string
package_info PackageInfo\|null
paid_amount_e2 int
partner array\|null Datos del servicio externo que creó la orden (incluye su OrderID externo y campos propios de la integración)
partner_name string\|null Nombre del servicio/asociado externo
partner_pod_pin string\|null PIN para validar la entrega entre el comercio y el servicio externo
partner_provider_id int\|null
partner_validation_code array\|null
partner_validation_url string\|null URL con un QR para autorizar la entrega
payment_attempting string\|null Método de pago que el usuario está intentando (Stripe, PayPal…); pago aún no concretado
payment_balance_e2 int
payment_debt_e2 int
payment_error string\|null Último error de pago; se limpia cuando hay un pago exitoso
payment_types array Tipos de pago realizados sobre la orden
payments Payment>
pickup_delay_in_seconds int
pickup_eta datetime
pickup_eta_in_seconds int
probable_eta datetime\|null ETA total estimado por el sistema: preparación del comercio + llegada del repartidor + trayecto
promo_code CouponUsage\|null
promo_code_e2 int
promo_code_tax OrderTax\|null
proofOfDeliveries ProofOfDelivery>
providerPendingFees ProviderPendingFee>
providerRatings ProviderRating>
providers Provider>
relatedBalanceMovements BalanceMovement>
revenue_e2 int
selected_payment_method SelectedPaymentMethod\|null Método elegido para pago contra entrega (POS, efectivo…)
service_charge array\|null Servicio de envío elegido para la orden (el fleet_association ganador entre los candidatos)
service_fee_e2 int Comisión de servicio de la app aplicada a la orden (× 100)
service_matches array\|null
shopper Provider\|null
shopper_attachments Collection Adjuntos cargados por el shopper (ej. fotos de la compra)
shopper_fee_e2 int
shopper_fee_to_pay_e2 int
shopper_notes Collection Notas registradas por el shopper
shopper_snapshot Provider\|null Datos congelados del shopper asignado
snapshots OrderDataSnapshot>
status_data array Volcado de los bitmasks para depuración; se mantiene por retrocompatibilidad, no usar en integraciones
status_for_branch_admins string Código de estado estable para administradores del comercio; N/A si no aplica
status_for_clients string Código de estado estable para el cliente; N/A si no aplica
status_for_company_admins string Código de estado estable para administradores de la company; N/A si no aplica
status_for_partners string Código de estado estable para el servicio/asociado externo; N/A si no aplica
status_for_payment string Código de estado de pago estable; N/A si no aplica
status_for_providers string Código de estado estable para el repartidor; N/A si no aplica
status_for_shoppers string Código de estado estable para el shopper; N/A si no aplica
subtotal_discount_e2 int
subtotal_promo_code_e2 int
tab_groups array
taxes OrderTax> Detalle de cargos y descuentos aplicados a la orden (delivery, servicio, promos…)
taxes_for_branch Collection
tracking_url string\|null
weight int

Ver Json

Endpoints

Insertar Order

Crear orden (deprecado)

Crea una Order para un cliente en un comercio, armando internamente un carrito.

{warning} Endpoint deprecado. Use el flujo de Cart (Carrito).

Método URI Cabeceras
POST /companies/{companyId}/branches/{branchId}/clients/{clientId}/orders Authorization 
{
    "receiver_name": "string|max:64",
    "receiver_phone": "string|max:32",
    "client_dni": "string|max:32",
    "client_phone": "string|max:32",
    "client_name": "string|max:128",
    "client_email": "string|email:rfc,filter",
    "is_gift": "boolean",
    "client_latitude_e6": "required_without:client_address_id|integer|between:-90000000,90000000",
    "client_longitude_e6": "required_with:client_latitude_e6||integer|between:-180000000,180000000",
    "client_address": "string|max:512",
    "client_address_id": "integer",
    "pickup_latitude_e6": "integer|between:-90000000,90000000",
    "pickup_longitude_e6": "integer|between:-180000000,180000000",
    "pickup_address": "string|max:512",
    "provider_id": "integer",
    "scheduled_at": "date",
    "use_local_tz": "boolean",
    "notes": "string|max:255",
    "goods": [
        {
            "good_id": "required|integer|exists:goods,id",
            "quantity": "required|integer|min:1",
            "units": "nullable|numeric|min:0.000001",
            "provider_id": "integer",
            "notes": "string|max:255",
            "properties": [
                {
                    "property_id": "required|integer",
                    "value": "required|string"
                }
            ]
        }
    ],
    "subtotal_e2": "integer|min:0",
    "service_charge_id": "nullable|integer",
    "service_charge": "nullable|array",
    "available_delivery_providers": "nullable|array",
    "use_balance": "boolean",
    "coupon_code": "nullable|string|min:5|max:20",
    "cart_identifier": "integer|min:0",
    "all_errors": "",
    "simulate": "",
    "force_scheduling": "boolean",
    "force_providers": [
        "integer"
    ]
}

Errores de negocio

Código HTTP Cuándo ocurre
EC140 400 El client_address_id indicado no pertenece al cliente o no existe.
EF312 400 El coupon_code no es válido o ya fue utilizado.
EF323 400 El código corresponde a una gift card; solo se canjea desde el perfil.
EC603 400 El contenido del carrito resultante no es válido.
EC229 400 Uno o más ítems del pedido no son válidos.

Listar Order

Listar órdenes

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

Lista las Order accesibles para el usuario autenticado. Si no se envía city_id y el usuario es administrador de una ciudad, se filtra automáticamente por su ciudad.

Parámetros de query adicionales:

  • city_id: filtra por la ciudad del comercio de la orden.
  • assignment: shopper | deliverer | any | none — estado de asignación de la orden.
  • mode: deleted | all — incluye órdenes archivadas (fuerza la paginación).
Método URI Cabeceras
GET /companies/{companyId}/orders Authorization

Listar órdenes de un comercio (marca)

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

Lista las Order de todas las sucursales del branch_group (comercio/marca) indicado. Con mode=deleted o mode=all incluye órdenes archivadas.

Método URI Cabeceras
GET /companies/{companyId}/branch-groups/{branchGroupId}/orders Authorization

Listar órdenes de un comercio

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

Lista las Order de la sucursal indicada. Con is_paid=1 (o si el comercio tiene auto-asignación de repartidor al pagar) filtra por órdenes pagadas. Con mode=deleted o mode=all incluye órdenes archivadas.

Método URI Cabeceras
GET /companies/{companyId}/branches/{branchId}/orders Authorization

Listar órdenes de un cliente

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

Lista las Order del cliente indicado. Con mode=deleted o mode=all incluye órdenes archivadas.

Método URI Cabeceras
GET /companies/{companyId}/clients/{clientId}/orders Authorization

Listar órdenes activas de un cliente

{info} Soporta: Filters

Devuelve las Order en curso del cliente (según CompanyActiveOrder), sin paginar.

Método URI Cabeceras
GET /companies/{companyId}/clients/{clientId}/orders/active Authorization

Listar órdenes disponibles para un repartidor

Devuelve las Order que el repartidor puede tomar según sus habilitaciones (repartidor, shopper, envío, viaje), su pertenencia a flotas, la distancia al punto de recolección, geocercas, restricciones de método de pago a flota y la configuración de pool del comercio. Las órdenes con partner externo se excluyen. Cada orden consultada queda registrada como vista por el repartidor.

Método URI Cabeceras
GET /companies/{companyId}/providers/{providerId}/orders/available Authorization

Listar órdenes creadas por un administrador

{info} Soporta: Paginación

Lista las Order cuyo creator_id es el administrador indicado (órdenes que ese admin registró en nombre de un cliente). Con mode=deleted o mode=all incluye órdenes archivadas.

Método URI Cabeceras
GET /companies/{companyId}/admins/{adminId}/orders Authorization

Lista el histórico de cambios de una orden

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

Mostrar Order

Mostrar orden

{info} Soporta: Carga dinámica

Devuelve el detalle completo de una Order, incluido el snapshot del servicio de envío (service_charge). Acepta órdenes archivadas. Cuando la consulta un repartidor, éste queda registrado como visor de la orden.

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

Actualizar Order

Actualizar orden

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

Actualiza campos editables de una Order y gestiona las notas de administración (admin_notes): con admin_note_id edita una nota existente (guardando una versión previa si cambió el texto); sin él, crea una nota nueva. Acepta órdenes archivadas.

Método URI Cabeceras
PATCH /companies/{companyId}/orders/{orderId} Authorization 
{
    "admin_note_id": "nullable|integer|min:1",
    "admin_notes": "nullable|string|max:512"
}

Subir imagen a una nota de administrador

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

Crea una evidencia (imagen) y lo vincula a una nota de administrador de una Orden. Se puede visualizar por el atributo de Orden: administrator_notes.attachments

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/add-attachment Authorization 
{
    "admin_notes": "nullable|string|max:512",
    "attachment": "nullable|image|mimes:jpeg,png,bmp|max:8192"
}

Subir notas/adjuntos como Shopper

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

Crea una evidencia (imagen) y una nota (texto) de un shopper y lo vincula a una orden. Útil para subir facturas o evidencias de la compra. Se puede visualizar por el atributo de Orden: shopper_notes. Sólo disponible para el shopper asignado.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/add-shopper-notes Authorization 
{
    "shopper_notes": [
        {
            "text": "nullable|string|max:512",
            "attachments": [
                "required|image|mimes:jpeg,png,bmp|max:8192"
            ]
        }
    ]
}

Cambiar dirección de envío

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

Aplica el cambio de dirección de destino de la Order previamente calculado con check-destination-address: actualiza tarifa de envío, ETA y flota asignada, y guarda el historial de ubicaciones. Si aumenta la deuda, la orden vuelve a estado de pago pendiente.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/update-destination-address Authorization 
{
    "client_latitude_e6": "required|integer|between:-90000000,90000000",
    "client_longitude_e6": "required|integer|between:-180000000,180000000",
    "client_address": "nullable|string|max:512",
    "address_notes": "nullable|string|max:255",
    "contact_name": "nullable|string|max:80",
    "contact_phone": "nullable|string|max:20",
    "contact_instructions": "nullable|string|max:1024"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC100 400 La orden no admite repartidor.
EC116 400 La orden ya está finalizada.
EC244 400 La orden no soporta envío a domicilio.
EC240 400 No hay un cálculo previo válido para esa dirección; ejecute primero check-destination-address.

Acciones de Order

Acción en lote sobre órdenes

Ejecuta una acción de transición sobre varias Order a la vez (campo ids). El parámetro de ruta action acepta: set-confirmed, set-paid, set-running, set-ready, set-completed, set-post-payment, set-being-prepared, set-prepared. Cada orden se procesa como si se llamara al endpoint individual correspondiente; la respuesta detalla el resultado por orden. Los errores de negocio son los del endpoint de la acción elegida.

Método URI Cabeceras
POST /companies/{companyId}/orders/batch-action/{action} Authorization 
{
    "ids": [
        "integer|min:1"
    ],
    "payload": ""
}

Mapa de calor de órdenes por comercio

Devuelve, por comercio, su ubicación y el total de Order pagadas y aún no completadas ni asignadas. Si no se envía city_id y el usuario es administrador de una ciudad, se filtra por su ciudad.

Método URI Cabeceras
GET /companies/{companyId}/orders/branch-heatmap Authorization

Confirmar orden

Confirma una Order pendiente y le asigna su number correlativo. Solo aplica a órdenes de comercio con al menos un producto.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-confirmed Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC103 400 La orden ya estaba confirmada.
EC242 400 La orden no está asociada a un comercio.
EC138 400 La orden no tiene productos.

Marcar orden como pagada

Registra un pago manual sobre la Order en nombre de un administrador. Útil para resolver incidencias con pagos ya recibidos fuera de la plataforma.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-paid Authorization 
{
    "type": "string|in:gateway,form,post-payment,balance",
    "name": "string",
    "ref": "string"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC102 400 La orden no está confirmada.
EC105 400 La orden ya está pagada.
EC106 400 La orden tiene reportes de pago pendientes de validación.

Iniciar orden (sin envío)

Marca una Order de comercio como en curso. Solo para órdenes que no requieren repartidor (retiro en tienda o consumo en local).

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-running Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC101 400 La orden admite repartidor; use el flujo de asignación en su lugar.
EC108 400 La orden ya fue iniciada.
EC242 400 La orden no está asociada a un comercio.

Marcar orden como lista (sin envío)

Marca una Order de comercio como lista para entregar. Solo para órdenes que no requieren repartidor.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-ready Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC102 400 La orden no está confirmada.
EC242 400 La orden no está asociada a un comercio.
EC101 400 La orden admite repartidor; use el flujo de asignación en su lugar.

Finalizar orden (entregada)

Marca una Order como entregada. Requiere que el método de pago esté definido. Si la orden requiere repartidor y ya está en estado "llegó", exige verificación en dos pasos: se completará sin generar ganancia para ningún repartidor.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-completed Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC104 400 La orden no tiene método de pago definido.

Cancelar orden

Cancela una Order. Si ya estaba completada con éxito, se marca como no entregada (a efectos de facturación) y se exige verificación en dos pasos, porque puede disparar un reembolso al cliente y anular el pago al repartidor o al comercio. Envía un correo de aviso.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-canceled Authorization 
{
    "reason": "required|string|max:64",
    "target_user_type": {
        "nullable": true,
        "string": true
    }
}

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está cancelada.

Activar pago contra entrega

Permite avanzar una Order sin pago previo: se cobrará al momento de la entrega (POS, efectivo, etc.). Requiere orden de comercio, no digital y que admita repartidor.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-post-payment Authorization 
{
    "id": "nullable|string",
    "currency_iso": "required_with:id|string|min:3|max:8",
    "cash_amount_e2": "nullable|integer|min:1"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC144 400 La orden es digital y no admite pago contra entrega.
EC100 400 La orden no admite repartidor.
EC242 400 La orden no está asociada a un comercio.
EC105 400 La orden ya está pagada.
EC504 400 El método de pago no está disponible para el pool privado de la orden.

Pagar orden con saldo del cliente

Salda la deuda de la Order debitando el saldo disponible del cliente.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-balance-payment Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC105 400 La orden ya está pagada.
EF500 400 El saldo del cliente es insuficiente para cubrir la deuda de la orden.

Iniciar preparación

Marca que el comercio inició la preparación de la Order. Registra being_prepared_at.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-being-prepared Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC102 400 La orden no está confirmada.
EC126 400 La orden ya está en preparación.
EC128 400 La orden ya está preparada.
EC242 400 La orden no está asociada a un comercio.

Marcar orden como preparada

Marca la Order como preparada y lista para entregar (al repartidor o al cliente). Con assign_shopper_as_deliverer: true el shopper asignado queda también como repartidor.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-prepared Authorization 
{
    "assign_shopper_as_deliverer": "nullable|boolean"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC116 400 La orden ya está finalizada.
EC102 400 La orden no está confirmada.
EC242 400 La orden no está asociada a un comercio.
EC138 400 La orden no tiene productos.
EC135 400 Se pidió usar el shopper como repartidor pero la orden no tiene shopper asignado.

Mover al pool privado

Pasa la Order al pool privado: el envío lo maneja el propio comercio. Requiere que el comercio tenga una flota propia.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-private-pool Authorization

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.
EC114 400 La orden ya está asignada.
EC142 400 La orden ya está en el pool privado.
EC242 400 La orden no está asociada a un comercio.
ES020 400 El comercio no tiene una flota propia habilitada.

Mover al pool público

Pasa la Order al pool público: el envío puede asignarse a cualquier flota de la plataforma.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-public-pool Authorization

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.
EC114 400 La orden ya está asignada.
EC141 400 La orden no está en el pool privado.
EC242 400 La orden no está asociada a un comercio.

Listar flotas disponibles para la orden

Devuelve las opciones de servicio de envío (flotas/tarifas) calculadas para la Order, tomadas del snapshot de matches. Requiere orden con repartidor y sin asignar.

Método URI Cabeceras
GET /companies/{companyId}/orders/{orderId}/available-fleets Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC100 400 La orden no admite repartidor.
EC114 400 La orden ya está asignada.
EC238 400 La orden no tiene una lista de opciones de envío disponible.

Cambiar flota de envío

Cambia la flota/tarifa de envío de la Order eligiendo una de las opciones del snapshot de matches (service_charge_id).

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/set-selected-fleet Authorization 
{
    "service_charge_id": "required|integer"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC100 400 La orden no admite repartidor, o el partner externo ya está asignado.
EC114 400 La orden ya está asignada.
EC238 400 La orden no tiene una lista de opciones de envío disponible.
EC239 400 El service_charge_id indicado no está en la lista de opciones de la orden.
EC241 400 No se puede cambiar de flota por una restricción de pago a flota (POS).

Enviar orden al pool

Encola la Order para asignación automática de repartidor según la configuración vigente. Con force: true fuerza el reintento aunque ya haya un intento en curso.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/send-to-pool Authorization 
{
    "force": "bool"
}

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.
EC114 400 La orden ya está asignada y su flota no admite reenvío al pool.

Excluir orden de facturación

Quita la Order de la facturación del comercio: el comercio no recibirá pago por ella. Exige verificación en dos pasos. La orden debe estar finalizada y asociada a un comercio.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/exclude-invoices Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC242 400 La orden no está asociada a un comercio.
EC115 400 La orden no está finalizada.
EC147 400 La orden ya está excluida de facturación, o su conciliación ya fue excluida, o ya tiene una factura emitida.

Incluir orden en facturación

Reincorpora la Order a la facturación del comercio: el comercio recibirá el pago correspondiente aunque la orden no se haya entregado al cliente. Exige verificación en dos pasos. La orden debe estar finalizada y asociada a un comercio.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/include-invoices Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC242 400 La orden no está asociada a un comercio.
EC115 400 La orden no está finalizada.
EC147 400 La orden ya está incluida en facturación, o su conciliación ya fue incluida, o ya tiene una factura emitida.

Calcular cambio de dirección de envío

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

Recalcula la tarifa y el ETA del envío de la Order para una nueva dirección de destino, sin aplicarlo. El resultado se cachea 5 minutos para confirmarlo luego con update-destination-address.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/check-destination-address Authorization 
{
    "client_latitude_e6": "required|integer|between:-90000000,90000000",
    "client_longitude_e6": "required|integer|between:-180000000,180000000"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC100 400 La orden no admite repartidor.
EC116 400 La orden ya está finalizada.
EC244 400 La orden no soporta envío a domicilio.
EC240 400 No hay flota de envío disponible para la nueva dirección.

Crear orden desde administración (deprecado)

Variante de creación para administradores: identifica al cliente por client_email (client_name, client_dni, client_phone opcionales) y lo crea si no existe; luego crea la Order igual que el endpoint de creación de cliente.

{warning} Endpoint deprecado. Use el flujo de Cart (Carrito).

Método URI Cabeceras
POST /companies/{companyId}/branches/{branchId}/orders Authorization 
{
    "receiver_name": "string|max:64",
    "receiver_phone": "string|max:32",
    "client_dni": "string|max:32",
    "client_phone": "string|max:32",
    "client_name": "string|max:128",
    "client_email": "string|email:rfc,filter",
    "is_gift": "boolean",
    "client_latitude_e6": "required_without:client_address_id|integer|between:-90000000,90000000",
    "client_longitude_e6": "required_with:client_latitude_e6||integer|between:-180000000,180000000",
    "client_address": "string|max:512",
    "client_address_id": "integer",
    "pickup_latitude_e6": "integer|between:-90000000,90000000",
    "pickup_longitude_e6": "integer|between:-180000000,180000000",
    "pickup_address": "string|max:512",
    "provider_id": "integer",
    "scheduled_at": "date",
    "use_local_tz": "boolean",
    "notes": "string|max:255",
    "goods": [
        {
            "good_id": "required|integer|exists:goods,id",
            "quantity": "required|integer|min:1",
            "units": "nullable|numeric|min:0.000001",
            "provider_id": "integer",
            "notes": "string|max:255",
            "properties": [
                {
                    "property_id": "required|integer",
                    "value": "required|string"
                }
            ]
        }
    ],
    "subtotal_e2": "integer|min:0",
    "service_charge_id": "nullable|integer",
    "service_charge": "nullable|array",
    "available_delivery_providers": "nullable|array",
    "use_balance": "boolean",
    "coupon_code": "nullable|string|min:5|max:20",
    "cart_identifier": "integer|min:0",
    "all_errors": "",
    "simulate": "",
    "force_scheduling": "boolean",
    "force_providers": [
        "integer"
    ]
}

Errores de negocio

Código HTTP Cuándo ocurre
EC140 400 El client_address_id indicado no pertenece al cliente o no existe.
EF312 400 El coupon_code no es válido o ya fue utilizado.
EF323 400 El código corresponde a una gift card; solo se canjea desde el perfil.
EC603 400 El contenido del carrito resultante no es válido.
EC229 400 Uno o más ítems del pedido no son válidos.

Asigna un shopper a una orden.

Método URI Cabeceras
PUT /companies/{companyId}/orders/{orderId}/shoppers/{providerId} Authorization

Quita al Shopper de una orden. La orden queda libre para asignarla a otro Shopper.

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

Ajustar el monto de una orden

Agrega un OrderTax de tipo ajuste (amount_e2 positivo o negativo) a la Order, con description. Con adjust_client_balance: true el ajuste impacta el saldo/deuda del cliente (soporta pagos parciales si la orden no está preparada ni es de pago diferido). Con is_forced: true se permite ajustar aunque la orden ya tenga factura, recalculándola. El monto final de la orden no puede quedar en negativo.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/adjust Authorization 
{
    "amount_e2": "required|integer",
    "description": "required|string|max:128",
    "adjust_client_balance": "required|boolean",
    "is_forced": "nullable|boolean"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC124 400 La orden está cancelada.
EC146 400 La orden ya tiene una factura emitida (use is_forced para ajustar igualmente).

Relaciones