Aller au contenu
Sursa Developers

POST/v1/finance/invoices

Lister les factures

finance_invoices

Renvoie les factures, les avoirs et les reçus de l’organisation page par page, avec des filtres (période, sens, catégorie, tiers, devise, type de document, payé, en retard, à revoir, recherche par numéro et par partie), un tri et le montant dans la devise de présentation avec le taux de conversion. Seuls les documents visibles pour l’utilisateur sont inclus. Pour obtenir la page suivante, transmettez next_cursor comme cursor avec les mêmes filtres. Exige un profil de données ayant accès aux données financières.

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 : FinanceListRequest

  • filtersFinanceFilter
  • date_basisstring

    Valeurs autorisées: documentpayment

    Par défaut : "document"

  • orderstring

    Valeurs autorisées: date_descdate_ascamount_descamount_asc

    Par défaut : "date_desc"

  • currency_modeFinanceCurrencyMode
  • limitinteger

    Par défaut : 100≥ 1, ≤ 1000

  • cursorstring
  • languagestring

    Langue des libellés des catégories, en|ru.

Réponses

200Une page de factures

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 : FinanceInvoicePage

  • invoicesarray of FinanceInvoiceRowobligatoire
  • totalintegerobligatoire

    Nombre total de factures correspondant aux filtres.

  • next_cursorstring

    Curseur de la page suivante. Si le champ est absent, c’est la dernière page.

  • currencystring

    Devise de présentation des champs reporting (mode reporting).

  • warningsarray of string

    Codes d’avertissement, les mêmes que dans FinanceReport.warnings.

  • has_moreboolean

    Indique s’il existe une page suivante. Présent quand la requête transmet limit ou cursor.

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