Skip to main content

Yango Integration Guide

Complete guide to integrating with Courimax as a Yango delivery partner.

Overview​

Courimax acts as the 3PL delivery fleet for Yango. This guide covers:

  • Creating delivery orders
  • Checking delivery window availability
  • Tracking order status
  • Handling webhooks
  • Managing zones

Prerequisites​

  1. Obtain API credentials from your Courimax account manager
  2. Configure your webhook endpoint
  3. Set up delivery zones in your system

Step 1: Authentication​

All API requests require an API key in the X-API-Key header:

curl -H "X-API-Key: cmx_your_api_key" \
  https://api.courimax.com/api/integrations/yango/orders

Step 2: Check Delivery Availability​

Before creating orders, check available delivery windows:

By Zone​

curl -X GET "https://api.courimax.com/api/integrations/yango/delivery-windows?zone=TLV-CENTER&date=2026-08-20" \
  -H "X-API-Key: cmx_your_api_key"

By Address​

curl -X GET "https://api.courimax.com/api/integrations/yango/delivery-windows?address=Rothschild+Blvd+1,+Tel+Aviv&date=2026-08-20" \
  -H "X-API-Key: cmx_your_api_key"

Response:

{
  "zone": "TLV-CENTER",
  "date": "2026-08-20",
  "timezone": "Asia/Jerusalem",
  "windows": [
    {
      "start": "2026-08-20T08:00:00+03:00",
      "end": "2026-08-20T12:00:00+03:00",
      "available": true,
      "scheduledCount": 5,
      "capacityLimit": 20
    }
  ]
}

Step 3: Create Orders​

Create a delivery order with all required information:

curl -X POST "https://api.courimax.com/api/integrations/yango/orders" \
  -H "X-API-Key: cmx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-order-id-123" \
  -d '{
    "pickupAddress": "Rothschild Blvd 1, Tel Aviv",
    "pickupLat": 32.0639,
    "pickupLng": 34.7742,
    "dropoffAddress": "Dizengoff Center, Tel Aviv",
    "dropoffLat": 32.0753,
    "dropoffLng": 34.7749,
    "recipientName": "Jane Doe",
    "recipientPhone": "+972501234567",
    "packageSize": "small",
    "externalRef": "YANGO-ORDER-123",
    "deliveryZone": "TLV-CENTER",
    "deliveryWindowStart": "2026-08-20T10:00:00Z",
    "deliveryWindowEnd": "2026-08-20T14:00:00Z",
    "notes": "Handle with care"
  }'

Required Fields​

  • pickupAddress - Pickup location
  • dropoffAddress - Delivery location
  • recipientName - Recipient name
  • recipientPhone - Recipient phone
  • externalRef - Your unique order reference
  • Either packageSize or weightKg
  • Either coordinates (pickupLat/Lng, dropoffLat/Lng) or geocodeOnIngest: true

Optional Fields​

  • deliveryZone - Delivery zone name
  • deliveryWindowStart/End - Preferred delivery window
  • weightKg - Package weight
  • temperatureClass - Ambient, Chilled, or Frozen
  • deliveryMethod - motorcycle, car, or refrigerated
  • notes - Additional instructions

Step 4: Track Orders​

Check order status anytime:

curl -X GET "https://api.courimax.com/api/integrations/yango/orders/YANGO-ORDER-123" \
  -H "X-API-Key: cmx_your_api_key"

Response:

{
  "externalRef": "YANGO-ORDER-123",
  "courimaxOrderId": "order-uuid",
  "status": "in_transit",
  "driver": {
    "id": "driver-uuid",
    "name": "David Cohen",
    "phone": "+972501234567"
  },
  "deliveryWindowStart": "2026-08-20T10:00:00.000Z",
  "deliveryWindowEnd": "2026-08-20T14:00:00.000Z",
  "trackingToken": "tracking-token-abc",
  "currentMappingStatus": "assigned"
}

Order Statuses​

  • pending - Order created, awaiting dispatch
  • dispatching - Being dispatched to drivers
  • assigned - Driver assigned
  • picked_up - Package picked up
  • in_transit - In transit to destination
  • delivered - Successfully delivered
  • failed - Delivery failed
  • cancelled - Order cancelled

Step 5: Release for Dispatch​

For future-dated orders, release them for dispatch when ready:

curl -X POST "https://api.courimax.com/api/integrations/yango/orders/YANGO-ORDER-123/release" \
  -H "X-API-Key: cmx_your_api_key"

Step 6: Set Up Webhooks​

Configure your webhook endpoint to receive real-time updates:

curl -X POST "https://api.courimax.com/api/provisioning/organizations/org-uuid/api-keys/key-uuid" \
  -H "X-Provisioning-Secret: your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Yango Key",
    "platform": "yango",
    "webhookUrl": "https://your-app.com/webhooks/courimax"
  }'

Webhook events you'll receive:

  • order.created - Order created
  • order.assigned - Driver assigned
  • order.picked_up - Package picked up
  • order.in_transit - In transit
  • order.delivered - Delivered
  • order.failed - Delivery failed
  • order.cancelled - Order cancelled

See Webhooks Documentation for payload formats and security.

Step 7: Export Zones​

Export your delivery zones for reconciliation:

curl -X GET "https://api.courimax.com/api/integrations/yango/zones/export" \
  -H "X-API-Key: cmx_your_api_key"

Best Practices​

Idempotency​

Always include Idempotency-Key header to safely retry requests:

curl -H "Idempotency-Key: unique-request-id" \
  -X POST "https://api.courimax.com/api/integrations/yango/orders" \
  ...

Error Handling​

Implement retry logic for transient errors:

async function createOrderWithRetry(orderData, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(
        'https://api.courimax.com/api/integrations/yango/orders',
        {
          method: 'POST',
          headers: {
            'X-API-Key': API_KEY,
            'Content-Type': 'application/json',
            'Idempotency-Key': generateUniqueId()
          },
          body: JSON.stringify(orderData)
        }
      );
      
      if (response.status === 429) {
        // Rate limited, wait and retry
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      
      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

Capacity Planning​

  • Check availability before creating orders
  • Use bulk availability for planning
  • Monitor window capacity limits

Zone Management​

  • Keep zones updated in both systems
  • Use zone slugs for consistency
  • Export zones regularly for reconciliation

Testing​

Sandbox Environment​

Use the sandbox environment for testing:

Base URL: https://api-sandbox.courimax.com/api

Test API Keys​

Request test API keys from your account manager for:

  • Development
  • Staging
  • Integration testing

Mock Mode​

Enable mock mode for development without actual deliveries:

Contact support to enable mock mode for your test environment.

Troubleshooting​

401 Unauthorized​

  • Verify API key is correct
  • Check API key is active
  • Ensure API key matches the platform (Yango)

400 Bad Request​

  • Check all required fields are present
  • Verify coordinate format (decimal degrees)
  • Ensure date format is ISO 8601

404 Not Found​

  • Verify external reference exists
  • Check you're using the correct API key
  • Ensure order belongs to your organization

409 Conflict​

  • External reference already exists
  • Use idempotency keys for retries
  • Check for duplicate order creation

Support​

Next Steps​