Comprendre Ulysse avant de l'intégrer
Ce guide explique comment Ulysse fonctionne : les notions à connaître, les étapes pour démarrer, ce qui se passe après chaque modification et les règles à respecter. Il s'adresse aux chefs de projet, aux product managers et aux équipes techniques qui préparent une intégration.
Les notions à connaître
Toute l'API s'organise autour de quelques notions. Les comprendre évite l'essentiel des questions d'intégration.
Activité
Le niveau de travail central. Une agence peut exercer plusieurs activités, chacune avec ses coordonnées, ses honoraires par défaut, ses collaborateurs et ses portails.
Annonce
Un bien à vendre ou à louer. Elle reçoit une référence unique à sa création et porte ses caractéristiques, son adresse, ses prix et ses photos.
Portail ouvert, portail choisi
Un portail est ouvert pour l'activité quand votre contrat le permet. Pour chaque annonce, vous choisissez ensuite parmi ces portails ouverts ceux sur lesquels elle part.
Règle de diffusion
La logique qui décide quelles annonces partent sur un portail : tout le portefeuille, une sélection, les plus récentes ou celles au-delà d'un prix.
Contact
Un mail ou un appel reçu d'un portail au sujet d'une annonce. Ulysse le récupère et le relie à l'annonce, au portail et au collaborateur concernés.
Rattachement
Le lien entre un contact et son annonce. Quand Ulysse ne peut pas l'établir seul, le contact reste "à rattacher" jusqu'à ce que vous le fassiez.
Démarrer en six étapes
Le parcours type d'une intégration, de l'ouverture des accès au passage en production.
Ouverture des accès
Nos équipes créent vos identifiants d'accès et une agence de démonstration pour vos essais. Vous recevez aussi l'accès à la documentation technique.
Authentification
Votre serveur échange ses identifiants contre un jeton d'accès, qu'il joint ensuite à chaque appel. Le jeton se renouvelle de la même façon à son expiration.
/oauth/tokenChargement des référentiels
Récupérez les listes de valeurs (types de biens, caractéristiques, villes) et faites correspondre vos propres données. C'est l'étape qui conditionne la qualité de vos annonces sur les portails.
/api/v1/referentials/property-typesPremière annonce
Créez une annonce sur l'agence de démonstration. Elle naît en brouillon avec une référence générée par Ulysse. Son adresse est géolocalisée en arrière-plan dans les secondes qui suivent.
/api/v1/listingsPrix et portails
Ajoutez un prix de vente ou une période de loyer, puis choisissez les portails de l'annonce parmi ceux ouverts pour l'activité.
/api/v1/listings/{id}/sale-prices/api/v1/listings/{id}/channelsSuivi puis mise en production
Lisez les statuts de publication et récupérez les contacts. Une fois ces essais validés, nos équipes basculent vos accès sur vos agences réelles.
/api/v1/listings/{id}/channels/api/v1/leadsLe cycle de vie d'une annonce
Une annonce porte trois statuts distincts. Chacun répond à une question différente et un seul est calculé par Ulysse.
Statut de saisie
L'annonce est-elle prête ? Elle démarre en brouillon. C'est vous qui le faites évoluer.
Statut commercial
Le bien est-il encore disponible ? Il démarre à "disponible". C'est vous qui le faites évoluer.
Statut de publication
Où l'annonce est-elle en ligne ? Calculé par Ulysse à partir des retours des portails, il n'est pas modifiable.
Les statuts de publication et la conduite à tenir
Ce qui se passe après une modification
Ulysse ne diffuse pas en temps réel, et c'est voulu : il regroupe les changements pour envoyer aux portails des annonces à jour plutôt qu'une série de versions intermédiaires.
Pour chaque annonce, la liste de ses portails distingue deux informations : le portail est-il ouvert pour l'activité, et est-il choisi pour cette annonce. Vous ne modifiez que la seconde.
/api/v1/listings/{id}/channelsL'ouverture d'un portail, les identifiants de diffusion et les quotas éventuels dépendent de votre contrat avec ce portail. Nos équipes les configurent pour votre activité. L'API vous permet ensuite de travailler avec les portails ouverts.
Recevoir et traiter les contacts
Les mails et appels générés par vos annonces sont importés automatiquement depuis les portails. Votre logiciel vient ensuite les chercher.
Ce qu'Ulysse fait
Il importe chaque contact, identifie l'annonce concernée et le relie au portail d'origine ainsi qu'au collaborateur en charge du bien. Si l'annonce ne peut pas être identifiée, le contact est marqué "à rattacher".
Ce que fait votre logiciel
Il interroge régulièrement la liste des contacts, filtrée par statut, type ou période, puis les intègre dans vos fiches. Un contact à rattacher se relie à une annonce en un appel.
/api/v1/leads?status=unmatched/api/v1/leads/{id}/matchCe que vous pouvez mesurer
Ulysse rend compte de la diffusion à deux niveaux : l'activité dans son ensemble et chaque portail.
Tableau de bord
Une synthèse de l'activité : annonces, état de la diffusion et contacts reçus, prête à afficher dans votre interface.
/api/v1/dashboardDernier export par portail
Pour chaque portail ouvert : la date du dernier envoi, le nombre d'annonces transmises, les erreurs et les alertes.
/api/v1/producer-activities/{id}/distribution-channelsEn rapprochant les contacts reçus par portail de ce que vous coûte chaque abonnement, vous obtenez la rentabilité de chaque portail.
Les règles métier à connaître
Certaines données obéissent à des règles précises, pensées pour garantir leur fiabilité sur les portails.
Prix de vente
Chaque changement de prix s'ajoute à un historique, sans jamais effacer le précédent. Ulysse calcule la variation d'un prix à l'autre et en déduit le prix affiché de l'annonce.
Loyers
Un loyer s'inscrit dans une période. Une nouvelle période clôt automatiquement la précédente et deux périodes ne peuvent pas se chevaucher. Charges, dépôt de garantie et honoraires restent modifiables.
Adresse
Chaque adresse est géolocalisée automatiquement à partir de la Base Adresse Nationale. Le résultat arrive quelques instants après l'enregistrement.
Certifications et proximités
Ces listes se remplacent en entier à chaque mise à jour : envoyez toujours la liste complète, pas seulement l'élément ajouté.
Programmes neufs
Un programme regroupe des lots, chacun étant une annonce. Le nombre de lots total et disponibles se calcule tout seul.
Coordonnées de l'agence
Les numéros sont convertis au format international. Un téléphone se désactive plutôt que de se supprimer, et chaque adresse mail porte un usage.
Les ressources de l'API
Les familles de ressources proposées par Ulysse, avec un exemple d'adresse et les opérations possibles. Le détail de chaque champ figure dans la documentation technique.
Annonces
Biens à vendre ou à louer avec leurs caractéristiques, leur adresse géolocalisée, leurs certifications et les commodités à proximité.
Prix et loyers
Historique complet des prix de vente avec leur variation. Loyers par période avec charges, dépôt de garantie et honoraires.
Diffusion
Portails ouverts pour l'agence, portails choisis pour chaque annonce et statut de publication sur chacun d'eux.
Contacts
Mails et appels reçus, filtrables par statut, portail ou période. Rattachement manuel à une annonce quand c'est nécessaire.
Tableau de bord
Une vue synthétique de l'activité : annonces, diffusion, contacts. Prête à afficher dans votre interface.
Programmes neufs
Programmes avec leur avancement et leurs lots. Le nombre de lots disponibles se met à jour tout seul.
Copropriétés
Cadre collectif d'un bien ou d'un programme : immeuble, lotissement, résidence étudiante ou senior.
Agence
Fiche de l'agence par activité (transaction, gestion locative, syndic) avec ses téléphones, ses adresses mail et ses honoraires par défaut.
Collaborateurs
L'équipe de l'agence, son métier et ses coordonnées. Chaque annonce désigne son interlocuteur commercial.
Utilisateurs
Comptes de connexion pour vos interfaces, par invitation, chacun rattachable à un collaborateur.
Référentiels
Villes, types de biens, caractéristiques, certifications, points d'intérêt, métiers, catalogue des portails. Des listes normalisées pour des annonces homogènes.
Connexion
Votre logiciel obtient un jeton d'accès avec ses identifiants, puis l'utilise pour chaque appel.
Les listes de valeurs
Les référentiels donnent le vocabulaire commun entre votre logiciel, Ulysse et les portails. Une annonce décrite avec ces valeurs est comprise de la même façon partout.
/api/v1/referentials/citiesLocaliser une annonce. Les villes se cherchent par nom./api/v1/referentials/transaction-typesVente, location, neuf./api/v1/referentials/property-typesAppartement, maison, terrain et autres catégories./api/v1/referentials/characteristicsSurface, pièces, équipements, avec le type de valeur attendu./api/v1/referentials/tax-certificationsLabels et dispositifs fiscaux associables à un bien./api/v1/referentials/points-of-interestCommodités à proximité : transports, écoles, commerces./api/v1/referentials/distribution-channelsL'ensemble des portails de diffusion disponibles./api/v1/referentials/distribution-policiesLes règles de sélection des annonces prêtes à l'emploi./api/v1/referentials/job-rolesDécrire l'agence et le rôle de chaque collaborateur./api/v1/referentials/condominium-frameworksImmeuble, lotissement, résidence étudiante ou senior.Les règles techniques, en clair
La répartition des rôles
Vous
- Saisir et mettre à jour les annonces
- Choisir les portails de chaque annonce
- Traiter les contacts reçus
- Gérer vos contrats avec les portails
Studio Net
- Ouvrir vos accès et votre agence de test
- Activer les portails de votre activité
- Exporter les annonces et remonter les statuts
- Vous accompagner jusqu'à la production
Les portails
- Publier les annonces reçues
- Refuser celles qui ne respectent pas leurs règles
- Transmettre les contacts des acquéreurs et locataires
Questions fréquentes
Puis-je modifier le statut de publication d'une annonce ?
Non. Il est calculé par Ulysse à partir des retours des portails. Vous agissez sur l'annonce elle-même ou sur le choix des portails, le statut suit.
Pourquoi mon annonce n'est pas encore visible sur un portail ?
Trois délais s'additionnent : le prochain cycle d'export, le temps de traitement propre au portail puis la remontée du statut. Consultez le détail par portail avant de conclure à une anomalie.
Comment modifier le prix d'une annonce ?
En ajoutant un nouveau prix de vente ou une nouvelle période de loyer. Le prix affiché de l'annonce se met à jour tout seul et l'historique reste consultable.
Que se passe-t-il si mon logiciel envoie deux fois la même création ?
Si la requête porte la même clé d'idempotence, Ulysse renvoie l'annonce déjà créée au lieu d'en créer une seconde. Si la même clé est réutilisée avec un contenu différent, la requête est refusée.
Comment connaître les valeurs acceptées pour un champ ?
Les listes de valeurs sont disponibles dans les référentiels. Le détail champ par champ figure dans la documentation technique fournie avec vos accès.
Puis-je ouvrir un nouveau portail pour mon agence depuis l'API ?
Non. L'ouverture d'un portail dépend de votre contrat avec lui. Nos équipes l'activent pour votre agence, puis vous le choisissez annonce par annonce depuis l'API.
Prêt à essayer ?
Demandez un accès de test : vous recevez vos identifiants, une agence de démonstration et la documentation technique.