> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colismove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> API ColisMove — Plateforme de transport collaboratif de colis entre particuliers

# Bienvenue sur l'API ColisMove

ColisMove est une plateforme de transport collaboratif de colis entre particuliers (à la manière de BlaBlaCar, mais pour les colis). Des voyageurs disposant d'espace bagages disponible peuvent transporter les colis d'expéditeurs sur leur trajet.

## Concepts clés

<CardGroup cols={2}>
  <Card title="Annonces" icon="bullhorn">
    Les transporteurs vérifiés créent des annonces de transport en précisant leur trajet, leurs dates et leur capacité disponible.
  </Card>

  <Card title="Réservations" icon="ticket">
    Les expéditeurs réservent une place sur une annonce pour expédier leur colis. Le cycle de vie complet est piloté par une machine à états.
  </Card>

  <Card title="Paiements" icon="credit-card">
    Paiements sécurisés via Stripe Connect avec entiercement (escrow) plateforme. Le transporteur reçoit ses fonds uniquement après confirmation de la livraison.
  </Card>

  <Card title="Agences" icon="building">
    Les agences professionnelles de transport peuvent s'enregistrer, gérer leurs branches, leurs employés et traiter des envois en masse.
  </Card>
</CardGroup>

## Comment ça marche

```mermaid theme={null}
sequenceDiagram
    participant Transporteur
    participant Plateforme
    participant Expediteur

    Transporteur->>Plateforme: Crée une annonce (trajet, dates, capacité)
    Expediteur->>Plateforme: Recherche et réserve un créneau colis
    Plateforme->>Expediteur: Stripe Checkout (paiement capté en escrow)
    Transporteur->>Plateforme: Accepte la réservation
    Expediteur->>Transporteur: Dépose le colis (validation par QR code)
    Transporteur->>Expediteur: Livre le colis (validation par QR code)
    Plateforme->>Transporteur: Verse les fonds (moins 15 % de commission plateforme)
```

## URL de base

Tous les endpoints de l'API sont préfixés par :

```
https://api.colismove.com/v1/api
```

En développement local :

```
http://localhost:3091/v1/api
```

## Démarrage rapide

<Steps>
  <Step title="Inscription">
    Créez un compte utilisateur via `POST /v1/api/auth/register`
  </Step>

  <Step title="Authentification">
    Connectez-vous pour obtenir vos tokens JWT via `POST /v1/api/auth/login`
  </Step>

  <Step title="Vérification KYC">
    Vérifiez votre identité via `POST /v1/api/kyc/init` pour débloquer les fonctionnalités transporteur
  </Step>

  <Step title="Utilisez l'API">
    Parcourez les annonces, créez des réservations ou publiez vos propres annonces
  </Step>
</Steps>

## Audiences

L'API est segmentée en trois audiences distinctes selon le client appelant :

<CardGroup cols={3}>
  <Card title="Particuliers" icon="user" href="/api-reference/overview">
    Mobile + Web particuliers — expéditeurs / transporteurs
  </Card>

  <Card title="Web Agence" icon="building" href="/api-reference/overview-web-agency">
    Portail web pour agences professionnelles
  </Card>

  <Card title="Web SuperAdmin" icon="shield" href="/api-reference/overview-superadmin">
    Console d'administration plateforme
  </Card>
</CardGroup>