Documents

Un document représente une pièce gérée dans Batis : contrat, attestation, bon d'acompte, document administratif ou autre typologie métier.

Les documents partagent une base commune :

• un identifiant ;
• un type ;
• un nom ;
• un fichier principal ;
• éventuellement des annexes.

Le détail du document dépend de sa typologie. La référence OpenAPI décrit ces formes avec des schémas polymorphes.

Périmètre de la liste

GET /api/v1/document expose les documents accessibles. Toutes les versions sont incluses, mais les brouillons sont exclus. Les opérations archivées restent accessibles ; les opérations supprimées sont exclues.

state correspond à l’état propre du document : validation, signature ou état documentaire enregistré. Les données historiques sans état enregistré retournent state: null, sans recalcul ; les champs status et detail sont alors également à null lorsqu’ils sont exposés. Les contrôles économiques du dossier, comme un montant insuffisant, sont disponibles dans GET /folder. Les types sans état documentaire dédié, notamment les évaluations, sont retournés avec ready.

Les montants amount et advance sont exprimés en euros HT : une valeur stockée de 12 345 centimes est retournée sous la forme 123.45. Les valeurs absentes restent à null et les valeurs nulles au sens numérique restent à 0. status, lorsqu’il est exposé, est le libellé français de l’état ; utilisez state pour les traitements automatiques.

Les champs spécialisés sans source métier restent à null, notamment insertionHours pour les OS. Les critères des évaluations sont disponibles dans noteDetails.

Fichiers

Batis ne fournit pas d'URL directe de téléchargement dans les payloads. Un fichier est exposé avec une clé opaque et un nom :

{
  "key": "main:asset_001",
  "name": "Contrat.pdf"
}

La liste expose les fichiers principaux disponibles et toutes les annexes disposant d’un fichier, y compris les annexes privées de l’équipe. Les annexes sont triées par ordre puis identifiant. Un fichier principal non généré ou retiré est retourné à null ; une liste d’annexes vide est retournée sous la forme []. La lecture ne génère aucun fichier.

Les clés sont stables pour un même fichier et doivent être traitées comme opaques. Aucun chemin de stockage ni URL directe n’est retourné.

Téléchargez le fichier avec le même token Bearer et le scope integration:read. Encodez la clé comme un segment d’URL (encodeURIComponent en JavaScript), sans la décoder ni interpréter son préfixe :

curl --fail "https://integration.batis.io/api/v1/document-file/main%3Aasset_001/download" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -o "Contrat.pdf"

Contrat de téléchargement

GET /api/v1/document-file/{fileKey}/download accepte les références suivantes :

Source	Champ contenant la clé
Fichier principal d’un document	mainDocument.key
Annexe, y compris privée	annexes[].key
Pièce administrative d’un fournisseur	administrativeDocuments[].file.key

Les clés actuelles commencent par main:, annex: ou team:. Utilisez toujours la clé reçue sans la construire vous-même. Les pièces fournisseurs sont exposées avec GET /supplier?includeAdministrativeDocuments=true.

Une réponse 200 contient le fichier complet en flux. Content-Type indique le type MIME enregistré ou application/octet-stream s’il est absent ou invalide. Content-Disposition: attachment fournit le nom via filename et filename* en UTF-8. Content-Length est présent uniquement lorsque la taille est confirmée par le stockage. La réponse porte Cache-Control: no-store. Les requêtes Range ne sont pas prises en charge : le fichier complet est retourné.

L’accès est vérifié à chaque appel selon les règles des listes. Les opérations archivées et toutes les versions métier admissibles restent accessibles ; les brouillons et opérations supprimées sont exclus. Pour les fournisseurs, seule la pièce administrative courante et visible est téléchargeable. Une pièce remplacée, détachée ou devenue invisible retourne 404, même si sa clé avait été obtenue auparavant. Une clé ne garantit pas un instantané immuable du contenu.

• 404 : clé invalide, inconnue ou inaccessible, ou absence du fichier explicitement signalée par le stockage ; le même message est retourné dans tous ces cas.
• 401 / 403 : authentification invalide ou scope insuffisant.
• 429 : limite d’appels atteinte ; respecter Retry-After.
• 503 : fichier indisponible ou erreur de stockage dont la cause ne peut pas être identifiée. Ce statut peut aussi couvrir un fichier manquant lorsque le stockage masque la cause ; il ne garantit pas une panne temporaire.

Les erreurs utilisent les formats habituels de l’API. Si le transfert est interrompu après son démarrage, la connexion est fermée : ne validez pas le fichier partiel et relancez le téléchargement complet. Le téléchargement ne génère pas de fichier et ne recalcule pas les états documentaires.