Phase 1 Integration

Overview

Our integration approach focuses on simplicity and reliability, starting with essential provider integrations.

API Design

Bulk Order Upload

POST /api/v1/orders/bulk
Content-Type: multipart/form-data

file: orders.csv

Route Optimization Request

POST /api/v1/routes/optimize
Content-Type: application/json

{
  "orders": ["order_id_1", "order_id_2"],
  "constraints": {
    "time_window": {
      "start": "2024-01-01T09:00:00Z",
      "end": "2024-01-01T17:00:00Z"
    },
    "priority": "normal"
  }
}

Provider Integration

Get Quotes

POST /api/v1/quotes
Content-Type: application/json

{
  "pickup": {
    "address": "string",
    "latitude": number,
    "longitude": number
  },
  "dropoffs": [
    {
      "address": "string",
      "latitude": number,
      "longitude": number
    }
  ]
}

Data Models

Order

class Order:
    id: str
    merchant_id: str
    pickup: Location
    dropoff: Location
    time_window: TimeWindow
    priority: Priority
    status: OrderStatus

Route

class Route:
    id: str
    orders: List[Order]
    provider: Provider
    estimated_cost: float
    estimated_duration: int

Integration Flow

1. Order Upload
2. Validate CSV/JSON format
3. Process orders in batch

4. Return batch ID

5. Route Optimization

6. Group orders by area
7. Calculate optimal routes

8. Consider time constraints

9. Provider Integration

10. Get quotes from providers
11. Select best options
12. Submit orders
13. Track status

Error Handling

Validation Errors

{
  "error": "validation_error",
  "message": "Invalid order data",
  "details": [
    {
      "field": "dropoff.address",
      "error": "required"
    }
  ]
}

Processing Errors

{
  "error": "processing_error",
  "message": "Unable to optimize route",
  "batch_id": "batch_123",
  "failed_orders": ["order_id_1"]
}

Best Practices

1. Input Validation
2. Validate all input data
3. Provide clear error messages

4. Handle partial failures

5. Error Recovery

6. Implement retry logic
7. Log all failures

8. Enable manual intervention

9. Monitoring

10. Track success rates
11. Monitor processing times
12. Alert on failures