Save France
Backend

Documentation de l'API

Guide complet de l'API REST avec authentification JWT et endpoints

Introduction

L'API REST de Save France permet d'interagir avec les différentes ressources du système de manière sécurisée. Elle suit les principes RESTful et utilise JSON comme format d'échange.

Authentification

L'API utilise JWT (JSON Web Tokens) pour l'authentification.

Obtenir un token

POST /api/login_check
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "votre-mot-de-passe"
}

Réponse réussie (200 OK) :

{
  "token": "votre.jwt.token.ici",
  "refresh_token": "votre.refresh.token.ici"
}

Utilisation du token

Ajoutez le token dans l'en-tête Authorization :

Authorization: Bearer votre.jwt.token.ici

Endpoints principaux

Utilisateurs

Récupérer le profil utilisateur

GET /api/users/me

Mettre à jour le profil

PATCH /api/users/me
Content-Type: application/merge-patch+json

{
  "firstName": "Nouveau prénom",
  "phone": "+33123456789"
}

Demandes (Requests)

Lister les demandes

GET /api/requests?page=1&itemsPerPage=10&status[]=new&status[]=in_progress

Créer une demande

POST /api/requests
Content-Type: application/json

{
  "title": "Problème d'équipement",
  "description": "Description détaillée du problème",
  "equipment": "/api/equipments/1"
}

Récupérer une demande

GET /api/requests/123

Équipements (Equipments)

Lister les équipements

GET /api/equipments?page=1&itemsPerPage=20

Créer un équipement

POST /api/equipments
Content-Type: application/json

{
  "name": "PC Portable",
  "model": "Dell XPS 15",
  "serialNumber": "XPS123456"
}

Pagination

Les réponses de liste sont paginées. Exemple de réponse :

{
  "@context": "/api/contexts/Request",
  "@id": "/api/requests",
  "@type": "hydra:Collection",
  "hydra:totalItems": 42,
  "hydra:view": {
    "@id": "/api/requests?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/requests?page=1",
    "hydra:last": "/api/requests?page=3",
    "hydra:next": "/api/requests?page=2"
  },
  "hydra:member": [
    {
      "@id": "/api/requests/1",
      "@type": "Request",
      "id": 1,
      "title": "Problème d'équipement",
      "status": "new"
    }
  ]
}

Filtres

Filtres disponibles

  • status : Filtrer par statut (ex: ?status=new,in_progress)
  • createdAt[after] : Demandes créées après une date
  • createdAt[before] : Demandes créées avant une date
  • equipment : ID de l'équipement

Exemple de filtre

GET /api/requests?status=new&createdAt[after]=2025-01-01&equipment=1

Tri

Utilisez le paramètre order pour trier les résultats :

GET /api/requests?order[createdAt]=desc

Codes de statut HTTP

  • 200 OK : Requête réussie
  • 201 Created : Ressource créée
  • 204 No Content : Suppression réussie
  • 400 Bad Request : Données invalides
  • 401 Unauthorized : Authentification requise
  • 403 Forbidden : Droits insuffisants
  • 404 Not Found : Ressource introuvable
  • 422 Unprocessable Entity : Erreur de validation
  • 500 Internal Server Error : Erreur serveur

Gestion des erreurs

En cas d'erreur, la réponse contient un objet avec les détails :

{
  "code": 400,
  "message": "Validation Failed",
  "errors": {
    "email": "Cette valeur n'est pas une adresse email valide.",
    "password": "Ce mot de passe est trop court."
  }
}

Webhooks

Événements disponibles

  • request.created : Nouvelle demande créée
  • request.updated : Demande mise à jour
  • offer.created : Nouvelle offre créée
  • troubleshooting.updated : Dépannage mis à jour

Configuration d'un webhook

POST /api/webhooks
Content-Type: application/json

{
  "url": "https://votre-app.com/webhooks/request-created",
  "event": "request.created",
  "secret": "votre-secret-pour-signature"
}

Payload du webhook

{
  "event": "request.created",
  "data": {
    "id": 123,
    "reference": "REQ-2023-0001",
    "status": "new"
  },
  "timestamp": "2023-01-01T12:00:00+01:00",
  "signature": "hmac-sha256-signature"
}

Limites de taux

  • 60 requêtes par minute par adresse IP
  • 1000 requêtes par heure par utilisateur

Versioning

L'API est versionnée via l'URL. La version actuelle est v1.

/api/v1/requests

Dépannage

Problèmes courants

  1. Token expiré
    • Renouvelez le token avec le refresh token
  2. Accès refusé
    • Vérifiez les rôles de l'utilisateur
    • Vérifiez les permissions sur la ressource
  3. Erreur de validation
    • Vérifiez le format des données envoyées
    • Consultez la documentation des contraintes de validation

Exemple complet avec cURL

# Authentification
TOKEN=$(curl -X POST -H "Content-Type: application/json" \
  -d '{"username":"user@example.com","password":"password"}' \
  https://api.savefrance.fr/api/login_check | jq -r '.token')

# Créer une demande
curl -X POST https://api.savefrance.fr/api/requests \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Problème technique","description":"Description..."}'

Support

Pour toute question ou problème, contactez l'équipe technique à support@savefrance.fr.

Symfony Messenger

Configuration et utilisation du bus de messages asynchrones (Symfony Messenger)

Services Métiers

Services métiers et logique de l'application Symfony