Développeurs
API REST
Lisez et mettez à jour les conversations, contacts et événements depuis vos propres systèmes.
L’API REST permet à vos propres systèmes de travailler avec votre espace de travail : synchroniser les contacts avec un CRM, envoyer des événements depuis votre boutique, répondre aux clients depuis un autre outil ou fermer automatiquement des conversations.
- URL de base :
https://app.shopxare.com/api/v1 - Format : JSON en entrée, JSON en sortie. Les heures sont au format ISO 8601 en UTC.
- Référence lisible par machine :
/api/v1/openapi.json(OpenAPI 3.1, à importer dans Postman, Insomnia ou un générateur de code).
Jetons
Créez un jeton dans Paramètres → API (propriétaires et administrateurs, ou toute personne dont le rôle dispose de l’autorisation développeur). Vous confirmez votre mot de passe, choisissez un nom, les autorisations et une date d’expiration, et voyez le jeton une seule fois — copiez-le à ce moment-là ; nous n’en conservons qu’un hachage.
Envoyez-le dans chaque requête :
curl https://app.shopxare.com/api/v1/me \
-H "Authorization: Bearer sxa_…"
Un jeton agit au nom du membre de l’équipe qui l’a créé. Il ne peut jamais faire plus que ce que permet le rôle de ce membre, et cesse de fonctionner lorsque celui-ci quitte l’espace de travail ou est désactivé. Révoquez un jeton à tout moment au même endroit.
| Autorisation | Permet |
|---|---|
conversations:read |
lister les conversations, lire les messages |
conversations:write |
répondre, ajouter des notes, fermer, reporter, assigner, prioriser, étiqueter |
contacts:read |
lister et rechercher des contacts, lire leurs événements |
contacts:write |
créer, modifier et supprimer des contacts, suivre des événements |
workspace:read |
lister les membres de l’équipe, les équipes et les étiquettes |
Endpoints
| Méthode | Chemin | Autorisation |
|---|---|---|
| GET | /me |
toutes |
| GET | /conversations |
conversations:read |
| GET | /conversations/{id} |
conversations:read |
| PATCH | /conversations/{id} |
conversations:write |
| GET | /conversations/{id}/messages |
conversations:read |
| POST | /conversations/{id}/messages |
conversations:write |
| POST | /conversations/{id}/tags |
conversations:write |
| GET, POST | /contacts |
contacts:read / contacts:write |
| GET, PATCH, DELETE | /contacts/{id} |
contacts:read / contacts:write |
| GET, POST | /contacts/{id}/events |
contacts:read / contacts:write |
| GET | /teammates, /teams, /tags |
workspace:read |
Répondre à un client
curl -X POST https://app.shopxare.com/api/v1/conversations/01K7…/messages \
-H "Authorization: Bearer sxa_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-shipped" \
-d '{"body": "Your order has shipped 📦"}'
La réponse parvient au client sur le canal de la conversation — Messenger, e-mail ou Telegram — exactement comme une réponse envoyée depuis la boîte de réception. Utilisez "type": "note" pour une note interne. Avec la même Idempotency-Key, une requête renvoyée retourne le premier message (statut 200 au lieu de 201) au lieu de l’envoyer deux fois.
Fermer ou assigner
curl -X PATCH https://app.shopxare.com/api/v1/conversations/01K7… \
-H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
-d '{"status": "closed"}'
Vous pouvez modifier assignee_id (un identifiant de membre provenant de /teammates, ou null), team_id, priority (normal, high) et status (open, snoozed avec snoozed_until, closed). Chaque modification apparaît dans la conversation comme dans la boîte de réception, et les automatisations s’exécutent comme d’habitude.
Créer ou mettre à jour un contact
curl -X POST https://app.shopxare.com/api/v1/contacts \
-H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
-d '{"email": "[email protected]", "name": "Lena", "external_id": "user-7", "attributes": {"plan": "pro"}}'
Recherchez une personne avec GET /contacts?email=… ou ?external_id=…. Avec PATCH, seuls les champs que vous envoyez changent ; les attributes sont fusionnés, et une clé définie sur null est supprimée. L’external_id est le même identifiant utilisateur que celui transmis au Messenger avec la vérification d’identité : l’API et le Messenger voient donc la même personne.
Suivre un événement
curl -X POST https://app.shopxare.com/api/v1/contacts/01K7…/events \
-H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
-d '{"name": "order_placed", "meta": {"order_id": "A-1042", "total": 59.9}}'
C’est l’équivalent de Shopxare('trackEvent', …) dans l’API JavaScript, mais depuis votre serveur.
Pagination
Les listes renvoient {"object": "list", "data": [...], "next_cursor": "…"}, les plus récents en premier. Renvoyez next_cursor sous le nom cursor jusqu’à ce qu’il soit null. limit va de 1 à 100 (25 par défaut). Pour synchroniser les modifications, filtrez avec updated_since.
Les messages sont listés du plus ancien au plus récent : passez le dernier id reçu dans after_id tant que has_more vaut true.
Erreurs
Les erreurs ont toujours la même forme :
{ "error": { "code": "validation_failed", "message": "…", "fields": { "email": ["…"] } } }
| Statut | Code | Signification |
|---|---|---|
| 401 | unauthorized |
jeton manquant, incorrect, expiré ou révoqué |
| 402 | limit_reached |
une limite du forfait est atteinte (par ex. le nombre de contacts) |
| 403 | insufficient_scope, forbidden, feature_unavailable |
il manque l’autorisation au jeton, la permission au membre de l’équipe, ou l’API au forfait |
| 404 | not_found |
cet objet n’existe pas dans cet espace de travail |
| 422 | validation_failed, invalid_request |
l’entrée est incorrecte ; voir fields |
| 429 | rate_limited |
trop de requêtes ; attendez Retry-After secondes |
Limites de débit
Les requêtes sont comptées par jeton et par minute ; la limite dépend de votre forfait et s’affiche dans Paramètres → API. Chaque réponse contient X-RateLimit-Limit et X-RateLimit-Remaining.
Être informé des changements
L’API sert à interroger et à modifier. Pour être informé lorsqu’il se passe quelque chose — une nouvelle conversation, une réponse, un ticket fermé — utilisez les webhooks.
Toujours bloqué ? Contact