# Overview

End-to-end recipes for the four common integrations.

Four end-to-end recipes, each written against endpoints that exist today. Every
field name is the real one, and every sample runs.

## The guides

| Guide                                                                                        | What it covers                                                                                                | You need                                      |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| [Create an order](https://www.salafems.com/developers/guide-create-an-order.md)              | Resolving a customer and variants, placing the order idempotently, and reading what comes back.               | `orders:write`, `products:read`               |
| [Sync inventory to an ERP](https://www.salafems.com/developers/guide-sync-inventory.md)      | The `updated_after` + cursor pattern, checkpoints that survive a crash, and why offset paging is not offered. | `products:read`, `inventory:read`             |
| [Handle webhooks idempotently](https://www.salafems.com/developers/guide-handle-webhooks.md) | Verify, de-duplicate, upsert, answer fast — the whole receiver.                                               | A webhook endpoint                            |
| [Build a custom storefront](https://www.salafems.com/developers/guide-custom-storefront.md)  | Reading the catalogue, checking availability, taking an order and recording payment.                          | Read scopes, `orders:write`, `payments:write` |

## Before any of them

1. **Create a key** with only the scopes that guide needs
   ([Authentication](https://www.salafems.com/developers/authentication.md)). Start with a store key.
2. **Export it** as `SALAF_API_KEY` — every sample in these docs reads it from
   the environment rather than inlining it.
3. **Point at `/ext/v1`** — `https://api.salafems.com/ext/v1`. The shorter
   `/v1` alias is not deployed yet.

```bash
export SALAF_API_KEY="salaf_sk_YOUR_API_KEY"

curl -sS "https://api.salafems.com/ext/v1/products?limit=1" \
  -H "Authorization: Bearer $SALAF_API_KEY"
```

If that returns a product, you are ready for any of the four.

## The patterns they share

Every integration in this list ends up leaning on the same four things, so they
are worth learning once:

- **Cursor pagination** — [`limit` + `starting_after` + `meta.has_more`](https://www.salafems.com/developers/pagination.md#walking-every-page).
- **Incremental sync** — [`updated_after` with a watermark](https://www.salafems.com/developers/pagination.md#syncing-changes-with-updated_after).
- **Idempotent writes** — [one key per logical operation](https://www.salafems.com/developers/idempotency.md#idempotency-key).
- **One error shape** — [branch on `code`, log the `request_id`](https://www.salafems.com/developers/errors.md#handling-errors-well).