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 :
// 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 |
| 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
curl -s -H "Authorization: Bearer omk_live_YOUR_KEY" https://console.omni-manager.com/api/v1/merenvoie les permissions de votre clé, ses limites de débit et le quota api_calls restant.