API REST

L'API JSON de BCard est exposée sous le préfixe /api. Elle est authentifiée par jeton JWT et documentée de façon interactive par Nelmio.

• Swagger UI : /api/docs
• Spécification OpenAPI : /api/doc.json

Ce document donne la vue d'ensemble ; la référence détaillée de chaque endpoint (corps attendu, codes de statut) se trouve dans les docblocks des contrôleurs src/Controller/api/ et dans le rendu phpDocumentor.

---

Authentification

Obtenir un jeton

POST /api/auth/login
Content-Type: application/json

{
  "email": "utilisateur@example.com",
  "password": "•••••••"
}

La réponse contient un jeton d'accès JWT et un refresh token.

Un second point d'entrée, /api/login_check, est géré directement par le pare-feu login en mode stateless (json_login de LexikJWTAuthenticationBundle).

Utiliser le jeton

Toutes les routes protégées attendent l'en-tête :

Authorization: Bearer <token>

Rafraîchir et révoquer

Route	Méthode	Rôle
/api/auth/token/refresh	POST	Émet un nouveau jeton d'accès à partir d'un refresh token
/api/auth/token/revoke	POST	Révoque un refresh token

---

Contrôle d'accès

Les règles déclarées dans config/packages/security.yaml s'appliquent dans l'ordre, la première correspondance l'emportant :

Chemin	Accès
/api/auth/change-password, /api/auth/me	Authentifié
/api/auth/* (autres)	Public
/api/docs	Public
/api/cards (GET)	Public
/api/business-cards/public (GET)	Public
/api/admin/*	ROLE_ADMIN
/api/* (reste)	Authentifié

Certaines méthodes appliquent en plus un contrôle de rôle ou de propriété dans leur corps (ROLE_ADMIN, ROLE_MANAGER, ROLE_EMPLOYEE, appartenance de la ressource à l'utilisateur).

---

Catalogue des endpoints

Authentification — AuthApiController

Méthode	Route	Description
POST	/api/auth/register	Inscription
POST	/api/auth/login	Connexion, émission du JWT
POST	/api/auth/logout	Déconnexion
GET	/api/auth/me	Profil du porteur du jeton
POST	/api/auth/change-password	Changement de mot de passe
POST	/api/auth/forgot-password	Demande de réinitialisation
POST	/api/auth/verify-email	Vérification de l'adresse e-mail
POST	/api/auth/resend-verification-code	Renvoi du code de vérification
POST	/api/auth/token/refresh	Rafraîchissement du jeton
POST	/api/auth/token/revoke	Révocation du refresh token

Cartes de visite numériques — BusinessCardApiController

Méthode	Route	Description
GET	/api/business-cards	Liste des cartes de l'utilisateur
POST	/api/business-cards	Création
GET	/api/business-cards/{id}	Détail
PUT / POST	/api/business-cards/{id}	Mise à jour
DELETE	/api/business-cards/{id}	Suppression
GET	/api/business-cards/public/{hash}	Public — carte publiée par son hash
GET	/api/business-cards/network/search	Recherche dans le réseau
POST	/api/business-cards/{id}/publish	Publication
POST	/api/business-cards/{id}/draft	Retour au brouillon
POST	/api/business-cards/{id}/disable	Désactivation
POST	/api/business-cards/{id}/mark-email-sent	Marque la carte comme envoyée par e-mail
POST	/api/business-cards/{id}/custom-logo	Téléversement d'un logo personnalisé

Catalogue de cartes — CardApiController

Méthode	Route	Description
GET	/api/cards	Public — liste des produits
GET	/api/cards/types	Public — types de cartes
GET	/api/cards/{id}	Public — détail d'un produit

Contacts — ContactApiController

Méthode	Route	Description
GET	/api/contacts	Liste
POST	/api/contacts	Création
GET	/api/contacts/search	Recherche
GET	/api/contacts/{id}	Détail
PUT	/api/contacts/{id}	Mise à jour
DELETE	/api/contacts/{id}	Suppression
POST	/api/contacts/from-bcard/{hash}	Import depuis une carte BCard
POST	/api/contacts/scan/paper	Scan d'une carte papier (analyse IA)

Cartes physiques — PhysicalCardApiController

Méthode	Route	Description
GET	/api/physical-cards/products	Produits disponibles
GET	/api/physical-cards/models	Modèles de carte
GET	/api/physical-cards/eligibility/free-card	Éligibilité à une carte offerte
POST	/api/physical-cards/create-order	Création d'une commande
GET	/api/physical-cards/orders	Commandes de l'utilisateur
GET	/api/physical-cards/{id}	Détail d'une carte
PATCH	/api/physical-cards/{id}/status	Changement de statut
POST	/api/physical-cards/{id}/create-payment-intent	Création d'une intention Stripe
POST	/api/physical-cards/{id}/confirm-payment	Confirmation du paiement

Commandes — OrderApiController

Méthode	Route	Description
GET	/api/orders	Liste
POST	/api/orders	Création
GET	/api/orders/{id}	Détail
POST	/api/orders/{id}/cancel	Annulation

Paiements — PaymentApiController

Méthode	Route	Description
GET	/api/payments	Liste
GET	/api/payments/stats	Statistiques
GET	/api/payments/{id}	Détail

Abonnements — SubscriptionApiController

Méthode	Route	Description
GET	/api/subscription/plans	Offres disponibles
GET	/api/subscription/current	Abonnement en cours
POST	/api/subscription/upgrade-to-pro	Passage à l'offre Pro
POST	/api/subscription/confirm-payment	Confirmation du paiement d'abonnement

Employés — EmployeeApiController

Méthode	Route	Description
GET	/api/employees	Liste
POST	/api/employees	Création
GET	/api/employees/{id}	Détail
PUT	/api/employees/{id}	Mise à jour
DELETE	/api/employees/{id}	Suppression

Utilisateurs — UserApiController

Méthode	Route	Description
GET	/api/users/profile	Profil
POST	/api/users/profile	Mise à jour du profil
DELETE	/api/users/profile	Suppression du compte
POST	/api/users/business/activate/{id}	Activation d'un compte professionnel

Administration — AdminApiController (ROLE_ADMIN)

Méthode	Route	Description
GET	/api/admin/dashboard	Indicateurs du tableau de bord
GET	/api/admin/users	Liste des utilisateurs
POST	/api/admin/users/{id}/activate-business	Activation d'un compte entreprise
POST	/api/admin/users/{id}/deactivate-business	Désactivation
GET	/api/admin/orders	Liste des commandes
PUT	/api/admin/orders/{id}/status	Changement de statut d'une commande

---

Gestion des erreurs

App\EventSubscriber\ApiExceptionSubscriber intercepte les exceptions et les convertit en réponses JSON, afin qu'un client d'API ne reçoive jamais de page HTML d'erreur. Il s'active lorsque le chemin commence par /api ou que la requête porte un en-tête Accept: application/json.

Charge utile renvoyée :

{
  "error": {
    "message": "Message de l'exception",
    "type": "NomCourtDeLaClasseDException"
  }
}

Le code de statut reprend celui de l'exception s'il est compris entre 400 et 599 ; sinon, 500 est utilisé.

À noter : le message d'exception est renvoyé tel quel au client, y compris en production. Il convient de veiller à ce qu'aucune information sensible ne transite par ces messages.