API Propuls — Documentation développeurs

1. Accès par plan

👑 BUSINESS — Lecture seule

• GET prospects, offres, devis/factures, stats
• 100 requêtes/heure
• Toute requête POST / PATCH / DELETE renvoie 403

💎 PLATINUM — Lecture + Écriture

• Tout Business + création / modification / suppression
• Prospects, offres, devis/factures, IA, rendez-vous
• 500 requêtes/heure

2. Authentification

Toutes les requêtes incluent un Bearer token dans le header Authorization.

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

Génère ta clé depuis Paramètres → Clés API.

3. Endpoints

GET/prospectsBusiness + Platinum

Liste des prospects (filtres : status, country, limit, offset).

Exemple cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}Business + Platinum

Détail d'un prospect.

Exemple cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposalsBusiness + Platinum

Offres commerciales d'un prospect.

Exemple cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documentsBusiness + Platinum

Liste devis/factures (filtres : type, status).

Exemple cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/statsBusiness + Platinum

Statistiques (period=month|quarter|year).

Exemple cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

POST/prospectsPlatinum uniquement

Créer un prospect. Réservé au plan Platinum.

Body

{ "name": "Jane Doe", "company": "Acme", "email": "jane@acme.io", "budget": 5000, "currency": "EUR" }

Exemple cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","company":"Acme"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

PATCH/prospects/{id}Platinum uniquement

Mettre à jour un prospect. Réservé au plan Platinum.

Body

{ "status": "won", "budget": 8000 }

Exemple cURL

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"won"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

DELETE/prospects/{id}Platinum uniquement

Supprimer un prospect. Réservé au plan Platinum.

Exemple cURL

curl -X DELETE -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

POST/prospects/{id}/proposalsPlatinum uniquement

Créer une offre. Réservé au plan Platinum.

Body

{ "title": "Refonte site", "amount": 3500, "currency": "EUR" }

Exemple cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"title":"Refonte"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

PATCH/proposals/{id}Platinum uniquement

Mettre à jour une offre. Réservé au plan Platinum.

Body

{ "status": "sent" }

Exemple cURL

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"sent"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/proposals/ID

POST/prospects/{id}/documentsPlatinum uniquement

Créer un devis ou une facture. Réservé au plan Platinum.

Body

{ "type": "invoice", "amount": 2500, "currency": "EUR" }

Exemple cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"type":"invoice","amount":2500}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/documents

POST/emails/generatePlatinum uniquement

Générer un email IA personnalisé. Réservé au plan Platinum.

Body

{ "prospect_id": "...", "template": "first_contact" }

Exemple cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/emails/generate

POST/whatsapp/generatePlatinum uniquement

Générer un message WhatsApp IA. Réservé au plan Platinum.

Body

{ "prospect_id": "...", "template": "relance douce" }

Exemple cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/whatsapp/generate

4. Exemples cURL par plan

Choisis la section qui correspond à ton plan. Les requêtes d'écriture depuis une clé Business renvoient un 403 plan_forbidden_write.

👑 BUSINESS

Exemples Business (lecture seule)

GET/prospects

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposals

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documents

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/stats

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

💎 PLATINUM

Exemples Platinum (lecture + écriture)

GET/prospects

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposals

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documents

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/stats

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

POST/prospects

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","company":"Acme"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

PATCH/prospects/{id}

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"won"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

DELETE/prospects/{id}

curl -X DELETE -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

POST/prospects/{id}/proposals

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"title":"Refonte"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

PATCH/proposals/{id}

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"sent"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/proposals/ID

POST/prospects/{id}/documents

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"type":"invoice","amount":2500}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/documents

POST/emails/generate

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/emails/generate

POST/whatsapp/generate

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/whatsapp/generate

5. Exemples de code

Python

import requests
r = requests.get(
  "https://propulse-ton-freelance.lovable.app/api/public/v1/prospects",
  headers={"Authorization": "Bearer sk_live_xxx"}
)
print(r.json())

JavaScript

const r = await fetch(
  "https://propulse-ton-freelance.lovable.app/api/public/v1/prospects",
  { headers: { Authorization: "Bearer sk_live_xxx" } }
);
console.log(await r.json());

6. Codes d'erreur & messages actionnables

Chaque erreur renvoie un JSON structuré : { error, code, upgrade_url?, docs_url?, retry_after_seconds?, limit_per_hour? }. code — pour afficher un message traduit et proposer l'action correspondante à l'utilisateur.

HTTP	code	Signification & action recommandée
401	invalid_key	Clé API invalide ou révoquée. Régénère une clé dans Paramètres → Clés API.
403	plan_no_api_access	Le plan ne donne pas accès à l'API. Message conseillé : « Cette action nécessite un plan Business ou Platinum — passer à un plan supérieur ».
403	plan_forbidden_write	Requête d'écriture (POST/PATCH/DELETE) depuis une clé Business. Message conseillé : « Cette action nécessite le plan Platinum — upgrade ». L'URL de l'action est fournie dans `upgrade_url`.
400	—	Champ manquant ou invalide. Corrige la payload.
404	—	Ressource introuvable.
429	rate_limited	Quota horaire atteint (100/h Business · 500/h Platinum). Le body inclut `retry_after_seconds` & `limit_per_hour`. Message conseillé : « Limite de requêtes atteinte, réessaie dans X minutes — voir les rate limits ». Le header HTTP `Retry-After`.
500	internal_error	Erreur serveur temporaire. Réessaie ou contacte le support.

Exemple 403 (Business POST) :

{
  "error": "This action requires the Platinum plan. Business API keys are read-only.",
  "code": "plan_forbidden_write",
  "upgrade_url": "https://propulse-ton-freelance.lovable.app/app/upgrade",
  "docs_url": "https://propulse-ton-freelance.lovable.app/docs/api"
}

Exemple 429 :

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "Rate limit exceeded (100/hour). Retry in a few minutes.",
  "code": "rate_limited",
  "retry_after_seconds": 3600,
  "limit_per_hour": 100,
  "docs_url": "https://propulse-ton-freelance.lovable.app/docs/api#rate-limits"
}

7. Limites par endpoint (rate limits détaillés)

Toutes les requêtes de la v1 partagent un même compteur horaire par compte (endpoint interne api_v1) : 100 req/h en Business, 500 req/h en Platinum. Le compteur est décrémenté par chaque requête authentifiée, quel que soit le verbe.

Méthode	Endpoints	Business (lecture seule)	Platinum
GET	/prospects, /prospects/:id, /prospects/:id/proposals, /prospects/:id/documents, /proposals/:id, /documents, /stats	✅ 100 req/h	✅ 500 req/h
POST	/prospects, /prospects/:id/proposals, /prospects/:id/documents, /emails/generate, /whatsapp/generate	❌ 403 `plan_forbidden_write`	✅ 500 req/h
PATCH	/prospects/:id, /proposals/:id	❌ 403 `plan_forbidden_write`	✅ 500 req/h
DELETE	/prospects/:id	❌ 403 `plan_forbidden_write`	✅ 500 req/h

Exemple 429 — dépassement en lecture (GET) :

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "Rate limit exceeded (100/hour). Retry in a few minutes.",
  "code": "rate_limited",
  "retry_after_seconds": 3600,
  "limit_per_hour": 100,
  "docs_url": ".../docs/api#rate-limits"
}

Exemple 403 — écriture depuis une clé Business :

HTTP/1.1 403 Forbidden

{
  "error": "This action requires the Platinum plan. Business API keys are read-only.",
  "code": "plan_forbidden_write",
  "upgrade_url": ".../app/upgrade",
  "docs_url": ".../docs/api"
}

Bonnes pratiques :

Respecte l'en-tête Retry-After plutôt que de retenter immédiatement.
Applique un backoff exponentiel (2s → 4s → 8s → …) sur les erreurs 429 et 500.
Batche les lectures : préfère un GET /prospects?limit=100 à 100 GET /prospects/:id.
Cache côté client les réponses GET /stats.