# AtlasBridge Orders API - Quickstart

> Classification: **SYNTHETIC DEMO**. AtlasBridge is fictional and this document makes no client or production claim.

## Goal

Create one order safely, retrieve it, and understand the retry contract.

## 1. Obtain a token

Use OAuth 2.0 client credentials with the scopes `orders:read orders:write`. Store credentials in your secret manager; never embed them in source code or logs.

## 2. Create an order

```bash
curl --request POST 'https://api.example.invalid/v1/orders' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 3df64025-86d3-49e9-9438-40ae8e4d8d60' \
  --header 'X-Correlation-Id: onboarding-0042' \
  --data '{"customerReference":"PO-2026-0042","currency":"EUR","lines":[{"sku":"COIL-S235JR-1250-2.0","quantity":24.5,"unit":"TNE"}]}'
```

Expected result: `201 Created` with an order ID and status `RECEIVED`.

## 3. Retry safely

If the connection ends before a response arrives, resend the identical request with the identical `Idempotency-Key`. The service returns the original result. Reusing the key for a different body returns `409 Conflict`.

## 4. Handle failures

- `400`: fix the request; do not retry unchanged.
- `401`: obtain a valid token; do not loop.
- `409`: inspect the idempotency or business-key conflict.
- `429`: wait for `Retry-After`, then retry with bounded jitter.
- `5xx` or network timeout: retry only with the same idempotency key.

## 5. Verify webhooks

Compute HMAC-SHA256 over `<timestamp>.<raw-body>`, compare in constant time, reject stale timestamps, and persist the event ID before processing. A duplicate event ID must not repeat business effects.

The complete contract is in `atlasbridge-openapi.yaml`.