Concepts clés

Cette page couvre les conventions partagées par toutes les routes de l'API ExoConnect. Comprenez-les une fois et vous saurez naviguer dans n'importe quelle entité.

Modes de réponse : Brief et Full

Tous les endpoints de listing retournent par défaut un format brief (résumé paginé). Le paramètre brief est à true par défaut. Passez ?brief=false pour obtenir la fiche complète de chaque ressource.

Brief (?brief=true, défaut)

{
  "id": 34,
  "code": "JACHETE",
  "name": "Jean Achète Inc.",
  "active": true,
  "updated_at": "2026-03-01T14:30:00",
  "_links": {
    "self": "/api/customers/by-id/34"
  }
}

Full (?brief=false)

{
  "id": 34,
  "code": "JACHETE",
  "description": "Jean Achète Inc.",
  "sort_key": "JACHETE",
  "care_of": "Marie Tremblay",
  "active": true,
  "address": {
    "line1": "123 rue Principale",
    "city": "Montréal"
  },
  "payment_term": { "id": 2, "code": "NET30" },
  "updated_at": "2026-03-01T14:30:00",
  "_links": { "self": "/api/customers/by-id/34" }
}

Utilisez le mode brief pour les synchronisations et les listes de sélection. Le champ _links.self vous permet de récupérer la fiche complète à la demande (pattern HATEOAS).

Pagination

Les endpoints de listing acceptent deux paramètres pour contrôler la pagination :

Paramètre	Type	Défaut	Description
`limit`	`integer`	`50`	Nombre maximum de résultats par page
`offset`	`integer`	`0`	Position de départ dans la liste

La réponse inclut des métadonnées pour gérer la pagination :

{
  "items": [...],
  "total": 412,
  "limit": 50,
  "offset": 0,
  "truncated": true
}

Lorsque truncated vaut true, il reste des résultats à récupérer. Incrémentez offset de la valeur de limit pour obtenir la page suivante.

Exemple de boucle de pagination :

Python

JavaScript

PHP

Accès par code ou par ID

La majorité des entités offrent deux routes de lecture :

Route	Usage
`GET /api/customers/{code}`	Accès par code métier (ex : `JACHETE`)
`GET /api/customers/by-id/{id}`	Accès par identifiant interne stable

Les deux routes retournent exactement la même réponse.

Préférez /by-id/{id} dans vos intégrations. L'identifiant interne est immuable, contrairement au code métier qui peut être modifié par un utilisateur Acomba.

Mutations : réponse unifiée

Toutes les opérations de création (POST), modification (PATCH) et suppression (DELETE) retournent un format unifié :

{
  "success": true,
  "id": 416
}

L'id retourné est l'identifiant interne de la ressource dans Acomba. Vous pouvez l'utiliser immédiatement pour un GET /by-id/{id} afin de récupérer la fiche complète.

HATEOAS : liens dans les réponses

Chaque ressource retournée inclut un objet _links qui contient l'URL vers sa fiche complète :

{
  "id": 34,
  "code": "JACHETE",
  "name": "Jean Achète Inc.",
  "_links": {
    "self": "/api/customers/by-id/34"
  }
}

Ce pattern est particulièrement utile en mode brief : listez vos ressources avec un appel léger, puis suivez le lien _links.self pour récupérer le détail complet uniquement des ressources qui vous intéressent.

Routes d'indexation

Les entités qui supportent l'indexation exposent deux routes utilitaires pour naviguer dans l'index par position :

Route	Description
`GET /api/customers/key-to-rank?key=JACHETE`	Retourne la position (rank) d'un code dans l'index
`GET /api/customers/rank-to-key?rank=15`	Retourne le code à une position donnée dans l'index

Ces routes sont utiles pour implémenter une navigation séquentielle (précédent/suivant) dans une interface utilisateur.

Synchronisation incrémentale

L'endpoint GET /api/helpers/updates retourne toutes les modifications indexées depuis un timestamp donné. C'est le point d'entrée recommandé pour une synchronisation continue entre vos systèmes et Acomba.

Paramètre	Type	Description
`since`	`datetime`	Timestamp ISO 8601 à partir duquel récupérer les changements
`entity`	`string`	Nom de l'entité à filtrer (optionnel)
`brief`	`boolean`	`true` (défaut) pour le résumé, `false` pour la fiche complète
`limit`	`integer`	Nombre maximum de résultats

Stockez le updated_at le plus récent de chaque synchronisation et utilisez-le comme valeur since au prochain appel. Vous récupérez ainsi uniquement les changements, sans avoir à scanner toute la base.

Modes de réponse : Brief et Full#

Pagination#

Accès par code ou par ID#

Mutations : réponse unifiée#

HATEOAS : liens dans les réponses#

Routes d'indexation#

Synchronisation incrémentale#

Modes de réponse : Brief et Full

Pagination

Accès par code ou par ID

Mutations : réponse unifiée

HATEOAS : liens dans les réponses

Routes d'indexation

Synchronisation incrémentale