Démarrage rapide

Documentation API TagadaOS

Connectez vos CRMs, formulaires et outils d'acquisition pour envoyer des leads directement dans TagadaOS. Démarrez en 3 étapes.

1

Créez une clé API

Dans le dashboard → section Clés API → cliquez Nouvelle clé API. Copiez la clé immédiatement — elle ne sera plus affichée.

Votre clé ressemble à ça

tgd_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

2

Envoyez un lead test

Testez l'intégration avec ce curl — remplacez YOUR_KEY par votre clé.

cURL

curl -X POST https://tagadaos-2.polsia.app/api/leads/webhook \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "leads": [{
      "email": "test@exemple.com",
      "source": "seo",
      "name": "Test Lead",
      "phone": "+33600000000",
      "quality_score": 4
    }]
  }'

3

Vérifiez dans le dashboard

Le lead apparaît immédiatement dans votre dashboard. Réponse attendue :

Réponse succès

{
  "imported": 1,
  "duplicates": 0,
  "errors": []
}

Authentification

TagadaOS utilise deux mécanismes d'authentification selon le contexte.

JWT — Accès Dashboard

Utilisé pour les endpoints /api/leads et /api/settings. Le token est obtenu via POST /api/auth/login et doit être passé dans le header Authorization: Bearer <token>.

Usage typique : Interface dashboard, scripts d'administration interne.

API Key — Intégrations externes

Utilisée pour le webhook POST /api/leads/webhook. La clé est passée dans le header X-API-Key: <votre-clé>. Format : tgd_<64 hex chars>.

Usage typique : CRM, formulaires de contact, scripts d'acquisition automatisés.

POST /api/auth/login Public

Authentifie l'utilisateur par email et retourne un JWT valable 7 jours.

Champ	Type	Requis	Description
email	string	Requis	Adresse email autorisée

JSON Body

{
  "email": "votre@email.com"
}

cURL

curl -X POST https://tagadaos-2.polsia.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "votre@email.com"}'

KEY X-API-Key: tgd_... API Key

Les clés API s'utilisent uniquement sur le webhook d'ingestion. Créez-en une depuis le dashboard → Clés API → Nouvelle clé API.

⚠️ Important : La clé n'est affichée qu'une seule fois à la création. Copiez-la immédiatement.

Header requis

X-API-Key: tgd_a3f8b2c1d4e5f6a7...

Propriété	Valeur
Format	`tgd_<64 caractères hex>`
Rate limit	100 requêtes/minute par clé
Stockage	Hash SHA-256 (plaintext jamais persisté)
Révocation	Soft delete via `DELETE /api/settings/api-keys/:id`

401 — Clé manquante ou invalide

{
  "error": "API key required"
}

429 — Rate limit dépassé

{
  "error": "Rate limit exceeded"
}

Leads

Leads API

CRUD complet sur les leads. Tous ces endpoints requièrent un JWT dans le header Authorization.

GET /api/leads JWT

Retourne la liste paginée des leads avec filtres, recherche plein texte et tri.

Paramètre	Type	Défaut	Description
q	string	—	Recherche plein texte (name, email, phone)
source	string	—	Filtrer par source : `seo`, `coreg`, `sma`
status	string	—	`nouveau`, `en_attente`, `contacte`, `qualifie`, `converti`, `rejete`
quality_min	integer	—	Score qualité minimum (1–10)
quality_max	integer	—	Score qualité maximum (1–10)
date_from	date	—	Date début ISO 8601 : `2025-01-01`
date_to	date	—	Date fin ISO 8601
sort	string	created_at	Colonne de tri : `created_at`, `quality_score`, `name`, `email`
order	string	desc	`asc` ou `desc`
page	integer	1	Numéro de page
limit	integer	20	Résultats par page (max 100)

200 OK

{
  "leads": [
    {
      "id": 1,
      "email": "jean.dupont@exemple.com",
      "name": "Jean Dupont",
      "phone": "+33612345678",
      "source": "seo",
      "quality_score": 7,
      "conversion_status": "contacte",
      "notes": null,
      "created_at": "2025-03-15T10:23:00.000Z",
      "status_updated_at": "2025-03-16T08:00:00.000Z"
    }
  ],
  "total": 500,
  "page": 1,
  "limit": 20,
  "pages": 25
}

cURL — recherche avec filtres

curl -G https://tagadaos-2.polsia.app/api/leads \
  -H "Authorization: Bearer YOUR_JWT" \
  --data-urlencode "q=dupont" \
  -d "source=seo&status=contacte&page=1&limit=20"

GET /api/leads/:id JWT

Retourne le détail complet d'un lead, incluant l'historique de statut.

200 OK

{
  "id": 42,
  "email": "jean.dupont@exemple.com",
  "name": "Jean Dupont",
  "phone": "+33612345678",
  "source": "seo",
  "quality_score": 7,
  "conversion_status": "contacte",
  "notes": "Rappeler jeudi matin",
  "created_at": "2025-03-15T10:23:00.000Z",
  "status_updated_at": "2025-03-16T08:00:00.000Z",
  "history": [
    {
      "old_status": "nouveau",
      "new_status": "contacte",
      "changed_at": "2025-03-16T08:00:00.000Z"
    }
  ]
}

cURL

curl https://tagadaos-2.polsia.app/api/leads/42 \
  -H "Authorization: Bearer YOUR_JWT"

PATCH /api/leads/:id JWT

Met à jour le statut et/ou les notes d'un lead. Loggue automatiquement dans lead_status_history.

Champ	Type	Requis	Valeurs acceptées
conversion_status	string	Optionnel	`nouveau`, `en_attente`, `contacte`, `qualifie`, `converti`, `rejete`
notes	string	Optionnel	Texte libre (max 2000 caractères)

JSON Body

{
  "conversion_status": "qualifie",
  "notes": "Très intéressé, budget confirmé"
}

200 OK

{
  "id": 42,
  "conversion_status": "qualifie",
  "notes": "Très intéressé, budget confirmé",
  "status_updated_at": "2025-04-20T14:30:00.000Z"
}

cURL

curl -X PATCH https://tagadaos-2.polsia.app/api/leads/42 \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"conversion_status": "qualifie", "notes": "Budget confirmé"}'

PATCH /api/leads/bulk JWT

Met à jour le statut ou supprime plusieurs leads en une seule requête. Opération transactionnelle (tout ou rien). Max 500 leads/requête.

Champ	Type	Requis	Description
ids	integer[]	Requis	IDs des leads à modifier (max 500)
action	string	Requis	`update_status` ou `delete`
conversion_status	string	Si action=update_status	Nouveau statut

JSON Body — mise à jour statut

{
  "ids": [10, 11, 12],
  "action": "update_status",
  "conversion_status": "contacte"
}

200 OK

{
  "updated": 3
}

cURL

curl -X PATCH https://tagadaos-2.polsia.app/api/leads/bulk \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"ids":[10,11,12],"action":"update_status","conversion_status":"contacte"}'

Import / Export

Import & Export CSV

POST /api/leads/import JWT

Importe des leads depuis un fichier CSV. Déduplique automatiquement par email (upsert). Détection automatique des colonnes (noms français et anglais acceptés).

Colonnes détectées automatiquement — noms insensibles à la casse, séparateur virgule ou point-virgule.

Colonne CSV	Alias acceptés	Requis	Type
email	`email`, `e-mail`, `courriel`	Requis	string (unique)
name	`name`, `nom`, `prénom`, `full_name`	Optionnel	string
phone	`phone`, `téléphone`, `tel`	Optionnel	string
source	`source`, `canal`	Optionnel	`seo` / `coreg` / `sma`
quality_score	`quality_score`, `score`, `qualité`	Optionnel	integer 1–10
conversion_status	`conversion_status`, `statut`, `status`	Optionnel	voir statuts valides

Exemple CSV

email,name,phone,source,quality_score
jean.dupont@exemple.com,Jean Dupont,+33612345678,seo,7
marie.martin@exemple.com,Marie Martin,,coreg,5

Limite	Valeur
Lignes max	10 000 lignes par fichier
Taille fichier max	~15 MB
Encodage	UTF-8 recommandé
Séparateur	Virgule `,` ou point-virgule `;`
Déduplification	Par email — upsert (mise à jour si existant)
Content-Type	`multipart/form-data`, champ : `file`

200 OK

{
  "imported": 487,
  "duplicates": 13,
  "errors": [
    { "row": 24, "reason": "Email invalide" }
  ]
}

cURL

curl -X POST https://tagadaos-2.polsia.app/api/leads/import \
  -H "Authorization: Bearer YOUR_JWT" \
  -F "file=@leads.csv"

GET /api/leads/export JWT

Exporte les leads filtrés en CSV (RFC 4180). Accepte les mêmes filtres que GET /api/leads plus une sélection par IDs. Fichier nommé leads_export_YYYY-MM-DD.csv.

Paramètre	Type	Description
ids	string	Export sélectif : `?ids=1,2,3`
source	string	Filtrer par source
status	string	Filtrer par statut
q	string	Recherche plein texte
date_from / date_to	date	Plage de dates
Limite : 50 000 lignes · Content-Type : `text/csv`

cURL — export filtré

curl -G https://tagadaos-2.polsia.app/api/leads/export \
  -H "Authorization: Bearer YOUR_JWT" \
  -d "source=seo&status=converti" \
  -o leads_export.csv

cURL — export par sélection d'IDs

curl https://tagadaos-2.polsia.app/api/leads/export?ids=1,2,3,4 \
  -H "Authorization: Bearer YOUR_JWT" \
  -o selection.csv

Webhook

Webhook d'ingestion

Point d'entrée principal pour l'intégration externe. Envoyez des lots de leads depuis n'importe quel CRM, formulaire ou script.

POST /api/leads/webhook API Key

Ingère un lot de leads en une seule requête. Déduplique par email (upsert). Retourne le bilan importé/doublons/erreurs.

Champ	Type	Requis	Description
leads	array	Requis	Tableau de leads (max 500)
leads[].email	string	Requis	Adresse email (clé de déduplification)
leads[].source	string	Optionnel	`seo`, `coreg`, `sma`
leads[].name	string	Optionnel	Nom complet du lead
leads[].phone	string	Optionnel	Numéro de téléphone
leads[].quality_score	integer	Optionnel	Score 1–10

JSON Body

{
  "leads": [
    {
      "email": "alice@exemple.com",
      "source": "seo",
      "name": "Alice Martin",
      "phone": "+33611223344",
      "quality_score": 8
    },
    {
      "email": "bob@exemple.com",
      "source": "coreg"
    }
  ]
}

200 OK

{
  "imported": 2,
  "duplicates": 0,
  "errors": []
}

200 OK — avec doublon et erreur

{
  "imported": 1,
  "duplicates": 1,
  "errors": [
    { "index": 2, "reason": "email manquant" }
  ]
}

Code HTTP	Cause	Réponse
`401`	X-API-Key manquante ou invalide	`{"error": "API key required"}`
`429`	Rate limit dépassé (100 req/min)	`{"error": "Rate limit exceeded"}`
`400`	Payload invalide ou tableau vide	`{"error": "Invalid payload"}`
`413`	Batch > 500 leads	`{"error": "Batch too large"}`

Limite	Valeur
Leads par requête	500 max
Rate limit	100 requêtes/minute par clé API
Content-Type	`application/json`
Déduplification	Par email (upsert — pas de doublon)
Erreurs partielles	Les leads valides sont importés même si certains échouent

cURL — batch simple

curl -X POST https://tagadaos-2.polsia.app/api/leads/webhook \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "leads": [
      {"email":"alice@exemple.com","source":"seo","name":"Alice","quality_score":8},
      {"email":"bob@exemple.com","source":"coreg","phone":"+33600000000"}
    ]
  }'

Python — intégration CRM

# Exemple d'intégration depuis un CRM Python
import requests

API_KEY = "tgd_votre_clé_ici"
WEBHOOK_URL = "https://tagadaos-2.polsia.app/api/leads/webhook"

leads = [
    {"email": "prospect@exemple.com", "source": "seo", "quality_score": 7},
    # ... autres leads
]

response = requests.post(WEBHOOK_URL,
    json={"leads": leads},
    headers={"X-API-Key": API_KEY}
)
print(response.json())  # {"imported": 1, "duplicates": 0, "errors": []}

Gestion des clés API

Clés API

Créez, listez et révoquez les clés API depuis le dashboard ou via l'API (JWT requis).

POST /api/settings/api-keys JWT

Génère une nouvelle clé API. La clé en clair est retournée une seule fois — elle ne peut pas être récupérée ensuite.

Champ	Type	Requis	Description
name	string	Requis	Nom descriptif de la clé (ex: "CRM Production")

JSON Body

{ "name": "CRM Production" }

201 Created

{
  "id": 3,
  "name": "CRM Production",
  "key": "tgd_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
  "created_at": "2025-04-20T10:00:00.000Z"
}

⚠️ Le champ key n'est retourné que dans cette réponse. Copiez-le immédiatement.

cURL

curl -X POST https://tagadaos-2.polsia.app/api/settings/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "CRM Production"}'

GET /api/settings/api-keys JWT

Retourne la liste des clés API actives. La valeur de la clé n'est jamais retournée ici.

200 OK

[
  {
    "id": 1,
    "name": "CRM Production",
    "active": true,
    "created_at": "2025-04-10T08:00:00.000Z",
    "last_used_at": "2025-04-20T09:15:00.000Z"
  }
]

cURL

curl https://tagadaos-2.polsia.app/api/settings/api-keys \
  -H "Authorization: Bearer YOUR_JWT"

DELETE /api/settings/api-keys/:id JWT

Révoque une clé API (soft delete). Les requêtes utilisant cette clé seront immédiatement rejetées avec 401.

200 OK

{ "success": true }

cURL

curl -X DELETE https://tagadaos-2.polsia.app/api/settings/api-keys/1 \
  -H "Authorization: Bearer YOUR_JWT"