API Doctimmo v1

API REST pour les professionnels de l'immobilier

v1Base URL: https://doctimmo.fr/api/v1

Authentification

Toutes les requêtes doivent inclure un en-tête Authorization avec votre clé API :

Authorization: Bearer dk_pro_votre_cle_ici

Les clés API sont créées depuis votre tableau de bord professionnel, section "API".

Chaque clé a des scopes (permissions) qui limitent les endpoints accessibles. Le scope * donne accès à tout.

Rate Limiting

Chaque clé API a une limite de requêtes par minute (configurable, 60/min par défaut, max 300/min).

Les headers de réponse indiquent l'état de votre quota :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1712000000

En cas de dépassement, vous recevrez un 429 Too Many Requests avec un header Retry-After.

Pagination

Les endpoints qui retournent des listes sont paginés :

GET /api/v1/properties?page=2&per_page=50

{
  "data": [...],
  "meta": {
    "pagination": {
      "page": 2,
      "per_page": 50,
      "total": 150,
      "total_pages": 3,
      "has_next": true,
      "has_prev": true
    }
  }
}

Erreurs

Les erreurs suivent un format standard :

{
  "error": {
    "message": "Description de l'erreur",
    "status": 404
  }
}

400 Requête invalide

401 Non authentifié / Clé invalide

403 Scope manquant / Type d'utilisateur non autorisé

404 Ressource introuvable

429 Rate limit dépassé

500 Erreur serveur

Profil

GET/api/v1/meprofile:read

Récupère le profil de l'utilisateur authentifié, son profil professionnel et les informations de la clé API.

Exemple de réponse

{
  "data": {
    "uuid": "abc-123",
    "email": "pro@example.com",
    "user_type": "agent_immo",
    "first_name": "Jean",
    "last_name": "Dupont",
    "professional_profile": {
      "company_name": "Agence Dupont",
      "siret": "12345678901234",
      ...
    },
    "api_key": {
      "uuid": "key-uuid",
      "scopes": ["*"],
      "rate_limit": 60
    }
  }
}

Biens

GET/api/v1/propertiesproperties:read

Liste les biens auxquels le professionnel a accès.

Query Parameters

page(number)— Page (défaut: 1)

per_page(number)— Résultats par page (défaut: 20, max: 100)

city(string)— Filtrer par ville

postal_code(string)— Filtrer par code postal

property_type(string)— Filtrer par type (maison, appartement, etc.)

POST/api/v1/propertiesproperties:write

Créer un nouveau bien.

Body (JSON)

address_street(string)— Adresse (requis)

city(string)— Ville (requis)

postal_code(string)— Code postal (requis)

property_type(string)— Type de bien

surface_m2(number)— Surface en m²

rooms_count(number)— Nombre de pièces

usage_type(string)— Usage (residence_principale, locatif, etc.)

GET/api/v1/properties/:uuidproperties:read

Détail d'un bien.

Paramètres URL

uuid(string)— UUID du bien

PATCH/api/v1/properties/:uuidproperties:write

Mettre à jour un bien (propriétaire/créateur uniquement).

Paramètres URL

uuid(string)— UUID du bien

Body (JSON)

address_street(string)— Adresse

city(string)— Ville

postal_code(string)— Code postal

surface_m2(number)— Surface en m²

property_type(string)— Type de bien

DELETE/api/v1/properties/:uuidproperties:write

Supprimer un bien (soft delete).

Paramètres URL

uuid(string)— UUID du bien

Documents

GET/api/v1/properties/:uuid/documentsdocuments:read

Liste les documents d'un bien.

Paramètres URL

uuid(string)— UUID du bien

Query Parameters

category(string)— Filtrer par catégorie

page(number)— Page

per_page(number)— Résultats par page

Diagnostics

GET/api/v1/properties/:uuid/diagnosticsdiagnostics:read

Liste les diagnostics d'un bien.

Paramètres URL

uuid(string)— UUID du bien

Query Parameters

type(string)— Filtrer par type (dpe, amiante, plomb, etc.)

page(number)— Page

POST/api/v1/properties/:uuid/diagnosticsdiagnostics:write

Créer un diagnostic sur un bien.

Paramètres URL

uuid(string)— UUID du bien

Body (JSON)

diagnostic_type(string)— Type (dpe, amiante, plomb, etc.) (requis)

diagnostic_date(string)— Date YYYY-MM-DD (requis)

expiry_date(string)— Date d'expiration

score(string)— Score (A-G pour DPE)

diagnostician_name(string)— Nom du diagnostiqueur

Accès

GET/api/v1/properties/:uuid/accessesaccesses:read

Liste les accès accordés sur un bien (propriétaire ou créateur uniquement).

Paramètres URL

uuid(string)— UUID du bien

POST/api/v1/properties/:uuid/accessesaccesses:write

Accorder un accès à un utilisateur sur un bien.

Paramètres URL

uuid(string)— UUID du bien

Body (JSON)

user_email(string)— Email de l'utilisateur (requis)

access_type(string)— Type d'accès

DELETE/api/v1/properties/:uuid/accessesaccesses:write

Révoquer un accès.

Paramètres URL

uuid(string)— UUID du bien

Body (JSON)

user_email(string)— Email de l'utilisateur (requis)

Partages

GET/api/v1/properties/:uuid/sharesaccesses:read

Liste les partages externes d'un bien.

Paramètres URL

uuid(string)— UUID du bien

Leads

GET/api/v1/leadsleads:readartisanagent_immo

Liste les leads. Pour les artisans: leads qui leur sont assignés. Pour les agents: leads sur leurs biens.

Query Parameters

status(string)— Filtrer par statut (new, contacted, quote_sent, accepted, in_progress, completed)

work_type(string)— Filtrer par type de travaux

GET/api/v1/leads/:idleads:readartisanagent_immo

Détail d'un lead.

Paramètres URL

id(string)— UUID du lead

PATCH/api/v1/leads/:idleads:writeartisanagent_immo

Mettre à jour le statut ou les notes d'un lead.

Body (JSON)

status(string)— Nouveau statut

artisan_notes(string)— Notes de l'artisan

GET/api/v1/leads/:id/quotesquotes:readartisan

Liste les devis d'un lead.

POST/api/v1/leads/:id/quotesquotes:writeartisan

Créer un devis pour un lead.

Body (JSON)

amount(number)— Montant (requis)

description(string)— Description

valid_until(string)— Date d'expiration YYYY-MM-DD

GET/api/v1/leads/:id/invoicesinvoices:readartisan

Liste les factures d'un lead.

POST/api/v1/leads/:id/invoicesinvoices:writeartisan

Créer une facture pour un lead.

Body (JSON)

amount(number)— Montant (requis)

invoice_number(string)— Numéro de facture

invoice_date(string)— Date YYYY-MM-DD

Immeubles

GET/api/v1/buildingsbuildings:readsyndic

Liste les immeubles gérés par le syndic.

POST/api/v1/buildingsbuildings:writesyndic

Créer un immeuble.

Body (JSON)

name(string)— Nom (requis)

address(string)— Adresse (requis)

city(string)— Ville (requis)

postal_code(string)— Code postal (requis)

total_lots(number)— Nombre total de lots

construction_year(number)— Année de construction

GET/api/v1/buildings/:idbuildings:readsyndic

Détail d'un immeuble.

Paramètres URL

id(string)— ID de l'immeuble

PATCH/api/v1/buildings/:idbuildings:writesyndic

Mettre à jour un immeuble.

Paramètres URL

id(string)— ID de l'immeuble

DELETE/api/v1/buildings/:idbuildings:writesyndic

Supprimer un immeuble (soft delete).

Paramètres URL

id(string)— ID de l'immeuble

Lots

GET/api/v1/buildings/:id/lotslots:readsyndic

Liste les lots d'un immeuble.

Paramètres URL

id(string)— ID de l'immeuble

POST/api/v1/buildings/:id/lotslots:writesyndic

Créer un lot dans un immeuble.

Paramètres URL

id(string)— ID de l'immeuble

Body (JSON)

lot_number(string)— Numéro du lot (requis)

floor(number)— Étage

type(string)— Type de lot

surface_area(number)— Surface en m²

tantieme(number)— Tantièmes

Assemblées

GET/api/v1/buildings/:id/assembliesassemblies:readsyndic

Liste les assemblées générales d'un immeuble.

Paramètres URL

id(string)— ID de l'immeuble

Query Parameters

status(string)— Filtrer par statut (planned, in_progress, completed, cancelled)

POST/api/v1/buildings/:id/assembliesassemblies:writesyndic

Créer une assemblée générale.

Paramètres URL

id(string)— ID de l'immeuble

Body (JSON)

title(string)— Titre (requis)

date(string)— Date YYYY-MM-DD (requis)

time(string)— Heure (requis)

location(string)— Lieu (requis)

type(string)— ordinaire ou extraordinaire

Notifications

GET/api/v1/notificationsnotifications:read

Liste les notifications.

Query Parameters

unread_only(boolean)— Ne retourner que les non-lues

page(number)— Page

POST/api/v1/notifications/mark-readnotifications:write

Marquer des notifications comme lues.

Body (JSON)

all(boolean)— Marquer toutes les notifications comme lues

ids(string[])— IDs des notifications à marquer

Messagerie

GET/api/v1/conversationsmessages:read

Liste les conversations.

GET/api/v1/conversations/:id/messagesmessages:read

Liste les messages d'une conversation.

Paramètres URL

id(string)— ID de la conversation

POST/api/v1/conversations/:id/messagesmessages:write

Envoyer un message dans une conversation.

Paramètres URL

id(string)— ID de la conversation

Body (JSON)

content(string)— Contenu du message (max 5000 caractères)

Équipe

GET/api/v1/teamteam:read

Liste les membres de l'équipe.

POST/api/v1/teamteam:write

Inviter un membre dans l'équipe.

Body (JSON)

email(string)— Email du membre (requis)

role(string)— Rôle: admin ou member (défaut: member)

PATCH/api/v1/teamteam:write

Modifier le rôle d'un membre.

Body (JSON)

email(string)— Email du membre (requis)

role(string)— Nouveau rôle: admin ou member (requis)

DELETE/api/v1/teamteam:write

Retirer un membre de l'équipe.

Body (JSON)

email(string)— Email du membre (requis)

Demandes

GET/api/v1/diagnostic-requestsdiagnostic-requests:read

Liste les demandes de diagnostic. Diagnostiqueurs: demandes reçues. Autres: demandes envoyées.

POST/api/v1/diagnostic-requestsdiagnostic-requests:write

Créer une demande de diagnostic.

Body (JSON)

property_uuid(string)— UUID du bien (requis)

diagnostic_types(string[])— Types de diagnostics (requis)

message(string)— Message

preferred_date(string)— Date souhaitée YYYY-MM-DD

PATCH/api/v1/diagnostic-requestsdiagnostic-requests:write

Mettre à jour une demande (statut, prix, date).

Body (JSON)

id(string)— ID de la demande (requis)

status(string)— Nouveau statut

estimated_price(number)— Prix estimé

scheduled_date(string)— Date programmée

GET/api/v1/document-requestsdocument-requests:read

Liste les demandes de documents envoyées.

POST/api/v1/document-requestsdocument-requests:write

Créer une demande de documents.

Body (JSON)

property_uuid(string)— UUID du bien (requis)

document_types(string[])— Types de documents (requis)

message(string)— Message

Webhooks

GET/api/v1/webhooksprofile:read

Liste les webhooks configurés.

POST/api/v1/webhooksprofile:write

Créer un webhook. Le secret HMAC est retourné une seule fois.

Body (JSON)

url(string)— URL HTTPS du webhook (requis)

events(string[])— Événements à écouter (ou ["*"] pour tous)

Exemple de réponse

{
  "data": {
    "uuid": "wh-123",
    "url": "https://example.com/webhook",
    "events": ["*"],
    "secret": "abc123...",
    "is_active": true
  }
}

PATCH/api/v1/webhooks/:idprofile:write

Mettre à jour un webhook (URL, événements, actif/inactif).

Paramètres URL

id(string)— UUID du webhook

Body (JSON)

url(string)— Nouvelle URL

events(string[])— Nouveaux événements

is_active(boolean)— Activer/désactiver

DELETE/api/v1/webhooks/:idprofile:write

Supprimer un webhook.

Paramètres URL

id(string)— UUID du webhook

GET/api/v1/webhooks/:id/deliveriesprofile:read

Historique des livraisons d'un webhook.

Paramètres URL

id(string)— UUID du webhook