Entregas

Recurso central da plataforma. Gerencia o ciclo de vida completo de uma entrega.

---

Diagrama de estados

pending --> assigned --> in_progress --> completed
   ^            |              |
   |            v              v
   +---------> cancelled <----+

Apenas o admin pode criar e cancelar. O driver transiciona assigned → in_progress → completed.

---

POST /api/v1/deliveries

Cria uma nova entrega. A distancia e o ganho estimado do motorista sao calculados automaticamente via OpenRouteService.

Auth: Bearer token — role admin

Request body

Campo	Tipo	Obrigatorio	Descricao
title	string	sim	Nome/descricao da entrega
origin_address	string	sim	Endereco de origem (texto livre)
origin_lat	float	sim	Latitude de origem
origin_lng	float	sim	Longitude de origem
destination_address	string	sim	Endereco de destino (texto livre)
destination_lat	float	sim	Latitude de destino
destination_lng	float	sim	Longitude de destino

Response 201 Created

Retorna o objeto DeliveryOut completo.

Erros

Codigo	Causa
400	Campos obrigatorios ausentes
401	Token invalido
403	Usuario nao e admin
502	OpenRouteService indisponivel

PythonJavaScriptShellRuby

import requests

BASE_URL = "https://fast-deliv-backend.vercel.app"
headers = {"Authorization": f"Bearer {TOKEN}"}

payload = {
    "title": "Entrega Centro",
    "origin_address": "Rua das Flores, 100, Goiania",
    "origin_lat": -16.6869,
    "origin_lng": -49.2648,
    "destination_address": "Av. Anhanguera, 500, Goiania",
    "destination_lat": -16.6643,
    "destination_lng": -49.2744,
}

resp = requests.post(
    f"{BASE_URL}/api/v1/deliveries",
    headers=headers,
    json=payload,
)
resp.raise_for_status()
delivery = resp.json()
print(f"ID: {delivery['id']}, Status: {delivery['status']}, Distancia: {delivery['distance_km']}km")

const BASE_URL = "https://fast-deliv-backend.vercel.app";
const headers = {
  Authorization: `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};

const resp = await fetch(`${BASE_URL}/api/v1/deliveries`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    title: "Entrega Centro",
    origin_address: "Rua das Flores, 100, Goiania",
    origin_lat: -16.6869,
    origin_lng: -49.2648,
    destination_address: "Av. Anhanguera, 500, Goiania",
    destination_lat: -16.6643,
    destination_lng: -49.2744,
  }),
});
const delivery = await resp.json();
console.log(delivery.id, delivery.status);

curl -s -X POST "${BASE_URL}/api/v1/deliveries" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Entrega Centro",
    "origin_address": "Rua das Flores, 100, Goiania",
    "origin_lat": -16.6869,
    "origin_lng": -49.2648,
    "destination_address": "Av. Anhanguera, 500, Goiania",
    "destination_lat": -16.6643,
    "destination_lng": -49.2744
  }' | jq '{id, status, distance_km, driver_earnings}'

require 'net/http'
require 'json'

uri = URI("#{BASE_URL}/api/v1/deliveries")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"
req['Content-Type'] = 'application/json'
req.body = JSON.dump(
  title: 'Entrega Centro',
  origin_address: 'Rua das Flores, 100, Goiania',
  origin_lat: -16.6869,
  origin_lng: -49.2648,
  destination_address: 'Av. Anhanguera, 500, Goiania',
  destination_lat: -16.6643,
  destination_lng: -49.2744
)

resp = http.request(req)
delivery = JSON.parse(resp.body)
puts "#{delivery['id']} | #{delivery['status']}"

---

GET /api/v1/deliveries

Lista todas as entregas. Suporta filtro por status.

Auth: Bearer token — role admin

Query parameters

Parametro	Tipo	Descricao
status	string	Filtrar por status: pending, assigned, in_progress, completed, cancelled

Response 200 OK

Array de objetos DeliveryOut.

PythonJavaScriptShellRuby

# Todas as entregas
resp = requests.get(f"{BASE_URL}/api/v1/deliveries", headers=headers)
deliveries = resp.json()

# Apenas pendentes
resp = requests.get(
    f"{BASE_URL}/api/v1/deliveries",
    headers=headers,
    params={"status": "pending"},
)
pending = resp.json()
print(f"{len(pending)} entregas pendentes")

// Apenas pendentes
const resp = await fetch(
  `${BASE_URL}/api/v1/deliveries?status=pending`,
  { headers }
);
const pending = await resp.json();
console.log(`${pending.length} entregas pendentes`);

# Todas
curl -s "${BASE_URL}/api/v1/deliveries" \
  -H "Authorization: Bearer ${TOKEN}" | jq 'length'

# Apenas pendentes
curl -s "${BASE_URL}/api/v1/deliveries?status=pending" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.[].id'

uri = URI("#{BASE_URL}/api/v1/deliveries")
uri.query = URI.encode_www_form(status: 'pending')

req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
resp = http.request(req)
deliveries = JSON.parse(resp.body)
puts "#{deliveries.length} entregas pendentes"

---

PATCH /api/v1/deliveries/{id}/assign

Motorista aceita uma entrega pendente. Status muda de pending para assigned.

Auth: Bearer token — role driver

Path parameters

Parametro	Tipo	Descricao
id	UUID	ID da entrega

Erros

Codigo	Causa
404	Entrega nao encontrada
422	Entrega nao esta em status pending

PythonJavaScriptShellRuby

delivery_id = "550e8400-e29b-41d4-a716-446655440000"

resp = requests.patch(
    f"{BASE_URL}/api/v1/deliveries/{delivery_id}/assign",
    headers=headers,
)
resp.raise_for_status()
print(resp.json()["status"])  # assigned

const deliveryId = "550e8400-e29b-41d4-a716-446655440000";

const resp = await fetch(
  `${BASE_URL}/api/v1/deliveries/${deliveryId}/assign`,
  { method: "PATCH", headers }
);
const d = await resp.json();
console.log(d.status); // assigned

DELIVERY_ID="550e8400-e29b-41d4-a716-446655440000"

curl -s -X PATCH "${BASE_URL}/api/v1/deliveries/${DELIVERY_ID}/assign" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.status'

delivery_id = "550e8400-e29b-41d4-a716-446655440000"

uri = URI("#{BASE_URL}/api/v1/deliveries/#{delivery_id}/assign")
req = Net::HTTP::Patch.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
resp = http.request(req)
puts JSON.parse(resp.body)['status']

---

PATCH /api/v1/deliveries/{id}/start

Motorista inicia a coleta. Status muda de assigned para in_progress.

Auth: Bearer token — role driver

PythonJavaScriptShellRuby

resp = requests.patch(
    f"{BASE_URL}/api/v1/deliveries/{delivery_id}/start",
    headers=headers,
)
print(resp.json()["status"])  # in_progress

const resp = await fetch(
  `${BASE_URL}/api/v1/deliveries/${deliveryId}/start`,
  { method: "PATCH", headers }
);
console.log((await resp.json()).status); // in_progress

curl -s -X PATCH "${BASE_URL}/api/v1/deliveries/${DELIVERY_ID}/start" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.status'

uri = URI("#{BASE_URL}/api/v1/deliveries/#{delivery_id}/start")
req = Net::HTTP::Patch.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
puts JSON.parse(http.request(req).body)['status']

---

PATCH /api/v1/deliveries/{id}/complete

Motorista finaliza a entrega. Status muda de in_progress para completed. O ganho e creditado automaticamente na carteira do motorista.

Auth: Bearer token — role driver

PythonJavaScriptShellRuby

resp = requests.patch(
    f"{BASE_URL}/api/v1/deliveries/{delivery_id}/complete",
    headers=headers,
)
d = resp.json()
print(f"Concluida! Ganho: R$ {d['driver_earnings']}")

const resp = await fetch(
  `${BASE_URL}/api/v1/deliveries/${deliveryId}/complete`,
  { method: "PATCH", headers }
);
const d = await resp.json();
console.log(`Concluida! Ganho: R$ ${d.driver_earnings}`);

curl -s -X PATCH "${BASE_URL}/api/v1/deliveries/${DELIVERY_ID}/complete" \
  -H "Authorization: Bearer ${TOKEN}" | jq '{status, driver_earnings}'

uri = URI("#{BASE_URL}/api/v1/deliveries/#{delivery_id}/complete")
req = Net::HTTP::Patch.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
d = JSON.parse(http.request(req).body)
puts "Concluida! Ganho: R$ #{d['driver_earnings']}"

---

PATCH /api/v1/deliveries/{id}/cancel

Admin cancela uma entrega (qualquer status exceto completed).

Auth: Bearer token — role admin

PythonJavaScriptShellRuby

resp = requests.patch(
    f"{BASE_URL}/api/v1/deliveries/{delivery_id}/cancel",
    headers=headers,
)
print(resp.json()["status"])  # cancelled

const resp = await fetch(
  `${BASE_URL}/api/v1/deliveries/${deliveryId}/cancel`,
  { method: "PATCH", headers }
);
console.log((await resp.json()).status); // cancelled

curl -s -X PATCH "${BASE_URL}/api/v1/deliveries/${DELIVERY_ID}/cancel" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.status'

uri = URI("#{BASE_URL}/api/v1/deliveries/#{delivery_id}/cancel")
req = Net::HTTP::Patch.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
puts JSON.parse(http.request(req).body)['status']

---

Campos do objeto DeliveryOut

Veja a referencia completa em Modelos de Dados — Entrega.

Campos principais:

Campo	Tipo	Descricao
id	UUID	Identificador unico
title	string	Nome da entrega
status	string	pending / assigned / in_progress / completed / cancelled
origin_address	string	Endereco de origem
destination_address	string	Endereco de destino
distance_km	float	Distancia calculada em km
driver_earnings	string	Ganho do motorista em BRL (formato decimal)
driver_id	UUID ou null	ID do motorista atribuido
created_at	datetime	Data de criacao (ISO 8601)
updated_at	datetime	Ultima atualizacao (ISO 8601)