# Comment fonctionnent les clés API

> Créer, sécuriser et utiliser une clé API OmniManager — ce qu'elle permet et ses limites anti-spam.

# Comment fonctionnent les clés API

Une clé API (`omk_live_…`) permet à un logiciel externe (votre site, votre
CRM, un script) d'agir sur votre compte OmniManager sans que vous soyez
devant l'écran : lister vos boutiques, connecter WhatsApp, envoyer des
messages, publier un statut, déclarer un contact consentant.

## Créer une clé

**Paramètres → API** → « Créer une clé ». La clé brute n'est affichée
qu'une seule fois : copiez-la immédiatement, OmniManager ne conserve que son
empreinte et ne peut pas vous la redonner. En cas de perte, régénérez-la.

## Sécurité

⚠️ Ne partagez jamais votre clé dans un message, un dépôt de code public ou
une capture d'écran. Toute personne qui la possède peut agir à votre place
dans la limite des permissions accordées.

## Trouver votre boutique avant toute chose

Chaque appel identifie une boutique par son identifiant ou son nom exact.
Si deux boutiques portent le même nom, l'appel échoue avec
`409 AMBIGUOUS_SHOP` — utilisez alors l'identifiant.

```
curl -H "Authorization: Bearer omk_live_VOTRE_CLE" https://app.omni-manager.com/api/v1/shops?limit=20
```

## Ce que vous pouvez faire

- Lister et créer des boutiques
- Connecter/déconnecter WhatsApp (QR code)
- Envoyer des messages WhatsApp, consulter leur état
- Publier un statut WhatsApp
- Lister vos groupes WhatsApp
- Déclarer ou retirer des contacts consentants (pour envoyer à des numéros
  qui n'ont jamais écrit à la boutique sans les compter comme « inconnus »)

## Ce que vous ne pouvez pas faire — les limites anti-spam

OmniManager protège votre numéro WhatsApp contre le bannissement : un
plafond quotidien et horaire de messages, un plafond réduit pour les
numéros jamais contactés (« froids »), un plafond dédié pour les contacts
que vous avez déclarés, et un blocage si le même texte part vers trop de
destinataires différents en une heure. Un destinataire qui répond « STOP »
ne peut plus être recontacté tant qu'il n'écrit pas à nouveau.

Le détail complet (codes d'erreur, valeurs par défaut) est dans
[Messaging & the anti-ban policy](messaging-policy) (article anglais,
partagé avec la documentation développeur publique).

## Exemple : envoyer un message

```bash
curl -X POST -H "Authorization: Bearer omk_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"channel":"whatsapp","to":"+24177000000","text":"Bonjour !","idempotencyKey":"commande-1234"}' \
  https://app.omni-manager.com/api/v1/shops/ID_BOUTIQUE/messages
```

La réponse (`202`) contient l'identifiant du message et le verdict de la
politique anti-spam qui a laissé passer l'envoi. Interrogez ensuite
`GET /messages/ID_DU_MESSAGE` pour connaître son état final
(`sent`, `failed`, `rejected`).