Référence API REST

L'API publique « Tauraco Public API » (version 1.0.0-beta) est décrite par une spécification OpenAPI 3.1 exportée de l'application elle-même, jamais écrite à la main : un test de contrat vérifie que le fichier publié liste exactement les routes servies.

Fichiers et référence interactive

Adresse et versions

• Adresse : https://api.tauraco.io/public/v1 (en ligne depuis le 2026-11-05 ; voir Versions et changelog).
• Version de l'API : en-tête de requête facultatif Tauraco-Version: 2026-11-01, toujours renvoyé dans la réponse ; une version non servie est refusée (400 invalid_request).
• Dépréciation : une opération retirée est d'abord annoncée par Deprecation, Sunset et Link: <…>; rel="deprecation" (RFC 9745, RFC 8594).

Ressources de la version 1

Le fichier OpenAPI ci-dessus fait foi : il publie 73 opérations, avec leurs paramètres, leurs schémas, leurs exemples et le scope exigé par chacune (x-required-scopes). Les opérations de l'établissement financier (/bank/*) y figurent (API banque, lot 2C).

Hors version 1 : /projects, /contracts, /applications, /guarantees, écritures de stock et de comptabilité. Les dépôts Collateral sont servis en REST en lecture : GET /collateral/depots et GET /collateral/depots/{depot_id} (scope collateral:read, délégant ERP_OWNER seulement) ; ils s'exportent aussi (jeu collateral_depots, voir Collateral).

Conventions

• Format. JSON UTF-8 ; une écriture qui porte un corps l'envoie avec Content-Type: application/json (sinon 415 unsupported_media_type) ; corps limité à 1 Mo (413 payload_too_large) ; un champ inconnu ou invalide donne 422 validation_failed. Une écriture exige aussi un rôle d'écriture de l'application dans l'entreprise (403 forbidden sinon).
• Montants. Chaînes décimales en unités majeures, à l'exposant de la devise : XOF, XAF, GNF et KMF sans décimale ("150000"), EUR et USD avec deux ("1234.56"). Lisez-les avec un type décimal, jamais un flottant.
• Dates. date au format AAAA-MM-JJ ; horodatages ISO 8601 UTC avec Z.
• Identifiants. Chaînes UUID ; les numéros métier (number d'une facture) sont des champs, pas des identifiants.
• Champs exclus. tenant_id, notes internes, coordonnées bancaires, champs d'affacturage, empreintes de chaînage, noms de personnes et données personnelles ne sont jamais servis par défaut.

Pagination

Les listes rendent {"data": [...], "next_cursor": "…", "has_more": true}. Paramètres : limit (1 à 200, 50 par défaut ; 100 au plus pour /exports et les livraisons de webhook) et cursor, opaque et signé : il est lié au jeu de données et aux filtres de la première page (un curseur rejoué avec d'autres filtres donne 400 invalid_cursor). L'ordre est stable (clé de création puis identifiant).

Filtres

Selon la ressource : status, tiers (customer_id, supplier_id, invoice_id), dates (issue_date_from / issue_date_to, due_date_from / due_date_to, paid_from / paid_to, movement_date_from / movement_date_to), période comptable (period_start, period_end, obligatoires pour la balance), created_after / created_before, updated_after / updated_before (seulement pour les jeux qui ont une date de modification), q (recherche textuelle là où elle est déclarée). Le fichier OpenAPI liste les filtres de chaque opération. Un paramètre inconnu donne 400 invalid_request ; une valeur invalide 422 validation_failed avec errors: [{field, message}].

Idempotence

Idempotency-Key (255 caractères ASCII imprimables au plus, sinon 400 invalid_request) est obligatoire sur tout POST (400 idempotency_key_required sinon). La clé est propre à votre application et à l'entreprise ; elle est conservée 24 heures. Même clé et même corps : réponse d'origine avec Idempotent-Replayed: true, sans nouvel effet. Même clé, autre corps : 422 idempotency_key_reused. Même clé pendant le traitement : 409 idempotency_in_progress. Une réponse rejouée ne contient jamais de secret.

En-têtes

Débit et quotas

Chaque application a un seau par minute (120 requêtes par défaut) et un quota journalier (50 000 par défaut, remis à zéro à minuit UTC), ajustables par Tauraco. Un dépassement donne 429 rate_limited ou 429 quota_exceeded avec Retry-After. L'ordre des refus est stable : authentification (401), puis débit (429), puis scope (403).

Sécurité

• HTTPS seulement ; aucune donnée d'entreprise n'est servie sans jeton.
• Le contrôle d'accès est fait à chaque couche : scope du jeton, droits de l'application Tauraco reconstruits pour l'entreprise de l'octroi, puis filtres d'entreprise des services. Une ressource d'une autre entreprise répond 404 not_found, indistinct d'une ressource absente.
• CORS : seules les origines du portail développeurs sont admises, sans cookie.