Aller au contenu
Sursa Developers

POST/v1/finance/report

Obtenir un rapport financier de synthèse

finance_report

Renvoie les totaux des factures ou des paiements de l’organisation, regroupés selon trois dimensions au plus (catégorie, groupe, secteur d’activité du fournisseur, fournisseur, acheteur, tiers, sens, devise, mois, trimestre, année), avec les mesures invoiced, paid, unpaid et tax. Les totaux ne comprennent que les documents visibles pour l’utilisateur (les collections et les catégories de son profil de données, et le réglage « answer only from verified cards » (répondre uniquement à partir des fiches validées)) ; les filtres de la requête restreignent ce périmètre sans jamais l’élargir.

En mode reporting (par défaut), les montants sont convertis dans la devise de présentation de l’organisation au taux de la date du document, et les montants sans taux sont listés dans conversion.unconverted. En mode original, les montants en devises différentes ne sont pas additionnés, et la devise devient une dimension de la ligne. S’il y a plus de lignes que limit, truncated vaut true, et totals couvre toujours toutes les lignes. Exige un profil de données ayant accès aux données financières (finance.forbidden).

Le rapport, les listes de factures et de paiements et leurs exports sont des opérations de lecture, bien qu’ils utilisent POST : ils sont disponibles en mode « View as » et pour les clés API ayant la portée read (et, comme auparavant, pour les clés ayant la portée write).

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres d’en-tête

  • X-View-Asstring

    Uniquement pour les clés API ayant le rôle admin. Exécute la requête avec le profil de données <profile>[:viewer|verifier|editor], par exemple employee:viewer. La clé d’installation ne peut pas utiliser cet en-tête (403).

Paramètres de cookie

  • kb_view_asstring

    Cookie du mode « View as » pour une session. POST /auth/view-as le définit et DELETE /auth/view-as le supprime.

Corps de la requête

application/json

Objet : FinanceReportRequest

  • basisstring

    invoices : factures, avoirs et reçus. payments : le journal des paiements (flux de trésorerie). Avec payments, la seule mesure est paid, et la dimension direction ainsi que le total indiquent le mouvement d’argent, in ou out, tandis qu’un virement entre vos propres entités juridiques est internal.

    Valeurs autorisées: invoicespayments

    Par défaut : "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Par défaut invoiced (paid pour payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Date qui définit la période et le filtre from/to : la date du document ou la date du paiement.

    Valeurs autorisées: documentpayment

    Par défaut : "document"

  • filtersFinanceFilter
  • order_bystring

    Mesure ou dimension de tri. Par défaut, la première mesure, par ordre décroissant.

  • order_descboolean

    Par défaut : true

  • limitinteger

    Par défaut : 1000≥ 1, ≤ 10000

  • languagestring

    Langue des libellés des catégories et des groupes, en|ru. Par défaut en.

Réponses

200Le rapport

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : FinanceReport

  • currency_modeFinanceCurrencyModeobligatoire
  • currencystring

    Devise de présentation (mode reporting).

  • rowsarray of FinanceReportRowobligatoire
  • totalsarray of FinanceReportTotalobligatoire

    Totaux sur toutes les lignes avant troncature, une entrée par devise (pour un rapport ventilé par sens, par devise et par sens, FinanceReportTotal.direction).

  • truncatedbooleanobligatoire
  • limitintegerobligatoire
  • total_rowsintegerobligatoire

    Nombre de lignes groupées avant troncature.

  • conversionFinanceConversion
  • warningsarray of string

    Codes d’avertissement : profile_missing, les coordonnées de l’entreprise de l’organisation ne sont pas renseignées, le sens des factures est donc in par défaut ; catalog_missing, l’annuaire des entreprises n’est pas chargé ; fx_rate_missing, certains montants n’ont pas de taux de change (conversion.unconverted) ; fx_rate_stale, certains taux sont obsolètes ; enrichment_pending, certains documents sont encore en cours de traitement et ne figurent pas dans les totaux. Affichez un code inconnu avec un message générique.

400La requête est invalide : la valeur d’un paramètre ou l’état de l’objet ne permet pas l’action (`detail` est un message).

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

  • Retry-After

    Nombre de secondes à attendre avant de réessayer la requête.

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

503Un service dont dépend cette requête est temporairement indisponible. Réessayez plus tard.

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec chaque POST et PATCH. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter à nouveau la requête.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← finance · Référence de l’API