Dose OS · API publique

Réponse · 200 OK

{
  "status": "ok",
  "name": "dose-os",
  "timestamp": "2026-04-28T09:12:34.000Z",
  "version": "abc1234"
}

version reflète VERCEL_GIT_COMMIT_SHA tronqué à 7 caractères, ou "dev" en local.

Exemple

curl https://dose-os.vercel.app/api/health

Notes

• force-dynamic · pas de cache, le timestamp est toujours frais.
• Pas d'auth · usage prévu pour des sondes anonymes.

Query parameters

Réponse · 200 OK

image/png · 1200×630 · Cache-Control: public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400.

Exemple

curl -o og.png \
  "https://dose-os.vercel.app/api/og?title=Hello&subtitle=World"

Notes

• Edge runtime · génération < 200ms en cold start.
• Charte alignée sur globals.css · gradient ink → gold.
• Une variante statique pleine page existe sur /opengraph-image.

Query parameters

Schéma CSV

id,name,email,phone,status,score,temperature,source,client_slug,created_at,last_activity_at

BOM UTF-8 en tête, séparateur virgule, CRLF en fin. last_activity_at tombe en fallback sur created_at si aucune activité.

Réponses

• 200 · text/csv; charset=utf-8 · Content-Disposition: attachment; filename="leads-YYYY-MM-DD.csv"
• 403 · { error: 'agency_only' }si l'utilisateur n'est pas membre agence
• 500 · { error: 'query_failed', details }

Exemple

# Export "hot" leads only since 2026-01-01
curl -L -b cookies.txt \
  "https://dose-os.vercel.app/api/leads/export.csv?temperature=hot&since=2026-01-01" \
  -o leads.csv

Notes

• Auth · session Supabase + appartenance agence (cf. isAgencyMember()). Pas de redirect 302 vers /login (un download d'HTML serait pire que la 403).
• Pas de pagination · cap dur à 10 000 leads. Pour des volumes plus grands, utiliser MCP list_recent_leads.
• Cache-Control: no-store.

Request · multipart/form-data

Colonnes reconnues (mapping fuzzy) · name, email, phone, source, stage, score, client_slug. Au moins email ou phonerequis. Si l'agence n'a qu'un client, client_slug est optionnel.

Réponse · 200 OK

{
  "ok": 142,
  "errors": [
    { "row": 17, "message": "email_invalid" },
    { "row": 23, "message": "missing_contact" },
    { "row": 89, "message": "unknown_client_slug" }
  ]
}

Le statut HTTP reste 200 même en cas d'échecs partiels — le client lit errors[] pour surfacer les problèmes ligne par ligne.

Codes d'erreur

• 400 · file_missing ou invalid_form
• 403 · agency_only
• 413 · file_too_large (max 5 MB)

Exemple

curl -X POST -b cookies.txt \
  -F "file=@leads.csv" \
  https://dose-os.vercel.app/api/leads/import

Notes

• Idempotence · pas de dédoublonnage automatique côté serveur. Si vous ré-importez le même CSV, vous créerez des doublons. Filtrez en amont si besoin.
• Insertion par batch de 100 lignes — un échec batch remonte sous la première ligne du batch dans errors[].
• RLS appliquée · les leads sont créés sur le client_id dérivé du client_slug.

Authorization header

Authorization: Bearer $DOSE_MCP_TOKEN

Le token est défini via la variable d'environnement DOSE_MCP_TOKEN. Si la variable est vide, l'endpoint répond 503 mcp_disabled. Comparaison constant-time (anti timing attack).

Méthodes JSON-RPC supportées

• initialize · handshake MCP
• tools/list · catalogue des 8 outils
• tools/call· exécution d'un outil avec arguments validés Zod

Les requêtes batch (array de payloads) sont supportées selon JSON-RPC 2.0 §6 — les notifications (sans id) sont silencieusement ignorées dans la réponse.

GET /api/mcp · descriptor

{
  "enabled": true,
  "transport": "json-rpc-2.0",
  "methods": ["initialize", "tools/list", "tools/call"]
}

Utile pour vérifier que l'URL est joignable depuis Claude Desktop avant de configurer le bearer.

Exemple · tools/list

curl -X POST https://dose-os.vercel.app/api/mcp \
  -H "Authorization: Bearer $DOSE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Exemple · tools/call

curl -X POST https://dose-os.vercel.app/api/mcp \
  -H "Authorization: Bearer $DOSE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_client_metrics",
      "arguments": { "client_slug": "roger-la-grenouille", "days": 30 }
    }
  }'

Erreurs

• 401 · { error: 'unauthorized' } (header absent ou token incorrect)
• 503 · { error: 'mcp_disabled' } (la variable DOSE_MCP_TOKEN n'est pas définie)
• 400 · JSON malformé · réponse JSON-RPC parse_error (-32700)
• Erreurs JSON-RPC standards · -32601 method not found, -32602 invalid params, -32603 internal error

Format de la requête

Content-Type: multipart/form-data
# Le body contient un seul field "json" avec l'event signé.
# La signature est dans event.event_hash :
#   hmac_sha256(API_KEY, event_time + event_type) === event_hash

Payload (subset lu, dans le field "json")

{
  "event": {
    "event_time": "1714402800",
    "event_type": "signature_request_all_signed",
    "event_hash": "<hmac_sha256_hex>",
    "event_metadata": { "related_signature_id": "..." }
  },
  "signature_request": {
    "signature_request_id": "abc-123",
    "is_complete": true,
    "signatures": [{
      "signer_email_address": "client@restaurant.fr",
      "status_code": "signed",
      "signed_at": 1714402800
    }],
    "metadata": { "client_id": "<uuid lead/client>", "formula_slug": "standard" }
  }
}

Events traités · signature_request_sent, signature_request_viewed, signature_request_all_signed, signature_request_declined, signature_request_canceled, signature_request_expired, callback_test.

Réponses

• 200 · body Hello API Event Received (texte exigé par Dropbox Sign — sans ça le webhook est désactivé après quelques échecs)
• 400 · { error: 'invalid_form_data' | 'missing_json_field' | 'invalid_json' | 'incomplete_event' }
• 403 · { error: 'invalid_signature' } (HMAC ne match pas)
• 503 · { error: 'not_configured' } (DROPBOX_SIGN_API_KEY vide)

Notes

• Activity contract_signed émise sur all_signed, contract_voided / contract_declined sur declined | canceled | expired.
• Audit log contract.status_updated systématique. Notification Slack + email contract_signed + email qonto_mandate en best-effort sur completion.
• Idempotence · le serveur merge l'objet brand_context.contract sans écraser signed_at / voided_at existants. La clé DB envelope_id contient le signature_request_id Dropbox Sign (ex-DocuSign envelope GUID).

GET · handshake Meta

GET /api/webhooks/whatsapp
  ?hub.mode=subscribe
  &hub.verify_token=$WHATSAPP_VERIFY_TOKEN
  &hub.challenge=<random>

Retourne le challenge en clair (200 text/plain) si le verify_token matche · sinon 403 forbidden.

POST · payload Meta (subset lu)

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "33612345678",
          "type": "text",
          "text": { "body": "OK" }
        }]
      }
    }]
  }]
}

Détection d'intention

• approve · /^(ok|oui|approve|approuv|go|yes)\b/i
• deny · /^(stop|non|no|refuse|skip)\b/i
• sinon · unknown → message d'aide envoyé au sender.

Réponse

Toujours 200 { ok: true } pour éviter les retries Meta. Les échecs internes sont loggés via audit_logs / console.error.

Notes

• Le numéro from est matché contre clients.whatsapp_number (avec / sans préfixe « + »). Si aucun client ne matche, le message est ignoré silencieusement.
• Sur approve, exécuteexecuteOptimizerAction() et pose une activity approval_granted. Sur deny, activity approval_denied.
• Idempotence · seule la dernière approval_requested non résolue est ciblée. Le payload est marqué resolved_at après décision.
• Pas de signature HMAC explicite en POST · Meta s'appuie sur le verify_token + canal dédié. Ne pas exposer cet endpoint sans un WHATSAPP_VERIFY_TOKEN configuré.

GET · handshake Meta

GET /api/webhooks/meta-leads
  ?hub.mode=subscribe
  &hub.verify_token=$META_LEAD_VERIFY_TOKEN
  &hub.challenge=<random>

Retourne le challenge en clair (200 text/plain) si le verify_token matche · sinon 403 forbidden.

POST · headers attendus

Content-Type: application/json
x-hub-signature-256: sha256=<hex(HMAC_SHA256(rawBody, $META_APP_SECRET))>

POST · payload Meta (subset lu)

{
  "object": "page",
  "entry": [{
    "id": "<page_id>",
    "time": 1735320000,
    "changes": [{
      "field": "leadgen",
      "value": {
        "leadgen_id": "987654321",
        "page_id": "1122334455",
        "form_id": "5566778899",
        "ad_id": "120211000000000000",
        "created_time": 1735320000
      }
    }]
  }]
}

Le webhook ne contient que les IDs · le détail (nom, email, téléphone) est récupéré via GET /v23.0/{leadgen_id}?fields=field_data en utilisant le PAGE_ACCESS_TOKEN stocké dans brand_context.meta_page_access_token (fallback META_ACCESS_TOKEN).

Configuration Meta

• Meta Business → App → Webhooks → Page → leadgen.
• Callback URL · https://agence.dosedefrance.com/api/webhooks/meta-leads.
• Verify token · $META_LEAD_VERIFY_TOKEN (Vercel env, identique des deux côtés).
• L'abonnement par page est posé automatiquement par /api/portal/onboarding/meta-callback via POST /v23.0/{page_id}/subscribed_apps.

Réponse

Toujours 200 { ok: true, processed: [...] } sauf signature invalide → 401. Les erreurs (page inconnue, fetch leadgen KO) sont loggées via Sentry breadcrumbs sans bloquer le 200 final (Meta retry sinon).

Notes

• Le matching client se fait sur clients.meta_page_id = page_id du payload.
• Les leads sont stockés avec source='META_LEAD_AD' et le payload Meta complet dans raw_payload (JSONB).
• Inngest event lead.createdémis → l'agent lead_concierge reprend en relais (notification, scoring, follow-up).
• Si le fetch leadgen échoue (token expiré, lead supprimé), on persiste tout de même un stub lead avec fetch_error dans raw_payload — pas de signal perdu.

Query parameters

Réponses

• 200 · { ok: true, to, sent_at }
• 400 · missing_to (ni query, ni env)
• 401 · unauthorized
• 403 · agency_only
• 503 · whatsapp_not_configured
• 502 · { ok: false, to, error } (la Graph API a refusé)

Exemple

curl -L -b cookies.txt \
  "https://dose-os.vercel.app/api/test/whatsapp/send?to=33612345678"

Notes

• Coût · ~0,005 à 0,05 €/message selon la zone (Meta Cloud tarif business). Usage debug exclusif — pas exposé en public.
• Le message envoyé contient un timestamp ISO pour faciliter le matching côté inbox WhatsApp.

Query parameters

Réponse · 200

{
  "ok": true,
  "impersonate": "gaetan@dosedefrance.com",
  "calendars_count": 4,
  "calendars": [
    { "id": "primary", "summary": "Gaetan", "primary": true,
      "timeZone": "Europe/Paris", "accessRole": "owner" }
  ],
  "next_slots_count": 5,
  "next_slots": [
    { "start": "2026-04-29T08:00:00.000Z",
      "end":   "2026-04-29T09:00:00.000Z",
      "label": "Mardi 29 avril · 10h00" }
  ]
}

Erreurs

• 401 · unauthorized
• 403 · agency_only
• 503 · gcal_not_configured
• 502 · gcal_dwd_failed(Workspace admin n'a probablement pas autorisé le scope calendar pour le client_id du service account — voir admin.google.com→ Sécurité > Délégation à l'échelle du domaine).

Notes

• getNextSlots cible la fenêtre Lun-Ven 10h-18h Europe/Paris, snap demi-heure, max 1 slot/jour, durée 60 min. Aligné sur la landing /audit-gratuit.
• Cache token DwD par {impersonate} (60 min) côté server process — pas de double JWT exchange entre les deux appels parallèles.

Query parameters

Réponse · 200

Content-Type: image/png
Cache-Control: private, max-age=600

<binary PNG bytes>

Erreurs

• 400 · missing_params / invalid_assetIdx
• 403 · agency_only
• 404 · generation_expired (TTL 30 min écoulé) ou asset_not_found

Query parameters

Réponse · 200

Content-Type: application/zip
Content-Disposition: attachment; filename="dose-content-<client>-<id>.zip"

README.txt
01-meta_feed/copy.txt
01-meta_feed/image.png
02-meta_story/copy.txt
02-meta_story/image.png
…

Erreurs

• 400 · missing_genId / invalid_assetIdx
• 403 · agency_only
• 404 · generation_expired

Notes

• ZIP encodé en méthode store (compression=0) — suffisant car les PNG sont déjà compressés. Pas de dépendance npm (JSZip non installé).
• Si une image hosted DALL-E a expiré entre la génération et le download, le ZIP contient un image-error.txt à la place — la copy reste accessible.