wevads-gpu/WEVADS_V2_BACKEND_API_CONTRACT.md

WEVADS IA v2 - Backend/API contract (handoff front a Claude)

Date: 2026-03-10
Scope: backend et API v2 finalises; frontend v2 a realiser cote Claude.

1) Base API

• Base URL: https://weval-consulting.com/api/v2
• Health: GET /health
• Auth: JWT Bearer token (Authorization: Bearer <token>)

2) Auth

• POST /auth/register
  • body: { "email", "password", "name", "company?" }
  • output: { status, token, user }
• POST /auth/login
  • body: { "email", "password" }
  • output: { status, token, user }
• GET /auth/me (auth)
  • output: { status, user }

3) Contacts

• GET /contacts (meta)
• GET /contacts/list?page=1&limit=25&q= (auth)
• POST /contacts (auth)
  • body: { email, first_name?, last_name?, company?, phone?, country?, tags?[] }
• PATCH /contacts/:id (auth)
• DELETE /contacts/:id (auth)

4) Templates

• GET /templates (meta)
• GET /templates/list (auth)
• POST /templates (auth)
  • body: { name, category?, html?, text? }
• PATCH /templates/:id (auth)
• DELETE /templates/:id (auth)

5) Campaigns

• GET /campaigns (meta)
• GET /campaigns/list?page=1&limit=20&q= (auth)
• POST /campaigns (auth)
  • body: { name, subject, content_html?, audience_size? }
• GET /campaigns/:id (auth)
• PATCH /campaigns/:id (auth)
• POST /campaigns/:id/schedule (auth)
  • body: { scheduled_at }
• POST /campaigns/:id/send-simulate (auth)

6) Analytics

• GET /analytics (meta)
• GET /analytics/overview (auth)
• GET /analytics/deliverability (auth)

7) AI endpoints

AI module

• GET /ai (meta)
• POST /ai/subject-optimizer
• POST /ai/content-generator
• POST /ai/send-time

Brain bridge

• GET /brain/status
• GET /brain/configs
  • fallback Sentinel actif si BrainEngine/getConfigs retourne controller-not-found
• POST /brain/ai/subject-optimizer
• POST /brain/ai/content-generator
• POST /brain/ai/send-time
• GET /brain/pmta/status

8) Etat de validation

Valide en live (smoke E2E):

• health/meta endpoints: OK
• register/login + bearer auth: OK
• CRUD contacts/templates/campaigns: OK
• analytics overview: OK
• AI + brain AI endpoints: OK
• non-regression globale apres deploiement: PASS (reports/nonreg_20260310_012904.md)

9) Travail restant (front a Claude)

1. Construire UI v2 (auth, dashboard, contacts, campaigns, templates, analytics)
2. Brancher formulaires et tables sur les endpoints ci-dessus
3. Gestion token front (login/register/logout + refresh UX)
4. Ecrans d'erreur/loading v2 et validations formulaire