io.insourcia/insourcia

Creation d'une recherche sauvegardee pour l'utilisateur, visible dans l'app Insourcia (page /news - Veille). Utiliser cet outil quand l'utilisateur veut SAUVEGARDER une recherche pour la suivre dans le temps (veille marche, suivi d'un secteur, pipeline de cibles) - pas pour une recherche ponctuelle (utiliser search_companies). Fonctionnement : - Les filtres acceptes sont les MEMES que search_companies (query texte libre + filtres geographie/secteur/financier/dirigeants/groupe + advanced_filters JSON). Au moins un critere est requis. - Idempotent : si une recherche sauvegardee ACTIVE du meme nom existe deja pour l'utilisateur, elle est renvoyee telle quelle (already_exists=true), sans doublon et sans modifier son alerte. - enable_alert=true active une alerte quotidienne : l'utilisateur est notifie (page /news + email) quand de NOUVELLES societes entrent dans les criteres de la recherche. A la creation, une notification initiale recapitule les societes entrees dans les 90 derniers jours ; ensuite seules les entrees futures declenchent. Reponse : { id, name, url (page /news), result_count (nombre de societes matchant actuellement, null si indisponible), filters (filtres normalises stockes, absent sur le hit idempotent), already_exists, alert_enabled }.

Fiche complete d'une entreprise francaise identifiee par son SIREN. Pour plusieurs entreprises, le parametre sirens sert jusqu'a 10 fiches en une requete, au lieu d'un appel par societe. COUT : 1 appel de quota par societe, en lot comme a l'unite. Pour comparer beaucoup de societes, search_companies rend les memes champs en include_fields (dont description_activite et site_internet), 20 societes par appel. Contenu : 1. Identite - forme juridique, dates de creation et d'immatriculation, date_cloture_exercice, capital, siege complet, activite (NAF, objet_social, description), effectif, LEI si present ; successeur si radiee. 2. Financier - date_cloture et type_bilan (K consolide, C social, S simplifie : un CA K n'est pas comparable a un CA C), CA, croissance, resultat net, marges, EBITDA, dette nette, effectif moyen. 3. Contact - site web, telephone, email et LinkedIn (pro). 4. Gouvernance - dirigeants principaux. 5. Groupe - est_filiale, parents direct et ultime, societe_mere, tete de groupe (siren_groupe, a passer a search_companies pour lister le groupe), nb filiales. Absent = independante. 6. IFRS - agregats consolides des cotees. 7. Signaux - cotation, procedures collectives, fusions, modifications de capital, transferts de siege, changements de denomination, ESS, societe a mission, dernier depot, radiation. 8. Score credit - grade AAA a D, probabilites de defaut 3/6/12 mois, facteurs ; detail dans get_credit_risk. Null si non scoree. 9. Cessions - historique (date, type, cedant, cessionnaire, prix). 10. Donnees publiques - marches publics, subventions, brevets, salons. 11. Fonds PE/VC - nom_fonds, siren_fonds (chainable vers get_company), annee d'entree. Pour approfondir : get_financials (historique), get_directors (mandats), get_events (annonces BODACC), get_company_graph (structure). watch_company met la societe sous surveillance.

Cartographie des entites autour d'UNE entreprise (par SIREN) : graphe oriente construit sur les mandats RCS/RNE et les liens de groupe. Pour la structure d'un groupe : holdings, filiales, societes soeurs, dirigeants communs. Complementaire de get_directors (mandats d'une societe) et de search_director_companies (empreinte d'une personne). Reponse : nodes[] (entreprises "co:<siren>", personnes "pp:<nom>|<prenom>|<AAAA-MM>", parents etrangers "co:ext:<slug>") et edges[] orientees : - mandat_pm : societe dirigeante -> societe dirigee - filiale : mere -> filiale (associe unique RNE) - parent_ultime : parent ultime (GLEIF) -> societe - mandat_pp : personne -> societe dirigee A savoir : - Pas de pourcentage de detention. Les commissaires aux comptes sont exclus. - depth=1 : liens directs. depth=2 (defaut) : expansion depuis les parents et societes dirigeantes, jamais depuis les filiales. - Les dirigeants de la racine tirent leurs autres societes (holdings personnelles, SCI, structures soeurs). expand_persons=false donne un graphe purement capitalistique. Un mandataire professionnel (plus de 50 mandats, ou cabinet comptable) n'est pas etendu : voir meta.truncated.hub_directors. - Plafonds par noeud et max_nodes : meta.truncated signale un graphe partiel. Filtres : include_personnes, include_sci, include_ceased, expand_persons. La racine n'est jamais filtree. Pour plusieurs entreprises, le parametre sirens sert 3 graphes en une requete (2 en depth=2), a depth=1 par defaut : une traversee coute 3 a 5 secondes et ne se parallelise pas.

Score de risque credit d'UNE entreprise francaise (par SIREN). Retourne le grade de risque (AAA -> D), la probabilite de defaut a 3/6/12 mois (taux du grade, master-scale) et les 5 facteurs principaux (aggravants / attenuants). Disponible sur tous les plans. Reponses possibles : - entreprise scoree : { scorable:true, risk:{ grade, grade_default_rate, factors, as_of, model } } - entreprise non scoree (pas de comptes recents) : { scorable:false, risk:null } - SIREN inconnu : erreur 404. Use case : risque fournisseur, due diligence. Pour scorer un portefeuille, le parametre sirens rend jusqu'a 10 scores en une requete.

Detail des dirigeants d'une entreprise avec structure hierarchique. Retourne les dirigeants classes par importance (decisionnaires en premier). Deux types d'entrees : - **PP** (personne physique) : nom, prenom, role, annee de naissance, date_debut_mandat, date_fin_mandat, linkedin_url - **PM** (personne morale) : denomination, SIREN, role, date_debut_mandat, date_fin_mandat, avec un tableau representants[] listant les personnes physiques qui la representent (nom, prenom, role dans la PM, dates de mandat) Inclut les commissaires aux comptes (role="CAC") avec leur date de debut/fin de mandat. Utile pour identifier le mandataire actif vs sortant. linkedin_url est le profil LinkedIn de la personne physique, present uniquement quand un profil a ete apparie avec certitude (nom + prenom + date de naissance). La clef est absente quand aucun profil n'est confirme : c'est le cas courant, pas une anomalie. Reserve au plan pro. Par defaut, seuls les mandataires actifs sont retournes. Utiliser include_inactive=true pour inclure l'historique. Pour plusieurs entreprises, le parametre sirens sert jusqu'a 10 societes en une requete. Le lot rend les 20 premiers mandataires de CHAQUE societe et signale celles qu'il a tronquees : limit et offset n'ont pas de sens sur dix societes a la fois, et l'appel unitaire reste la pour derouler l'historique complet d'une seule.

Timeline unifiee des evenements d'UNE entreprise (par SIREN). Flux chronologique decroissant qui reunit : - une ligne par annonce BODACC de modification (forme juridique, dirigeants, siege, activite, capital, denomination, dissolution), avec libelle, sous_type et source_url vers l'avis officiel ; - une ligne par depot des comptes (un par exercice) et par immatriculation ; - les cessions (y compris cote cedant d'une vente) et les procedures collectives ; - la radiation, l'augmentation de capital, la creation ; - une ligne par annee de marches publics, les subventions ; - sur 12 mois, les mouvements de dirigeants et changements de groupe ou de note credit (types dirigeant_*, changement_*). Pour plusieurs entreprises, le parametre sirens sert jusqu'a 10 timelines en une requete, 20 evenements par societe et sans pagination. Pour de la prospection cross-SIREN sans liste de depart, utiliser search_events. COUT : 1 appel de quota par societe.

Historique financier detaille d'une entreprise sur plusieurs exercices. COUT : 1 appel de quota par societe, reponse de ~10 a 45 Kio selon detail et years. Pour le seul dernier exercice (ca, ebitda, resultat_exploitation, resultat_net, effectif_moyen), search_companies le rend en include_fields, 20 societes par appel. Pour plusieurs entreprises, le parametre sirens sert jusqu'a 10 historiques en une requete (3 en detail=full). Le lot part en compact sauf demande explicite, y compris sur Pro, et ne pagine pas. Niveau de detail : - compact (defaut sur free, ~40 champs par exercice) : compte de resultat complet, bilan abrege PCG, ratios (tresorerie, dette nette, BFR, marges, endettement, CAF, delais de paiement), dividendes, effectif moyen. - full (defaut sur Pro, ~140 champs) : tous les postes. Refuse sur free (403). - fields : ajoute quelques champs a compact sans gonfler la reponse, ex fields=["roe","bfr_jours_ca","autonomie_financiere"]. Plus de 130 disponibles : ratios, postes detailles, immobilisations brutes, reserves, croissances (cagr_ebitda_3ans...). type_bilan : K consolide, C social, S simplifie. Quand la fenetre melange plusieurs types, un seul est garde et type_bilan_mixte l'indique ; type_bilan force un type. Les cotees ont en plus un bloc ifrs. Rendu : _layout decrit par section l'ordre PCG des lignes, leur libelle (line.label), leur indentation (level) et leur nature (kind) ; exercices[annee][line.key] porte la valeur, null = poste absent. not_applicable_pcg signale un bilan de banque ou d'assurance. Montants en euros.

Veille quotidienne de l'utilisateur : le fil d'actualite de ses societes surveillees, tel qu'il apparait sur la page /news de l'app Insourcia. Utiliser cet outil pour repondre a "quoi de neuf sur ma veille ?", "qu'est-ce qui a bouge sur mes societes ?", "resume-moi ma veille de la semaine", ou avant de rediger un point hebdomadaire. Contenu : les alertes reellement delivrees (email/push) ET l'activite des societes des listes de veille (changements de dirigeants, annonces BODACC : procedures collectives, cessions, radiations...), fusionnees et dedupliquees, les plus recentes d'abord. Couvre toutes les listes de l'utilisateur, tous espaces confondus (source.espace indique lequel). Chaque ligne est HYBRIDE : "label" donne la phrase francaise prete a lire (identique a l'app) et "type"/"before"/"after"/"siren"/"date" donnent les champs structures pour filtrer ou raisonner. "date" est le jour de DETECTION (axe de fraicheur) ; "effective_date", quand present, est la date d'effet juridique. unread_only=true ne renvoie que ce que l'utilisateur n'a pas encore lu. "read_key" identifie chaque ligne : la passer a mark_news_read pour la marquer lue. truncated=true signale plus de signaux que la limite demandee ; since_days et event_types permettent de resserrer (pas de pagination sur ce fil). Si counts_are_partial=true, "total" et "unread_count" sont des PLANCHERS et non des totaux : le fil est compose sur une fenetre bornee (les 100 dernieres notifications et les 100 derniers evenements), et cette fenetre etait pleine. hidden_by_plan, quand present, compte les signaux non retournes parce que le plan actuel ne donne acces qu'aux 10 signaux les plus recents, exactement comme la page /news. Un fil ainsi tronque n'est pas complet, et hidden_by_plan dit de combien. Reponse : { news: [...], total, unread_count, last_seen_at, since_days, truncated, url (page /news) }. news vide = aucun signal sur la periode, ce n'est pas une erreur.

Liste des recherches sauvegardees de l'utilisateur (page /news - Veille de l'app Insourcia). Utiliser cet outil : - AVANT create_saved_search, pour verifier qu'une veille equivalente n'existe pas deja et eviter les doublons de nom. - Pour repondre a "quelles veilles ai-je ?" / "quelles sont mes recherches sauvegardees ?". Reponse : { saved_searches: [{ id, name, filters (filtres normalises stockes), result_count (nombre de societes matchant, null si indisponible), alert_enabled (alerte quotidienne nouvelles societes active ou non), url (page /news), created_at }], total }. Les recherches sont triees de la plus recente a la plus ancienne. Liste vide = aucune veille configuree.

Liste des societes surveillees par l'utilisateur dans ses listes de veille (page /lists de l'app Insourcia). Utiliser cet outil : - AVANT watch_company, pour verifier si une societe est deja surveillee et connaitre les listes existantes (leur nom exact). - Pour repondre a "quelles societes je surveille ?" / "qu'y a-t-il dans ma liste X ?". list_name (optionnel) restreint a une liste precise (nom exact). Sans list_name, toutes les listes de l'utilisateur sont retournees. Un list_name qui ne matche aucune liste renvoie companies: [] et total: 0 (ce n'est pas une erreur : simplement aucune societe surveillee sous ce nom). Reponse : { companies: [{ siren, company_name, naf_code, region, list_id, list_name, added_at }] (aplaties toutes listes confondues, plus recentes d'abord), lists: [{ id, name, company_count, alert_enabled }], total, url (page /lists) }.

Marque comme lus des signaux precis de la veille de l'utilisateur (page /news de l'app Insourcia). Utiliser cet outil quand l'utilisateur indique avoir traite des signaux ("ok j'ai vu", "marque-les comme lus"). Fonctionnement : - Prend les "read_key" renvoyees par get_news, telles quelles ; leur format varie selon le type de signal et n'est pas reconstructible. - Idempotent : une cle deja lue est ignoree (comptee dans already_read), sans erreur ni doublon. - Marquage cible uniquement : il n'existe volontairement pas de "tout marquer lu" via l'API, pour ne pas effacer par erreur la file de tri de l'utilisateur. - N'efface rien : la ligne reste visible dans l'app, elle passe simplement de "nouveau" a "lu". - Ne modifie pas la date de derniere visite de l'utilisateur sur /news. Reponse : { marked_read, already_read, unread_remaining, url (page /news) }.

Rapprochement EN LOT de fiches mal identifiees (CRM, tableur, export CSV) vers leur SIREN. A utiliser pour une LISTE de societes a identifier ("retrouve les SIREN de ces 200 clients"). Pour UNE societe cherchee par son nom, search_companies, qui rend des resultats classes ; celui-ci rend une decision, et refuse de trancher quand il n'est pas sur. Chaque fiche revient avec un status : - resolved : SIREN certain. - review : plusieurs candidats plausibles ou nom trop generique ; les candidats sont retournes et le choix revient a l'utilisateur. - no_match : aucune correspondance. reason explique un review : ambiguous_candidates, weak_name_overlap, shared_domain (site partage par un reseau ; domain_company_count dit combien de societes, fournir un nom ou un code postal), missing_name, invalid_domain, domain_no_match, lookup_failed (panne a rejouer, PAS une absence de correspondance). Conseils : domain (domaine ou URL) resout seul quand il designe une seule societe. Le code postal double quasiment le taux de rapprochement. Un mot en trop dans le nom ("Carrefour Massy") nuit plus qu'un nom tronque. Un siren, siret ou numero de TVA francais est resolu sans recherche. COUT : 1 appel de quota par fiche soumise, quelle que soit sa forme. Retourne results[] (ordre d'entree, avec l'id fourni) et summary{total, resolved, review, no_match}.

Revele l'email PROFESSIONNEL d'un dirigeant identifie (apres get_directors). Offres payantes uniquement (erreur plan_required sinon). COUT : 1 credit du quota mensuel par email trouve. Rien n'est debite si aucun email n'est trouve, ni si le meme email a deja ete revele par ce compte dans les 3 mois. quota_remaining est rendu a chaque reponse. OUTIL UNITAIRE : pas de variante par lot. Boucler sur une liste epuise le quota et declenche une limite horaire. LIRE deliverability_proven : true = adresse verifiee, utilisable ; false = domaine catch-all, existence de la boite non prouvee. email=null avec reason=not_found ou rejected_by_verification : aucun quota consomme, inutile de reessayer. DEUX VITESSES : avec un profil LinkedIn connu (rare), reponse en 10 a 15 s. Sans, la recherche par nom prend ~90 s : l'outil rend status="pending" et un retrieval_token ; RAPPELER l'outil avec ce SEUL parametre apres retry_after_seconds, tant que la reponse est pending. Jeton a usage unique, valable 15 min. Un appel pending ne consomme rien. Ni telephone ni email personnel. RESPONSABILITE : contact professionnel lie a la fonction. L'appelant devient responsable de traitement des reception : base legale, information de la personne au premier contact (mention fournie dans _notice), respect de toute opposition. Reconstituer un fichier est interdit et plafonne.

Recherche d'entreprises francaises par nom, SIREN/SIRET, activite ou criteres (geographie, secteur, effectif, financier, dirigeants, groupe). Pour une societe citee par son nom : trouver le SIREN ici, puis get_company ou get_financials. Effectif et statut departagent les homonymes. - Le siren est dans chaque resultat : ne pas les repasser par resolve_companies (fiches sans identifiant). - Valeurs : un chiffre (ca, ebitda, resultat_net, effectif_moyen, signaux publics...) n'est retourne que s'il figure dans include_fields, meme quand il sert de filtre. 3 champs par recherche (free), 10 (pro). Un nom inconnu est liste dans include_fields_unknown : le corriger plutot que d'appeler get_company ligne par ligne. get_financials sert l'historique multi-annees. - Filtres simples au premier niveau, les deux bornes cote a cote (effectif_min et effectif_max ; idem ca, resultat_net, tresorerie, cagr_ca, date_creation, age_dirigeant). Criteres avances (ratios, CAGR, bilan, delais, signaux publics, fonds, CAC, comptes) dans advanced_filters ; une cle inconnue est rejetee (400). - Groupe : siren_groupe (valeur donnee par get_company) liste toutes les societes du groupe. - Dirigeant : dirigeant_nom + dirigeant_prenom (+ dirigeant_naissance). Inclut les dirigeants remontes via une personne morale ; mandats directs d'une personne : search_director_companies. - Tri : sort_by (relevance, chiffre_affaires, resultat_net, effectif_moyen, date_creation, capital) et sort_order. - Cessions : include_fields=nb_cessions,derniere_cession_date signale les societes a lire dans get_events. 20 resultats par defaut, max 20 (free) ou 100 (pro) ; pagination par cursor sur Pro. COUT : 1 appel de quota par tranche de 20 lignes servies ; la reponse donne _user_plan et le quota restant. Pour suivre la recherche dans le temps : create_saved_search. Retourne l'identite de base de chaque societe (siren, denomination, NAF, localisation, effectif, statut) + include_fields.

Cartographie de l'empreinte corporate d'UNE personne physique : toutes les entreprises ou elle detient un mandat direct, identifiee de facon non ambigue par nom + prenom + date de naissance exacte. C'est le pivot "personne -> entreprises", complement de search_directors (trouver la personne) et get_directors (dirigeants d'une entreprise). Cas d'usage M&A : tracer le perimetre de societes d'un fondateur/dirigeant (holdings, SCI, filiales) sans confondre les homonymes. Parametres TOUS REQUIS : nom, prenom, date_naissance (format YYYY-MM-DD). La date de naissance est obligatoire : c'est elle qui distingue la bonne personne de ses homonymes. L'obtenir au prealable via search_directors ou get_directors (champ date_naissance). Reponse : dirigeant { nom, prenom, date_naissance, annee_naissance } + data[] = entreprises { siren, denomination, role, ville, departement, code_ape, forme_juridique, est_tete_de_groupe } + pagination { total, returned, limit }. Resultat vide = aucun mandat direct trouve pour cette identite exacte (verifier la date_naissance). Note : ne couvre que les mandats DIRECTS de la personne physique (exclut les dirigeants remontes depuis une PM representee, resolved_from_pm). C'est la difference de perimetre avec search_companies(dirigeant_nom/prenom/naissance), qui filtre plus large (inclut ces remontees, granularite mois) et retourne des entreprises, pas une empreinte centree personne. Pour la structure de detention capitalistique d'une entreprise, voir les champs groupe de get_company.

Recherche de personnes (dirigeants) a travers toutes les entreprises francaises, par nom de famille. A la difference de search_companies (qui retourne des ENTREPRISES et accepte dirigeant_nom/dirigeant_prenom comme filtres), search_directors retourne directement des PERSONNES avec leur entreprise de rattachement. Cas d'usage : "toutes les entreprises ou siege un dirigeant nomme DUPONT", cartographie d'un reseau de mandats. Parametres : nom (REQUIS, nom de famille), prenom (optionnel, desambiguise), role (optionnel, ex "President", "Gerant", "Administrateur"). Par defaut seuls les mandats actifs ; include_inactive=true pour inclure les anciens mandats. Reponse : data[] = personnes { nom, prenom, civilite, role, role_description, date_naissance, annee_naissance, lieu_naissance, type_personne, linkedin_url, entreprise { siren, denomination, ville, departement, code_ape } }. linkedin_url n'est present que si un profil a ete apparie avec certitude (plan pro) ; son absence est le cas courant, pas une anomalie. pagination { total (nb entreprises matchees), limit, returned }. Homonymes : un meme nom+prenom recouvre souvent plusieurs personnes distinctes. date_naissance est le champ qui les distingue : deux dates differentes = deux personnes ; date absente = identite non confirmee ; meme date = meme personne. La date est diffusee au MOIS (jour normalise a 01), conformement au regime de diffusion du registre : deux personnes nees le meme mois restent indistinguables. Pour lister TOUTES les entreprises d'une personne donnee une fois sa date de naissance connue, enchainer avec search_director_companies (nom + prenom + date_naissance). Pour la fiche complete d'un dirigeant d'une entreprise donnee, utiliser get_directors avec le SIREN.

Recherche unifiee d'evenements d'entreprise (cross-SIREN), basee sur notre index ES. Renvoie des EVENEMENTS individuels (pas des entreprises) : { date, type, siren, denomination, data }. Couvre 8 types : cession (cessions de fonds), procedure (procedures collectives), depot_comptes, augmentation_capital, marche_public, subvention, radiation, creation. Couvre les evenements BODACC (cessions, procedures collectives, radiations, creations) ainsi que les depots de comptes, augmentations de capital, marches publics et subventions derives des scalaires silver. REGLE : preciser au moins un filtre region / departement / ville / code_naf, OU un filtre d'evenement (date_min, date_max, cedant_siren, cessionnaire_siren, prix_min/max, tribunal, procedure_type) — sinon 400. IMPORTANT : passer UN SEUL type quand la question porte sur un type precis. Les filtres de cadrage (existence de l'evenement, fenetre de dates) ne sont pousses dans la requete que dans ce cas ; avec plusieurs types ils s'excluraient mutuellement, et la recherche se rabat sur un tri general dont on ne lit que les premieres pages — une question pointue y parait vide. Cas d'usage : - "Cessions de fonds > 1M en Ile-de-France depuis 2024" → type="cession", region="Ile-de-France", date_min="2024-01-01", prix_min=1000000 - "Procedures collectives a Lyon" → type="procedure", ville="Lyon" - "Liquidations prononcees a Marseille en juillet 2026" → type="procedure", procedure_type="liquidation", ville="Marseille", date_min="2026-07-01", date_max="2026-07-31" - "Marches publics recents dans le BTP" → type="marche_public", code_naf="4120A"

Retrait d'une societe de la surveillance : l'enleve d'une liste de veille de l'utilisateur (page /lists de l'app Insourcia). Inverse de watch_company. Utiliser cet outil quand l'utilisateur veut ARRETER de suivre une societe ("je ne suis plus interesse par X", "enleve X de ma veille", "nettoie ma liste"). Fonctionnement : - Sans list_name, la societe est retiree de TOUTES les listes de l'utilisateur - c'est le sens naturel de "arrete de surveiller X". Avec list_name, seule cette liste est nettoyee. - Idempotent : si la societe n'est dans aucune liste (ou si la liste nommee n'existe pas), l'appel renvoie removed=false sans erreur. - La liste elle-meme n'est jamais supprimee, meme si elle devient vide. Une alerte active sur la liste reste active pour les autres societes. - Le retrait fonctionne meme pour une societe absente de l'index (radiee, disparue) : ce qui a pu etre ajoute peut toujours etre enleve. list_watched_companies donne le nom exact des listes et les societes qu'elles contiennent. Reponse : { siren, company_name (null si non renseignee), removed, removed_from: [{ list_id, list_name }], url (page /lists) }.

Mise sous surveillance d'une societe : l'ajoute a une liste de veille de l'utilisateur, visible dans l'app Insourcia (page /lists). Utiliser cet outil quand l'utilisateur veut SUIVRE une societe dans le temps (cible d'acquisition, concurrent, client, fournisseur a risque) - pas pour une simple consultation (utiliser get_company). Fonctionnement : - list_name designe la liste cible ; la liste "Surveillance" est utilisee par defaut et creee automatiquement si besoin (idem pour toute liste nommee qui n'existe pas encore). - Idempotent : si la societe est deja dans la liste, l'appel renvoie already_watched=true sans creer de doublon. - enable_alert=true active une alerte quotidienne sur la liste : l'utilisateur est notifie des evenements FUTURS touchant les societes de la liste (annonces BODACC : procedures collectives, cessions... et changements de dirigeants). Pas de replay de l'historique. Reponse : { siren, company_name (null si non renseignee), list_id, list_name, url (page /lists), already_watched, alert_enabled }.