Tableaux de bord et analyses

Les endpoints de cette section retournent des données déjà calculées à partir d'Acomba : soldes, âges de comptes, synthèses de ventes, prévisions, indicateurs de paie. Ils sont en lecture seule et prêts à alimenter un tableau de bord, un rapport ou un écran de suivi, sans avoir à reconstituer vous-même les calculs à partir des fiches et des transactions.

Quand utiliser cette section ?

Pour afficher ou analyser : utilisez les tableaux de bord.
Pour synchroniser ou modifier des données : utilisez les sections par entité (Clients, Fournisseurs, Inventaire, Facturation, Paie…).

Contenu de la section

Sous-section	Ce que vous obtenez
Comptes clients	Comptes à recevoir, âge des comptes, état de compte, activité récente, factures impayées, vue 360° d'un client, allocations de paiement
Comptes fournisseurs	Les mêmes vues côté fournisseurs : comptes à payer, âge des comptes, état de compte, activité récente, factures impayées, vue 360°
Trésorerie	Soldes bancaires, prévision de trésorerie, taxes à remettre, encaissements clients et décaissements fournisseurs
Ventes	Synthèse et comparaison de périodes, ventes par représentant et par territoire, meilleurs clients et produits, clients inactifs
Produits et inventaire	Analytique produits (ventes, marge), vue 360° d'un produit ou d'un groupe, vélocité des ventes, santé du stock, réapprovisionnement
Paie	Sommaire de paie, DAS à remettre, roulement du personnel, prévision de masse salariale, coût horaire, vérification de paie, vue 360° et historique de paie d'un employé

Fraîcheur des données et cache

Chaque réponse est calculée à partir d'Acomba, puis conservée en cache pour une durée qui dépend de la période demandée. Le premier appel peut prendre quelques secondes sur un gros volume de données ; les appels suivants avec les mêmes paramètres répondent en quelques millisecondes.

Chaque réponse contient un bloc cache qui indique d'où vient la donnée :

"cache": {
  "status": "hit",
  "cached_at": "2026-10-07T12:20:49-04:00",
  "expires_at": "2026-10-07T13:20:49-04:00",
  "age_seconds": 125,
  "ttl_remaining_seconds": 3474,
  "ttl_policy": "current_period_1h",
  "force_refreshed": false
}

Champ	Signification
`status`	`miss` : calculé à l'instant · `hit` : servi depuis le cache · `bypassed` : recalcul forcé (`force_refresh=true`) · `partial_hit` : une partie seulement venait du cache
`cached_at` / `expires_at`	Moment du calcul et moment où la donnée sera recalculée
`age_seconds` / `ttl_remaining_seconds`	Âge de la donnée et temps restant avant expiration
`ttl_policy`	Règle de durée appliquée (voir ci-dessous)
`force_refreshed`	`true` si l'appel a forcé le recalcul

Durée de conservation — la règle dépend de la nature des données :

`ttl_policy`	Cas	Durée
`current_period_4h`	La période demandée inclut aujourd'hui (les chiffres peuvent encore bouger)	4 heures
`historical_24h`	La période demandée est entièrement passée	24 heures
`current_period_1h`	Soldes bancaires (ils changent à chaque transfert au grand livre)	1 heure
`stock_1h`	Quantités et valeurs en stock	1 heure
`forced_bypass`	Recalcul forcé par `force_refresh=true`	—
`not_cached_empty_scan`	Résultat vide : il n'est pas mis en cache, le prochain appel recalcule	—

Certains endpoints combinent plusieurs calculs (par exemple le stock et les ventes) : leur bloc cache contient alors un sous-bloc components avec l'état de chaque partie.

Forcer le recalcul

Ajoutez force_refresh=true pour ignorer le cache et recalculer immédiatement ; le résultat remplace l'entrée en cache. Réservez-le aux actions explicites de l'utilisateur (bouton « Actualiser ») : ces calculs parcourent les données d'Acomba et peuvent prendre plusieurs secondes.

Données modifiées après le calcul

Une modification faite dans Acomba après cached_at n'apparaît qu'à l'expiration du cache ou avec force_refresh=true. Affichez cached_at à vos utilisateurs lorsque la fraîcheur compte.

Conventions de réponse

Références aux entités

Les clients, fournisseurs, produits, comptes et factures cités dans une réponse sont des références compactes :

"customer": { "id": 639, "code": "P20-100", "name": "Les Peintures 20-100" }

id est l'identifiant interne utilisable avec les routes /by-id/{id} ; code est la clé métier (numéro de client, de fournisseur, de produit…).

Liens de navigation (`_links`)

Les réponses et leurs éléments portent des liens prêts à appeler : self (la requête elle-même, paramètres par défaut inclus), next (page suivante) et des liens vers les vues liées. Par exemple, une facture à recevoir pointe vers la vue 360° et l'état de compte de son client.

"_links": {
  "invoice_detail": "/api/customers/invoice-ar/by-id/15773",
  "customer_overview": "/api/customers/by-id/639/overview",
  "customer_statement": "/api/customers/by-id/639/statement?from=2025-10-07&to=2026-10-07"
}

Bloc `metadata`

Informations sur le calcul : organisation_id, extracted_at (moment de l'extraction), scope (périmètre des données incluses) et, selon l'endpoint, des notes de limites (data_freshness, limitations). Le champ sdk_indexes_used est purement informatif.

Pagination et limites

limit fixe le nombre d'éléments retournés. Quand il y en a davantage, metadata.truncated vaut true. Les totaux (summary) sont toujours calculés sur l'ensemble des résultats, pas seulement sur la page retournée.

Les listes longues acceptent aussi offset : activité récente et factures impayées d'un client ou d'un fournisseur, historique de paie d'un employé, analytique produits, santé du stock et réapprovisionnement. Utilisez metadata.has_more, metadata.next_offset ou directement _links.next pour charger la suite.

Paramètres de période

Paramètre	Usage
`as_of`	Date de référence d'un instantané (âge des comptes, comptes à recevoir et à payer). Par défaut : aujourd'hui
`from` / `to`	Période analysée (ventes, encaissements, décaissements…)
`from_date` / `to_date`	Période analysée pour la paie
`lookback_months`	Profondeur d'historique des vues d'activité

Les paramètres exacts, leurs valeurs par défaut et leurs bornes sont décrits sur chaque endpoint.

Montants clients et fournisseurs : soldes nets

Les vues de comptes à recevoir et à payer raisonnent en solde net, comme Acomba : les crédits non appliqués apparaissent comme des éléments à part (is_credit: true) avec un montant négatif, et viennent réduire le total. Par défaut, les clients ou fournisseurs dont le solde net est nul ou négatif sont exclus ; ajoutez include_zero_balance=true pour les voir.

Limites à connaître

Écritures non transférées : les soldes bancaires et les taxes à remettre ne tiennent compte que des écritures transférées au grand livre.

Calculs coûteux : les analyses sur une longue période (année complète, tous les produits) peuvent prendre plusieurs secondes au premier appel. Préférez des périodes ciblées et laissez le cache travailler.

Présentation

Tableaux de bord et analyses#

Contenu de la section#

Fraîcheur des données et cache#

Forcer le recalcul#

Conventions de réponse#

Références aux entités#

Liens de navigation (_links)#

Bloc metadata#

Pagination et limites#

Paramètres de période#

Montants clients et fournisseurs : soldes nets#

Limites à connaître#