Développeurs

Guide des exports

Le centre d'export produit, en tâche de fond, un fichier à partir d'un ou plusieurs jeux de données de l'entreprise. Les mêmes jeux servent l'export, l'API publique, le serveur MCP et les connecteurs : une colonne, un filtre ou un contrôle d'accès est défini une seule fois.

État : développé et testé (lots 1A et 1B) ; module ouvert en production depuis le 2026-11-05. Exports depuis l'application : Données et intégrations › Mes exports ; par l'API : /exports (scopes exports:read et exports:write) ; par MCP : outil tauraco_request_export.

Jeux de données

Code	Contenu	Scope
`company`	fiche société	`company:read`
`customers`	clients	`customers:read`
`invoices`	factures clients	`invoices:read`
`invoice_lines`	lignes de factures clients	`invoices:read`
`payments`	encaissements	`payments:read`
`products`	produits et services	`products:read`
`suppliers`	fournisseurs (sans coordonnées bancaires)	`suppliers:read`
`bills`	factures fournisseurs	`bills:read`
`purchase_orders`	bons de commande	`purchases:read`
`cash_movements`	mouvements de trésorerie	`treasury:read`
`accounts`	plan de comptes	`accounting:read`
`journals`	journaux comptables	`accounting:read`
`journal_entries`	écritures comptables	`accounting:read`
`journal_lines`	lignes d'écritures	`accounting:read`
`trial_balance`	balance générale	`accounting:read`
`general_ledger`	grand livre	`accounting:read`
`inventory_items`	articles de stock	`inventory:read`
`inventory_movements`	mouvements de stock	`inventory:read`
`inventory_balances`	soldes de stock	`inventory:read`
`financing_requests`	demandes de financement (sans montant d'offre ni taux)	`financing:read`
`financing_repayments`	échéances de remboursement	`financing:read`
`collateral_depots`	dépôts confiés à un tiers détenteur, avec avertissement juridique	`collateral:read`
`tenders`	avis de marchés publics relayés (données externes non vérifiées)	`tenders:read`
`status_history`	historique d'une pièce	`invoices:read`

Chaque jeu applique le même contrôle que la liste correspondante de l'application : un utilisateur ou une application qui ne voit pas une liste ne peut pas l'exporter. Le catalogue complet (colonnes, libellés, filtres, formats acceptés) est servi par GET /integrations/datasets, limité aux jeux que votre jeton et vos droits permettent d'exporter ; GET /integrations/formats liste les formats, GET /integrations/connections les connexions de livraison (delivery).

Formats

Code	Format	Remarques
`csv`	CSV (RFC 4180)	séparateur, encodage et en-tête configurables ; formules neutralisées
`xlsx`	Excel (XLSX)	une feuille par jeu, cellules typées
`json`	JSON	document unique
`jsonl`	JSON Lines	une ligne par enregistrement, adapté aux gros volumes
`xml`	XML	structure générique
`zip`	archive ZIP	plusieurs jeux dans une archive
`pdf`	PDF (tableau)	limité à 5 000 lignes
`fec`	FEC (fichier des écritures comptables)	régime comptable français seulement ; refusé ailleurs (`409 regime_not_supported`)

Neutralisation des formules. En CSV et en XLSX, une cellule de texte qui commence par =, +, -, @, une tabulation ou un retour chariot est préfixée d'une apostrophe pour qu'un tableur ne l'exécute pas. Les montants, nombres et dates sont écrits depuis leur valeur typée et ne sont jamais préfixés ; JSON, JSON Lines et XML ne sont pas modifiés (ils sont lus par un programme).

Cycle de vie d'un export

QUEUED → RUNNING → SUCCEEDED, ou FAILED (avec un code d'erreur), ou CANCELLED. Un fichier SUCCEEDED passe à EXPIRED après 30 jours, puis il est purgé (410 export_expired). Un export volumineux ne bloque jamais l'application : il est lu par lots dans une transaction en lecture seule, avec un délai par requête.

Limites par export : 1 000 000 de lignes, 500 Mo, 30 minutes ; au-delà, 422 export_limit_exceeded. Tant que l'export n'est pas terminé, son téléchargement répond 409 export_not_ready.

Données personnelles

Les colonnes de données personnelles (e-mail, téléphone, adresse d'un client…) sont exclues par défaut. Seul un ERP_OWNER ou un ERP_ADMIN de l'entreprise peut demander leur inclusion (include_pii: true), rôle relu à la demande comme à l'exécution ; un tel export n'est visible que des utilisateurs qui ont eux-mêmes ce droit dans l'entreprise (ERP_OWNER ou ERP_ADMIN, relus à chaque consultation), son auteur compris tant qu'il le garde. Une application en client_credentials ne reçoit ce droit d'aucun scope en v1 : sa demande est refusée (403 forbidden). Un accès délégué (authorization_code) n'est admis que si l'utilisateur qui l'a accordé est lui-même ERP_OWNER ou ERP_ADMIN. Une application ne voit que les exports qu'elle a créés pour le même sujet, et jamais un export avec données personnelles créé par un utilisateur.

Téléchargement

Le fichier n'est jamais servi par une URL de stockage : il passe par Tauraco, avec Cache-Control: private, no-store, X-Content-Type-Options: nosniff et X-Content-SHA256. Par l'API, deux voies :

GET /exports/{job_id}/download avec votre jeton : le fichier en flux (409 export_not_ready tant que l'export n'a pas réussi, 410 export_expired après la purge) ;
POST /exports/{job_id}/download-link : un lien signé à usage unique, valable 60 secondes, vers GET /exports/{job_id}/file?token=…, à ouvrir sans en-tête Authorization (outil tiers, navigateur ; Referrer-Policy: no-referrer). Les droits de l'application sont relus en base au téléchargement. Une réponse rejouée par Idempotency-Key porte url: null : demandez un nouveau lien.

Depuis l'application, le même lien signé peut être émis. Un lien ne doit être ni partagé ni journalisé.

Exports planifiés et différentiels

Un modèle d'export (jeux, colonnes, filtres, format) peut être planifié (quotidien, hebdomadaire, mensuel) depuis Exports planifiés. En mode différentiel, chaque exécution ne reprend que les lignes modifiées depuis le dernier succès, avec un recouvrement de 5 minutes : un enregistrement peut apparaître deux fois, dédoublonnez sur son identifiant. Une planification qui échoue pour une raison durable (droits retirés, jeu indisponible) est désactivée (disabled, « Désactivée » à l'écran) et son auteur est notifié ; une erreur passagère ne la désactive pas. Un événement export.completed ou export.failed est émis à la fin de chaque exécution.

Exemple : export par l'API

curl -sS -X POST "https://api.tauraco.io/public/v1/exports" \
  -H "Authorization: Bearer ${TAURACO_TOKEN}" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"datasets":[{"dataset":"invoices","filters":{"status":"PAID"}}],"format":"xlsx"}'

Corps (ExportRequest) : datasets, un à dix objets {dataset, columns, filters} (columns absent : colonnes par défaut du jeu) ; format, un code de GET /integrations/formats ; format_options ; include_pii (faux par défaut) ; file_name ; delivery (download par défaut, ou une connexion de GET /integrations/connections). La réponse 202 rend l'export QUEUED et son adresse dans Location ; suivez GET /exports/{job_id} ou l'événement export.completed. POST /exports/{job_id}/cancel annule un export en file ou en cours (409 s'il est terminé).