# Prise en main de l'API OmniManager

> Authentification, enveloppe de réponse, permissions et limites de débit communes à toutes les routes /api/v1.

# Prise en main

L'API publique OmniManager (`/api/v1/**`) donne un accès programmatique au
compte d'un tenant via une clé API propre au tenant : boutiques, connexion
et envoi WhatsApp, statuts, groupes, et gestion du consentement — avec la
politique anti-bannissement de la plateforme appliquée en votre nom à chaque
envoi.

URL de base : `https://console.omni-manager.com/api/v1`

## Authentification

Créez une clé dans **Paramètres → API** (nécessite `canEditSettings`), ou
demandez à un administrateur OmniManager d'en créer une pour votre tenant.
La clé brute (`omk_live_…`) n'est affichée qu'une seule fois ; seule son
empreinte SHA-256 est stockée, donc si vous la perdez, vous devez la
régénérer, pas la « récupérer ».

Envoyez-la à chaque requête :

```
Authorization: Bearer omk_live_YOUR_KEY
```

(`x-api-key: omk_live_YOUR_KEY` est accepté comme alias.)

Une clé peut porter une expiration et une liste blanche d'IP ; révoquer une
clé (depuis les Paramètres ou l'administration) prend effet immédiatement —
la requête suivante avec cette clé échoue avec `401 API_KEY_REVOKED`.

## Permissions

Chaque route requiert une permission de cette liste
(`src/libs/api-keys/permissions.ts`) ; une clé ne dispose que de celles qui
lui ont été accordées :

| Permission | Accorde |
|---|---|
| `shops.read` | lister/lire les boutiques |
| `shops.write` | créer des boutiques |
| `whatsapp.read` | lire l'état du canal WhatsApp |
| `whatsapp.connect` | démarrer/interroger/arrêter la connexion WhatsApp |
| `messages.send` | envoyer des messages WhatsApp |
| `messages.read` | lire l'état des messages/livraisons |
| `statuses.post` | publier un statut WhatsApp |
| `contacts.read` | lister les contacts déclarés (consentants) |
| `contacts.write` | déclarer / révoquer des contacts consentants |
| `groups.read` | lister les groupes WhatsApp de la boutique |

`GET /me` ne nécessite aucune de ces permissions — une clé n'ayant qu'une
seule permission peut tout de même se vérifier elle-même.

## Enveloppe

Chaque réponse prend l'une de ces deux formes :

```jsonc
// succès
{ "success": true, "data": { /* … */ } }
// erreur
{ "success": false, "error": { "code": "DAILY_CAP_REACHED", "message": "…", "retryAfter": 3600 } }
```

Chaque réponse porte `X-Request-Id` (renvoyé tel quel si vous en fournissez
un) et, une fois authentifié, `X-RateLimit-Limit / Remaining / Reset / Scope`
pour le compartiment que cette requête vient de consommer.

### Codes d'erreur courants

| HTTP | code | signification |
|---|---|---|
| 401 | `API_KEY_MISSING` / `API_KEY_INVALID` / `API_KEY_REVOKED` / `API_KEY_EXPIRED` | problèmes de clé |
| 402 / 429 | `QUOTA_EXCEEDED` | quota du plan ou capacité épuisée |
| 403 | `IP_NOT_ALLOWED` / `TENANT_INACTIVE` / `FORBIDDEN_PERMISSION` | accès refusé |
| 404 | `SHOP_NOT_FOUND` / `MESSAGE_NOT_FOUND` / `DOC_ARTICLE_NOT_FOUND` | |
| 409 | `AMBIGUOUS_SHOP` | plusieurs boutiques partagent ce nom — passez l'identifiant à la place |
| 409 | `WHATSAPP_NOT_CONFIGURED` | faites un `GET` sur connect avant tout `POST` connect |
| 422 | `VALIDATION_ERROR` | corps/requête invalide (`error.fields`) |
| 429 | `RATE_LIMITED` | limite par clé à la minute/heure/jour (`Retry-After`) |
| 429 | codes de la politique anti-bannissement | voir [Messagerie et politique anti-bannissement](messaging-policy) |
| 503 | `BOT_SERVICE_UNREACHABLE` / `WHATSAPP_NOT_CONNECTED` / `WHATSAPP_SESSION_LOST` | session / bot indisponible |

## Limites de débit et mesure d'usage

Par clé, par défaut : 60/min, 1 000/h, 10 000/jour (voir les en-têtes
`X-RateLimit-*` sur chaque réponse ; un dépassement renvoie
`429 RATE_LIMITED` avec `Retry-After`). Chaque appel compte dans le forfait
`api_calls` du plan, visible via `GET /me` ; chaque requête est journalisée
(modèle de route, statut, latence, IP — jamais le corps de la requête) et
visible par les administrateurs OmniManager.

## Premier appel

```bash
curl -s -H "Authorization: Bearer omk_live_YOUR_KEY" https://console.omni-manager.com/api/v1/me
```

renvoie les permissions de votre clé, ses limites de débit et le quota
`api_calls` restant.