API Improvements request.

A practical wish-list of API improvements.

## Must-haves

1. **Real “Order” resource (bill-centric)**

* Introduce `/orders` with one ID per `id_bill`.
* Include items array, buyer, shipping address, shipping cost, currency, fees, payment status, timestamps, and seller notes.


2. **Fulfillment APIs**

* `POST /orders/{id}/fulfillments` with `{carrier, tracking_number, tracking_url, shipped_at}`.
* `GET /orders/{id}/fulfillments` to read them.
* Optional “notify buyer” flag.

3. **Event/webhook overhaul**

* Send webhooks as JSON body (`Content-Type: application/json`), not form-encoded XML blobs.
* Include `event_id`, `event_type`, `created_at`, `resource_type`, `resource_id`, and a stable signature.
* HMAC signature header, e.g. `X-Delcampe-Signature` with timestamp and SHA-256.
* Standard types: `order.created`, `order.paid`, `order.refunded`, `order.cancelled`, `order.fulfillment.created`, `item.updated`, `item.closed`.
* Delivery controls: retry schedule documented, `X-Delivery-Attempt`, `X-Event-ID`, and a replay API:

* `POST /webhooks/events/{event_id}/replay`
* `GET /webhooks/logs?since=…&status=failed|delivered`
* “Test send” endpoint: `POST /webhooks/test {type, destination}`.

4. **Webhook management that prevents duplicates**

* Server-side uniqueness on `(type, destination)` per seller, or an `active` flag with single active allowed.
* Proper DELETE that actually removes, and `PATCH /webhooks/{id} {active:false}` to disable.

5. **Filtering and pagination that scale**

* Cursor pagination everywhere:

* `GET /orders?limit=200&cursor=abc123`
* Response includes `next_cursor`.
* Filters: `updated_since`, `status`, `buyer_id`, `item_id`, `sku`, `selling_type`.

6. **Clean numeric money fields**

* Always send amounts as strings with 2–4 decimals plus a `currency` code on each envelope.
* Include both `platform_fee` and `shipping` as numeric fields in `Seller_Payment_Received` equivalents.

## Nice-to-haves that save everyone time

7. **JSON everywhere with versioning**

* Dual format is fine, but JSON should be first-class with a clear versioning scheme:

* Header based: `Accept: application/vnd.delcampe.v1+json`
* Or path based: `/v1/orders`.

8. **Auth & security**

* OAuth 2.0 client-credentials for server-to-server in addition to API keys.
* Key rotation API.
* IP allowlist docs for webhook source IPs.
* Optional mTLS for webhooks.

9. **Idempotency**

* Support `Idempotency-Key` on POST endpoints and return the same result when retried.
* Include a `dedupe_key` in webhooks to help consumers ignore duplicates.

10. **Error model and rate limit headers**

* Consistent error envelope:

```json
{ "error": { "code":"rate_limited", "message":"…", "details":{…}, "request_id":"req_123" } }
```

* Standard headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`.

11. **Change data capture**

* `GET /events?since=cursor&types=order.paid,item.updated` so integrators can backfill or catch missed webhooks without guessing which resource to poll.

12. **Catalog sync quality**

* Webhooks for `item.created`, `item.updated`, `item.closed`, `item.relisted`.
* Bulk endpoints: `POST /items/bulk`, `GET /items?ids=…`.

13. **Messaging**

* `POST /orders/{id}/messages` to send a seller→buyer message with attachments.
* Webhook `order.message.created` when buyer replies.

14. **Sandbox and tooling**

* Dedicated sandbox environment with test buyers and fake payments.
* Official OpenAPI 3.1 spec, Postman collection, and minimal SDKs (PHP, Python, JS).
* “Try it” console with real credential masking.

15. **Docs and stability signals**

* Clear state diagrams for item and order lifecycles.
* Changelog with breaking-change windows.
* Public status page and incident history for webhooks and API.

16. **Consistency fixes**

* Uniform ISO-8601 timestamps with timezone.
* Field naming without oddities like `Ressource`.
* Use `200/201/204/400/401/403/404/409/422/429/5xx` predictably.

## Small but high-leverage tweaks

17. **Orders “updated\_since”**

* `GET /orders?updated_since=2025-08-26T00:00:00Z` returns any order touched after that timestamp.

18. **Webhook delivery window**

* Document the exact timeout and backoff curve. Include the last 50 attempts in the logs API with request and response status.

19. **Bulk export**

* `GET /orders/export?from=…&to=…&format=csv|ndjson` for accounting and reconciliation.

20. **Test helpers**

* `POST /orders/{id}/simulate {event:"paid"}` in sandbox.
* `POST /webhooks/test` to validate receiving endpoint and signature verification.

Hi fdstamps_test,

Thank you for this list, all the changes have been added to our backlog for further analysis

Fred