vicket
Commencer
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

GroupeAuthRôle
GET /v1/mesessionUtilisateur courant
/v1/orgssessionLister, créer des orgs
/v1/orgs/{slug}sessionLire, mettre à jour une org
/v1/orgs/{slug}/memberssessionInviter, lister, changer le rôle des membres
/v1/orgs/{slug}/sitessessionCRUD des sites d'une org
/v1/orgs/{slug}/statusessessionCRUD des statuts de ticket
/v1/orgs/{slug}/prioritiessessionCRUD des priorités
/v1/orgs/{slug}/templatessessionCRUD des templates de formulaire
/v1/orgs/{slug}/workflowssessionCRUD des workflows + historique des runs
/v1/orgs/{slug}/help/articlessessionRédiger les articles
/v1/orgs/{slug}/help/faqssessionRédiger les FAQ
/v1/orgs/{slug}/ticketssessionFile de tickets côté agent
/support/v1/templatesclé du siteTemplates de formulaire publiés
/support/v1/ticketsclé du siteSoumission publique de tickets
/support/v1/ticket?token=clé du site + tokenLire un ticket via le lien magique
/support/v1/ticket/messages?token=clé du site + tokenRépondre au ticket via le lien magique
/support/v1/ticket/attachments?token=clé du site + tokenInitier l'upload d'un fichier sur une réponse
/support/v1/help/articlesclé du siteArticles publiés
/support/v1/help/faqsclé du siteFAQ publiées

Verbes et conventions

VerbeEffet
GETLecture. Idempotent.
POSTCréation. Retourne la ressource créée avec un ID serveur.
PATCHMise à jour partielle. N'envoyez que les champs à changer.
PUTRemplacement complet. Rare, utilisé pour les graphes de workflow.
DELETESuppression. 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 Origin ou X-Vicket-Origin: https://votre-app.com sur POST /support/v1/tickets pour que Vicket construise {origin}/ticket?token=... avec votre domaine.
  • Templates : GET /support/v1/templates -> Template[], puis GET /support/v1/templates/{key} -> { template, version, fields }.
  • Créer un ticket : POST /support/v1/tickets avec { email, template_key, answers: [{ field_key, value_text | value_number | value_date | value_datetime | value_bool | value_array }] } (plus Idempotency-Key optionnel). Retourne 201 { 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 vers upload_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