# JetsLab API Integration Guide

JetsLab provides public developer documentation for logistics, delivery, merchant, marketplace, and checkout integrations. The docs are public; request authentication only applies to the API routes themselves.

## Base URLs

- Website docs: https://jetslab.co/apis
- LLM discovery: https://jetslab.co/apis/llms.txt
- API base: https://api.jetslab.co/api/v1

## Authentication models

### Merchant API key

Use this for server-to-server delivery and merchant integrations.

```http
X-API-Key: your_merchant_api_key
```

### End-user bearer token

Use this for user-owned routes and authenticated buyer sessions.

```http
Authorization: Bearer your_access_token
```

### Merchant delivery confirmation

The merchant delivery confirmation route requires both the API key and merchant secret.

```http
X-API-Key: your_merchant_api_key
X-Merchant-Secret: your_webhook_secret
```

## Recommended server integration flow

1. Create or onboard the merchant account.
2. Save the merchant API key in a secure server-side secret store.
3. Create delivery or service orders with the unified order endpoint.
4. Include `X-Idempotency-Key` on create retries so duplicate submissions do not create duplicate orders.
5. Poll order status with `GET /orders/my-orders/` or subscribe to merchant webhooks.
6. Mark the order as received after successful fulfillment.

## Core endpoints

| Purpose | Method | Path | Auth |
| --- | --- | --- | --- |
| Create order (recommended) | POST | `/orders/orders/unified-create/` | `X-API-Key` or Bearer token |
| Create delivery order (legacy) | POST | `/orders/api_deliveries/merchant_create_order` | `X-API-Key` |
| List current actor orders | GET | `/orders/my-orders/` | `X-API-Key` or Bearer token |
| Update order | PUT | `/orders/orders/{id}/` | `X-API-Key` or Bearer token |
| Delete order | DELETE | `/orders/orders/{id}/` | `X-API-Key` or Bearer token |
| Cancel order | POST | `/orders/orders/{order_id}/cancel/` | `X-API-Key` or Bearer token |
| Mark as received | POST | `/orders/order/mark-as-received` | `X-API-Key` and `X-Merchant-Secret` |
| Register merchant | POST | `/merchant/register/` | None |
| Register webhook | POST | `/merchant/register-webhook/` | Bearer token |

## Minimal create-order example

```bash
curl -X POST \
  https://api.jetslab.co/api/v1/orders/orders/unified-create/ \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_merchant_api_key' \
  -H 'X-Idempotency-Key: order-2026-04-20-001' \
  -d '{
    "services": [
      {
        "type": "DeliveryService",
        "name": "Store to customer delivery",
        "package_type": "consumer_packaged",
        "sensitivity_type": "average",
        "quantity_type": "1-10KGS",
        "urgency_type": "standard",
        "transport_type": "motorcycle",
        "locations": [
          {
            "role": "pickup",
            "locationName": {
              "address": "Store address, Kampala",
              "place_contact": "+256700000111"
            }
          },
          {
            "role": "dropoff",
            "locationName": {
              "address": "Customer address, Kampala",
              "place_contact": "+256700000222"
            }
          }
        ]
      }
    ]
  }'
```

## Webhooks

Merchant webhook registrations are authenticated with a bearer token. Keep the generated secret server-side and verify it on every inbound webhook before processing updates.

## Payments and checkout

- Keep documentation public, but enforce auth at the API request layer.
- For buyer payments, let the buyer choose the payment method instead of forcing MTN or Airtel in the UI.
- For single-buyer multi-merchant checkout, JetsLab supports one escrow with staged disbursement and partial failure handling.

## Operational guidance

- Treat all retries on create endpoints as idempotent and send `X-Idempotency-Key`.
- Keep API keys and webhook secrets on the server only.
- Use the public HTML docs when humans are browsing and the markdown guide or llms.txt when generating integrations with tooling or assistants.

## Support and docs discovery

- Public docs: https://jetslab.co/apis
- LLM discovery: https://jetslab.co/apis/llms.txt
- Root alias: https://jetslab.co/llms.txt