Format des réponses

L'enveloppe JSON dépend du type d'opération. Trois formes sont utilisées.

Récupération d'une ressource unique

GET /v1/{resource}/{id} :

{
  "statusCode": 200,
  "data": { /* l'objet demandé */ }
}

Récupération d'une liste

GET /v1/{resource} :

{
  "statusCode": 200,
  "data": [ /* tableau d'objets */ ],
  "meta": {
    "pagination": {
      "total_items": 100,
      "items_per_page": 10,
      "total_pages": 10,
      "current_page": 1,
      "offset": 0,
      "has_previous_page": false,
      "has_next_page": true,
      "next_page": 2,
      "previous_page": null
    },
    "generated_at": "2026-05-07T14:32:11.000Z"
  }
}

Écritures en lot

POST / PUT / bulk-delete :

{
  "statusCode": 200,
  "sent_count": 18,
  "rejected_count": 2,
  "rejected_items": [ /* index, payload original, erreurs de validation */ ]
}

Le traitement est asynchrone : un 200 confirme l'acceptation, pas la visibilité immédiate sur les lectures suivantes. Voir aussi Codes d'erreur.

Pagination, filtrage, tri, projection

Les endpoints de listing acceptent les paramètres standard :

Paramètre	Rôle
limit	Nombre d'items par page
offset	Décalage de départ
filters	Critères de filtrage
order	Tri
fields	Projection : ne renvoyer que certains champs

Mapping avec le SDK JavaScript

Le SDK enveloppe chaque réponse dans { ok, statusCode, data, error }. Le corps de l'API se trouve dans res.data :

// Liste
const page = await SpmCustomers.list(client, { limit: 50, offset: 0 });
if (page.ok) {
  console.log(page.data);                  // tableau d'objets (data de l'API)
  // la pagination de l'API est exposée telle quelle dans la réponse
}

// Élément unique
const one = await SpmCustomers.get(client, 'cust_1');
console.log(one.data);                      // l'objet (data.data côté API selon l'endpoint)

// Écriture en lot
const res = await SpmCustomers.bulkSave(client, items, { chunk: true });
if (res.ok) {
  console.log(res.data.sent_count, res.data.rejected_count);
  console.log(res.data.chunks);             // détail par chunk si chunking activé
}

Avec le chunking activé, le SDK agrège les compteurs de tous les chunks dans une seule enveloppe — voir Résilience.