Champs spécifiques

Certaines intégrations exposent des champs additionnels dans l'objet customFields. Cette fonctionnalité est disponible sur les opérations et les dossiers. Les champs standards restent à la racine de la ressource.

Les champs sont configurés par Batis pour vos identifiants OAuth. Deux applications d'une même équipe peuvent donc recevoir des champs différents. Leurs noms et leur signification sont convenus avec votre intégration.

{
  "id": "operation_123",
  "code": "OTP-001",
  "customFields": {
    "legalEntityName": "Entreprise Exemple",
    "legalEntitySiret": "12345678900012",
    "responsibleName": "Alice Martin",
    "responsibleEmail": "alice@example.com",
    "responsibleAccountingCode": "000123",
    "duration": "12 mois",
    "contractValidationCircuitId": "group_123",
    "contractValidationCircuitSourceType": "group"
  }
}

Valeurs et champs absents

• Sans champ configuré, customFields est absent.
• Une donnée manquante pour un champ configuré vaut null.
• Les valeurs de cette première version sont des chaînes, des nombres, des booléens ou null. Les dates sont des chaînes ISO 8601 UTC.
• Les valeurs false, 0 et les chaînes vides sont conservées. Les codes utilisateur restent des chaînes, avec leurs zéros initiaux.
• Les données sources brutes, objets complets et listes ne sont pas exposés dans cette version.
• Les noms de champs restent stables pour l'intégration concernée. Ajouter un champ spécifique ne modifie pas les champs standards.

Informations d'opération disponibles

Selon votre configuration, les champs peuvent comprendre le type et la date de marché, la description, la durée, le type d'identité, la date de DOC, le groupe, l'entité juridique, le responsable, le signataire de contrat par défaut, les auteurs historiques et la référence de configuration du circuit de validation des contrats.

Les noms, emails et codes utilisateur (accountingCode) du responsable et du signataire sont des champs séparés. Ils décrivent les personnes actuellement rattachées à l'opération.

La durée conserve le texte saisi dans Batis, sans conversion en entier ni unité imposée. La date de DOC correspond au champ configurable startingAt.

L'entité juridique est celle du groupe directement rattaché à l'opération. Dans l'exemple de configuration, legalEntitySiret contient un SIRET ou null, sans repli sur le SIREN ; le champ standard legalEntityRegistrationNumber conserve son repli sur le SIREN. L'adresse juridique est l'adresse textuelle enregistrée dans Batis.

Informations de dossier disponibles

Les champs dossier configurables sont la rue, le code postal, la ville, le code pays et l’email du contact principal de l’entreprise. Ils sont indépendants des champs configurés sur les opérations.

Exemple de réponse lorsque les cinq champs sont configurés :

{
  "id": "folder_123",
  "customFields": {
    "enterpriseStreet": "10 rue Exemple",
    "enterprisePostalCode": "00123",
    "enterpriseCity": "Paris",
    "enterpriseCountryCode": "FR",
    "enterpriseMainEmail": "contact@example.com"
  }
}

Ces valeurs sont des chaînes ou null. Le code postal conserve ses zéros initiaux. Les données d’adresse proviennent des composants enregistrés de l’entreprise. Le code pays n’a pas de valeur par défaut, contrairement au champ standard enterprise.country. L’email est celui du contact actuel de l’entreprise, sans remplacement par un email comptable. Les données manquantes valent null et les chaînes vides restent vides.

Créateur et dernier auteur connu

createdByName correspond au nom conservé dans le premier événement de création de l'opération. updatedByName correspond au nom conservé dans son dernier événement de création, modification, archivage, désarchivage ou changement de groupe.

Les noms sont ceux enregistrés au moment des événements, même si l'utilisateur a ensuite changé de nom ou a été supprimé. Les commentaires et les modifications de documents ne changent pas ces champs. Sans information historique, la valeur est null. Les modifications techniques non historisées ne sont pas reconstituées.

Référence du circuit de validation

La référence comporte deux champs, à utiliser ensemble :

Type de source	Identifiant
operation	ID de l'opération dont le circuit est personnalisé, même si sa liste de validateurs est vide.
group	ID du groupe le plus proche fournissant les validateurs de contrat dans la hiérarchie.
null	Aucun circuit hérité applicable ; l'identifiant vaut également null.

Cette référence désigne la configuration du circuit. Elle reste stable lorsque la liste de ses validateurs change au même endroit. Elle ne représente pas le circuit exécuté sur un document particulier.

Synchronisation incrémentale

updatedAt tient compte des sources des champs configurés et de la dernière modification de votre configuration. Un changement de responsable, d'entité juridique ou de configuration du circuit peut donc réémettre l'opération via updatedSince. Un champ configurable operationUpdatedAt permet de lire séparément la date propre à l'opération.

Pour les dossiers, updatedAt inclut l’entreprise lorsque des champs dossier sont configurés, et son contact lorsque l’email est configuré. Les retraits et remplacements du contact, ainsi que les changements d’entreprise, sont pris en compte. La modification de l’opération seule ne réémet pas le dossier.

Modifier ou supprimer votre configuration réémet les opérations et les dossiers pour vos identifiants OAuth, même si seule l’autre famille de ressources a changé. Les tokens déjà délivrés utilisent automatiquement la configuration actuelle.

À la réception, remplacez entièrement l'objet customFields enregistré et retirez-le s'il est absent. Cela permet de supprimer les anciennes clés après une modification de configuration. Conservez une borne de synchronisation par client OAuth et famille de ressources.

Les règles de pagination, de reprise inclusive et de réconciliation restent décrites dans Pagination et erreurs.