> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vambe.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> Security model, lifecycle, event types, supported currencies and operational notes for Custom Ecommerce Apps.

## Security model

| Direction              | Auth         | Detail                                                                                                                              |
| ---------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Inbound (you → Vambe)  | HMAC-SHA256  | Sign `{timestamp}.{rawBody}` with your `signing_secret`; send `x-vambe-signature` + `x-vambe-timestamp`. 5-minute freshness window. |
| Outbound (Vambe → you) | Bearer token | Vambe sends `Authorization: Bearer {merchant access_token}` + `X-Vambe-Store-Id`.                                                   |
| OAuth state            | Encrypted    | The `state` parameter is encrypted by Vambe; echo it back unchanged.                                                                |
| Secrets at rest        | AES-256      | Your `client_secret` and the app `signing_secret` are encrypted at rest.                                                            |

<Note>
  Rotate your signing secret anytime with `POST /api/ecommerce-app/{id}/rotate-secret`. The new
  secret is returned once; update your webhook signer before the old one stops being used.
</Note>

### Outbound URL requirements

* **HTTPS only.**
* Must resolve to a **public IP** — private, loopback and link-local addresses are blocked (SSRF protection).
* Respond within **\~15 seconds**.

## App lifecycle

| State            | Visible to   | Editable      | Receives events              |
| ---------------- | ------------ | ------------- | ---------------------------- |
| `draft`          | Creator      | Yes           | Yes (creator's own installs) |
| `pending_review` | Creator      | No            | Yes                          |
| `approved`       | All accounts | No            | Yes                          |
| `rejected`       | Creator      | Yes (→ draft) | No                           |
| `suspended`      | Nobody       | No            | No                           |

## Event types

### Inbound (`capabilities.inbound_events`)

| Event         | Endpoint                                                              |
| ------------- | --------------------------------------------------------------------- |
| `order`       | `POST /api/public/apps/{appId}/events/order`                          |
| `checkout`    | `POST /api/public/apps/{appId}/events/checkout`                       |
| `fulfillment` | `POST /api/public/apps/{appId}/events/fulfillment`                    |
| `product`     | `POST /api/public/apps/{appId}/events/product` and `…/product/delete` |

### Outbound (`capabilities.outbound`)

| Capability        | Tool it powers                                  |
| ----------------- | ----------------------------------------------- |
| `order_get`       | Live order status ("where is my order?")        |
| `stock_get`       | Stock by location                               |
| `checkout_create` | Checkout link generation                        |
| `products_list`   | Reserved — catalog pull (coordinate with Vambe) |

## Supported currencies

ISO codes accepted in `currency` / `total_price` / `price` fields:

```
CLP, USD, MXN, BRL, UF, ARS, COP, UYU, PEN, EUR, HNL, BOB, PYG,
GTQ, NIO, PAB, CRC, DOP, VES, BZD, SRD, GYD
```

## Operational notes

* **Idempotency.** Orders, checkouts, fulfillments and products upsert on their external id —
  safe to retry. Always retry on non-2xx; webhooks may be redelivered.
* **Product sync is incremental.** A product webhook only affects the product it carries; it
  never deletes the rest of your catalog.
* **Multi-store resolution** depends on `account_info_url` populating `external_id`. Without it,
  only single-installation apps resolve automatically.
* **Graceful degradation.** If an outbound capability is missing, slow, or errors, the
  corresponding assistant tool simply returns no data — it does not break the conversation.

## Endpoint cheat-sheet

| Method  | Path                                      | Auth        | Who               |
| ------- | ----------------------------------------- | ----------- | ----------------- |
| `POST`  | `/api/ecommerce-app`                      | `x-api-key` | Provider          |
| `PATCH` | `/api/ecommerce-app/{id}`                 | `x-api-key` | Provider          |
| `POST`  | `/api/ecommerce-app/{id}/submit`          | `x-api-key` | Provider          |
| `POST`  | `/api/ecommerce-app/{id}/rotate-secret`   | `x-api-key` | Provider          |
| `GET`   | `/api/ecommerce-app/available`            | `x-api-key` | Merchant          |
| `GET`   | `/api/public/apps/oauth/callback`         | OAuth state | Provider redirect |
| `POST`  | `/api/public/apps/{appId}/events/{event}` | HMAC        | Provider          |