GET
Détail complet d'un bail (Éditeur de documents)
Il faudra que l’équipe flatbay vous fournisse une clé d’API (au niveau du groupe) pour utiliser cette route. À partir de l’identifiant d’un document (un bail ou un acte de cautionnement généré via l’éditeur de documents), cette route renvoie toutes les données du bail : le bien et ses lots, les intervenants, les mandats de prélèvement SEPA, la TVA, les variables du document, le statut, les annexes, les RIB des locataires et les URL de téléchargement du PDF signé, des annexes et des RIB.

Intervenants

intervenants liste les parties réellement présentes sur le bail, telles que figées au moment de la génération — et non l’ensemble des locataires / bailleurs rattachés au bien. Elles sont groupées par rôle : agent, bailleurs, locataires, garants. Chaque partie porte un flatbayId : l’identifiant flatbay de la partie (proprietaire pour un bailleur, locataire pour un locataire, utilisateur pour un représentant, l’agent ou un garant) lorsqu’elle a été choisie depuis le carnet d’adresses flatbay, ou un identifiant local si elle a été saisie manuellement dans l’éditeur. garants n’est renseigné que pour les baux qui portent des garants. Pour l’acte de cautionnement, les informations de la caution sont dans document.lease (champs caution*) et document.fieldValues.

Avancement de la signature

document.signature dit où en est la procédure, y compris pendant qu’elle est en cours :
  • signersTotal : le nombre de parties portées à la signature. Un destinataire à qui le document est simplement partagé n’y figure pas.
  • signersSigned : le nombre de signatures déjà apposées.
  • signed : true uniquement lorsque toutes les parties ont signé. C’est la même information que signersSigned === signersTotal.
  • signedAt : la date de complétude.
Tant que signed vaut false, le PDF servi par pdf.url n’est pas le bail définitif : c’est la version en cours de procédure. N’archivez le document qu’une fois signed à true.

Données du bail

  • document.lease : le sous-ensemble stable des données du bail (montants, dates, caution), figé à la génération — fiable même si le brouillon a été supprimé.
  • document.tva : la TVA sur le loyer et sur les charges (voir ci-dessous).
  • document.fieldValues : toutes les variables du document. Le jeu de clés dépend du type de document.

Colocation

Deux formes de bail, deux champs distincts sous property :
  • Bail individuel de colocation — un bail par chambre : property.room porte la chambre louée (null sinon), et property.rooms vaut [].
  • Bail collectif de colocation — un seul bail pour toutes les chambres : property.room vaut null et property.rooms porte le détail par chambre. Les montants par chambre sont la clé de répartition convenue entre les colocataires, imprimée dans le bail sous le titre « Quotes-parts ».
property.rooms vaut [] sur tout autre type de bail. Les montants y sont ceux figés à la génération : ils peuvent avoir été corrigés depuis sur la fiche du bien, c’est le bail signé qui fait foi. loyerCc et quotePartLoyerCc sont dérivés (loyer + charges, puis part du loyer charges comprises du bail) ; la somme des quotes-parts peut ne pas retomber exactement sur 100 après arrondi au centième.

TVA

document.tva porte, pour la ligne loyer et pour la ligne charges, l’assujettissement (assujetti), le taux en %, et les montants montantHt, montantTva, montantTtc. Ce sont des nombres, jamais des chaînes. document.tva vaut null quand le type de bail ne gère pas la TVA — seuls les baux résidence étudiante la portent. C’est une valeur distincte d’un bloc rempli de zéros, qui signifierait « bail assujetti, montants nuls ». Sur une ligne assujettie, le montant saisi est le HT ; montantTva et montantTtc en sont dérivés. Sur une ligne non assujettie, taux, montantTva et montantTtc valent null — montantHt reste renseigné.

RIB des locataires

Chaque locataire porte un tableau ribs : les RIB déposés sur sa fiche flatbay. Le champ est toujours présent — il vaut [] (et non null) quand le locataire n’a pas de RIB, quand il a été saisi manuellement dans l’éditeur (il n’a alors pas de fiche flatbay) ou quand le bail n’a pas été produit par l’éditeur de documents.

Mandats de prélèvement SEPA

mandatsSepa liste les mandats de prélèvement SEPA signés avec le bail, chacun imprimé sur ses propres pages du PDF. Le champ est toujours présent — il vaut [] quand le bail n’en porte pas. Un mandat de prélèvement SEPA seul (document.typeSlug = mandat-prelevement-sepa) est servi par la même route, avec le même bloc.
  • flatbayId : l’identifiant du mandat, stable d’une regénération à l’autre — c’est la clé de dédoublonnage.
  • rum : la référence unique du mandat (JJMMAAAA + numéro d’ordre du jour sur trois chiffres), unique par ICS. Elle est attribuée à la génération définitive et vaut null avant : un mandat sans RUM n’est pas utilisable. Un mandat n’est valable qu’une fois signé : attendez document.signature.signed à true avant de prélever.
  • type : recurrent (prélèvement mensuel, au jour jourPrelevement, de 1 à 31) ou ponctuel (prélèvement unique, à la date datePrelevement, au format AAAA-MM-JJ). La valeur qui ne s’applique pas vaut null.
  • locataireFlatbayId : le locataire pour qui le mandat est signé, même quand le payeur est un tiers (un parent, une société). Dans un bail, c’est le flatbayId d’un des intervenants.locataires ; pour un mandat seul, l’identifiant de la fiche locataire. Il vaut null si ce locataire n’est plus une partie du document.
  • creancier.source : mandataire (l’établissement du bloc etablissement, dont l’ICS est celui de sa fiche), bailleur (bailleurFlatbayId désigne alors un des intervenants.bailleurs, ou la fiche propriétaire pour un mandat seul — null si ce bailleur n’est plus une partie), ou null pour un créancier saisi à la main.
  • creancier.type / payeur.type : physique ou morale. Toutes les clés sont présentes ; celles qui ne concernent pas le type valent null (le firstName d’une société, le companyName d’une personne). payeur.representant (firstName, lastName, quality) n’est renseigné que pour un payeur personne morale. civility suit les codes des autres parties (user.civility.m, user.civility.mme…).
  • creancier.ics et payeur.iban ne sont publiés que valides — null sur un brouillon en cours de saisie. L’IBAN est au format électronique (sans espaces), celui d’un fichier de prélèvement.

Téléchargements

Le PDF final, chaque annexe et chaque RIB se téléchargent via des routes dédiées, dont les URL (clé d’API incluse) sont fournies dans pdf.url, annexes[].fileUrl et intervenants.locataires[].ribs[].fileUrl :

Path Parameters

id
integer
required

Identifiant du document (bail ou acte de cautionnement) sur la table document

Example:

12345

Query Parameters

apiKey
string
required

Mot de passe pour l'accès sécurisé

Example:

"api_key_here"

Response

Détail du bail

Détail complet d'un bail généré via l'éditeur de documents

document
object

Métadonnées du document + données figées du bail

property
object

Bien objet du bail. Adresse non masquée (partenaire authentifié).

etablissement
object

Établissement (agence mandataire) gérant le bien

intervenants
object

Parties réellement présentes sur le bail, figées à la génération (et non l'ensemble des locataires / bailleurs rattachés au bien)

mandatsSepa
object[]

Mandats de prélèvement SEPA signés avec le bail, chacun sur ses propres pages du PDF. Toujours présent, [] si le document n'en porte pas. Un mandat n'est utilisable qu'avec une rum, sur un document signé.

annexes
object[]

Annexes du bail (le binaire est servi via fileUrl)

pdf
object

PDF final du bail