Conventions utilisées dans ce cookbook

Identifiants

Champ	Rôle
id (UUID)	Identifiant interne Ublo — à conserver après création
customReference	Référence courte Ublo (ex. U000014, O000002)
externalId / foreignId	Votre clé métier pour sync import/export

Dans les exemples, les UUID sont des placeholders :

00000000-0000-4000-8000-000000000001

Remplacez-les par les IDs renvoyés par vos mutations.

Montants

Dans les captures UI analysées, les montants monétaires sont des entiers en centimes :

Valeur API	Lecture métier
100000	1 000,00 €
20000	200,00 €
300000	3 000,00 €

Confirmez toujours l’échelle sur votre environnement via une lecture (getUnit / compte locataire) après écriture.

Fragments

L’UI admin envoie souvent de gros fragments (UnitV2Fields, etc.). Pour une intégration, réduisez la sélection de champs au strict nécessaire — le schéma autorise cette sélection partielle.

Mutations GraphQL

Les exemples ciblent les champs de RootMutationType du schéma backend (noms d’opération = noms d’arguments = schéma). Les documents GraphQL de l’admin UI peuvent porter un autre nom d’opération (upsert…, …NoReturn) tout en résolvant le même champ — ne vous basez pas sur ces alias front pour une intégration API.

Erreurs

Exemple typique :

{
  "data": null,
  "errors": [
    {
      "message": "Validation failed",
      "extensions": { "code": "VALIDATION_ERROR" }
    }
  ]
}

Traitez extensions.code dans votre logique (validation, droits, not found…).

Source des exemples

Voir Légende des sources.