Concepts clés

Cette page décrit les conventions communes à toutes les routes. Les tableaux de bord ont en plus leurs propres conventions (cache, périodes, soldes nets), décrites dans la page Présentation de la section « Tableaux de bord et analyses ».

Résumé ou fiche complète

Les listes renvoient par défaut un résumé de chaque fiche (brief=true). Passez brief=false pour obtenir la fiche complète.

Résumé (brief=true, défaut)

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

Fiche complète (brief=false, extrait)

{
  "id": 34,
  "code": "JACHETE",
  "description": "Jean Achète Inc.",
  "address": { "line1": "123 rue Principale", "city": "Montréal", "postal_code": "H2X 1A1", "country_code": "CA" },
  "payment_term": { "id": 5, "code": 1 },
  "status": { "is_active": true },
  "metadata": { "unique_id": 340, "updated_at": "2026-03-01T14:30:00-05:00" },
  "_links": { "self": "/api/customers/by-id/34" }
}

Les deux formes ne portent pas les mêmes noms

Le résumé est fait pour l'affichage : name, active, updated_at. La fiche complète suit la structure d'Acomba : description, status.is_active, metadata.updated_at. Ne mélangez pas les deux dans votre code.

Le résumé est rapide. La fiche complète est relue dans Acomba à chaque appel : réservez-la aux fiches dont vous avez besoin. Vous pouvez aussi lister en résumé, puis suivre _links.self.

Pagination

Les listes se paginent avec deux paramètres :

Paramètre	Défaut	Maximum	Description
`page`	`1`	—	Numéro de la page, à partir de 1
`page_size`	`50`	`100`	Nombre de fiches par page

{
  "items": [ ... ],
  "total": 412,
  "page": 1,
  "page_size": 50,
  "total_pages": 9
}

total compte les fiches qui répondent à vos filtres, et chaque page est pleine sauf la dernière.

Python

JavaScript

Les tableaux de bord paginent autrement

Certaines analyses (activité récente, factures impayées, analyse de produits…) utilisent limit et offset, avec metadata.has_more et next_offset. La référence de chaque endpoint indique ses paramètres.

Par code ou par ID

La plupart des fiches se lisent de deux façons, avec la même réponse :

Route	Clé
`GET /api/customers/{code}`	Code métier visible dans Acomba (ex. `JACHETE`)
`GET /api/customers/by-id/{id}`	Identifiant interne (`id`)

Garder le lien avec une fiche Acomba

Identifiant	Stable ?	Usage
`code`	Non : un utilisateur Acomba peut le modifier	Affichage, saisie
`id`	Non : Acomba réutilise l'`id` d'une fiche supprimée pour la prochaine fiche créée	Routes `/by-id/{id}`
`metadata.unique_id`	Oui : propre à une fiche, jamais réutilisé	Lien durable avec votre système

Recommandation

Stockez id et unique_id. Lisez par id, puis vérifiez que unique_id correspond toujours. S'il diffère, la fiche d'origine a été supprimée et l'id désigne maintenant une autre fiche.

Réponses des écritures

Les écritures (POST, PUT, PATCH, DELETE) renvoient success: true et l'identifiant de la fiche touchée. Le nom de ce champ dépend du domaine :

Type de ressource	Forme la plus courante
Fiches de référence : clients, fournisseurs, produits et inventaire, plan comptable, taxes, vendeurs, territoires…	`{"success": true, "created_id": 416, "updated_id": null, "deleted_id": null}`
Documents : factures, commandes, soumissions, paiements, transactions	`{"success": true, "id": 892}`, parfois enrichi (numéro, statut)
Paie	Réponse propre à chaque route (par exemple `id`, `code` et liste des champs modifiés)

Il existe des exceptions : la section « Responses » de chaque endpoint donne toujours la forme exacte. Pour obtenir la fiche à jour, relisez-la avec GET …/by-id/{id}.

Liens `_links`

Chaque fiche contient un objet _links avec l'adresse de sa fiche complète (self) et, selon l'entité, des liens vers ses vues associées :

"_links": {
  "self": "/api/customers/by-id/34",
  "aging": "/api/customers/aging/by-id/34",
  "statement": "/api/customers/by-id/34/statement",
  "overview": "/api/customers/by-id/34/overview"
}

Les liens sont relatifs : ajoutez-les à votre adresse de base.

Parcourir un index Acomba

Pour une navigation « précédent / suivant » dans l'ordre d'un index Acomba, la plupart des entités exposent deux routes :

Route	Paramètres	Réponse
`GET /api/customers/index/key-to-rank`	`index` (défaut `1`) et la clé de cet index : `code` (index 1), `sort_key` (index 2), `modified_at` ou `unique` (index 12)	La position de la fiche dans l'index
`GET /api/customers/index/rank-to-key`	`index`, `rank` (requis), `brief`	La fiche qui occupe cette position

Les index acceptés varient selon l'entité ; ils sont indiqués dans la référence de chaque route.

Suivre les changements

GET /api/helpers/updates renvoie les fiches modifiées dans un intervalle, regroupées par entité. Il lit la copie locale qu'ExoConnect tient à jour à partir d'Acomba.

Paramètre	Requis	Description
`from_datetime`	oui	Début de l'intervalle (ISO 8601, heure locale)
`to_datetime`	non	Fin de l'intervalle. Sans ce paramètre, toutes les fiches modifiées depuis `from_datetime` sont renvoyées, et la réponse donne dans `to_datetime` le moment jusqu'auquel la copie locale est complète
`entities`	non	Entités à inclure, séparées par des virgules (ex. `customers,products`). La liste : `GET /api/helpers/list/entities`
`brief`	non	`true` (défaut) : `id`, `code`, `updated_at` ; `false` : fiche de la copie
`limit`	non	Total maximal de fiches, toutes entités confondues (défaut 5 000, maximum 50 000)

{
  "from_datetime": "2026-03-10T00:00:00-04:00",
  "to_datetime": "2026-03-17T00:00:00-04:00",
  "brief": true,
  "truncated": false,
  "total_count": 3,
  "entities": {
    "customers": {
      "count": 2,
      "items": [
        { "id": 1, "code": "CLI001", "updated_at": "2026-03-12T14:30:00-04:00" },
        { "id": 2, "code": "CLI002", "updated_at": "2026-03-15T09:00:00-04:00" }
      ]
    },
    "products": {
      "count": 1,
      "items": [{ "id": 10, "code": "SERV01", "updated_at": "2026-03-11T16:45:00-04:00" }]
    }
  }
}

Entités non suivies

Les factures et transactions clients et fournisseurs, les paiements clients et fournisseurs, et les mouvements d'inventaire ne sont pas copiés localement : ils sont lus directement dans Acomba. Pour ces entités, /helpers/updates renvoie toujours count: 0. Utilisez plutôt leurs listes avec les filtres de date, par exemple GET /api/customers/invoice-ar?from_datetime=…, GET /api/customers/payments?from_datetime=… ou GET /api/suppliers/payments?from_datetime=….

Synchronisation continue

Appelez la route sans to_datetime, puis réutilisez comme prochain from_datetime le to_datetime de la réponse : c'est le moment jusqu'auquel la copie locale est complète, si bien qu'aucune modification n'est perdue, même faite pendant le cycle de copie. Une fiche peut donc revenir une seconde fois : ignorez celles dont l'id et l'updated_at sont déjà connus. Si truncated vaut true, réduisez le nombre d'entités ou relancez à partir du dernier updated_at reçu.

La copie locale est mise à jour par ExoConnect en arrière-plan, environ toutes les 15 minutes par défaut. Une modification faite dans Acomba apparaît donc dans /helpers/updates après le cycle suivant.

Dates, montants et langues

Dates en réponse : ISO 8601 avec le décalage horaire local, par exemple 2026-03-01T14:30:00-05:00.

Dates en entrée : 2026-03-19 ou 2026-03-19T00:00:00. Sans décalage, l'heure locale du poste Acomba s'applique.

Montants : nombres décimaux dans la devise du dossier Acomba.

Références à d'autres fiches : { "id": …, "code": … }. Selon l'entité, le code est un texte (client JACHETE) ou un nombre (terme de paiement 1).

Une requête à la fois dans Acomba

Acomba ne traite qu'une opération à la fois. ExoConnect met donc les requêtes en file : elles sont toujours sûres, mais ne vont pas plus vite en parallèle.

Envoyez vos requêtes une ou deux à la fois, pas des dizaines en parallèle.

Prévoyez un délai d'attente généreux (300 secondes) : un calcul long ou une file chargée peut prendre plus d'une minute.

Sur un 503, attendez puis réessayez, en augmentant le délai entre deux essais (voir Codes d'erreur).

Pour les tableaux de bord, le premier appel calcule et les suivants sont servis par le cache : appelez-les à la demande plutôt qu'en boucle.

Résumé ou fiche complète#

Pagination#

Par code ou par ID#

Garder le lien avec une fiche Acomba#

Réponses des écritures#

Liens _links#

Parcourir un index Acomba#

Suivre les changements#

Dates, montants et langues#

Une requête à la fois dans Acomba#