Collega BeeRoutes a tutto ciò che usi

Autenticazione

Crea una chiave API in BeeRoutes in Integrazioni → Chiavi API (solo account dell'ufficio). Inviala nell'header Authorization di ogni richiesta. Le chiavi appartengono alla tua azienda: vedono sempre e solo i tuoi dati.

curl https://app.beeroutes.com/api/v1/orders?status=delivered \
  -H "Authorization: Bearer br_live_…"

Limite: 300 richieste al minuto per chiave. Gli elenchi restituiscono fino a 200 elementi (limit, offset).

Endpoint

https://app.beeroutes.com/api/v1

Crea un ordine

Invia external_ref con l'id del tuo ordine: se invii lo stesso ordine due volte, ricevi quello esistente invece di un duplicato. Aggiungi "confirm": true per confermarlo subito.

curl -X POST https://app.beeroutes.com/api/v1/orders \
  -H "Authorization: Bearer br_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "PO-10442",
    "customer_email": "orders@cafe-central.com",
    "delivery_date": "2026-11-03",
    "slot_from": "08:00",
    "slot_to": "11:00",
    "items": [
      { "sku": "WAT-05", "quantity": 20 },
      { "sku": "JUI-01", "quantity": 6 }
    ]
  }'

Webhook

BeeRoutes invia con POST un evento JSON al tuo URL quando un ordine viene creato, confermato, assegnato, è in viaggio, consegnato, non riuscito o annullato. Aggiungi i webhook in Integrazioni o tramite l'API.

Eventi

{
  "id": "evt_5f2c…",
  "event": "order.delivered",
  "created_at": "2026-11-03T09:42:10.000Z",
  "data": {
    "id": 1842,
    "number": "ORD-2026-01842",
    "external_ref": "PO-10442",
    "status": "delivered",
    "delivery_date": "2026-11-03",
    "customer": { "id": 77, "business_name": "Café Central", … },
    "items": [ { "sku": "WAT-05", "quantity": 20, "delivered_qty": 20, … } ],
    "total": 182.4,
    "proof": { "receiver_name": "Maria", "has_signature": true, "has_photo": false },
    "delivered_at": "2026-11-03T09:42:08.000Z"
  }
}

Verifica la firma

Ogni richiesta ha un header BeeRoutes-Signature: t (unix time) e v1, l'HMAC-SHA256 di “t.body” con il secret del tuo webhook. Rispondi con un qualsiasi 2xx entro 10 secondi; le consegne non riuscite vengono ritentate una volta e un webhook viene disattivato dopo 25 errori consecutivi. Rispondi 410 per annullare l'iscrizione.

import crypto from "node:crypto";

// header: "t=1762162930,v1=5d41…"
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Errori

Gli errori usano i codici di stato HTTP e un corpo JSON con un codice e un messaggio:

{ "error": { "code": "product_not_found", "message": "Unknown or inactive products: sku JUI-09" } }

401 chiave mancante o non valida · 404 non trovato · 409 non consentito nello stato attuale dell'ordine · 422 campi non validi, SKU sconosciuto o indirizzo non trovato · 429 troppe richieste

Shopify

Nessuna app da installare. In BeeRoutes apri Integrazioni → Shopify, copia il tuo URL webhook privato in Shopify (Impostazioni → Notifiche → Webhook, “Creazione ordine” e “Annullamento ordine”) e incolla in BeeRoutes il secret di firma di Shopify. I prodotti vengono abbinati tramite SKU; i nuovi clienti vengono creati dall'indirizzo di spedizione.