Crealcs Development DokuWiki

Outils pour utilisateurs

Outils du site

Piste : • 3-spec-open-api
ujusum:3-codage:1-repository:3-spec-open-api

Ceci est une ancienne révision du document !

Table des matières

Phase 3 — Spécification OpenAPI 3.1 Enterprise

Objectif

À ce stade : 

Schema Prisma
≈ 110 modèles

Architecture Hexagonale NestJS

DDD

CQRS

RBAC

Multi-Tenant

Enterprise Security

Internationalisation

IA

sont désormais définis.

La prochaine étape consiste à construire la : 

Source de vérité contractuelle

du système : 

openapi.yaml

qui permettra ensuite de générer automatiquement : 

Swagger

DTO NestJS

Validation Zod

SDK TypeScript

Client React Query

Mocks

Tests contractuels

Documentation API

Stratégie

Vu la taille du projet : 

100+ modèles

1000+ endpoints

nous allons procéder par domaines.

Découpage OpenAPI

Domaine 1

Core & Security 

/auth

/users

/roles

/permissions

/sessions

/mfa

/security

Domaine 2

Owners 

/owners

/owner-documents

/owner-bank-accounts

Domaine 3

Properties 

/properties

/property-media

/property-features

/property-rates

/property-availability

Domaine 4

Customers 

/customers

/customer-documents

/customer-notes

Domaine 5

Reservations 

/reservations

/reservation-guests

/reservation-pricing

/reservation-events

Domaine 6

Contracts 

/contracts

/contract-templates

/signatures

Domaine 7

Finance 

/payments

/refunds

/invoices

/accounting

Domaine 8

CRM 

/leads

/opportunities

/pipelines

/tasks

/activities

Domaine 9

Messaging 

/notifications

/conversations

/messages

/emails

/sms

Domaine 10

Marketing 

/campaigns

/segments

/marketing-events

Domaine 11

Governance 

/audit

/workflows

/feature-flags

Domaine 12

OTA 

/channels

/distributions

/channel-reservations

/syncs

Domaine 13

Revenue 

/pricing-rules

/dynamic-prices

/revenue-forecasts

Domaine 14

Compliance 

/consents

/risks

/incidents

/compliance-audits

Domaine 15

Internationalisation 

/countries

/currencies

/languages

/translations

Domaine 16

IA 

/ai/conversations

/ai/messages

/knowledge

/recommendations

Ordre recommandé

Pour démarrer la génération réelle du backend : 

OpenAPI Domain 1

doit être produit en premier.

Phase 3-A

Core Security API

Modules

Auth

Users

Roles

Permissions

Sessions

MFA

Livrable

Premier fichier : 

openapi-core-security.yaml

contenant :

  • Security Schemes
  • JWT
  • Refresh Token
  • Users API
  • Roles API
  • Permissions API
  • Pagination
  • Error Model
  • Validation Model

Exemple

Security Scheme

components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT

Endpoint

GET /users

Réponse

200:

  description: Users list

  content:

    application/json:

      schema:

        $ref: '#/components/schemas/UserListResponse'

Phase 3-A.1 — OpenAPI Core Security

Objectif

Définir le premier contrat API officiel de la plateforme.

Ce document couvre : 

Auth

Users

Roles

Permissions

Sessions

Refresh Tokens

MFA

Pagination

Filtering

Sorting

Error Handling

Compatible : 

OpenAPI 3.1

NestJS

Swagger

OpenAPI Generator

Zod

React Query

Structure

Fichier

apps/api/openapi/openapi-core-security.yaml

En-tête OpenAPI

openapi: 3.1.0

info:
  title: Rental Platform API
  version: 1.0.0
  description: Enterprise Rental Platform

servers:
  - url: https://api.company.com/v1
    description: Production

  - url: https://staging-api.company.com/v1
    description: Staging

tags:
  - name: Authentication
  - name: Users
  - name: Roles
  - name: Permissions
  - name: Sessions
  - name: MFA

Security

JWT

components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT

Common Schemas

UUID

Uuid:

  type: string

  format: uuid

Timestamp

Timestamp:

  type: string

  format: date-time

Pagination

PaginationMeta:

  type: object

  properties:

    page:
      type: integer

    pageSize:
      type: integer

    total:
      type: integer

    totalPages:
      type: integer

Error Model

ApiError

ApiError:

  type: object

  required:

    - code
    - message

  properties:

    code:
      type: string

    message:
      type: string

    details:
      type: object

ValidationError

ValidationError:

  allOf:

    - $ref: '#/components/schemas/ApiError'

    - type: object

      properties:

        fields:

          type: array

          items:

            type: object

            properties:

              field:
                type: string

              message:
                type: string

Authentication

RegisterRequest

RegisterRequest:

  type: object

  required:

    - email
    - password
    - firstName
    - lastName

  properties:

    email:
      type: string
      format: email

    password:
      type: string
      minLength: 8

    firstName:
      type: string

    lastName:
      type: string

LoginRequest

LoginRequest:

  type: object

  required:

    - email
    - password

  properties:

    email:
      type: string
      format: email

    password:
      type: string

TokenResponse

TokenResponse:

  type: object

  properties:

    accessToken:
      type: string

    refreshToken:
      type: string

    expiresIn:
      type: integer

    tokenType:
      type: string
      example: Bearer

POST /auth/register

/auth/register:

  post:

    tags:
      - Authentication

    summary: Register user

    requestBody:

      required: true

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/RegisterRequest'

    responses:

      '201':

        description: User created

      '400':

        description: Validation error

POST /auth/login

/auth/login:

  post:

    tags:
      - Authentication

    summary: Login

    requestBody:

      required: true

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/LoginRequest'

    responses:

      '200':

        description: Authentication success

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/TokenResponse'

POST /auth/refresh

/auth/refresh:

  post:

    tags:
      - Authentication

    summary: Refresh token

POST /auth/logout

/auth/logout:

  post:

    security:

      - bearerAuth: []

    tags:

      - Authentication

    summary: Logout

Users

User

User:

  type: object

  properties:

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

    email:
      type: string

    firstName:
      type: string

    lastName:
      type: string

    active:
      type: boolean

    createdAt:
      $ref: '#/components/schemas/Timestamp'

UserListResponse

UserListResponse:

  type: object

  properties:

    data:

      type: array

      items:

        $ref: '#/components/schemas/User'

    meta:

      $ref: '#/components/schemas/PaginationMeta'

GET /users

/users:

  get:

    security:

      - bearerAuth: []

    tags:

      - Users

    summary: List users

    parameters:

      - name: page
        in: query
        schema:
          type: integer

      - name: pageSize
        in: query
        schema:
          type: integer

      - name: search
        in: query
        schema:
          type: string

      - name: sort
        in: query
        schema:
          type: string

    responses:

      '200':

        description: User list

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/UserListResponse'

GET /users/{id}

/users/{id}:

  get:

    security:

      - bearerAuth: []

    tags:

      - Users

    parameters:

      - name: id
        in: path
        required: true
        schema:
          format: uuid
          type: string

    responses:

      '200':

        description: User

POST /users

/users:

  post:

    security:

      - bearerAuth: []

    tags:

      - Users

    summary: Create user

PATCH /users/{id}

/users/{id}:

  patch:

    security:

      - bearerAuth: []

    tags:

      - Users

DELETE /users/{id}

/users/{id}:

  delete:

    security:

      - bearerAuth: []

    tags:

      - Users

Roles

Role

Role:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    name:
      type: string

Endpoints

GET    /roles

POST   /roles

GET    /roles/{id}

PATCH  /roles/{id}

DELETE /roles/{id}

Permissions

Permission

Permission:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    name:
      type: string

Endpoints

GET /permissions

GET /permissions/{id}

User Roles

Endpoints

POST   /users/{id}/roles

DELETE /users/{id}/roles/{roleId}

Sessions

Session

Session:

  type: object

  properties:

    id:
      type: string

    ipAddress:
      type: string

    userAgent:
      type: string

    lastActivityAt:
      type: string
      format: date-time

Endpoints

GET /sessions

DELETE /sessions/{id}

MFA

Enable MFA

POST /mfa/enable

Verify MFA

POST /mfa/verify

Disable MFA

POST /mfa/disable

HTTP Status Codes

200 OK

201 Created

204 No Content

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Headers

Multi Tenant

X-Tenant-Id:
  required: true

Correlation

X-Correlation-Id:
  required: false

Volume API

Phase 3-A.1 fournit : 

≈ 25 endpoints

≈ 15 schemas

≈ 6 tags

≈ 3 security flows

Phase 3-A.2 — OpenAPI Owners & Properties

Objectif

Définir le premier domaine métier principal de la plateforme : 

Owners

Properties

Property Media

Property Features

Property Availability

Property Rates

Ce domaine couvre : 

Sprint 3

Catalogue Immobilier

et constitue le socle métier de : 

Réservations

Contrats

Paiements

OTA

Revenue Management

Tags OpenAPI

tags:

  - name: Owners

  - name: OwnerDocuments

  - name: OwnerBankAccounts

  - name: Properties

  - name: PropertyMedia

  - name: PropertyFeatures

  - name: PropertyAvailability

  - name: PropertyRates

Schémas

Owner

Owner:

  type: object

  properties:

    id:
      type: string
      format: uuid

    ownerNumber:
      type: string

    firstName:
      type: string

    lastName:
      type: string

    email:
      type: string
      format: email

    phone:
      type: string

    active:
      type: boolean

    createdAt:
      type: string
      format: date-time

CreateOwnerRequest

CreateOwnerRequest:

  type: object

  required:

    - firstName
 
    - lastName
 
    - email

  properties:

    firstName:
      type: string

    lastName:
      type: string

    email:
      type: string
      format: email

    phone:
      type: string

Endpoints Owners

Collection

GET    /owners

POST   /owners

Ressource

GET    /owners/{id}

PATCH  /owners/{id}

DELETE /owners/{id}

Recherche

GET /owners

?page=1

&pageSize=20

&search=dupont

&active=true

&sort=lastName

Owner Documents

Endpoints

GET    /owners/{id}/documents

POST   /owners/{id}/documents

DELETE /owners/{id}/documents/{documentId}

Upload

multipart/form-data

Types

IDENTITY

TAX

INSURANCE

MANDATE

CONTRACT

Owner Bank Accounts

BankAccount

BankAccount:

  type: object

  properties:

    id:
      type: string

    iban:
      type: string

    bic:
      type: string

    accountHolder:
      type: string

Endpoints

GET    /owners/{id}/bank-accounts

POST   /owners/{id}/bank-accounts

PATCH  /owners/{id}/bank-accounts/{accountId}

DELETE /owners/{id}/bank-accounts/{accountId}

Properties

Property

Property:

  type: object

  properties:

    id:
      type: string
      format: uuid

    code:
      type: string

    title:
      type: string

    slug:
      type: string

    propertyType:
      type: string

    status:
      type: string

    published:
      type: boolean

    maxGuests:
      type: integer

    bedrooms:
      type: integer

    bathrooms:
      type: integer

    surface:
      type: number

    createdAt:
      type: string
      format: date-time

CreatePropertyRequest

CreatePropertyRequest:

  type: object

  required:

    - title
 
    - propertyType

  properties:

    title:
      type: string

    description:
      type: string

    propertyType:
      type: string

    maxGuests:
      type: integer

    bedrooms:
      type: integer

    bathrooms:
      type: integer

Endpoints Properties

Collection

GET    /properties

POST   /properties

Ressource

GET    /properties/{id}

PATCH  /properties/{id}

DELETE /properties/{id}

Publication

POST /properties/{id}/publish

POST /properties/{id}/unpublish

Recherche

GET /properties

?search=villa

?propertyType=HOUSE

?published=true

?ownerId=xxx

?page=1

&pageSize=20

Property Address

Endpoints

GET /properties/{id}/address

PUT /properties/{id}/address

Property Owners

Affectation

GET /properties/{id}/owners

POST /properties/{id}/owners

DELETE /properties/{id}/owners/{ownerId}

Property Media

PropertyMedia

PropertyMedia:

  type: object

  properties:

    id:
      type: string

    fileUrl:
      type: string

    title:
      type: string

    position:
      type: integer

    isCover:
      type: boolean

Endpoints

GET    /properties/{id}/media

POST   /properties/{id}/media

PATCH  /properties/{id}/media/{mediaId}

DELETE /properties/{id}/media/{mediaId}

Upload

multipart/form-data

Property Features

PropertyFeature

PropertyFeature:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    label:
      type: string

Exemples

POOL

WIFI

AIR_CONDITIONING

PARKING

SEA_VIEW

JACUZZI

Endpoints

GET /property-features

GET /properties/{id}/features

POST /properties/{id}/features

DELETE /properties/{id}/features/{featureId}

Property Availability

Availability

Availability:

  type: object

  properties:

    id:
      type: string

    startDate:
      type: string
      format: date

    endDate:
      type: string
      format: date

    available:
      type: boolean

Endpoints

GET /properties/{id}/availability

POST /properties/{id}/availability

PATCH /availability/{id}

DELETE /availability/{id}

Recherche

GET /properties/{id}/availability

?from=2026-07-01

&to=2026-07-31

Property Rates

PropertyRate

PropertyRate:

  type: object

  properties:

    id:
      type: string

    startDate:
      type: string
      format: date

    endDate:
      type: string
      format: date

    nightlyRate:
      type: number

    minimumStay:
      type: integer

Endpoints

GET /properties/{id}/rates

POST /properties/{id}/rates

PATCH /property-rates/{id}

DELETE /property-rates/{id}

Property Search API

Endpoint public

GET /catalog/properties

Filtres

destination

checkIn

checkOut

guests

priceMin

priceMax

bedrooms

features

Réponse

PropertySearchResponse:

  type: object

  properties:

    data:

      type: array

      items:

        $ref: '#/components/schemas/Property'

    meta:

      $ref: '#/components/schemas/PaginationMeta'

Permissions RBAC

Owners

owners.read

owners.create

owners.update

owners.delete

Properties

properties.read

properties.create

properties.update

properties.publish

properties.delete

Volume API

Cette phase ajoute : 

≈ 42 endpoints

≈ 12 schémas OpenAPI

≈ 8 tags Swagger

Cumul OpenAPI

Après Phase 3-A.2 : 

≈ 67 endpoints

≈ 30 schémas

≈ 14 tags

Phase 3-A.3 — OpenAPI Customers & Reservations

Objectif

Définir le cœur transactionnel de la plateforme : 

Customers

Reservations

Reservation Guests

Reservation Pricing

Reservation Events

Reservation Status History

Cette phase couvre : 

Sprint 4

Réservation & Calendrier

et constitue la base de : 

Contrats

Paiements

OTA

Revenue Management

CRM

Tags OpenAPI

tags:

  - name: Customers

  - name: CustomerDocuments

  - name: CustomerNotes

  - name: Reservations

  - name: ReservationGuests

  - name: ReservationPricing

  - name: ReservationEvents

  - name: ReservationCalendar

Customers

Customer

Customer:

  type: object

  properties:

    id:
      type: string
      format: uuid

    customerNumber:
      type: string

    firstName:
      type: string

    lastName:
      type: string

    email:
      type: string
      format: email

    phone:
      type: string

    nationality:
      type: string

    active:
      type: boolean

    createdAt:
      type: string
      format: date-time

CreateCustomerRequest

CreateCustomerRequest:

  type: object

  required:

    - firstName
 
    - lastName
 
    - email

  properties:

    firstName:
      type: string

    lastName:
      type: string

    email:
      type: string
      format: email

    phone:
      type: string

    nationality:
      type: string

Endpoints Customers

Collection

GET    /customers

POST   /customers

Ressource

GET    /customers/{id}

PATCH  /customers/{id}

DELETE /customers/{id}

Recherche

GET /customers

?search=smith

?email=test@email.com

?page=1

&pageSize=20

Customer Documents

Endpoints

GET    /customers/{id}/documents

POST   /customers/{id}/documents

DELETE /customers/{id}/documents/{documentId}

Customer Notes

Endpoints

GET    /customers/{id}/notes

POST   /customers/{id}/notes

PATCH  /customer-notes/{id}

DELETE /customer-notes/{id}

Reservations

Reservation

Reservation:

  type: object

  properties:

    id:
      type: string
      format: uuid

    reference:
      type: string

    propertyId:
      type: string
      format: uuid

    customerId:
      type: string
      format: uuid

    status:
      $ref: '#/components/schemas/ReservationStatus'

    checkInDate:
      type: string
      format: date

    checkOutDate:
      type: string
      format: date

    nights:
      type: integer

    adults:
      type: integer

    children:
      type: integer

    totalGuests:
      type: integer

    createdAt:
      type: string
      format: date-time

ReservationStatus

ReservationStatus:

  type: string

  enum:

    - DRAFT
    - PENDING
    - OPTION
    - CONFIRMED
    - CONTRACT_SENT
    - CONTRACT_SIGNED
    - PARTIALLY_PAID
    - PAID
    - CHECKED_IN
    - CHECKED_OUT
    - COMPLETED
    - CANCELLED
    - REFUNDED

CreateReservationRequest

CreateReservationRequest:

  type: object

  required:

    - propertyId
    - checkInDate
    - checkOutDate
    - adults

  properties:

    propertyId:
      type: string
      format: uuid

    customerId:
      type: string
      format: uuid

    checkInDate:
      type: string
      format: date

    checkOutDate:
      type: string
      format: date

    adults:
      type: integer

    children:
      type: integer

    customerNotes:
      type: string

Endpoints Reservations

Collection

GET    /reservations

POST   /reservations

Ressource

GET    /reservations/{id}

PATCH  /reservations/{id}

DELETE /reservations/{id}

Recherche

GET /reservations

?status=CONFIRMED

?propertyId=xxx

?customerId=xxx

?from=2026-07-01

?to=2026-07-31

Réservation Workflow

Confirmation

POST /reservations/{id}/confirm

Annulation

POST /reservations/{id}/cancel

Check-In

POST /reservations/{id}/check-in

Check-Out

POST /reservations/{id}/check-out

Vérification Disponibilité

Endpoint

POST /reservations/check-availability

Request

AvailabilityCheckRequest:

  type: object

  properties:

    propertyId:
      type: string

    checkInDate:
      type: string
      format: date

    checkOutDate:
      type: string
      format: date

Response

AvailabilityCheckResponse:

  type: object

  properties:

    available:
      type: boolean

    conflicts:

      type: array

      items:

        type: string

Reservation Guests

ReservationGuest

ReservationGuest:

  type: object

  properties:

    id:
      type: string

    firstName:
      type: string

    lastName:
      type: string

    nationality:
      type: string

    birthDate:
      type: string
      format: date

    isPrimary:
      type: boolean

Endpoints

GET    /reservations/{id}/guests

POST   /reservations/{id}/guests

PATCH  /reservation-guests/{id}

DELETE /reservation-guests/{id}

Reservation Pricing

ReservationPricing

ReservationPricing:

  type: object

  properties:

    nightlyAmount:
      type: number

    cleaningFee:
      type: number

    touristTax:
      type: number

    extrasAmount:
      type: number

    discountAmount:
      type: number

    totalAmount:
      type: number

    currencyCode:
      type: string

Endpoints

GET /reservations/{id}/pricing

POST /reservations/{id}/pricing/recalculate

Reservation Events

ReservationEvent

ReservationEvent:

  type: object

  properties:

    id:
      type: string

    eventType:
      type: string

    payload:
      type: object

    createdAt:
      type: string
      format: date-time

Endpoints

GET /reservations/{id}/events

Historique des statuts

Endpoint

GET /reservations/{id}/history

Response

ReservationStatusHistory:

  type: object

  properties:

    previousStatus:
      type: string

    newStatus:
      type: string

    changedAt:
      type: string
      format: date-time

    changedBy:
      type: string

Calendrier

Calendrier d'un bien

GET /properties/{id}/calendar

Paramètres

from

to

Réponse

CalendarDay:

  type: object

  properties:

    date:
      type: string

    available:
      type: boolean

    reservationId:
      type: string

Catalogue Public

Recherche

GET /catalog/search

Filtres

destination

checkInDate

checkOutDate

adults

children

priceMin

priceMax

features

Réponse

CatalogSearchResponse:

  type: object

  properties:

    properties:
      type: array

    total:
      type: integer

Permissions RBAC

Customers

customers.read

customers.create

customers.update

customers.delete

Reservations

reservations.read

reservations.create

reservations.update

reservations.cancel

reservations.checkin

reservations.checkout

Volume API

Cette phase ajoute : 

≈ 52 endpoints

≈ 18 schémas

≈ 8 tags Swagger

Cumul OpenAPI

Après Phase 3-A.3 : 

≈ 120 endpoints

≈ 48 schémas

≈ 22 tags

Phase 3-A.4 — OpenAPI Contracts & Finance

Objectif

Définir le domaine financier et contractuel de la plateforme.

Cette phase couvre : 

Sprint 5

Contrats & Signature Électronique

Sprint 6

Paiements & Facturation

Elle permet : 

Réservation

↓

Contrat

↓

Signature

↓

Paiement

↓

Facture

↓

Comptabilité

Tags OpenAPI

tags:

  - name: Contracts

  - name: ContractTemplates

  - name: ContractSignatures

  - name: Payments

  - name: Refunds

  - name: Invoices

  - name: Accounting

Contracts

Contract

Contract:

  type: object

  properties:

    id:
      type: string
      format: uuid

    contractNumber:
      type: string

    reservationId:
      type: string
      format: uuid

    status:
      $ref: '#/components/schemas/ContractStatus'

    generatedAt:
      type: string
      format: date-time

    signedAt:
      type: string
      format: date-time

    pdfUrl:
      type: string

ContractStatus

ContractStatus:

  type: string

  enum:

    - DRAFT
    - GENERATED
    - SENT
    - VIEWED
    - SIGNED
    - CANCELLED

Endpoints Contracts

Collection

GET    /contracts

POST   /contracts

Ressource

GET    /contracts/{id}

PATCH  /contracts/{id}

DELETE /contracts/{id}

Réservation

GET /reservations/{id}/contracts

Génération

Générer un contrat

POST /contracts/generate

Request

GenerateContractRequest:

  type: object

  required:

    - reservationId
    - templateId

  properties:

    reservationId:
      type: string

    templateId:
      type: string

Réponse

GenerateContractResponse:

  type: object

  properties:

    contractId:
      type: string

    pdfUrl:
      type: string

PDF

Télécharger

GET /contracts/{id}/pdf

Régénérer

POST /contracts/{id}/regenerate

Contract Templates

ContractTemplate

ContractTemplate:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    name:
      type: string

    active:
      type: boolean

Endpoints

GET    /contract-templates

POST   /contract-templates

GET    /contract-templates/{id}

PATCH  /contract-templates/{id}

DELETE /contract-templates/{id}

Contract Signatures

Signature

ContractSignature:

  type: object

  properties:

    id:
      type: string

    signerName:
      type: string

    signerEmail:
      type: string

    signedAt:
      type: string
      format: date-time

    status:
      type: string

Envoyer pour signature

POST /contracts/{id}/send-signature

Consulter

GET /contracts/{id}/signatures

Relancer

POST /contracts/{id}/remind-signature

Annuler

POST /contracts/{id}/cancel-signature

Payments

Payment

Payment:

  type: object

  properties:

    id:
      type: string
      format: uuid

    paymentReference:
      type: string

    reservationId:
      type: string

    amount:
      type: number

    currencyCode:
      type: string

    status:
      $ref: '#/components/schemas/PaymentStatus'

    paidAt:
      type: string
      format: date-time

PaymentStatus

PaymentStatus:

  type: string

  enum:

    - PENDING
    - AUTHORIZED
    - PAID
    - FAILED
    - CANCELLED
    - REFUNDED

Endpoints Payments

Collection

GET /payments

POST /payments

Ressource

GET /payments/{id}

PATCH /payments/{id}

Réservation

GET /reservations/{id}/payments

Paiement CB

Créer session

POST /payments/checkout-session

Request

CheckoutSessionRequest:

  type: object

  properties:

    reservationId:
      type: string

    amount:
      type: number

Réponse

CheckoutSessionResponse:

  type: object

  properties:

    sessionId:
      type: string

    checkoutUrl:
      type: string

Webhooks

Stripe

POST /payments/webhooks/stripe

PayPal

POST /payments/webhooks/paypal

Transactions

Historique

GET /payments/{id}/transactions

Refunds

Refund

Refund:

  type: object

  properties:

    id:
      type: string

    amount:
      type: number

    refundedAt:
      type: string
      format: date-time

    reason:
      type: string

Endpoints

GET /refunds

POST /refunds

GET /refunds/{id}

Rembourser

POST /payments/{id}/refund

Invoices

Invoice

Invoice:

  type: object

  properties:

    id:
      type: string

    invoiceNumber:
      type: string

    amountExclTax:
      type: number

    taxAmount:
      type: number

    amountInclTax:
      type: number

    status:
      $ref: '#/components/schemas/InvoiceStatus'

    issueDate:
      type: string
      format: date

InvoiceStatus

InvoiceStatus:

  type: string

  enum:

    - DRAFT
    - ISSUED
    - PAID
    - PARTIALLY_PAID
    - CANCELLED

Endpoints Invoices

Collection

GET    /invoices

POST   /invoices

Ressource

GET    /invoices/{id}

PATCH  /invoices/{id}

Réservation

GET /reservations/{id}/invoices

PDF

GET /invoices/{id}/pdf

Envoi

POST /invoices/{id}/send

Accounting

AccountingEntry

AccountingEntry:

  type: object

  properties:

    id:
      type: string

    entryDate:
      type: string
      format: date

    accountCode:
      type: string

    label:
      type: string

    debit:
      type: number

    credit:
      type: number

Endpoints

GET /accounting/entries

GET /accounting/entries/{id}

Export

GET /accounting/export

Paramètres

from

to

format

Formats

CSV

XLSX

FEC

Workflow Métier

Contrat

Reservation

↓

Generate Contract

↓

Send Signature

↓

Signed

Paiement

Reservation

↓

Checkout Session

↓

Payment

↓

Invoice

Remboursement

Payment

↓

Refund

↓

Accounting Entry

Permissions RBAC

Contrats

contracts.read

contracts.create

contracts.update

contracts.send

contracts.sign

Paiements

payments.read

payments.create

payments.refund

Facturation

invoices.read

invoices.create

invoices.send

Volume API

Cette phase ajoute : 

≈ 65 endpoints

≈ 22 schémas

≈ 7 tags Swagger

Cumul OpenAPI

Après Phase 3-A.4 : 

≈ 185 endpoints

≈ 70 schémas

≈ 29 tags

Étape suivante

Phase 3-A.5

OpenAPI CRM & Relation Client 

Leads

Lead Sources

Pipelines

Pipeline Stages

Opportunities

Activities

Tasks

Tags

Segments

Cette phase couvrira : 

Sprint 8

CRM & Relation Client

et ajoutera environ : 

70 endpoints supplémentaires
ujusum/3-codage/1-repository/3-spec-open-api.1780870955.txt.gz · Dernière modification : 2026/06/08 00:22 de admin
DokuWiki Appliance - Powered by TurnKey Linux