API / Nº 04
Endpoints de l'API
L'API Vicket est REST, JSON, versionnée à /v1 pour la surface dashboard et /support/v1 pour la surface publique que votre page de support appelle. Tous les endpoints retournent une enveloppe stable : la donnée en succès, { "error": { "code", "message" } } en échec. Les règles d'authentification sont dans authentification.
Groupes d'endpoints
| Groupe | Auth | Rôle |
|---|---|---|
GET /v1/me | session | Utilisateur courant |
/v1/orgs | session | Lister, créer des orgs |
/v1/orgs/{slug} | session | Lire, mettre à jour une org |
/v1/orgs/{slug}/members | session | Inviter, lister, changer le rôle des membres |
/v1/orgs/{slug}/sites | session | CRUD des sites d'une org |
/v1/orgs/{slug}/statuses | session | CRUD des statuts de ticket |
/v1/orgs/{slug}/priorities | session | CRUD des priorités |
/v1/orgs/{slug}/templates | session | CRUD des templates de formulaire |
/v1/orgs/{slug}/workflows | session | CRUD des workflows + historique des runs |
/v1/orgs/{slug}/help/articles | session | Rédiger les articles |
/v1/orgs/{slug}/help/faqs | session | Rédiger les FAQ |
/v1/orgs/{slug}/tickets | session | File de tickets côté agent |
/support/v1/templates | clé du site | Templates de formulaire publiés |
/support/v1/tickets | clé du site | Soumission publique de tickets |
/support/v1/help/articles | clé du site | Articles publiés |
/support/v1/help/faqs | clé du site | FAQ publiées |
Verbes et conventions
| Verbe | Effet |
|---|---|
GET | Lecture. Idempotent. |
POST | Création. Retourne la ressource créée avec un ID serveur. |
PATCH | Mise à jour partielle. N'envoyez que les champs à changer. |
PUT | Remplacement complet. Rare, utilisé pour les graphes de workflow. |
DELETE | Suppression. 204 en succès. |
Idempotence
POST /support/v1/tickets accepte un en-tête optionnel Idempotency-Key. La même clé avec le même corps retourne la réponse en cache ; la même clé avec un corps différent retourne 409. Les composants générés envoient un UUID par soumission, donc les double-clics accidentels sont sans danger.
Limites de débit
Les endpoints publics sont limités par site et par IP. Dépasser la limite retourne 429 ; attendez et réessayez.
Exemple : lister les articles publiés
GET /support/v1/help/articles HTTP/1.1
Host: api.vicket.app
X-Vicket-Key: pk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
La suite
- De nous vers vous : webhooks.
- Les détails d'auth : authentification.