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/ticket?token= | clé du site + token | Lire un ticket via le lien magique |
/support/v1/ticket/messages?token= | clé du site + token | Répondre au ticket via le lien magique |
/support/v1/ticket/attachments?token= | clé du site + token | Initier l'upload d'un fichier sur une réponse |
/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.
Parcours magic-link client (/ticket?token=)
Lorsqu'un ticket est soumis via POST /support/v1/tickets, Vicket génère un token valable 30 jours et envoie par email le lien {origin}/ticket?token=... au client (en utilisant l'Origin / X-Vicket-Origin de la requête ou la première origine autorisée du site). Le client reste sur votre domaine pour consulter le fil (GET /support/v1/ticket?token=...), répondre (POST /support/v1/ticket/messages?token=...) et joindre des fichiers (POST /support/v1/ticket/attachments?token=...).
Proxifier /support/v1/* depuis votre propre backend
Si vous proxifiez /support/v1/* via votre propre BFF au lieu d'appeler api.vicket.app depuis le navigateur :
- En-tête requis :
X-Vicket-Key: pk_... - En-tête recommandé : transmettez
OriginouX-Vicket-Origin: https://votre-app.comsurPOST /support/v1/ticketspour que Vicket construise{origin}/ticket?token=...avec votre domaine. - Templates :
GET /support/v1/templates->Template[], puisGET /support/v1/templates/{key}->{ template, version, fields }. - Créer un ticket :
POST /support/v1/ticketsavec{ email, template_key, answers: [{ field_key, value_text | value_number | value_date | value_datetime | value_bool | value_array }] }(plusIdempotency-Keyoptionnel). Retourne201 { ticket_id, public_number, subject, score, priority_key, status_key }. - Lire un fil :
GET /support/v1/ticket?token=...->{ ticket, answers, comments }. - Répondre :
POST /support/v1/ticket/messages?token=...avec{ body_markdown }->201 Comment({ id, ... }). - Joindre un fichier :
POST /support/v1/ticket/attachments?token=...avec{ comment_id, filename, mime_type, size_bytes }->201 { attachment, upload_grant: { upload_url, method, key, headers } }, puis envoyez le fichier versupload_grant.upload_url.
Exemple proxy backend en Go
func proxyToVicket(w http.ResponseWriter, r *http.Request, method, path string, query url.Values) {
target := "https://api.vicket.app" + path
if len(query) > 0 {
target += "?" + query.Encode()
}
req, _ := http.NewRequestWithContext(r.Context(), method, target, r.Body)
req.Header.Set("X-Vicket-Key", os.Getenv("VICKET_API_KEY"))
if origin := r.Header.Get("Origin"); origin != "" {
req.Header.Set("X-Vicket-Origin", origin)
}
if ct := r.Header.Get("Content-Type"); ct != "" {
req.Header.Set("Content-Type", ct)
}
if ik := r.Header.Get("Idempotency-Key"); ik != "" {
req.Header.Set("Idempotency-Key", ik)
}
resp, err := (&http.Client{Timeout: 20 * time.Second}).Do(req)
if err != nil {
http.Error(w, "upstream unavailable", http.StatusBadGateway)
return
}
defer resp.Body.Close()
w.Header().Set("Content-Type", resp.Header.Get("Content-Type"))
w.WriteHeader(resp.StatusCode)
io.Copy(w, resp.Body)
}
Exemple appel direct Next.js / React / Vue / SvelteKit / Astro
const res = await fetch("https://api.vicket.app/support/v1/tickets", {
method: "POST",
headers: {
"X-Vicket-Key": process.env.NEXT_PUBLIC_VICKET_SITE_KEY!, // ou import.meta.env.VITE_VICKET_SITE_KEY / PUBLIC_VICKET_SITE_KEY
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
email: "client@exemple.fr",
template_key: "tmpl-...",
answers: [{ field_key: "subject", value_text: "Besoin d'aide" }],
}),
});
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.