API integration guide

export AFI_API_KEY="afi_…"          # your key, from Settings → Developers
export AFI="https://app.afi.io/api/v1"
export DAY="2026-11-03"              # a delivery day, YYYY-MM-DD: today or later

curl "$AFI/me" -H "Authorization: Bearer $AFI_API_KEY"

{
  "company": { "id": 1, "name": "Bayside Fresh Co." },
  "key": { "id": 1, "name": "Shop backend", "prefix": "afi_wzPUFcTM", "scope": "full", "expiresAt": null },
  "subscription": { "state": "trial", "limits": { "maxStopsPerPlan": 500, "optimizationsPerMonth": 2000, … } }
}

curl -X POST "$AFI/orders" \
  -H "Authorization: Bearer $AFI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: SHOP-1042-$DAY" \
  -d @- <<EOF
{
  "ref": "SHOP-1042",
  "day": "$DAY",
  "name": "Olivia Shah",
  "phone": "+14155550142",
  "email": "olivia@example.com",
  "address": "1355 Market St, San Francisco, CA 94103",
  "lat": 37.7768,
  "lng": -122.4166,
  "timeWindows": [{ "start": "09:00", "end": "12:00" }],
  "packages": 2,
  "weightKg": 4.5,
  "customerNote": "Leave with the front desk"
}
EOF

{
  "id": 1,
  "ref": "SHOP-1042",
  "day": "2026-11-03",
  "status": "new",
  "test": false,
  "phoneIssue": null,
  "addressIssue": null,
  "timeZone": "America/Los_Angeles",
  "timeWindows": [{ "start": "09:00", "end": "12:00", "startAt": "2026-11-03T09:00:00-08:00", "endAt": "2026-11-03T12:00:00-08:00" }],
  "route": null,
  "draftRoute": null,
  "trackingUrl": "https://app.afi.io/t/1.bfc92ec4c7c1da1b30b0ccce",
  …
}

curl -X POST "$AFI/orders/batch" \
  -H "Authorization: Bearer $AFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "orders": [
    { "ref": "SHOP-1043", "day": "$DAY", "name": "Marcus Lee", "address": "600 Guerrero St, San Francisco, CA 94110", "lat": 37.7612, "lng": -122.4241 },
    { "ref": "SHOP-1044", "day": "$DAY", "name": "Ana Torres", "address": "2101 Irving St, San Francisco, CA 94122", "lat": 37.7637, "lng": -122.4825,
      "timeWindows": [{ "start": "13:00", "end": "17:00" }] },
    { "ref": "SHOP-1045", "day": "$DAY", "name": "Jordan Price", "lat": 120, "lng": -122.4752 }
  ]
}
EOF

{
  "results": [
    { "row": 1, "ref": "SHOP-1043", "id": 2, "result": "created", "addressIssue": null },
    { "row": 2, "ref": "SHOP-1044", "id": 3, "result": "created", "addressIssue": null },
    { "row": 3, "ref": "SHOP-1045", "result": "error", "error": "Latitude can't be more than 90", "code": "invalid_order", "field": "lat" }
  ],
  "created": 2, "updated": 0, "failed": 1
}

curl "$AFI/drivers" -H "Authorization: Bearer $AFI_API_KEY"

curl -X PUT "$AFI/days/$DAY/drivers" \
  -H "Authorization: Bearer $AFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "driverIds": [1, 2] }'

curl -X POST "$AFI/days/$DAY/optimize" \
  -H "Authorization: Bearer $AFI_API_KEY" \
  -H "Idempotency-Key: plan-$DAY-1"

{ "jobId": "75d50077-6549-449a-bccc-80cc661174c6", "state": "running", "planId": 1, "day": "2026-11-03" }

curl "$AFI/jobs/$JOB_ID" -H "Authorization: Bearer $AFI_API_KEY"

{ "id": "75d50077-…", "state": "done", "kind": "optimize", "planId": 1, "day": "2026-11-03", "error": null, … }

curl "$AFI/days/$DAY/plan" -H "Authorization: Bearer $AFI_API_KEY"

{
  "day": "2026-11-03", "planId": 1, "plannedAt": null, "dispatchedAt": null,
  "routes": [],
  "notOnRoute": [],
  "draft": {
    "plannedAt": "2026-11-02T22:12:43Z",
    "routes": [
      { "driverId": 1, "driverName": "Daniel Kim", "start": "2026-11-03T16:32:57Z", "end": "2026-11-03T17:12:57Z",
        "distanceMeters": 12623, "travelSeconds": 1233, "breaks": [],
        "visits": [
          { "position": 1, "orderId": 2, "ref": "SHOP-1043", "kind": "delivery", "arrival": "2026-11-03T16:39:51Z", "departure": "2026-11-03T16:44:51Z" },
          { "position": 2, "orderId": 1, "ref": "SHOP-1042", "kind": "delivery", "arrival": "2026-11-03T17:00:00Z", "departure": "2026-11-03T17:05:00Z" }
        ] }
    ],
    "notOnRoute": []
  }
}

curl -X POST "$AFI/days/$DAY/dispatch" \
  -H "Authorization: Bearer $AFI_API_KEY" \
  -H "Idempotency-Key: send-$DAY-1"

{
  "day": "2026-11-03",
  "dispatchedAt": "2026-11-03T14:02:57Z",
  "drivers": [
    { "driverId": 1, "url": "https://app.afi.io/d/1.3uu3J7…" },
    { "driverId": 2, "url": "https://app.afi.io/d/2.Qm9xk2…" }
  ]
}

curl "$AFI/orders/$ORDER_ID" -H "Authorization: Bearer $AFI_API_KEY"

{
  "id": 1, "ref": "SHOP-1042", "status": "assigned",
  "route": { "driverId": 1, "driverName": "Daniel Kim", "position": 2, "eta": "2026-11-03T17:00:00Z", "liveEta": null, "pickupEta": null },
  "draftRoute": null,
  "trackingUrl": "https://app.afi.io/t/1.bfc92ec4c7c1da1b30b0ccce",
  "events": [],
  "attempts": [{ "number": 1, "orderId": 1, "day": "2026-11-03", "current": true, "moved": false, "outcome": null }],
  …
}

curl "$AFI/orders?day=$DAY&ref=SHOP-1042" -H "Authorization: Bearer $AFI_API_KEY"

curl "$AFI/orders?day=$DAY&status=assigned&limit=100" -H "Authorization: Bearer $AFI_API_KEY"

curl -X PATCH "$AFI/orders/$ORDER_ID" \
  -H "Authorization: Bearer $AFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "timeWindows": [{ "start": "10:00", "end": "13:00" }], "notes": "Gate code at the side door" }'

curl -X POST "$AFI/webhooks" \
  -H "Authorization: Bearer $AFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/afi/webhooks",
    "events": ["order.status_changed", "order.eta_changed", "route.dispatched"],
    "description": "Shop backend"
  }'

{
  "id": 1,
  "url": "https://example.com/afi/webhooks",
  "events": ["order.status_changed", "order.eta_changed", "route.dispatched"],
  "enabled": true,
  "secret": "whsec_…",
  …
}

POST /afi/webhooks
Afi-Event: order.status_changed
Afi-Delivery: 3
Afi-Signature: t=1793078018,v1=5f0c…

{
  "id": "evt_EbCy9y6Dq8yoTQXL",
  "type": "order.status_changed",
  "sequence": 3,
  "occurredAt": "2026-11-03T14:02:58Z",
  "createdAt": "2026-11-03T14:02:58Z",
  "companyId": 1,
  "test": false,
  "data": {
    "order": { "id": 1, "ref": "SHOP-1042", "status": "assigned", "route": { "driverId": 1, "eta": "2026-11-03T17:00:00Z", … }, … },
    "previousStatus": "new",
    "event": null
  }
}

import http from 'node:http'
import crypto from 'node:crypto'

const secret = process.env.AFI_WEBHOOK_SECRET // whsec_…

function verify(header, rawBody) { // rawBody: the bytes as they came, before any JSON parsing
  const parts = header.split(',').map((p) => p.split('='))
  const t = Number(parts.find(([k]) => k === 't')?.[1])
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false // older than 5 minutes
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest()
  return parts.filter(([k]) => k === 'v1').some(([, sig]) => {
    const got = Buffer.from(sig, 'hex')
    return got.length === expected.length && crypto.timingSafeEqual(got, expected)
  })
}

http.createServer((req, res) => {
  const chunks = []
  req.on('data', (c) => chunks.push(c))
  req.on('end', () => {
    const raw = Buffer.concat(chunks)
    if (!verify(req.headers['afi-signature'] ?? '', raw)) { res.writeHead(401).end(); return }
    res.writeHead(200).end() // answer first, then process
    const event = JSON.parse(raw.toString('utf8'))
    const order = event.data.order ?? event.data // order.deleted, order.moved_back: id, ref, day
    console.log(event.sequence, event.type, order.ref, order.status)
  })
}).listen(3000)

orders/create, orders/updated  →  bridge  →  POST /orders
orders/cancelled               →  bridge  →  DELETE /orders/{id}
fulfillment, tracking link     ←  bridge  ←  webhooks (signed)

// Shopify orders/create and orders/updated → Afi Planner (check Shopify's own signature first)
async function sendToAfi(o, day) {
  const a = o.shipping_address
  const res = await fetch(`${process.env.AFI}/orders`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AFI_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `shopify-${o.id}-${o.updated_at}`, // Shopify may send a webhook twice
    },
    body: JSON.stringify({
      ref: o.name,
      day,
      name: a.name,
      phone: a.phone ?? o.phone,
      email: o.email,
      address: [a.address1, a.city, a.province_code, a.zip].filter(Boolean).join(', '),
      unit: a.address2 || undefined,
      ...(a.latitude != null ? { lat: a.latitude, lng: a.longitude } : {}),
      customerNote: o.note || undefined,
      customFields: { shopifyOrderId: String(o.id) },
    }),
  })
  const body = await res.json()
  if (!res.ok) throw new Error(`Afi Planner ${res.status} ${body.code}: ${body.error}`)
  return body // keep body.id with the Shopify order
}

{ "error": "Latitude can't be more than 90", "code": "invalid_request", "field": "lat" }

HTTP/1.1 200 OK
RateLimit-Limit: 600
RateLimit-Remaining: 599
RateLimit-Reset: 4