Guide

Développeur

API Reference

Documentation technique de l'API REST de senDemarches. Tous les endpoints utilisent JSON et nécessitent une authentification par session JWT.

URL de base

Base URL

https://www.sendemarches.com/api

Toutes les requêtes doivent inclure le header Content-Type: application/json. L'authentification est gérée par NextAuth via cookies de session JWT.

Authentification

L'API utilise NextAuth 4 avec le provider Credentials. La connexion retourne un token JWT stocké dans un cookie httpOnly sécurisé.

POST /api/auth/callback/credentials

// Corps de la requête
{
  "email": "usager@exemple.com",    // ou numéro de téléphone
  "password": "votreMotDePasse"
}

// Réponse : cookie de session JWT (automatique)

Session JWT

Le token JWT contient : id, email, name, role. Il est automatiquement inclus dans les requêtes suivantes via le cookie. Durée de validité : 30 jours.

Procédures (Démarches)

Lister les procédures

GET /api/procedures

// Réponse 200
[
  {
    "id": "clx...",
    "title": "Demande d'acte de naissance",
    "description": "Obtenir une copie d'acte de naissance...",
    "category": "ETAT_CIVIL",
    "fee": 500,
    "estimatedDays": 3,
    "published": true,
    "createdAt": "2026-01-15T10:30:00Z",
    "_count": { "fields": 8, "dossiers": 142 }
  }
]

Détail d'une procédure

GET /api/procedures/:id

// Réponse 200
{
  "id": "clx...",
  "title": "Demande d'acte de naissance",
  "description": "...",
  "category": "ETAT_CIVIL",
  "fee": 500,
  "published": true,
  "fields": [
    {
      "id": "clx...",
      "label": "Nom complet",
      "type": "TEXT",
      "required": true,
      "order": 1
    }
  ]
}

Créer une procédure

POST /api/procedures (ADMIN)

// Corps de la requête
{
  "title": "Certificat de résidence",
  "description": "Demande de certificat de résidence...",
  "category": "ETAT_CIVIL",
  "fee": 1000
}

// Réponse 201 — Procédure créée

Dossiers

Soumettre un dossier

POST /api/dossiers (USAGER)

// Corps de la requête
{
  "procedureId": "clx...",
  "data": {
    "nom_complet": "Amadou Diallo",
    "date_naissance": "1990-05-15",
    "lieu_naissance": "Dakar",
    "motif": "Inscription universitaire"
  }
}

// Réponse 201
{
  "id": "clx...",
  "reference": "SD-2026-0042",
  "status": "SUBMITTED",
  "createdAt": "2026-03-13T14:30:00Z"
}

Lister les dossiers

GET /api/dossiers

// Paramètres optionnels
?status=SUBMITTED&procedureId=clx...&page=1&limit=20

// USAGER : retourne ses propres dossiers
// AGENT/ADMIN : retourne les dossiers de ses démarches assignées

// Réponse 200
{
  "dossiers": [...],
  "total": 42,
  "page": 1,
  "totalPages": 3
}

Détail d'un dossier

GET /api/dossiers/:id

// Réponse 200
{
  "id": "clx...",
  "reference": "SD-2026-0042",
  "status": "IN_REVIEW",
  "data": { ... },
  "procedure": { "title": "..." },
  "user": { "name": "Amadou Diallo", "email": "..." },
  "statusHistory": [
    {
      "status": "SUBMITTED",
      "comment": null,
      "createdAt": "2026-03-13T14:30:00Z",
      "user": { "name": "Amadou Diallo" }
    }
  ],
  "createdAt": "2026-03-13T14:30:00Z"
}

Changement de statut

PATCH /api/dossiers/:id/status (AGENT/ADMIN)

// Corps de la requête
{
  "status": "APPROVED",       // APPROVED, REJECTED, PENDING_INFO, IN_REVIEW
  "comment": "Dossier complet et conforme. Attestation générée."
}

// Réponse 200
{
  "id": "clx...",
  "status": "APPROVED",
  "updatedAt": "2026-03-14T09:15:00Z"
}

Statuts possibles

Statut	Code	Transitions autorisées
Déposé	SUBMITTED	IN_REVIEW
En instruction	IN_REVIEW	APPROVED, REJECTED, PENDING_INFO
En attente	PENDING_INFO	IN_REVIEW (après complément usager)
Accepté	APPROVED	COMPLETED
Refusé	REJECTED	— (terminal)
Terminé	COMPLETED	— (terminal)

Assignation d'expert

POST /api/dossiers/:id/experts (AGENT/ADMIN)

// Corps de la requête
{
  "expertId": "clx...",
  "note": "Merci de vérifier la conformité urbanistique"
}

// Réponse 200
{
  "id": "clx...",
  "expert": { "name": "Dr. Ndiaye" },
  "note": "..."
}

Documents

Récépissé de dépôt

GET /api/dossiers/:id/receipt

// Réponse : PDF (application/pdf)
// Headers: Content-Disposition: attachment; filename="recepisse-SD-2026-0042.pdf"

Attestation

GET /api/dossiers/:id/attestation

// Disponible uniquement si status = APPROVED
// Réponse : PDF (application/pdf)
// Headers: Content-Disposition: attachment; filename="attestation-SD-2026-0042.pdf"

Vérification

GET /api/attestations/:code

// Code = code de vérification à 8 caractères
// Réponse 200
{
  "valid": true,
  "type": "ATTESTATION",
  "reference": "SD-2026-0042",
  "procedure": "Demande d'acte de naissance",
  "beneficiary": "Amadou Diallo",
  "issuedAt": "2026-03-14T09:15:00Z"
}

// Réponse 404
{ "valid": false, "error": "Document non trouvé" }

Invitations

POST /api/invitations (ADMIN)

// Corps de la requête
{
  "email": "agent@exemple.com",
  "role": "AGENT"              // AGENT, EXPERT, ADMIN
}

// Réponse 201
{
  "id": "clx...",
  "email": "agent@exemple.com",
  "role": "AGENT",
  "token": "abc123...",
  "expiresAt": "2026-03-20T14:30:00Z"
}

GET /api/invitations/:token

// Valider et accepter une invitation
// Réponse 200
{
  "valid": true,
  "email": "agent@exemple.com",
  "role": "AGENT",
  "organization": "Ministère de l'Intérieur"
}

Endpoints administrateur

Notifications

POST /api/admin/notifications (ADMIN)

// Envoyer une notification manuelle
{
  "userId": "clx...",
  "channel": "EMAIL",          // EMAIL, SMS, WHATSAPP
  "template": "CUSTOM",
  "message": "Votre dossier nécessite une action..."
}

Super-admin

GET /api/super-admin/stats

// Réponse 200
{
  "users": { "total": 1250, "byRole": { "USAGER": 1200, "AGENT": 35, ... } },
  "dossiers": { "total": 3420, "byStatus": { "SUBMITTED": 120, ... } },
  "organizations": 8,
  "procedures": 24
}

Codes d'erreur

Code HTTP	Signification	Action
200	Succès	—
201	Ressource créée	—
400	Requête invalide	Vérifiez le corps de la requête
401	Non authentifié	Connectez-vous ou renouvelez votre session
403	Accès interdit	Votre rôle ne permet pas cette action
404	Ressource introuvable	Vérifiez l'identifiant
409	Conflit	La ressource existe déjà
422	Données invalides	Vérifiez les champs obligatoires et les formats
500	Erreur serveur	Contactez l'administrateur

Format d'erreur standard

{
  "error": "Description de l'erreur",
  "details": {
    "field": "email",
    "message": "Format d'e-mail invalide"
  }
}

Limites

Paramètre	Valeur
Taille max. corps de requête	10 Mo
Taille max. fichier upload	10 Mo
Formats fichier acceptés	PDF, JPG, JPEG, PNG
Pagination par défaut	20 éléments par page
Pagination maximale	100 éléments par page

PrécédentGuide Administrateur