Quickstart

Six steps, about five minutes. You'll create a test-mode API key on production, install an SDK, make your first signed call, register a pickup branch, dispatch a simulated delivery, and watch the webhook lifecycle play out — all without dispatching a real driver or moving real money.

1. Create a test-mode API key

1. Sign in to the business app at business.armadadelivery.com.
2. Open API Keys (under Automated Ordering) in the left nav.
3. Click Create key. A new key appears at the top of the list.
4. A banner shows the secret — copy it now. This is the only time it's shown in plain text during creation (you can always re-reveal later with the Show secret button).
5. Expand the key and make sure Test mode is ON, and at minimum these permissions are checked: delivery:write, delivery:read, wallet:read.

2. Install an SDK (or the CLI)

Every SDK installs directly from GitHub — no npm / Packagist accounts needed. Pick whichever fits your stack; the CLI is the fastest way to try the API without writing code.

npm i github:armadadelivery/armada-node#v0.1.0-beta.0

Set two environment variables so the SDK doesn't need the values hard-coded:

export ARMADA_API_KEY=main_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export ARMADA_API_SECRET=00000000-0000-0000-0000-000000000000

3. Make your first signed call

Fetch your wallet balance. The SDK handles HMAC signing; you'll never touch the headers directly unless you want to (see Authentication).

import { ArmadaClient } from '@armada/sdk';

const armada = new ArmadaClient({
  apiKey: process.env.ARMADA_API_KEY!,
  apiSecret: process.env.ARMADA_API_SECRET!,
  // defaults to https://api.armadadelivery.com
});

const { data: wallet } = await armada.wallet.get();
console.log(`balance: ${wallet.balance} ${wallet.currency}`);

If you see a balance printed, auth works. If you see a 401, double-check the environment variables — a common mistake is copying a key or secret with a trailing newline.

4. Register a pickup branch

A delivery needs a pickup branch. Create one for your testing — you'll reuse the id in every order. See Branches for the full reference.

cat > branch.json <<'EOF'
{
  "name": "QA Kitchen",
  "phone": "+96599900000",
  "address": "Salmiya Block 1, Street 1",
  "location": { "lat": 29.3359, "lng": 48.0758 }
}
EOF

armada branches create --from-file branch.json
# → note the id field in the response

5. Dispatch a test delivery

Use the branch id you just created as origin.branch_id. Because the key is flagged as Test mode, the full lifecycle (dispatched → en_route → completed) plays out in about 30 seconds with a simulated driver — no real driver is dispatched, no wallet charge.

const { data: order } = await armada.deliveries.create({
  reference: 'qs-' + Date.now(),
  payment: { amount: 4.5, type: 'paid' },
  origin_format: 'branch_format',
  origin: { branch_id: 'YOUR_BRANCH_ID' },
  destination_format: 'location_format',
  destination: {
    contact_name: 'Test Customer',
    contact_phone: '+96590000000',
    latitude: 29.3759,
    longitude: 47.9774,
    first_line: 'Salmiya, Block 5, Street 3',
  },
});

console.log(order.id, order.status);

Poll GET /v2/deliveries/:id or watch the business-app dashboard — the order will carry a "Test" badge and advance through statuses on its own.

6. Catch the webhooks (optional)

Point the delivery webhook at an endpoint you control, and you'll get notified on every status change without polling. Minimal receiver:

import express from 'express';
const app = express();
app.use(express.json());

app.post('/armada-webhook', (req, res) => {
  const topic = req.headers['x-armada-webhook-topic'];
  const keyId = req.headers['x-armada-key-id'];
  console.log(`[${topic}] order ${req.body.id} → ${req.body.status}`);
  res.sendStatus(200);
});

app.listen(3000);

In the business-app API Keys page, paste your public URL (e.g. from ngrok, cloudflared, or a deployed endpoint) into the Order update webhook field and tick the events you care about. See Webhooks for the full event catalog and payload shapes.

You're done

From here, the usual next steps:

• Deliveries — full lifecycle, all address formats, retry, cancel.
• Webhooks — every event type and payload shape.
• Test mode — what the bot driver does, when to flip it off.
• Authentication — HMAC details for when you're writing a client from scratch.