Cette spécification constitue le contrat officiel entre :

• Frontend NextJS
• Backend NestJS
• Applications mobiles futures
• SDK partenaires
• Intégrations externes

Elle permet :

• Génération Swagger
• Génération SDK TypeScript
• Génération SDK Java
• Génération SDK PHP
• Génération SDK Flutter
• Génération automatique des DTO

https://api.location-platform.com/api/v1

application/json

UTF-8

/api/v1
/api/v2

Header obligatoire :

Authorization: Bearer <access_token>

components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT

{
  "success": true,
  "data": {},
  "meta": {},
  "links": {}
}

{
  "success": false,
  "error": {
    "code": "PROPERTY_NOT_FOUND",
    "message": "Property not found"
  }
}

?page=1
?pageSize=20

{
  "success": true,
  "data": [],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 245,
    "pages": 13
  }
}

?sort=createdAt

?sort=-createdAt

?sort=price

?sort=-price

GET /properties

?city=Montpellier
&status=PUBLISHED
&minPrice=100
&maxPrice=300

Uuid:
  type: string
  format: uuid

Money:
  type: number
  format: double

Date:
  type: string
  format: date

DateTime:
  type: string
  format: date-time

POST /auth/login

Body :

{
  "email": "john@example.com",
  "password": "secret"
}

{
  "success": true,
  "data": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresIn": 3600
  }
}

POST /auth/register

POST /auth/refresh

POST /auth/logout

User:

  type: object

  properties:

    id:
      $ref: '#/components/schemas/Uuid'

    email:
      type: string

    status:
      type: string

    profile:
      $ref: '#/components/schemas/UserProfile'

UserProfile:

  type: object

  properties:

    firstName:
      type: string

    lastName:
      type: string

    phone:
      type: string

GET    /users/me
 
PUT    /users/me
 
GET    /users/{id}
 
GET    /users
 
DELETE /users/{id}

Property:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    title:
      type: string

    status:
      type: string

    surface:
      type: number

    roomCount:
      type: integer

    bedroomCount:
      type: integer

    bathroomCount:
      type: integer

    capacity:
      type: integer

    address:
      $ref: '#/components/schemas/PropertyAddress'

PropertyAddress:

  type: object

  properties:

    address1:
      type: string

    city:
      type: string

    postalCode:
      type: string

    country:
      type: string

    latitude:
      type: number

    longitude:
      type: number

GET /properties

Paramètres :

city
status
minPrice
maxPrice
bedrooms
bathrooms
capacity
page
pageSize
sort

POST /properties

GET /properties/{id}

PUT /properties/{id}

DELETE /properties/{id}

Reservation:

  type: object

  properties:

    id:
      type: string

    reservationNumber:
      type: string

    status:
      type: string

    startDate:
      type: string

    endDate:
      type: string

    totalAmount:
      type: number

POST /reservations

Body :

{
  "propertyId": "uuid",
  "startDate": "2026-07-01",
  "endDate": "2026-07-15",
  "guestCount": 4
}

GET /reservations/{id}

PUT /reservations/{id}

POST /reservations/{id}/cancel

Contract:

  type: object

  properties:

    id:
      type: string

    contractNumber:
      type: string

    status:
      type: string

    signedAt:
      type: string

POST /contracts/generate

POST /contracts/{id}/sign

GET /contracts/{id}/download

Payment:

  type: object

  properties:

    id:
      type: string

    amount:
      type: number

    status:
      type: string

    paymentDate:
      type: string

POST /payments

GET /payments
 
GET /payments/{id}

POST /payments/{id}/refund

GET /crm/leads
 
POST /crm/leads
 
PUT /crm/leads/{id}
 
DELETE /crm/leads/{id}

GET /crm/activities
 
POST /crm/activities

GET /conversations
 
POST /conversations
 
GET /conversations/{id}

GET /conversations/{id}/messages
 
POST /conversations/{id}/messages

GET /reports/dashboard

GET /reports/kpis

POST /reports/export

title:
  minLength: 5
  maxLength: 255

surface:
  minimum: 1

capacity:
  minimum: 1

startDate:
  required: true

endDate:
  required: true

guestCount:
  minimum: 1

amount:
  minimum: 0.01

const config =
  new DocumentBuilder()
    .setTitle('Rental API')
    .setDescription('Rental Platform API')
    .setVersion('1.0')
    .addBearerAuth()
    .build();

https://api.location-platform.com/docs

Total estimé : environ 250 endpoints REST.

• Contrat OpenAPI 3.1
• Swagger UI
• DTO TypeScript
• SDK Frontend
• SDK Mobile
• Validation JSON Schema
• Documentation API

À partir de cette spécification OpenAPI, nous pouvons désormais produire :

• Architecture Frontend NextJS 15
• Organisation des pages App Router
• Gestion d'état (TanStack Query)
• Génération automatique du client API
• Design System
• Maquettes détaillées
• Parcours utilisateurs
• Backlog Agile complet

Le prochain livrable recommandé est :

Backlog Agile détaillé (Epics → Features → User Stories → Tasks)

Ce document deviendra la base du pilotage projet et des futurs sprints Scrum.