Dropzon Public API

const express = require('express');
const crypto = require('crypto');
const app = express();

const CLIENT_ID = 'dzo_your_client_id';
const CLIENT_SECRET = 'dzs_your_client_secret';
const REDIRECT_URI = 'https://yourapp.com/callback';
const OAUTH_AUTHORIZE = 'https://dropzon.app/oauth';  // consent screen (frontend)
const OAUTH_API = 'https://api.dropzon.app/api/oauth';              // token + userinfo (API)

// Step 1: Redirect to Dropzon
app.get('/login', (req, res) => {
  const state = crypto.randomBytes(16).toString('hex');
  req.session.oauthState = state;

  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    response_type: 'code',
    scope: 'profile email',
    state,
  });

  res.redirect(OAUTH_AUTHORIZE + '/authorize?' + params);
});

// Step 3-4: Handle callback and exchange code
app.get('/callback', async (req, res) => {
  const { code, state, error } = req.query;

  if (error) return res.send('Authorization denied');
  if (state !== req.session.oauthState) return res.status(403).send('Invalid state');

  // Exchange code for tokens
  const tokenRes = await fetch(OAUTH_API + '/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      code,
      redirect_uri: REDIRECT_URI,
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
    }),
  });
  const { data: tokens } = await tokenRes.json();

  // Step 5: Fetch user info
  const userRes = await fetch(OAUTH_API + '/userinfo', {
    headers: { Authorization: 'Bearer ' + tokens.access_token },
  });
  const { data: user } = await userRes.json();

  // user = { sub, name, email, ... }
  req.session.user = user;
  res.redirect('/dashboard');
});

<a href="https://dropzon.app/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=profile email&state=RANDOM_STATE"
   style="display:inline-flex;align-items:center;gap:10px;height:44px;padding:0 20px;background:#0d84d4;color:#fff;border:none;border-radius:12px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;font-size:14px;font-weight:600;text-decoration:none;cursor:pointer;transition:opacity 0.15s;"
   onmouseover="this.style.opacity='0.9'" onmouseout="this.style.opacity='1'">
  <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none"><path d="M12 2C8.13 2 5 5.13 5 9c0 5.25 7 13 7 13s7-7.75 7-13c0-3.87-3.13-7-7-7z" fill="#ffffff"/><circle cx="12" cy="9" r="2.5" fill="white"/></svg>
  Sign in with Dropzon
</a>

<!-- 1. Add a target div where the widget should appear -->
<div id="dz-address"></div>

<!-- 2. Include the widget script with your API key -->
<script
  src="https://api.dropzon.app/widget/dz-address.js"
  data-api-key="YOUR_API_KEY"
  data-target="#dz-address"
></script>

<div id="dz-address"></div>

<!-- Your existing checkout form -->
<input id="address-line1" name="line1" placeholder="Address line 1" />
<input id="address-line2" name="line2" placeholder="Address line 2" />
<input id="address-city"  name="city"  placeholder="City" />
<input id="address-zip"   name="zip"   placeholder="ZIP / Postal code" />
<input id="address-country" name="country" placeholder="Country" />

<script
  src="https://api.dropzon.app/widget/dz-address.js"
  data-api-key="YOUR_API_KEY"
  data-target="#dz-address"
  data-autofill-line1="#address-line1"
  data-autofill-line2="#address-line2"
  data-autofill-city="#address-city"
  data-autofill-zip="#address-zip"
  data-autofill-country="#address-country"
></script>

<script src="https://api.dropzon.app/widget/dz-address.js"></script>
<script>
  const widget = Dropzon.init({
    apiKey: 'YOUR_API_KEY',
    target: '#dz-address',
    label: 'Delivery Address',
    placeholder: 'Enter your DZ# code',

    // Auto-fill form fields (CSS selectors)
    autofill: {
      line1: '#checkout-line1',
      line2: '#checkout-line2',
      city: '#checkout-city',
      zip: '#checkout-zip',
      country: '#checkout-country',
    },

    // Callbacks
    onResolve: function(address) {
      console.log('Address resolved:', address);
      // address.formatted.full   - "21 Manet St, DZ#001-01, Dar es Salaam, 16102, TZ"
      // address.formatted.line1  - "21 Manet St"
      // address.formatted.line2  - "DZ#001-01"
      // address.formatted.city   - "Dar es Salaam"
      // address.formatted.zip_code - "16102"
      // address.formatted.country - "Tanzania"
      // address.dropzon.name     - "Goba Road Dropzon"
    },

    onError: function(err) {
      console.log('Lookup failed:', err.error);
    },

    onClear: function() {
      console.log('Address cleared');
    },
  });

  // Programmatic methods
  widget.getCode();       // Returns current input value
  widget.getValue();      // Returns resolved address or null
  widget.setCode('DZ#001-01');  // Set a code and trigger lookup
  widget.clear();         // Clear everything
  widget.destroy();       // Remove widget from DOM
</script>

<script src="https://api.dropzon.app/widget/dz-address.js"></script>
<script>
  // Look up a DZ# code - returns full address data
  Dropzon.lookup('YOUR_API_KEY', 'DZ#001-01')
    .then(function(address) {
      console.log(address.formatted.full);
    })
    .catch(function(err) {
      console.error(err);
    });

  // Validate a DZ# code - check if it exists and is active
  Dropzon.validate('YOUR_API_KEY', 'DZ#001-01')
    .then(function(result) {
      console.log('Valid:', result.valid);
    });
</script>

{
  "dz_code": "DZ#001-01",
  "dz_full_code": "DZ-001-001-001-001-001",
  "label": "Home",
  "status": "active",
  "formatted": {
    "full": "21 Manet St, DZ#001-01, Dar es Salaam, 16102, TZ",
    "line1": "21 Manet St",
    "line2": "DZ#001-01",
    "city": "Dar es Salaam",
    "region": "Dar es Salaam",
    "zip_code": "16102",
    "postal_code": "16102",
    "country": "Tanzania",
    "country_code": "TZ"
  },
  "dropzon": {
    "name": "Goba Road Dropzon",
    "dz_code": "DZ#001",
    "city": "Dar es Salaam"
  }
}

<!-- 1. Add a target div where the badge should appear -->
<div id="dz-badge"></div>

<!-- 2. Include the badge script with your API key and the DZ# code -->
<script
  src="https://api.dropzon.app/widget/dz-badge.js"
  data-api-key="YOUR_API_KEY"
  data-code="DZ#001-01"
  data-target="#dz-badge"
></script>

<!-- Light theme (default), medium size -->
<script src="https://api.dropzon.app/widget/dz-badge.js"
  data-api-key="YOUR_API_KEY" data-code="DZ#001-01"
  data-target="#badge-1" data-theme="light" data-size="md">
</script>

<!-- Dark theme, large size -->
<script src="https://api.dropzon.app/widget/dz-badge.js"
  data-api-key="YOUR_API_KEY" data-code="DZ#001-01"
  data-target="#badge-2" data-theme="dark" data-size="lg">
</script>

<!-- Minimal theme (transparent bg), small size -->
<script src="https://api.dropzon.app/widget/dz-badge.js"
  data-api-key="YOUR_API_KEY" data-code="DZ#001-01"
  data-target="#badge-3" data-theme="minimal" data-size="sm">
</script>

<!-- Brand theme (Dropzon blue) -->
<script src="https://api.dropzon.app/widget/dz-badge.js"
  data-api-key="YOUR_API_KEY" data-code="DZ#001-01"
  data-target="#badge-4" data-theme="brand">
</script>

<script src="https://api.dropzon.app/widget/dz-badge.js"></script>
<script>
  const badge = DropzonBadge.init({
    apiKey: 'YOUR_API_KEY',
    code: 'DZ#001-01',
    target: '#dz-badge',
    size: 'md',        // 'sm' | 'md' | 'lg'
    theme: 'light',    // 'light' | 'dark' | 'minimal' | 'brand'
    showCode: true,    // Show the DZ# code next to "Verified"
    showTooltip: true, // Hover tooltip with status message
    animated: true,    // Pop-in animation on verify

    onVerified: function(data) {
      console.log('Address verified:', data);
      // data.valid  = true
      // data.active = true
      // data.code   = 'DZ#001-01'
    },

    onFailed: function(err) {
      console.log('Verification failed:', err);
    },
  });

  // Methods
  badge.getStatus();  // 'pending' | 'verified' | 'unverified'
  badge.reverify();   // Re-check (e.g. after code change)
  badge.destroy();    // Remove badge from DOM
</script>

<script src="https://api.dropzon.app/widget/dz-badge.js"></script>
<script>
  DropzonBadge.verify('YOUR_API_KEY', 'DZ#001-01')
    .then(function(result) {
      if (result.valid && result.active) {
        console.log('Address is verified and active');
      } else {
        console.log('Address not verified');
      }
    })
    .catch(function(err) {
      console.error('Verification error:', err);
    });
</script>

https://dropzon.app/address/DZ%23007-01

# URL pattern
https://dropzon.app/address/{url-encoded-dz-code}

# Examples
https://dropzon.app/address/DZ%23001-01   → DZ#001-01
https://dropzon.app/address/DZ%23007-03   → DZ#007-03

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "event": "package.delivered",
  "createdAt": "2025-01-15T14:30:00.000Z",
  "data": {
    "package_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tracking_number": "DZP-KE-20250115-ABC123",
    "status": "delivered",
    "origin_code": "DZ#001-01",
    "destination_code": "DZ#002-05",
    "sender_name": "John Doe",
    "recipient_name": "Jane Smith",
    "delivered_at": "2025-01-15T14:28:00.000Z"
  }
}

const crypto = require('crypto');

function verifyWebhookSignature(req, secret) {
  const signature = req.headers['x-dropzon-signature'];
  if (!signature) return false;

  const body = JSON.stringify(req.body);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  // Use timingSafeEqual to prevent timing attacks
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    );
  } catch {
    return false;
  }
}

// Express middleware example
app.post('/webhooks/dropzon', express.json(), (req, res) => {
  const WEBHOOK_SECRET = process.env.DROPZON_WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { id, event, data } = req.body;

  switch (event) {
    case 'package.delivered':
      console.log('Package delivered:', data.tracking_number);
      // Update your order status, send customer notification, etc.
      break;
    case 'package.in_transit':
      console.log('Package in transit:', data.tracking_number);
      break;
    // Handle other events...
  }

  // Respond quickly with 200
  res.status(200).json({ received: true });
});

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = 'your_webhook_secret'

def verify_signature(payload, signature, secret):
    if not signature:
        return False
    expected = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/webhooks/dropzon', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Dropzon-Signature')
    if not verify_signature(request.data, signature, WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.json
    event_type = event.get('event')
    data = event.get('data', {})

    if event_type == 'package.delivered':
        print(f"Package delivered: {data.get('tracking_number')}")
        # Update order status, notify customer, etc.

    return jsonify({'received': True}), 200

<?php
$webhookSecret = getenv('DROPZON_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_DROPZON_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $webhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

$event = json_decode($payload, true);
$eventType = $event['event'];
$data = $event['data'];

switch ($eventType) {
    case 'package.delivered':
        // Update order status, notify customer, etc.
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);

// Example delivery record in the webhook detail response
{
  "deliveries": [
    {
      "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
      "event_type": "package.delivered",
      "status_code": 200,
      "success": true,
      "attempt": 1,
      "duration_ms": 145,
      "delivered_at": "2025-01-15T14:30:01.145Z",
      "error_message": null
    },
    {
      "id": "a9b8c7d6-e5f4-3210-abcd-ef0987654321",
      "event_type": "package.in_transit",
      "status_code": 500,
      "success": false,
      "attempt": 1,
      "duration_ms": 2340,
      "delivered_at": null,
      "error_message": null
    }
  ]
}

# Register a webhook
curl -X POST https://api.dropzon.app/api/v1/webhooks \
  -H "Authorization: Bearer dzk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/dropzon",
    "events": ["package.delivered", "package.in_transit", "package.collected"],
    "description": "Order status updates"
  }'

# Response includes the webhook secret - save it!
# {
#   "webhook": {
#     "id": "abc123...",
#     "url": "https://yoursite.com/webhooks/dropzon",
#     "events": ["package.delivered", "package.in_transit", "package.collected"],
#     "secret": "whsec_xxxxxxxxxxxxxxxx",
#     "active": true,
#     "description": "Order status updates"
#   }
# }

curl -X POST https://api.dropzon.app/api/v1/rates/estimate \
  -H "Authorization: Bearer dzk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "DZ#001-01",
    "destination": "DZ#002-05",
    "weight_kg": 2.5
  }'

{
  "success": true,
  "data": {
    "origin": {
      "dropzon_id": "abc-123",
      "name": "Kariakoo Hub",
      "code": "DZ#001"
    },
    "destination": {
      "dropzon_id": "def-456",
      "name": "Mikocheni Point",
      "code": "DZ#002"
    },
    "scope": "in_city",
    "weight_kg": 2.5,
    "pricing": {
      "pickup_fee": 0,
      "shipping_fee": 5750,
      "delivery_fee": 0,
      "total": 5750,
      "currency": "TZS"
    },
    "estimated_transit": {
      "min_days": 0,
      "max_days": 1
    },
    "pickup_method": "self_drop",
    "delivery_method": "pickup"
  }
}

const response = await fetch('https://api.dropzon.app/api/v1/rates/estimate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dzk_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    origin: 'DZ#001-01',
    destination: 'DZ#002-05',
    weight_kg: 3.0,
    delivery_method: 'dropper',  // include door delivery fee
  }),
});

const { data } = await response.json();
console.log(data.pricing.total, data.pricing.currency);
// 8750 TZS
console.log(data.estimated_transit);
// { min_days: 0, max_days: 1 }

import requests

response = requests.post(
    'https://api.dropzon.app/api/v1/rates/estimate',
    headers={'Authorization': 'Bearer dzk_your_api_key'},
    json={
        'origin': 'DZ#001-01',
        'destination': 'DZ#005-12',
        'weight_kg': 5.0,
        'pickup_method': 'door_pickup',
        'delivery_method': 'dropper',
    },
)

data = response.json()['data']
print(f"Shipping: {data['pricing']['total']} {data['pricing']['currency']}")
print(f"Scope: {data['scope']}")
print(f"Transit: {data['estimated_transit']['min_days']}-{data['estimated_transit']['max_days']} days")

$ch = curl_init('https://api.dropzon.app/api/v1/rates/estimate');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer dzk_your_api_key',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'origin' => 'DZ#001-01',
        'destination' => 'DZ#002-05',
        'weight_kg' => 2.5,
    ]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$pricing = $response['data']['pricing'];
echo "Total: " . $pricing['total'] . " " . $pricing['currency'];

const response = await fetch('https://api.dropzon.app/api/v1/dispatch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dzk_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sender_dz_code: 'DZ#001-01',
    recipient_name: 'Amina Hassan',
    recipient_phone: '+255712345678',
    recipient_dz_code: 'DZ#002-05',
    weight_kg: 1.5,
    description: 'Electronics - phone case',
    client_reference: 'ORD-2026-0042',
  }),
});

const { data } = await response.json();
console.log(data.tracking_number);  // DZL-A1B2C3D4
console.log(data.pricing.total_price, data.pricing.currency);  // 5000 TZS

import requests

resp = requests.post(
    'https://api.dropzon.app/api/v1/dispatch',
    headers={'Authorization': 'Bearer dzk_your_api_key'},
    json={
        'sender_dz_code': 'DZ#001-01',
        'recipient_name': 'Baraka Ngowi',
        'recipient_phone': '+255621000000',
        'recipient_dz_code': 'DZ#003-12',
        'weight_kg': 3.0,
        'client_reference': 'SHOP-9001',
    },
)

pkg = resp.json()['data']
print(f"Tracking: {pkg['tracking_number']}")
print(f"Price: {pkg['pricing']['total_price']} {pkg['pricing']['currency']}")

const response = await fetch('https://api.dropzon.app/api/v1/dispatch/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dzk_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    parcels: [
      {
        sender_dz_code: 'DZ#001-01',
        recipient_name: 'Amina Hassan',
        recipient_phone: '+255712345678',
        recipient_dz_code: 'DZ#002-05',
        weight_kg: 1.5,
        client_reference: 'ORD-001',
      },
      {
        sender_dz_code: 'DZ#001-01',
        recipient_name: 'Baraka Ngowi',
        recipient_phone: '+255621000000',
        recipient_dz_code: 'DZ#003-12',
        weight_kg: 3.0,
        client_reference: 'ORD-002',
      },
    ],
  }),
});

const { data } = await response.json();
console.log(`Dispatched: ${data.dispatched}/${data.total}`);
console.log(`Grand total: ${data.grand_total} ${data.currency}`);

// Check for any failures
if (data.errors) {
  data.errors.forEach(err => {
    console.error(`Parcel ${err.index} (${err.client_reference}) failed: ${err.error}`);
  });
}

// Request
{
  "sender_dz_code": "DZ#001-01",
  "recipient_name": "Customer",
  "recipient_phone": "+255700000000",
  "recipient_dz_code": "DZ#005-03",
  "weight_kg": 2.0,
  "client_reference": "SHOPIFY-ORD-12345"
}

// Response
{
  "id": "pkg-uuid",
  "tracking_number": "DZL-A1B2C3D4",
  "client_reference": "SHOPIFY-ORD-12345",
  "status": "received",
  ...
}