Skip to main content

Floating Deli Integration Guide

Complete guide to integrating with Courimax for Floating Deli merchant deliveries.

Overview​

Courimax integrates with Floating Deli for restaurant and merchant deliveries. This guide covers:

  • Checking delivery feasibility
  • Creating delivery orders
  • Marking orders ready for pickup
  • Tracking order status
  • Canceling orders
  • Handling webhooks

Prerequisites​

  1. Obtain Floating Deli API credentials from your Courimax account manager
  2. Configure your webhook endpoint
  3. Understand your merchant delivery workflow

Step 1: Authentication​

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

curl -H "X-API-Key: cmx_your_floating_deli_api_key" \
  https://api.courimax.com/api/integrations/floating-deli/orders

Step 2: Check Feasibility​

Before creating an order, check if delivery is feasible:

curl -X POST "https://api.courimax.com/api/integrations/floating-deli/feasibility" \
  -H "Content-Type: application/json" \
  -d '{
    "pickupLat": 32.0639,
    "pickupLng": 34.7742,
    "dropoffLat": 32.0753,
    "dropoffLng": 34.7749,
    "packageSize": "small"
  }'

Response:

{
  "feasible": true,
  "estimatedDeliveryMinutes": 25,
  "distance": 3.5,
  "zone": "TLV-CENTER"
}

Feasibility Request Schema​

{
  pickupLat: number;      // Pickup latitude
  pickupLng: number;      // Pickup longitude
  dropoffLat: number;     // Dropoff latitude
  dropoffLng: number;     // Dropoff longitude
  packageSize?: string;   // "small", "medium", or "large"
}

Response Fields​

  • feasible - Whether delivery is possible
  • estimatedDeliveryMinutes - Estimated delivery time
  • distance - Distance in kilometers
  • zone - Delivery zone

Step 3: Create Orders​

Create a delivery order:

curl -X POST "https://api.courimax.com/api/integrations/floating-deli/orders" \
  -H "X-API-Key: cmx_your_floating_deli_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-order-id-789" \
  -d '{
    "pickupAddress": "Restaurant Name, Rothschild Blvd, Tel Aviv",
    "pickupLat": 32.0639,
    "pickupLng": 34.7742,
    "dropoffAddress": "Customer Address, Dizengoff Center, Tel Aviv",
    "dropoffLat": 32.0753,
    "dropoffLng": 34.7749,
    "recipientName": "John Doe",
    "recipientPhone": "+972501234567",
    "externalRef": "FD-ORDER-123",
    "merchantName": "Pizza Palace",
    "prepMinutes": 15,
    "items": [
      {
        "name": "Margherita Pizza",
        "quantity": 2
      },
      {
        "name": "Caesar Salad",
        "quantity": 1
      }
    ],
    "requiresPinHandshake": false,
    "notes": "Ring doorbell"
  }'

Required Fields​

  • pickupAddress - Merchant address
  • pickupLat/Lng - Merchant coordinates
  • dropoffAddress - Customer address
  • dropoffLat/Lng - Customer coordinates
  • recipientName - Customer name
  • recipientPhone - Customer phone
  • externalRef - Your unique order reference
  • merchantName - Merchant name

Optional Fields​

  • prepMinutes - Preparation time (max 180 minutes)
  • items - Array of order items
  • requiresPinHandshake - Require PIN verification
  • notes - Delivery instructions

Item Schema​

{
  name: string;         // Item name
  quantity: number;     // Quantity (default: 1)
}

Step 4: Mark Order Ready​

When the merchant finishes preparation, mark the order as ready:

curl -X POST "https://api.courimax.com/api/integrations/floating-deli/orders/FD-ORDER-123/ready" \
  -H "X-API-Key: cmx_your_floating_deli_api_key"

Response:

{
  "ready": true,
  "orderId": "order-uuid",
  "status": "pending",
  "readyAt": "2026-08-19T12:30:00.000Z"
}

This triggers driver dispatch for pickup.

Step 5: Track Orders​

Check order status:

curl -X GET "https://api.courimax.com/api/integrations/floating-deli/orders/FD-ORDER-123" \
  -H "X-API-Key: cmx_your_floating_deli_api_key"

Response:

{
  "externalRef": "FD-ORDER-123",
  "courimaxOrderId": "order-uuid",
  "status": "in_transit",
  "driver": {
    "id": "driver-uuid",
    "name": "David Cohen",
    "phone": "+972501234567"
  },
  "merchantName": "Pizza Palace",
  "items": [
    { "name": "Margherita Pizza", "quantity": 2 },
    { "name": "Caesar Salad", "quantity": 1 }
  ],
  "trackingToken": "tracking-token-abc",
  "currentMappingStatus": "assigned"
}

Step 6: Cancel Orders​

Cancel an order if needed:

curl -X POST "https://api.courimax.com/api/integrations/floating-deli/orders/FD-ORDER-123/cancel" \
  -H "X-API-Key: cmx_your_floating_deli_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer cancelled order"
  }'

Response:

{
  "cancelled": true,
  "orderId": "order-uuid",
  "status": "cancelled"
}

Step 7: Set Up Webhooks​

Configure your webhook endpoint:

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 Floating Deli Key",
    "platform": "floating_deli",
    "webhookUrl": "https://your-app.com/webhooks/courimax"
  }'

Webhook events:

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

Merchant Workflow​

Standard Flow​

  1. Order Received: Customer places order with merchant
  2. Feasibility Check: Check if delivery is feasible
  3. Create Order: Create delivery order in Courimax
  4. Preparation: Merchant prepares order (prepMinutes)
  5. Mark Ready: Merchant marks order ready
  6. Driver Dispatch: System assigns driver
  7. Pickup: Driver picks up from merchant
  8. Delivery: Driver delivers to customer
  9. Confirmation: Receive webhook confirmation

PIN Handshake​

For high-value orders, require PIN verification:

{
  "requiresPinHandshake": true
}

Driver must collect PIN from customer before completing delivery.

Best Practices​

Preparation Time​

Accurately estimate preparation time:

{
  "prepMinutes": 15
}

This helps optimize driver dispatch timing.

Order Items​

Include order items for driver reference:

{
  "items": [
    { "name": "Margherita Pizza", "quantity": 2 },
    { "name": "Caesar Salad", "quantity": 1 }
  ]
}

Delivery Instructions​

Provide clear delivery instructions:

{
  "notes": "Ring doorbell, leave at door if no answer"
}

Feasibility Checks​

Always check feasibility before creating orders:

async function createOrderIfFeasible(orderData) {
  // Check feasibility first
  const feasibility = await checkFeasibility({
    pickupLat: orderData.pickupLat,
    pickupLng: orderData.pickupLng,
    dropoffLat: orderData.dropoffLat,
    dropoffLng: orderData.dropoffLng,
    packageSize: orderData.packageSize
  });
  
  if (!feasibility.feasible) {
    throw new Error('Delivery not feasible');
  }
  
  // Create order
  return await createOrder(orderData);
}

Timing​

  • Check feasibility immediately when order is placed
  • Create order as soon as feasible
  • Mark ready when preparation is complete
  • Monitor driver assignment

Error Handling​

Common Errors​

400 Bad Request - Validation error

{
  "statusCode": 400,
  "message": ["externalRef (merchant order ID) is required"],
  "error": "Bad Request"
}

401 Unauthorized - Invalid API key

{
  "statusCode": 401,
  "message": "Missing X-API-Key header",
  "error": "Unauthorized"
}

404 Not Found - Order not found

{
  "statusCode": 404,
  "message": "Order not found",
  "error": "Not Found"
}

409 Conflict - Cannot cancel order

{
  "statusCode": 409,
  "message": "Cannot cancel order that has already been picked up",
  "error": "Conflict"
}

Testing​

Test Orders​

Create test orders:

curl -X POST "https://api.courimax.com/api/integrations/floating-deli/orders" \
  -H "X-API-Key: cmx_floating_deli_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pickupAddress": "Test Restaurant",
    "pickupLat": 32.0639,
    "pickupLng": 34.7742,
    "dropoffAddress": "Test Customer",
    "dropoffLat": 32.0753,
    "dropoffLng": 34.7749,
    "recipientName": "Test Customer",
    "recipientPhone": "+972500000000",
    "externalRef": "TEST-001",
    "merchantName": "Test Merchant",
    "prepMinutes": 10
  }'

Integration Checklist​

  • Obtain API credentials
  • Configure webhook endpoint
  • Implement feasibility checks
  • Implement order creation
  • Implement mark ready
  • Implement order tracking
  • Implement order cancellation
  • Handle webhook events
  • Implement error handling
  • Test in sandbox environment
  • Deploy to production
  • Monitor webhook delivery

Support​

Next Steps​