BCard - Documentation technique

Désérialise le corps JSON directement en entité Contact, puis applique deux contrôles d'unicité limités au carnet de l'utilisateur courant : un contact portant le même email, puis un contact portant le même téléphone. Les deux contrôles ne sont effectués que si la valeur correspondante est renseignée. Le contact est ensuite rattaché à l'utilisateur authentifié, validé, puis persisté.

Route : /api/contacts (POST), nom api_contacts_create.

Corps attendu : objet JSON dont les propriétés correspondent aux champs de l'entité Contact, par exemple {"firstname": "string", "lastname": "string", "email": "string — contrôlé en unicité", "phone": "string — contrôlé en unicité", "company": "string", "jobTitle": "string", "note": "string"}. Toutes les clés sont optionnelles côté désérialisation ; les obligations réelles proviennent des contraintes de validation de l'entité.

Réponses : 201 contact créé, 400 corps JSON invalide ({"error": "Invalid JSON data"}), 400 violations de contraintes ({"errors": {propriété: message}}), 409 email déjà présent dans le carnet, 409 téléphone déjà présent, 401 appelant non authentifié.

La carte est d'abord recherchée par son publicHash. En cas d'échec, un repli historique tente une recherche par identifiant numérique, uniquement si la valeur est numérique et fait moins de 20 caractères — précaution destinée à éviter qu'un hash entièrement numérique ne soit interprété comme un identifiant. Un contrôle d'unicité sur l'email est ensuite appliqué au carnet de l'appelant. Le contact créé reprend nom, prénom, email, entreprise et fonction de la carte ; le téléphone retenu est le premier numéro visible, avec repli sur le numéro principal. Le contact est marqué isBCard = true et reçoit une note mentionnant l'identifiant de la BCard d'origine. Aucune validation explicite n'est exécutée avant la persistance.

Route : /api/contacts/from-bcard/{hash} (POST), nom api_contacts_create_from_bcard.

Corps attendu : aucun ; la source est identifiée par le segment {hash}.

Réponses : 201 contact créé, 404 business card introuvable par hash ou par identifiant, 409 contact déjà présent avec le même email, 401 appelant non authentifié.

Après contrôle de propriété, l'entité est retirée définitivement de la base (suppression physique, sans archivage ni corbeille). Aucun corps n'est renvoyé.

Route : /api/contacts/{id} (DELETE), nom api_contacts_delete.

Réponses : 204 contact supprimé (corps vide), 404 contact inexistant, appartenant à autrui, ou appelant non authentifié.

Délègue la pagination et le filtrage textuel au dépôt via findByUserWithSearch(), puis recompte le total avec countByUser() en appliquant le même terme de recherche afin que la pagination reste cohérente. Les paramètres page et limit sont lus comme entiers sans borne haute ; la sérialisation utilise le groupe contact:read.

Route : /api/contacts (GET), nom api_contacts_list.

Paramètres de requête : page (optionnel, défaut 1), limit (optionnel, défaut 20), search (optionnel, défaut chaîne vide).

Réponses : 200 liste renvoyée, 401 aucun utilisateur authentifié ({"error": "Authentication required"}).

Reçoit une photo en multipart/form-data, vérifie qu'elle est présente, valide et non vide, puis la soumet à AIAnalysisService::analyzeBusinessCard() avant d'extraire les champs structurés via extractContactData(). Si l'email extrait correspond à un contact déjà présent dans le carnet, l'opération est interrompue et l'identifiant du contact existant est renvoyé. Sinon un contact est créé avec les données extraites, chaque champ manquant étant remplacé par la chaîne « Non spécifié » (y compris email et téléphone), activitySector et country étant systématiquement forcés à cette même valeur. Les informations d'adresse, de ville, de code postal, de pays et de site web sont concaténées dans la note. La photo est enfin stockée dans contact_photo_directory et rattachée au contact. Toute exception est convertie en réponse 400 ; le message est spécialisé lorsque l'erreur mentionne un problème de JSON valide (photo jugée trop peu nette).

Route : /api/contacts/scan/paper (POST), nom api_contacts_scan_paper.

Corps attendu (multipart/form-data) : {"photo": "file — image de la carte de visite (obligatoire)"}

Réponses : 200 carte analysée et contact créé ({success: true, message, contact}), 400 photo absente, 400 contact déjà existant pour l'email extrait ({success: false, message, existing_contact_id}), 400 photo invalide ou vide, analyse IA en échec ou upload en erreur ({success: false, message, error}), 401 appelant non authentifié.

Recherche rapide restreinte au carnet de l'utilisateur authentifié, déléguée à ContactRepository::searchByUser(). Le terme q est obligatoire : une chaîne vide ou absente est rejetée. Le paramètre limit, non documenté dans l'attribut OpenApi, borne le nombre de résultats (défaut 10). La réponse encapsule les résultats sous la clé contacts, alors que le schéma OpenApi déclare un tableau de premier niveau.

Attention : la route /{id} étant déclarée avant celle-ci, ce point d'entrée peut être court-circuité par ContactApiController::show() lors du routage.

Route : /api/contacts/search (GET), nom api_contacts_search.

Paramètres de requête : q (obligatoire, terme recherché), limit (optionnel, défaut 10).

Réponses : 200 résultats renvoyés, 400 terme de recherche manquant ou vide, 401 appelant non authentifié.

Le contact est résolu automatiquement par le ParamConverter à partir du segment {id} (un identifiant inconnu provoque donc une 404 émise par Symfony avant l'exécution de la méthode). Le contrôle de propriété qui suit renvoie également une 404 — et non une 403 — lorsque le contact appartient à un autre utilisateur ou que l'appelant n'est pas authentifié, afin de ne pas révéler son existence.

Route : /api/contacts/{id} (GET), nom api_contacts_show.

Réponses : 200 contact renvoyé, 404 contact inexistant, appartenant à autrui, ou appelant non authentifié.

Après contrôle de propriété, le corps JSON est désérialisé par-dessus l'entité existante (object_to_populate) : seules les clés présentes sont écrasées, la requête se comporte donc comme une mise à jour partielle malgré le verbe PUT. Aucun contrôle d'unicité sur l'email ou le téléphone n'est effectué ici, contrairement à ContactApiController::create(). La date de mise à jour est repositionnée à l'instant courant avant validation et flush().

Route : /api/contacts/{id} (PUT), nom api_contacts_update.

Corps attendu : objet JSON partiel reprenant les champs de l'entité Contact (firstname, lastname, email, phone, company, jobTitle, note, …).

Réponses : 200 contact mis à jour, 400 corps JSON invalide ({"error": "Invalid JSON data"}), 400 violations de contraintes ({"errors": {propriété: message}}), 404 contact inexistant, appartenant à autrui, ou appelant non authentifié.