VeloCitta API — Documentazione

Introduzione

L'API VeloCitta consente alle aziende di integrare il servizio di consegne urbane nei propri sistemi ERP, e-commerce o gestionali.

🔑 Autenticazione: Includi il tuo API key nell'header x-api-key di ogni richiesta. Trovi la chiave nella sezione "API Access" del tuo profilo aziendale.

Base URL

https://velocitta.freccia-verde.com/functions/v1/api-gateway

Autenticazione

curl -H "x-api-key: vlt_la_tua_chiave" \
     -H "Content-Type: application/json" \
     https://velocitta.freccia-verde.com/functions/v1/api-gateway/subscription

Ordini

POST/orders

Crea un nuovo ordine di consegna.

Parametri

pickup_address obbligatorio — Indirizzo di ritiro

delivery_address obbligatorio — Indirizzo di consegna

price_total obbligatorio — Prezzo totale in EUR (min €8)

cargo_category — small | medium | large | other (default: small)

recipient_name — Nome del destinatario

recipient_phone — Telefono del destinatario

description — Descrizione della merce

{
  "pickup_address": "Via Roma 1, 30100 Venezia",
  "delivery_address": "Via Verdi 5, 30100 Venezia",
  "price_total": 12.00,
  "cargo_category": "small",
  "recipient_name": "Mario Rossi",
  "recipient_phone": "+393391234567"
}

Risposta

{
  "order_id": "uuid",
  "order_number": "VLT-001025",
  "status": "pending"
}

GET/orders

Lista degli ordini dell'azienda.

Query parameters

status — Filtra per stato (pending, accepted, in_transit, delivered, cancelled)

limit — Numero di risultati (default: 20, max: 100)

offset — Paginazione (default: 0)

GET /orders?status=delivered&limit=10&offset=0

GET/orders/{id}

Dettaglio e stato di un singolo ordine.

{
  "id": "uuid",
  "order_number": "VLT-001025",
  "status": "in_transit",
  "pickup_address": "...",
  "delivery_address": "...",
  "price_total": 12.00,
  "created_at": "2026-05-05T10:00:00Z",
  "accepted_at": "2026-05-05T10:05:00Z",
  "picked_up_at": "2026-05-05T10:30:00Z",
  "delivered_at": null
}

DELETE/orders/{id}

Annulla un ordine. Possibile solo se lo stato è pending o awaiting_payment.

{ "success": true, "message": "Order cancelled" }

Webhooks

I webhooks ti consentono di ricevere notifiche automatiche quando lo stato di un ordine cambia.

POST/webhooks

Registra un endpoint per ricevere eventi.

{
  "url": "https://tuosistema.com/velocitta-webhook",
  "events": ["order.accepted", "order.delivered", "order.cancelled"]
}

Eventi disponibili

order.created — Ordine creato

order.accepted — Corriere assegnato

order.picked_up — Pacco ritirato

order.delivered — Consegna completata

order.cancelled — Ordine annullato

GET/webhooks

Lista degli endpoint registrati.

Abbonamento

GET/subscription

Stato della tua sottoscrizione API.

{
  "status": "trial",
  "trial_ends_at": "2026-08-03T10:00:00Z",
  "days_remaining": 90,
  "monthly_price_eur": 29.00
}

Codici di errore

Codice	Significato
401	API key mancante o non valida
402	Abbonamento scaduto — effettua il pagamento
400	Parametri mancanti o non validi
404	Risorsa non trovata
503	API temporaneamente disabilitata