Lidheni BeeRoutes me gjithçka që përdorni

Autentikimi

Krijoni një çelës API në BeeRoutes te Integrimet → Çelësat API (vetëm llogaritë e zyrës). Dërgojeni në kokën Authorization të çdo kërkese. Çelësat i përkasin kompanisë suaj: shohin vetëm të dhënat tuaja.

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

Kufiri: 300 kërkesa në minutë për çelës. Listat kthejnë deri në 200 elemente (limit, offset).

Pikat fundore

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

Krijimi i një porosie

Dërgoni external_ref me id-në e porosisë suaj: nëse e njëjta porosi dërgohet dy herë, kthehet ajo ekzistuese në vend të një kopjeje. Shtoni "confirm": true për ta konfirmuar menjëherë.

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 }
    ]
  }'

Webhooks

BeeRoutes dërgon me POST një ngjarje JSON në URL-në tuaj kur një porosi krijohet, konfirmohet, i caktohet shoferit, niset, dorëzohet, dështon ose anulohet. Shtoni webhooks te Integrimet ose me API.

Ngjarjet

{
  "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"
  }
}

Verifikoni nënshkrimin

Çdo kërkesë ka kokën BeeRoutes-Signature: t (koha unix) dhe v1, HMAC-SHA256 i “t.body” me sekretin e webhook-ut. Përgjigjuni me çfarëdo 2xx brenda 10 sekondave; dërgimet e dështuara provohen edhe një herë dhe webhook-u çaktivizohet pas 25 dështimesh radhazi. Përgjigjuni me 410 për t'u çabonuar.

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));
}

Gabimet

Gabimet përdorin kodet e statusit HTTP dhe një trup JSON me kod dhe mesazh:

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

401 çelës mungon ose i pavlefshëm · 404 nuk u gjet · 409 nuk lejohet në statusin e porosisë · 422 fusha të pavlefshme, SKU e panjohur ose adresë e pagjetur · 429 shumë kërkesa

Shopify

Pa aplikacion për të instaluar. Në BeeRoutes hapni Integrimet → Shopify, kopjoni URL-në tuaj private të webhook-ut në Shopify (Settings → Notifications → Webhooks, “Order creation” dhe “Order cancellation”) dhe ngjitni sekretin e nënshkrimit të Shopify. Produktet përputhen sipas SKU-së; klientët e rinj krijohen nga adresa e dërgesës.