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

Headers attendus

Content-Type: application/json
x-docusign-signature-1: <base64(HMAC_SHA256(rawBody, $DOCUSIGN_WEBHOOK_SECRET))>

Payload (subset lu)

{
  "event": "envelope-completed",
  "data": {
    "envelopeId": "abc-123",
    "envelopeSummary": {
      "status": "completed",
      "completedDateTime": "2026-04-28T09:00:00.000Z"
    }
  }
}

L'ancienne forme « flat » (envelopeId + envelopeStatus au top-level) est aussi supportée. Statuts reconnus · sent | delivered | completed | declined | voided | created.

Réponses

• 200 · { ok: true }
• 200 · { ok: false, reason: 'client_not_found' } (envelope_id inconnu — DocuSign ne retry pas sur 2xx)
• 400 · { error: 'invalid json' } ou { error: 'missing envelope_id' }
• 401 · { error: 'unauthorized' } (HMAC invalide ou absent)
• 503 · { error: 'webhook disabled' } (la variable DOCUSIGN_WEBHOOK_SECRET n'est pas configurée)

Notes

• Activity contract_signed émise sur completed, contract_voided sur declined | voided.
• Audit log contract.status_updated systématique. Notification Slack + email contract_signed best-effort sur completion.
• Idempotence · le serveur merge l'objet brand_context.contract sans écraser signed_at / voided_at existants.

Headers attendus

Content-Type: application/json
stripe-signature: t=...,v1=...,v0=...

Format standard Stripe · verifyStripeSignature() côté serveur lit le raw body avant tout parsing JSON.

Événements consommés

• checkout.session.completed · seed brand_context.stripe (customer_id + subscription_id), activity subscription_paid
• invoice.paid · last_invoice_paid_at + status: "active". Première facture → subscription_paid, suivantes → subscription_renewed
• customer.subscription.deleted · status: "canceled", activity subscription_cancelled

Tout autre event.type est silencieusement acquitté (200 ignored) pour éviter les retry storms Stripe.

Stratégie de réconciliation

Le client est résolu via (1) metadata.client_id côté Stripe (préféré, posé à la création de la session) puis (2) fallback sur customer_id stocké dans brand_context.stripe.customer_id. Si aucune correspondance · réponse 200 { ok: false, reason: 'client_not_found' } (Stripe ne retry pas sur 2xx).

Réponses

• 200 · { ok: true } ou { ok: true, ignored: '<event.type>' }
• 401 · signature invalide
• 400 · JSON malformé
• 503 · STRIPE_WEBHOOK_SECRET non défini

Notes

• Runtime Node.js obligatoire · request.text() sur le raw body pour la vérification de signature.
• Les montants sont reçus en cents et persistés en euros.
• Audit log stripe.<event.type> systématique avec event_id pour traçabilité.

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é.

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.