Format des réponses

Tous les points de terminaison SaleSprint suivent le même contrat de réponse : un client peut donc analyser n’importe lequel de la même façon. La source de vérité lisible par une machine est la Référence de l’API générée ; cette page explique les formes communes qui la sous-tendent.

Succès

Une ressource unique

Renvoyée telle quelle — sans enveloppe.

// GET /admin/companies/{id}
{
  "id": "0f8c…",
  "name": "Acme Ltd",
  "code": "ACME",
  "status": "active"
}

Une collection

Tous les points de terminaison de liste renvoient la même enveloppe : un tableau items et un objet pagination. items est toujours un tableau — jamais null — même vide.

// GET /admin/companies?page=1&page_size=20
{
  "items": [ { "id": "…", "name": "Acme Ltd" } ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "has_next": true,
    "has_prev": false
  }
}

Champ	Signification
page	numéro de page (à partir de 1) ayant produit ces éléments
page_size	nombre maximal d’éléments par page (taille effective, bornée)
total	nombre total d’éléments, toutes pages confondues
total_pages	nombre de pages pour ce page_size
has_next	une page existe après celle-ci
has_prev	une page existe avant celle-ci

La pagination se demande avec les paramètres de requête page et page_size. page vaut 1 par défaut, page_size vaut 20, et page_size est borné à 200 au maximum. L’objet pagination renvoie toujours les valeurs effectives : ce que vous relisez correspond à ce que la requête a réellement exécuté. Certaines petites listes de référence renvoient toujours toutes les lignes en une seule page complète.

Un accusé de réception

Les points de terminaison qui n’ont rien à renvoyer (déconnexion, suppression, « lien de réinitialisation envoyé ») renvoient un court message.

{ "message": "logged out" }

Erreurs

Toute réponse non 2xx est un problem detail RFC 9457, servi en application/problem+json, étendu d’un code stable et — pour les échecs de validation — d’un tableau errors par champ.

// HTTP 422
{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "validation_failed",
  "detail": "one or more fields are invalid",
  "errors": [
    { "field": "email", "code": "invalid", "message": "must be a valid email" }
  ]
}

Branchez-vous sur code, pas sur detail. code est stable et lisible par une machine ; detail et title sont de la prose destinée aux humains et peuvent changer. errors est présent lors des échecs de validation, avec une entrée par champ fautif, où field est le chemin pointé (email, items.0.qty).

Codes

HTTP	code	Quand
400	bad_request	Requête mal formée
401	unauthorized	Authentification absente ou invalide
403	forbidden	Authentifié mais non autorisé
404	not_found	La ressource n’existe pas
409	conflict	Entre en conflit avec l’état actuel (doublon, etc.)
422	validation_failed	Analysée, mais un ou plusieurs champs sont invalides
429	rate_limited	Limité en débit
500	internal_error	Défaillance serveur imprévue

La même forme est renvoyée pour les erreurs de niveau framework (validation de requête, routes inconnues, panics) que pour les erreurs qu’un gestionnaire déclenche délibérément : il n’y a donc jamais qu’une seule forme d’erreur à traiter.