Cotiza y crea un envío

# Prices a delivery, then dispatches it at the price it was quoted.
#
#   LISTO_API_KEY=lst_test_... LISTO_STORE_ID=st_... ruby quote_and_create.rb
#
require "json"
require "net/http"
require "uri"

BASE_URL = ENV.fetch("LISTO_API_BASE_URL", "https://api.listo.delivery")
API_KEY = ENV.fetch("LISTO_API_KEY")
STORE_ID = ENV.fetch("LISTO_STORE_ID")

# Your own reference for this order. It is what you will recognise the delivery
# by in every response and every webhook, so use the id your system already has.
ORDER_ID = "order-841"

# The refusal envelope every Listo error carries, or a stand-in built from the
# status when the body is not that envelope at all. Something between you and
# Listo, a proxy or a load balancer, can answer with an HTML error page or with
# JSON of some other shape, and the code that handles a failure must not itself
# fail trying to read it.
def parse_error(response)
  stand_in = {"code" => "HTTP #{response.code}", "param" => nil}
  body = JSON.parse(response.body.to_s)
  error = body["error"] if body.is_a?(Hash)
  error.is_a?(Hash) ? error : stand_in
rescue JSON::ParserError
  stand_in
end

def post(path, payload, headers = {})
  uri = URI("#{BASE_URL}#{path}")

  request = Net::HTTP::Post.new(uri)
  request["Authorization"] = "Bearer #{API_KEY}"
  request["Content-Type"] = "application/json"
  headers.each { |name, value| request[name] = value }
  request.body = JSON.generate(payload)

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
    http.request(request)
  end

  # Check the status BEFORE parsing the body. Every refusal from Listo answers
  # with the same envelope, so branch on `error.code`, never on the message, and
  # retry only when `error.retryable` says you may.
  unless response.code.start_with?("2")
    abort("POST #{path} refused: #{parse_error(response)["code"]}")
  end

  JSON.parse(response.body)
end

dropoff = {
  "name" => "Ana Torres",
  "phone" => "+528112345678",
  "street" => "Blvd. Puerta de Hierro 4965, Zapopan, Jalisco 45116",
  "lat" => 20.709395,
  "lng" => -103.413393
}

# 1. Ask what the delivery costs. The price is held until `expires_at`, so you
# can show it to your customer before anyone commits to anything. No money
# moves and no courier is called.
quote = post(
  "/v1/quotes",
  {
    "store_id" => STORE_ID,
    "payment_method" => "cash",
    "order_value_cents" => 19_600,
    "dropoff" => dropoff
  }
)

puts "fee #{quote["fee_cents"]} #{quote["currency"]}, of which you pay #{quote["business_fee_cents"]}"
puts "the courier collects #{quote["cash_to_collect_cents"]} at the door"

# 2. Dispatch it at exactly that price by sending the quote id back.
#
# The Idempotency-Key is REQUIRED. Send the same one again after a timeout and
# you get the original delivery back instead of a second courier; send it with
# a different body and the call is refused with `idempotency_conflict`. Key it
# on your order, not on the attempt.
delivery = post(
  "/v1/deliveries",
  {
    "store_id" => STORE_ID,
    "quote_id" => quote["id"],
    "external_id" => ORDER_ID,
    "payment_method" => "cash",
    "order_value_cents" => 19_600,
    "dropoff" => dropoff
  },
  {"Idempotency-Key" => "create-#{ORDER_ID}"}
)

puts "delivery #{delivery["id"]} is #{delivery["status"]}"
puts "follow it at #{delivery["tracking_url"] || "(no link until a courier is assigned)"}"

​

La cotización

• Crear contra una cotización expirada devuelve 400 quote_expired. Pide una nueva e intenta de nuevo; no se creó nada.
• Una cotización es de un solo uso. Gastarla dos veces devuelve 400 quote_consumed, que es como se ve desde aquí un doble clic en el formulario.

​

La creación

​

Idempotency-Key es obligatorio

​

external_id es cómo lo vas a reconocer

​

Métodos de pago

• POST /v1/quotes con prepaid rechaza un business_fee_share distinto de 100 con 422 validation_failed nombrando business_fee_share. Envía 100 o déjalo fuera: sin campos de reparto, la cotización se calcula con 100, sin importar el reparto por defecto de tu tienda. Una cotización que no indica payment_method se calcula exactamente igual, porque la única entrega que puede enlazarla es una prepaid: también rechaza una parte distinta de 100, con un mensaje que lo dice y que explica que puedes indicar el payment_method. Para repartir la tarifa con tu cliente, cotiza como cash o card.
• POST /v1/deliveries con prepaid y sin quote_id fuerza la parte a 100 y crea el pedido.
• POST /v1/deliveries con prepaid y un quote_id necesita una cotización que se haya pedido con payment_method: prepaid o sin payment_method, y ambas se calculan siempre con 100. Cualquier otra cotización se rechaza con 422 validation_failed, nombrando lo primero que no coincide. Una cotización pedida como cash o card se rechaza nombrando payment_method. Una cotización cuyo reparto no es 100 sin tope (una guardada antes de esta regla) se rechaza nombrando business_fee_share (o business_fee_cap_cents), con un mensaje que dice que pidas una cotización nueva como prepaid.

​

Lo que Listo le manda a tu cliente

• El enlace de pago, en los pedidos card. En cuanto se crea un pedido card y queda esperando el pago, Listo le manda al cliente un WhatsApp con su nombre, el nombre de tu tienda, lo que debe y el enlace payment.url, y le dice que el repartidor sale en cuanto pague. Si ese WhatsApp no le llega (el número no tiene WhatsApp, o el mensaje falla), Listo le manda el mismo enlace por SMS, desde un código corto, para que lo reciba de todos modos. Se manda una vez por pedido, sin que tengas que llamar nada. Un enlace que ya no está vigente, porque el pedido se pagó o se canceló, no se manda.
• Los mensajes del repartidor, en todos los pedidos. Cuando se asigna un repartidor, cuando va en camino, cuando está llegando y cuando se entrega el pedido, Listo le manda al cliente un WhatsApp desde el mismo número, con el enlace de seguimiento y, si lo pediste, el código de entrega. Esto incluye los pedidos prepaid y cash: haber cobrado en tu propio checkout no impide que Listo le diga al cliente dónde va su pedido.

​

Propina para el repartidor

​

Programación

​

Enviarlo en coche

• Un coche es un sedán. Podemos garantizar un coche, nunca una camioneta.
• Hay menos coches que motos, así que un coche puede tardar más en asignarse.
• Un coche le suma un recargo a la tarifa de envío. Va dentro de fee_cents y se reparte como el resto de la tarifa, así que el precio que te cotizamos es el precio completo, sin una línea aparte.

​

El detalle opcional

• manifest.items es una lista de {name, quantity, size} para que el repartidor coteje. Es descriptiva: el dinero sale de order_value_cents, y lo único que un artículo puede cambiar es el vehículo, con su size (consulta enviarlo en coche).
• handoff es meet_at_door (el valor por defecto), leave_at_door o meet_outside. Los pedidos en efectivo siempre se entregan en persona.
• dropoff.notes son instrucciones por pedido para esa dirección, de máximo 280 caracteres. Las instrucciones permanentes de la tienda van en la tienda, como pickup_notes.
• verification.dropoff_pincode: true pide un código que el cliente le tiene que dar al repartidor. Regresa en el envío como verification.pincode en cuanto un repartidor tiene uno. Listo también se lo da a tu cliente en sus propios mensajes del repartidor, así que solo necesitas mostrarlo tú si lo quieres en tu pantalla.
• dropoff.lat y dropoff.lng son opcionales. Si los dejas fuera, la calle se ubica por ti; si los mandas, se usan tal cual. Manda los dos o ninguno.

​

Cuando un pedido regresa: el código de devolución

{
  "status": "returning",
  "return_verification": { "pincode": "4821" }
}

• return_verification siempre viene en el objeto. pincode es una cadena de 4 dígitos mientras status es returning, y null en cualquier otro estado, así que muestra el código cuando venga y escóndelo cuando no.
• No necesitas sondear. El webhook delivery.status_changed del paso a returning trae el objeto completo del envío, código incluido (ve webhooks).
• Es el código de la tienda, nunca el del cliente, y no es verification.pincode, que es el código de entrega que el cliente le da al repartidor. No se lo mandes a tu cliente.
• El personal debe dárselo al repartidor solo cuando ya tenga el pedido en la mano.
• Cada intento tiene su propio código. Un envío reintentado es un intento nuevo, así que recibe un código nuevo.
• Cuando el envío queda en returned, el código ya se usó y pincode vuelve a null.

​

Qué recibes de vuelta

​

Cuándo se rechaza

{
  "error": {
    "code": "out_of_service_area",
    "message": "The dropoff address is outside the delivery service area.",
    "param": null,
    "retryable": false
  }
}

​

Después de despacharlo

• GET /v1/deliveries/{id} lee uno, y GET /v1/deliveries los lista del más reciente al más antiguo, filtrados por status, payment_status, store_id, external_id, origin y una ventana de creación, y paginados con un cursor opaco.
• POST /v1/deliveries/{id}/cancellations lo cancela, con un motivo de la lista de Listo: customer_canceled, store_closed, item_unavailable, wrong_address, no_longer_needed, u other con una description. Funciona desde cualquier estado no final, y cancelar un envío ya cancelado simplemente responde con él.
• POST /v1/deliveries/{id}/retries vuelve a despachar un envío que terminó en no_courier. El id y tu external_id sobreviven al reintento, así que para ti sigue siendo un solo pedido. Si la red de repartidores rechaza la distancia del envío reintentado en la orilla de la zona de servicio, el reintento responde 422 out_of_service_area, que es definitivo: el envío se queda en no_courier y no se cobra nada.