Skip to main content

Évolutions API - Septembre 2026

Lecture du document référencé sous forme d'objet​

En lecture sur RentalAccountInvoice, referencedInvoiceId et referencedCreditNoteId sont dépréciés et seront supprimés à partir du 1er janvier 2027. Ils sont remplacés par referencedInvoice et referencedCreditNote, qui exposent directement l'objet RentalAccountInvoice référencé plutôt que son seul identifiant.

query getRentalAccountInvoice($id: UUID!) {
getRentalAccountInvoice(id: $id) {
  id
  nature
  referencedInvoice {
    id
    custom_reference
  }
  referencedCreditNote {
    id
    custom_reference
  }
  referencedDocumentIdentifier
}
}

Important : nous vous recommandons de migrer vers referencedInvoice / referencedCreditNote dès maintenant. Les champs referencedInvoiceId et referencedCreditNoteId seront retirés de l'API à partir du 1er janvier 2027.

referencedDocumentIdentifier n'est pas concerné par cette dépréciation.

Côté écriture, les mutations continuent d'accepter referencedInvoiceId et referencedCreditNoteId.

Activation de la facturation électronique (Factur-X)​

Un nouveau champ electronicInvoicingSubmitted est disponible sur AutoInvoicingConfig, en lecture et en écriture. Lorsqu'il est activé, les factures et avoirs générés pour le dossier de location concerné sont émis au format électronique (Factur-X) plutôt qu'au format PDF classique.

Activer la facturation électronique​

mutation updateAutoInvoicingConfig($rentalAccountId: UUID!, $autoInvoicingConfig: autoInvoicingConfigInput!) {
updateAutoInvoicingConfig(
  rentalAccountId: $rentalAccountId
  autoInvoicingConfig: $autoInvoicingConfig
) {
  electronicInvoicingSubmitted
}
}

Validations à l'activation​

L'activation (electronicInvoicingSubmitted: true) est bloquée si :

  • au moins un élément de loyer du dossier de location n'a pas de code TVA renseigné
  • le locataire signataire n'a pas d'adresse renseignée (adresse du logement actuel pour une personne physique, adresse de la structure pour une personne morale)

Important : les deux conditions doivent être remplies simultanément pour que l'activation réussisse.

Évolutions API - Août 2026

À partir du 14 août 2026, de nouvelles fonctionnalités seront disponibles sur l'API Ublo.

Gestion des codes TVA et d'exemption​

Pour chaque opération comptable (éléments de loyer, variations de loyer, lignes de facture, avoirs), il sera désormais possible de renseigner :

  • un code TVA
  • un code d'exemption associé

Important : dans un premier temps, aucune validation stricte ne sera appliquée sur ces champs. À partir de janvier 2027, la présence du code TVA sera contrôlée de manière renforcée sur l'API publique. Nous vous recommandons d'anticiper cette évolution dès maintenant.

Récupérer les codes disponibles​

1. Liste des codes TVA disponibles

query listVatCodes {
listVatCodes {
  id
  code
  label
}
}

2. Liste des codes d'exemption associés à un code TVA

En filtrant avec l'id du code TVA sélectionné, vous obtenez la liste des codes d'exemption compatibles :

query listVatExemptionCodes($vatCodeId: ID!) {
listVatExemptionCodes(vatCodeId: $vatCodeId) {
  id
  code
  legalReason
}
}

Mutations concernées​

L'ensemble des mutations relatives aux opérations comptables (createInvoice, updateRentItems, etc.), sauf le remboursement et la transaction, acceptent désormais deux nouveaux paramètres :

  • l'id du code TVA
  • l'id du code d'exemption

Nature et référence des factures et avoirs​

Nature du document​

Seuls les avoirs ont une nature :

  • standard : avoir sans lien de correction (remise, geste commercial...). Il n'annule ni ne corrige aucun document.
  • corrective : avoir qui corrige une facture (montant, TVA, erreur). Il doit obligatoirement référencer la facture qu'il corrige.

Les factures restent inchangées : pour l'instant il n'est pas possible de créer une facture corrective, leur nature est toujours standard.

Référencer un document​

Trois nouveaux champs sont disponibles, un seul doit être renseigné à la fois :

  • referencedInvoiceId : référence vers une facture Ublo
  • referencedCreditNoteId : référence vers un avoir Ublo
  • referencedDocumentIdentifier : référence libre vers un document externe non géré dans Ublo

Sur une facture, ce champ reste optionnel : il permet de la lier à une facture ou un avoir existant afin d’assurer la traçabilité et la continuité entre les objets financiers, sans effet de correction.

Sur un avoir de nature corrective, l'un de ces trois champs devient obligatoire. Le document référencé doit exister et ne pas être à l'état draft. Un document ne peut pas se référencer lui-même.

Récupérer les documents éligibles comme référence​

query referenceableDocuments($rentalAccountId: UUID!, $creatingDocumentType: InvoiceType!, $creatingDocumentNature: InvoiceNature!) {
referenceableDocuments(
  rentalAccountId: $rentalAccountId
  creatingDocumentType: $creatingDocumentType
  creatingDocumentNature: $creatingDocumentNature
) {
  id
  reference
  type
}
}

Mutations concernées​

Les mutations createRentalAccountInvoice / createRentalAccountInvoiceV2 et updateRentalAccountInvoice / updateRentalAccountInvoiceV2 (pour les factures comme pour les avoirs) acceptent désormais trois nouveaux paramètres :

  • nature
  • referencedInvoiceId, referencedCreditNoteId ou referencedDocumentIdentifier

Ces champs sont également exposés en lecture sur RentalAccountInvoice.

Évolutions API - Juillet 2026

À partir du 20 juillet 2026, plusieurs évolutions seront disponibles sur l'API du flux financier et des RentalAccount.

Ces évolutions introduisent de nouvelles mutations en version V2, ainsi qu'une séparation plus claire des opérations de mise à jour d'un compte de location.

Les mutations existantes restent disponibles et conservent leur comportement actuel.

La dépréciation de la v1 est planifiée en janvier 2027.

Mutations financières V2

Nouveau format de réponse​

De nouvelles versions des mutations du flux financier sont introduites.

Contrairement aux mutations existantes qui retournent l'entité complète RentalAccount ou RentalAccountRefund, les mutations V2 retournent un objet financialObjectPayload contenant uniquement les informations nécessaires pour identifier la ressource concernée.

Response Payload​

Response Payload
{
  "id": "UUID-1234-5679",
  "rentalAccountId": "UUID-1234-9876"
}

Le payload contient :

  • id : l'identifiant de la ressource créée ou modifiée.
  • rentalAccountId : l'identifiant du RentalAccount associé.

Exemple​

Mutation existante​

La mutation existante retourne l'entité complète :

mutation DeleteRentalAccountInvoice($id: UUID!, $accountId: UUID!) {
  deleteRentalAccountInvoice($id: uuid_1234, $accountId: uuid_account) {
    id
    invoices {
      id
      iotTotalAmount
    }
  }
}

Mutation V2​

La version V2 retourne uniquement les identifiants nécessaires :

mutation DeleteRentalAccountInvoiceV2($id: UUID!, $accountId: UUID!) {
  deleteRentalAccountInvoiceV2($id: uuid_1234, $accountId: uuid_account) {
    id
    rentalAccountId
  }
}

Mutations disponibles en V2​

Les mutations suivantes sont disponibles en version V2 :

  • createRentalAccountInvoiceV2
  • updateRentalAccountInvoiceV2
  • freezeRentalAccountInvoiceV2
  • updateInvoiceTransactionsV2
  • lockPaidInvoiceV2
  • deleteInvoiceV2
  • createTransactionV2
  • deleteTransactionV2
  • createDraftRefundV2
  • updateDraftRefundV2
  • deleteDraftRefundV2
  • emitRefundOperationV2
  • confirmRefundOperationV2

Modèle de cohérence des mutations V2

Les mutations V2 utilisent un modèle de cohérence éventuelle (eventual consistency).

Une mutation confirme uniquement que l'opération a été acceptée et enregistrée.

La mise à jour des modèles de lecture est effectuée de manière asynchrone.

En conséquence, la ressource créée ou modifiée peut ne pas être immédiatement disponible via une requête (query) après l'exécution de la mutation.

Si votre application a besoin de récupérer la ressource mise à jour, elle devra effectuer une requête ultérieure en utilisant l'identifiant retourné par la mutation.

[!NOTE] Les mutations existantes conservent leur comportement actuel. Le modèle de cohérence éventuelle s'applique uniquement aux mutations V2.

Mise à jour des informations RentalAccount

À partir de janvier 2027, la mutation updateRentalFolder ne prendra plus en charge les modifications liées au RentalAccount.

Les mises à jour du compte de location doivent désormais être effectuées via les mutations dédiées suivantes.

updateRentalAccountRentItems​

Cette mutation permet de mettre à jour les éléments de loyer d'un dossier de location.

mutation UpdateRentalAccountRentItems($rentalAccountId: UUID!, $rentalAccountRentItems: rentalAccountRentItemsInput!) {
  updateRentalAccountRentItems(
    rentalAccountId: uuid,
    rentalAccountRentItems: {}
  ) {
    rentalAccountId
  }
}

updateRentRevision​

Cette mutation permet de mettre à jour le paramétrage de révision de loyer d'un dossier de location.

mutation UpdateRentRevision($rentalAccountId: UUID!, $rentRevision: rentalAccountRentRevisionInput!) {
  updateRentRevision(
    rentalAccountId: uuid,
    rentRevision: {}
  ) {
    rentalAccountId
  }
}

updateProcurementOrder​

Cette mutation permet de mettre à jour la configuration Chorus Pro d'un dossier de location.

mutation UpdateProcurementOrder($rentalAccountId: UUID!, $procurementOrderInput: procurementOrderInput!) {
  updateProcurementOrder(
    rentalAccountId: uuid,
    procurementOrderInput: {}
  ) {
    rentalAccountId
  }
}

setBalanceOffset​

Cette mutation permet de créer ou mettre à jour le solde initial d'un dossier de location.

mutation SetBalanceOffset($rentalAccountId: UUID!, $setBalanceOffsetInput: setBalanceOffsetInput!) {
  setBalanceOffset(
    rentalAccountId: uuid,
    setBalanceOffsetInput: {}
  ) {
    rentalAccountId
  }
}
Last updated on by grtcdr