Crea un envío

Despacha un envío.

Idempotency-Key es obligatorio. Envía un valor que generes por pedido, y reintenta la misma llamada con la misma llave si nunca viste una respuesta: una repetición dentro de 24 horas devuelve la respuesta original, incluido el código de estado, sin despachar un segundo repartidor ni cobrar dos veces. La misma llave con un cuerpo distinto es un 409, y también lo es una repetición enviada mientras la solicitud original todavía se está procesando (idempotency_conflict en ambos casos). Esa repetición no creó nada y no significa que la original haya fallado: una vez que la original respondió, la misma solicitud con la misma llave repite la respuesta.

dropoff.phone es E.164. Un número mexicano es +52 seguido de 10 dígitos (+52 1 seguido de 10 se acepta como lo escribe WhatsApp); un número de Estados Unidos o Canadá es +1 seguido de 10 dígitos; un número de cualquier otro país se acepta con 8 a 15 dígitos en total. Cualquier otra cosa se rechaza con validation_failed.

external_id es tu propia referencia de pedido. Es único por modo de llave, aparece en cada payload y webhook, y se puede filtrar en la lista, así que puedes conciliar sin guardar nunca nuestros ids.

pickup_ready_at programa la recolección para un momento futuro, entre 10 minutos y 29 días. Si no se envía, el pedido se despacha ahora.

El cliente paga según payment_method. cash hace que el repartidor cobre en la puerta, hasta un tope. card genera un enlace de pago de marca en payment.url, que Listo envía a tu cliente por WhatsApp (y por SMS cuando el WhatsApp no le llega), así que no necesitas enviarlo; el pedido queda en awaiting_payment hasta que el cliente paga. prepaid significa que ya te pagaron y el pedido se despacha de inmediato.

En una creación prepaid que no vincula cotización, business_fee_share se fuerza a 100 y business_fee_cap_cents se ignora, pase lo que pase en lo que envíes: ya cobraste a tu cliente, así que toda la tarifa es tuya. Una creación que vincula una cotización se sujeta al reparto con el que se fijó esa cotización, así que pide la cotización con payment_method: prepaid o sin payment_method: cualquiera de las dos siempre se fija con reparto de 100 y vincula una creación prepaid. Cualquier otra cotización se rechaza con 422 validation_failed, y se nombra lo primero que no coincida. Una cotización pedida con otro payment_method (cash o card) se rechaza y nombra payment_method. Una cotización cuyo reparto no es el que tiene un pedido prepaid (reparto de 100, sin techo) se rechaza y nombra business_fee_share o business_fee_cap_cents, y error.message dice por qué y qué enviar en lugar de eso: una cotización nueva pedida con payment_method: prepaid.

vehicle es moto (el valor por defecto) o car, y manifest.items[].size es small (el valor por defecto), medium, large o xlarge. Un trayecto va en auto cuando lo pides o cuando algún artículo tiene talla xlarge, y por ningún otro motivo. Un auto es un sedán, nunca una camioneta, puede tardar más en asignarse, y suma un recargo dentro de fee_cents. El vehicle del envío indica con qué se cotizó y despachó el trayecto; courier.vehicle_type es lo que llegó en realidad, que puede ser un auto en un trayecto moto sin que la tarifa cambie.

Una creación que vincula una cotización se sujeta al vehículo con el que se cotizó. Si omites vehicle, hereda el de la cotización. Si pones moto contra una cotización de auto, car contra una cotización de moto, o envías un artículo de talla xlarge contra una cotización de moto, se rechaza con 422 validation_failed y nombra vehicle (o manifest.items cuando lo que no coincide son las tallas). Vuelve a cotizar con el carrito que quieres enviar.

simulate ensaya lo que sale mal, y solo funciona con una llave de prueba. Una llave real que lo envíe se rechaza con 422 validation_failed y nombra simulate, y lo mismo pasa con cualquier valor que no sea uno de los tres de abajo. Si lo omites, el envío sigue el flujo normal sin incidentes.

• returned: el repartidor llega a la puerta, no puede entregar el pedido y se lo lleva de vuelta. El envío pasa a returning y termina en returned con failure_reason: customer_unavailable, y la devolución se cobra igual que una real: una entrada return_fee en charges cubre ambos trayectos (ver charges).
• no_courier: la creación responde el mismo 409 no_couriers_available que una creación real cuando todos los repartidores están ocupados, y no se crea, cobra ni registra nada bajo tu Idempotency-Key. No hay envío que reintentar; repite la llamada.
• delayed_pickup: el repartidor llega tarde. La recolección ocurre unos 25 minutos después de la creación y la entrega unos 5 minutos después de eso, contados desde pickup_ready_at si enviaste uno (el envío espera en scheduled hasta entonces). Pasa por los mismos estados que la ejecución normal.

En modo de prueba, un envío puede pasar de dispatching directamente a picking_up sin mostrar nunca un estado courier_assigned, en todos los escenarios. No esperes a que aparezca: courier_assigned_at y el objeto del repartidor ya vienen llenos.

No hay escenario para un repartidor que desiste antes de la recolección. El mismo Idempotency-Key con un simulate distinto es un 409 idempotency_conflict, como cualquier cuerpo modificado, una vez que una solicitud usó la llave (creó un envío o todavía se está procesando). Una solicitud rechazada antes de crear algo, como el 409 de no_courier, deja la llave libre: envíala de nuevo con un simulate distinto, o sin él, y será una solicitud nueva. Un envío returned no se puede reintentar (409 not_retriable): su pedido terminó.

Un carrito demasiado grande para un solo viaje de repartidor se rechaza con 422 order_too_large, nombra manifest.items, y no se despacha ni se cobra nada. Divídelo en dos envíos.

Listo entrega en México. Una tienda que resulte estar en otro lugar se rechaza con 422 unsupported_country y no se despacha ni se cobra nada; es definitivo en lugar de reintentable, y la misma tienda se rechazará siempre.

Una tienda cuyo punto de recolección no podemos avalar por ahora se rechaza con 409 pickup_point_pending, y no se despacha ni se cobra nada: hasta que se confirme, un repartidor podría ir al lugar equivocado. Por lo general la dirección de la tienda acaba de cambiar y la confirmación todavía no llega, pero no siempre, así que no lo leas como “el comercio se mudó”. A diferencia del rechazo de arriba, este sí es reintentable, porque nada de tu solicitud está mal y la misma llamada funciona en cuanto se confirma el punto de recolección.

Reintenta con una espera de minutos, por un número acotado de intentos, y luego pásalo a una persona en lugar de seguir consultando. La mayoría de los cambios se resuelven solos en minutos; unos pocos se detienen por algo que solo nuestro equipo puede liberar y tardan bastante más, y esta respuesta no distingue entre los dos. Por eso no hay Retry-After: estaríamos inventando el número. El restaurante también puede desbloquearlo él mismo desde su propia consola de Listo, que suele ser la vía más rápida de las dos.

Cuando todos los repartidores cercanos al trayecto están ocupados al momento en que la creación lo cotiza, la creación se rechaza con 409 no_couriers_available, y no se despacha ni se cobra nada. Es reintentable: repite la solicitud idéntica, con el mismo Idempotency-Key, después de unos minutos, por un número acotado de intentos. No quedó nada registrado con esa llave, así que la repetición crea el pedido en cuanto haya un repartidor libre, en lugar de repetir el rechazo.

Una tienda real cuyo Plan Listo no está pagado al corriente se rechaza con 402 plan_required, y no se despacha ni se cobra nada. Es un rechazo distinto de 402 insufficient_balance, que trata de tu saldo: lee error.code, nunca solo el estado. error.message nombra el motivo (no hay plan activo, un cobro pendiente, un plan que terminó en una fecha dada, un plan cuyos envíos incluidos del ciclo ya se usaron todos, o una tienda que no puede pedir repartidores en este momento), y no es retryable. Consulta Plan y facturación.

Un punto de entrega más allá del área de servicio de 15 km de la tienda se rechaza con 422 out_of_service_area, que es definitivo. La red de repartidores también puede rechazar la distancia de un punto de entrega justo en el borde de ese círculo, y la respuesta es el mismo 422, ya sea que lo rechace por el precio o por la creación misma. En la creación, esto ocurre después de que el envío quedó registrado, así que el envío se queda, terminado en no_courier con failure_reason: delivery_failed bajo tu external_id, con el cargo de tarifa devuelto por completo y sin ningún otro cobro; repetir la solicitud responde el mismo 422. Envía ese pedido a otra dirección con un external_id nuevo.