{"openapi":"3.0.3","info":{"title":"Magic-Lead API","description":"\n# API Magic-Lead\n\nAPI publique pour intégrer Magic-Lead avec vos outils (Zapier, n8n, Make, custom integrations).\n\n## Authentification\n\nToutes les requêtes doivent inclure un header `Authorization` avec votre clé API :\n\n```\nAuthorization: Bearer ml_votre_cle_api\n```\n\nou\n\n```\nAuthorization: ApiKey ml_votre_cle_api\n```\n\n## Rate Limiting\n\n- Par défaut : 1000 requêtes/heure\n- Header `X-RateLimit-Remaining` dans les réponses\n\n## Scopes\n\n- `read` : Lecture seule\n- `write` : Création/modification\n- `delete` : Suppression\n- `admin` : Accès complet\n    ","version":"1.0.0","contact":{"name":"Magic-Lead Support","email":"contact@magic-lead.com","url":"https://magic-lead.com"}},"servers":[{"url":"https://magic-lead.com/api/v1","description":"Production"}],"tags":[{"name":"Contacts","description":"Gestion des contacts"},{"name":"Campaigns","description":"Gestion des campagnes email"},{"name":"Statistics","description":"Statistiques et analytics"},{"name":"Scraping","description":"Recherche d'entreprises (CCI/INPI)"},{"name":"E-Commerce","description":"Produits et commandes"},{"name":"Tags","description":"Gestion des tags"},{"name":"Senders","description":"Gestion des expéditeurs"}],"paths":{"/contacts":{"get":{"tags":["Contacts"],"summary":"Lister les contacts","description":"Récupère la liste paginée des contacts avec filtres optionnels.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Recherche par email, nom ou entreprise"},{"name":"tagIds","in":"query","schema":{"type":"string"},"description":"IDs de tags séparés par virgule"}],"responses":{"200":{"description":"Liste des contacts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"BearerAuth":[]}]},"post":{"tags":["Contacts"],"summary":"Créer un contact","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","firstName"],"properties":{"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"sourceUrl":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"IDs des tags"}}}}}},"responses":{"201":{"description":"Contact créé"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"description":"Email déjà existant"}},"security":[{"BearerAuth":[]}]},"delete":{"tags":["Contacts"],"summary":"Supprimer des contacts","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"IDs séparés par virgule"}],"responses":{"200":{"description":"Contacts supprimés"}},"security":[{"BearerAuth":[]}]}},"/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Détail d'un contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Détail du contact avec historique emails"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"BearerAuth":[]}]},"patch":{"tags":["Contacts"],"summary":"Modifier un contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"unsubscribed":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Contact mis à jour"}},"security":[{"BearerAuth":[]}]},"delete":{"tags":["Contacts"],"summary":"Supprimer un contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact supprimé"}},"security":[{"BearerAuth":[]}]}},"/campaigns":{"get":{"tags":["Campaigns"],"summary":"Lister les campagnes","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","RUNNING","COMPLETED","ERROR"]}}],"responses":{"200":{"description":"Liste des campagnes"}},"security":[{"BearerAuth":[]}]},"post":{"tags":["Campaigns"],"summary":"Créer une campagne","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","templateId"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"templateId":{"type":"string"},"contactIds":{"type":"array","items":{"type":"string"}},"senderIds":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Campagne créée"}},"security":[{"BearerAuth":[]}]}},"/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Détail d'une campagne","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Détail de la campagne avec contacts et senders"}},"security":[{"BearerAuth":[]}]},"delete":{"tags":["Campaigns"],"summary":"Supprimer une campagne","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campagne supprimée"}},"security":[{"BearerAuth":[]}]}},"/campaigns/{id}/launch":{"post":{"tags":["Campaigns"],"summary":"Lancer une campagne","description":"Envoie les emails de la campagne à tous les contacts assignés.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Résultat du lancement","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"status":{"type":"string"},"emailsSent":{"type":"integer"},"errors":{"type":"integer"}}}}}},"400":{"description":"Campagne déjà lancée ou sans contacts"}},"security":[{"BearerAuth":[]}]}},"/campaigns/{id}/stats":{"get":{"tags":["Campaigns"],"summary":"Statistiques d'une campagne","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Statistiques détaillées","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object"},"stats":{"type":"object","properties":{"totalSent":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer"},"bounced":{"type":"integer"},"openRate":{"type":"string"},"clickRate":{"type":"string"},"bounceRate":{"type":"string"}}},"bySender":{"type":"array"}}}}}}},"security":[{"BearerAuth":[]}]}},"/stats":{"get":{"tags":["Statistics"],"summary":"Statistiques globales","parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["7d","30d","90d","all"],"default":"30d"}}],"responses":{"200":{"description":"Statistiques globales avec tendances"}},"security":[{"BearerAuth":[]}]}},"/scraping":{"get":{"tags":["Scraping"],"summary":"Rechercher des entreprises","description":"Recherche d'entreprises via l'API Pappers (CCI/INPI/INSEE).","parameters":[{"name":"query","in":"query","schema":{"type":"string"},"description":"Nom ou mot-clé"},{"name":"department","in":"query","schema":{"type":"string"},"description":"Code département (75, 13, etc.)"},{"name":"region","in":"query","schema":{"type":"string"},"description":"Région"},{"name":"activityCode","in":"query","schema":{"type":"string"},"description":"Code NAF (56.10A, etc.)"},{"name":"legalForm","in":"query","schema":{"type":"string"},"description":"Forme juridique (SAS, SARL, etc.)"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"Liste des entreprises"},"402":{"description":"Crédits Pappers épuisés"}},"security":[{"BearerAuth":[]}]},"post":{"tags":["Scraping"],"summary":"Importer des contacts","description":"Importe les entreprises sélectionnées comme contacts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["companies"],"properties":{"companies":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"director":{"type":"string"},"siren":{"type":"string"},"legalForm":{"type":"string"},"nafCode":{"type":"string"},"address":{"type":"string"}}}},"tagIds":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Résultat de l'import","content":{"application/json":{"schema":{"type":"object","properties":{"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}}}}}}},"security":[{"BearerAuth":[]}]}},"/ecommerce/products":{"get":{"tags":["E-Commerce"],"summary":"Lister les produits","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","ARCHIVED"]}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Liste des produits"}},"security":[{"BearerAuth":[]}]},"post":{"tags":["E-Commerce"],"summary":"Créer un produit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"supplierUrl":{"type":"string"},"supplierPrice":{"type":"number"},"sellingPrice":{"type":"number"},"category":{"type":"string"},"imageUrl":{"type":"string"}}}}}},"responses":{"201":{"description":"Produit créé"}},"security":[{"BearerAuth":[]}]}},"/ecommerce/products/{id}":{"get":{"tags":["E-Commerce"],"summary":"Détail d'un produit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Détail du produit avec commandes"}},"security":[{"BearerAuth":[]}]},"patch":{"tags":["E-Commerce"],"summary":"Modifier un produit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"supplierPrice":{"type":"number"},"sellingPrice":{"type":"number"},"status":{"type":"string","enum":["DRAFT","ACTIVE","ARCHIVED"]},"marketingDesc":{"type":"string"}}}}}},"responses":{"200":{"description":"Produit mis à jour"}},"security":[{"BearerAuth":[]}]},"delete":{"tags":["E-Commerce"],"summary":"Supprimer un produit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Produit supprimé"}},"security":[{"BearerAuth":[]}]}},"/ecommerce/orders":{"get":{"tags":["E-Commerce"],"summary":"Lister les commandes","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING","PAID","ORDERED_FROM_SUPPLIER","SHIPPED","DELIVERED","CANCELLED","REFUNDED"]}}],"responses":{"200":{"description":"Liste des commandes"}},"security":[{"BearerAuth":[]}]},"patch":{"tags":["E-Commerce"],"summary":"Mettre à jour une commande","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId","status"],"properties":{"orderId":{"type":"string"},"status":{"type":"string","enum":["PENDING","PAID","ORDERED_FROM_SUPPLIER","SHIPPED","DELIVERED","CANCELLED","REFUNDED"]},"trackingNumber":{"type":"string"}}}}}},"responses":{"200":{"description":"Commande mise à jour"}},"security":[{"BearerAuth":[]}]}},"/tags":{"get":{"tags":["Tags"],"summary":"Lister les tags","responses":{"200":{"description":"Liste des tags avec compteur de contacts"}},"security":[{"BearerAuth":[]}]},"post":{"tags":["Tags"],"summary":"Créer un tag","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"color":{"type":"string","description":"Couleur hex (#60B5FF)"}}}}}},"responses":{"201":{"description":"Tag créé"}},"security":[{"BearerAuth":[]}]},"delete":{"tags":["Tags"],"summary":"Supprimer un tag","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tag supprimé"}},"security":[{"BearerAuth":[]}]}},"/senders":{"get":{"tags":["Senders"],"summary":"Lister les expéditeurs","responses":{"200":{"description":"Liste des expéditeurs"}},"security":[{"BearerAuth":[]}]},"post":{"tags":["Senders"],"summary":"Créer un expéditeur","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","signature"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"signature":{"type":"string"}}}}}},"responses":{"201":{"description":"Expéditeur créé"},"409":{"description":"Email déjà existant"}},"security":[{"BearerAuth":[]}]}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Clé API Magic-Lead (ml_xxx...)"}},"schemas":{"Contact":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"sourceUrl":{"type":"string"},"unsubscribed":{"type":"boolean"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"createdAt":{"type":"string","format":"date-time"}}},"Tag":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}},"responses":{"Unauthorized":{"description":"Clé API invalide ou manquante","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"BadRequest":{"description":"Requête invalide"},"NotFound":{"description":"Ressource non trouvée"}}}}