{"openapi":"3.1.0","info":{"title":"Argos Sourcing API","version":"1.0.0","summary":"Sociétés européennes par pays et secteur : 18,7 millions d'entreprises, 25 pays, 84 secteurs, export Excel.","description":"API REST de la base Argos Sourcing. Les mêmes données que l'interface web, en JSON.\n\n**Authentification** : en-tête `Authorization: Bearer as_live_...` (clef personnelle créée dans Mon compte).\nSans clef et sans compte : 2 sociétés par appel, offset borné, aucun quota d'export ni d'API. Le champ `total` reste toujours complet : il donne la taille réelle du périmètre.\n\n**Quotas par offre** (aucun plafond illimité, tout est chiffré et appliqué par le serveur) :\n\n| Offre | Résultats par recherche | Lignes par appel API | Appels API par jour | Exports Excel par mois | Coordonnées | États financiers |\n| --- | --- | --- | --- | --- | --- | --- |\n| Sans compte | 2 | 2 | 0 | 0 | non | non |\n| Découverte (gratuit) | 5 | 5 | 50 | 2 x 25 | non | oui |\n| Starter (39 EUR HT/mois) | 50 | 50 | 200 | 10 x 500 | oui | oui |\n| Business (119 EUR HT/mois) | 200 | 200 | 1000 | 40 x 2500 | oui | oui |\n| Intégration (349 EUR HT/mois) | 1000 | 500 | 5000 | 100 x 10000 | oui | oui |\n\nChaque réponse porte le plafond appliqué (`plafond_resultats`), le drapeau `tronque`, le nombre de sociétés restantes (`restantes`) et l'offre immédiatement supérieure (`offre_suivante`) avec ses chiffres : l'appelant n'a rien à deviner.\nLes en-têtes `X-Plafond-Resultats`, `X-Quota-Limit` et `X-Quota-Used` reprennent la même information.\n\n**Coordonnées** (`site_web`, `domaine`, `email`, `telephone`) : renvoyées seulement à partir de l'offre Starter. En dessous, les champs sont présents mais valent `null`, jamais une valeur approximative.\n\n**Pays** : codes ISO 3166-1 alpha-2, avec `UK` pour le Royaume-Uni (GB accepté). Liste sur `/api/v1/pays`.\n**Secteurs** : libellés FR exacts ou slugs (voir `/api/v1/secteurs`), plusieurs valeurs séparées par `|`.\n\nLes chiffres d'affaires sont en euros (colonne `ca_eur`, dernier exercice publié, taux annuel moyen). Les montants locaux sont exposés avec leur devise et leur multiplicateur.","contact":{"name":"Argos","email":"contact@argos-finance.fr","url":"https://sourcing.argos-finance.fr"},"termsOfService":"https://sourcing.argos-finance.fr/cgu","x-logo":{"url":"https://sourcing.argos-finance.fr/icon-512.png"}},"servers":[{"url":"https://sourcing.argos-finance.fr"}],"tags":[{"name":"Référentiels"},{"name":"Sociétés"},{"name":"Export"}],"components":{"securitySchemes":{"clefApi":{"type":"http","scheme":"bearer","bearerFormat":"as_live_...","description":"Clef personnelle (Mon compte > Clefs API)."}},"parameters":{"pays":{"name":"pays","in":"query","description":"Codes pays séparés par des virgules (ex. `FR,IT,BE`). Vide = tous.","schema":{"type":"string"},"example":"FR,IT"},"secteur":{"name":"secteur","in":"query","description":"Secteur(s) : libellé FR exact ou slug, séparés par `|`. Vide = tous.","schema":{"type":"string"},"example":"restauration|hotellerie"},"sous_secteur":{"name":"sous_secteur","in":"query","description":"Sous-secteur(s) : libellés exacts tels que renvoyés par /api/v1/sous-secteurs, séparés par `|`. Ne s'applique qu'avec `secteur`. Vide = tout le secteur.","schema":{"type":"string"},"example":"Restauration rapide|Traiteurs"},"q":{"name":"q","in":"query","description":"Recherche par nom (contient) ou identifiant national (préfixe).","schema":{"type":"string","maxLength":120}},"tri":{"name":"tri","in":"query","schema":{"type":"string","enum":["ca_desc","ca_asc","nom","effectif_desc","recent","capital_desc","score"],"default":"ca_desc"}},"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":50},"description":"Nombre de sociétés demandées. Plafonné par l'offre : 2 sans compte, 5 en Découverte, 50 en Starter, 200 en Business, 1000 en Intégration. Une clef API est en outre bornée par lignesParAppel."},"offset":{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Décalage dans la liste. `offset + limit` reste borné par le plafond de l'offre : la pagination ne contourne pas le quota."},"ca_min":{"name":"ca_min","in":"query","schema":{"type":"number"},"description":"CA minimum en EUR."},"ca_max":{"name":"ca_max","in":"query","schema":{"type":"number"}},"effectif_min":{"name":"effectif_min","in":"query","schema":{"type":"integer"}},"effectif_max":{"name":"effectif_max","in":"query","schema":{"type":"integer"}},"site_web":{"name":"site_web","in":"query","schema":{"type":"string","enum":["1"]},"description":"Uniquement les sociétés avec un site web déclaré."},"avec_ca":{"name":"avec_ca","in":"query","schema":{"type":"string","enum":["1"]},"description":"Uniquement les sociétés avec un CA publié."}},"schemas":{"Societe":{"type":"object","properties":{"iso2":{"type":"string","example":"FR"},"id":{"type":"string","description":"Identifiant national (SIREN, Company number, etc.)","example":"552032534"},"nom":{"type":"string"},"forme":{"type":["string","null"]},"statut":{"type":["string","null"]},"activite":{"type":["string","null"]},"ville":{"type":["string","null"]},"code_postal":{"type":["string","null"]},"region":{"type":["string","null"]},"adresse":{"type":["string","null"]},"date_creation":{"type":["string","null"]},"effectif":{"type":["integer","null"]},"tranche_effectif":{"type":["string","null"]},"capital_social":{"type":["number","null"]},"capital_devise":{"type":["string","null"]},"ca_eur":{"type":["number","null"],"description":"Chiffre d'affaires en EUR, dernier exercice publié"},"ca_last":{"type":["number","null"]},"ca_year":{"type":["integer","null"]},"ca_devise":{"type":["string","null"]},"ca_mult":{"type":["integer","null"]},"total_actif_last":{"type":["number","null"]},"exercice_actif":{"type":["integer","null"]},"devise":{"type":["string","null"]},"unite_mult":{"type":["integer","null"]},"n_exercices":{"type":["integer","null"]},"exercice_min":{"type":["integer","null"]},"exercice_max":{"type":["integer","null"]},"secteur":{"type":["string","null"]},"grand_secteur":{"type":["string","null"]},"sous_secteur":{"type":["string","null"]},"nace_code":{"type":["string","null"]},"nace_libelle":{"type":["string","null"]},"description":{"type":["string","null"]},"site_web":{"type":["string","null"]},"domaine":{"type":["string","null"]},"email":{"type":["string","null"]},"telephone":{"type":["string","null"]},"est_cotee":{"type":["boolean","null"]},"url_registre":{"type":["string","null"]},"score":{"type":["number","null"],"description":"Complétude des données (tri interne)"}}},"OffreSuivante":{"type":["object","null"],"description":"Offre immédiatement supérieure et ses quotas chiffrés, pour proposer la montée en gamme sans deviner. null sur l'offre la plus haute.","properties":{"plan":{"type":"string","example":"starter"},"nom":{"type":"string","example":"Starter"},"nom_en":{"type":"string"},"prix_mensuel_eur":{"type":"number","example":39},"prix_annuel_eur":{"type":"number","example":390},"resultats_par_recherche":{"type":"integer","example":50},"exports_par_mois":{"type":"integer"},"lignes_par_export":{"type":"integer"},"appels_api_par_jour":{"type":"integer"},"lignes_par_appel":{"type":"integer"},"societes_avec_comptes_par_export":{"type":"integer","description":"Sociétés dont les états financiers complets (une feuille chacune) sont écrits dans chaque export Excel.","example":25},"coordonnees":{"type":"boolean"},"etats_financiers":{"type":"boolean"},"url":{"type":"string","enum":["/inscription","/tarifs"]}}},"Erreur":{"type":"object","properties":{"erreur":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/api/v1/pays":{"get":{"tags":["Référentiels"],"summary":"Pays couverts avec compteurs","operationId":"listerPays","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"total":25,"pays":[{"iso2":"UK","slug":"royaume-uni","nom_fr":"Royaume-Uni","nom_en":"United Kingdom","devise":"GBP","registre":"Companies House","n_societes":7227000}]}}}}}}},"/api/v1/sous-secteurs":{"get":{"tags":["Référentiels"],"summary":"Sous-secteurs réellement présents pour un ou plusieurs secteurs (et pays), avec compteurs","operationId":"listerSousSecteurs","parameters":[{"$ref":"#/components/parameters/secteur"},{"$ref":"#/components/parameters/pays"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"total":6,"perimetre":{"pays":["FR"],"secteurs":["Restauration"]},"sous_secteurs":[{"sous_secteur":"Restauration traditionnelle","n_societes":61234}]}}}},"400":{"description":"Secteur manquant ou inconnu"}}}},"/api/v1/secteurs":{"get":{"tags":["Référentiels"],"summary":"Secteurs (84) avec compteurs, optionnellement pour un périmètre de pays","operationId":"listerSecteurs","parameters":[{"$ref":"#/components/parameters/pays"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"total":84,"secteurs":[{"secteur":"Restauration","secteur_en":"Restaurants","slug":"restauration","grand_secteur":"Tourisme, Loisirs & Restauration","n_societes":378069}]}}}}}}},"/api/v1/societes":{"get":{"tags":["Sociétés"],"summary":"Rechercher des sociétés par pays et secteur","operationId":"rechercherSocietes","security":[{"clefApi":[]},{}],"parameters":[{"$ref":"#/components/parameters/pays"},{"$ref":"#/components/parameters/secteur"},{"$ref":"#/components/parameters/sous_secteur"},{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/tri"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/ca_min"},{"$ref":"#/components/parameters/ca_max"},{"$ref":"#/components/parameters/effectif_min"},{"$ref":"#/components/parameters/effectif_max"},{"$ref":"#/components/parameters/site_web"},{"$ref":"#/components/parameters/avec_ca"}],"responses":{"200":{"description":"Liste paginée, plafonnée par l'offre","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Sociétés correspondant au filtre dans toute la base. Jamais tronqué."},"limit":{"type":"integer"},"offset":{"type":"integer"},"plan":{"type":"string","enum":["visiteur","free","starter","business","integration"]},"plafond_resultats":{"type":"integer","description":"Sociétés que l'offre autorise à afficher pour cette recherche."},"visibles":{"type":"integer"},"tronque":{"type":"boolean"},"restantes":{"type":"integer","description":"total - visibles"},"coordonnees":{"type":"boolean","description":"false : site_web, domaine, email et telephone valent null."},"offre_suivante":{"$ref":"#/components/schemas/OffreSuivante"},"apercu":{"type":"boolean","description":"true si appel non identifié (offre visiteur)"},"societes":{"type":"array","items":{"$ref":"#/components/schemas/Societe"}}}}}}},"400":{"description":"Pays ou secteur inconnu : le parametre n'est jamais ignore en silence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erreur"},"example":{"erreur":{"code":"pays_inconnu","message":"Pays non couvert : DE. Liste des 25 pays disponibles sur /api/v1/pays.","pays_inconnus":["DE"]}}}}},"401":{"description":"Clef API invalide ou révoquée : l'appel retombe sur l'offre visiteur, aucune clef n'est acceptée à moitié"},"429":{"description":"Quota atteint ou trop de requêtes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erreur"}}}}}}},"/api/v1/societes/{iso}/{id}":{"get":{"tags":["Sociétés"],"summary":"Fiche d'une société (identité + états financiers pour les utilisateurs identifiés)","operationId":"ficheSociete","security":[{"clefApi":[]},{}],"parameters":[{"name":"iso","in":"path","required":true,"schema":{"type":"string"},"example":"FR"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"552032534"}],"description":"Identité publique. Les états financiers détaillés (`comptes`) sont servis aux offres dont `etatsFinanciers` est vrai, c'est-à-dire tout compte, y compris Découverte qui est gratuite. Les coordonnées suivent le droit `coordonnees` (offres payantes).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"societe":{"$ref":"#/components/schemas/Societe"},"plan":{"type":"string"},"comptes":{"type":"array","description":"Lignes d'états financiers (etat, libelle, valeur, devise, exercice...)","items":{"type":"object"}},"comptes_message":{"type":"string","description":"Présent à la place de comptes quand l'offre n'y donne pas droit."},"droits":{"type":"object","properties":{"etats_financiers":{"type":"boolean"},"coordonnees":{"type":"boolean"}}},"offre_suivante":{"$ref":"#/components/schemas/OffreSuivante"}}}}}},"400":{"description":"Code pays ou identifiant invalide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erreur"}}}},"401":{"description":"Clef API invalide : l'appel retombe sur l'offre visiteur"},"404":{"description":"Introuvable"},"429":{"description":"Quota journalier atteint ou trop de requêtes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erreur"}}}}}}},"/api/v1/export":{"get":{"tags":["Export"],"summary":"Classeur Excel (xlsx) du périmètre : Intro, Synthèse (Périmètre, Par pays, Par secteur), Sociétés (Liste, Contacts), Comptes (une feuille d'états financiers par société), Ressources (Méthodologie, Journal)","operationId":"exporterExcel","security":[{"clefApi":[]}],"description":"Compte requis. Quota mensuel et plafond de lignes fixés par l'offre : 2 x 25 en Découverte, 10 x 500 en Starter, 40 x 2500 en Business, 100 x 10000 en Intégration. Colonnes Site web, Email et Téléphone : remplies à partir de l'offre Starter. En dessous elles partent vides. Famille \"Comptes >>\" : une feuille par société avec bilan actif, bilan passif, compte de résultat et annexes (un exercice par colonne, agrégats en gras), pour les premières sociétés du tri : 3 en Découverte, 25 en Starter, 100 en Business, 250 en Intégration. Paramètres identiques à /api/v1/societes, plus `lang` (fr|en).","parameters":[{"$ref":"#/components/parameters/pays"},{"$ref":"#/components/parameters/secteur"},{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/tri"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/ca_min"},{"$ref":"#/components/parameters/ca_max"},{"$ref":"#/components/parameters/effectif_min"},{"$ref":"#/components/parameters/effectif_max"},{"$ref":"#/components/parameters/site_web"},{"$ref":"#/components/parameters/avec_ca"},{"name":"lang","in":"query","schema":{"type":"string","enum":["fr","en"],"default":"fr"}}],"responses":{"200":{"description":"Fichier xlsx. En-têtes X-Export-Lignes, X-Export-Total, X-Export-Plafond, X-Export-Comptes (sociétés avec feuille de comptes), X-Export-Comptes-Plafond, X-Export-Coordonnees, X-Quota-Used, X-Quota-Limit.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Pays ou secteur inconnu","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erreur"}}}},"401":{"description":"Compte requis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erreur"},"example":{"erreur":{"code":"compte_requis","message":"Creez un compte gratuit pour exporter en Excel (2 exports par mois de 25 lignes), ou passez une clef API."}}}}},"429":{"description":"Quota d'exports atteint. Le message nomme l'offre suivante et son plafond chiffré.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erreur"}}}}}},"post":{"tags":["Export"],"summary":"Idem GET, paramètres dans un corps JSON","operationId":"exporterExcelPost","security":[{"clefApi":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pays":{"type":"string"},"secteur":{"type":"string"},"q":{"type":"string"},"tri":{"type":"string"},"limit":{"type":"integer"},"lang":{"type":"string"}}},"example":{"pays":"FR,BE","secteur":"restauration","limit":500,"lang":"fr"}}}},"responses":{"200":{"description":"Fichier xlsx"}}}}}}