API Corpo search

Introduction

Corporama met à votre disposition un webservice sous la forme d'une API
REST permettant de récupérer le contenu des fiches société afin des les intégrer dans vos pages. Pour en savoir plus sur l'API, son mode d'utilisation ou pour l'obtention d'une clef d'API, n'hésitez pas à nous contacter.

Clef d'API

Une fois la clef obtenue, il suffit d'ajouter le paramètre key= à tous vos appels HTTP. Chaque appel avec cette clef peut être facturé. Veillez donc ne pas rendre cette clef visible dans vos applications.

Utilisateurs

Votre clef d'API peut servir pour plusieurs utilisateurs. Par exemple, vous êtes un éditeur de CRM, et vous utilisez l'API Corporama pour que vos clients puissent remplir leurs fiches automatiquement. Dans ce cas, vous pouvez nous passer un argument supplementaire user= qui nous permettra de faire un décompte de requêtes par utilisateur.

Limitations

Afin d'éviter les abus du services, les requêtes devront être espacées d'un certain laps de temps. En fonction des contenus retournés, cette temporisation peut varier.

Opérations disponibles

Informations légales

http://corporama.com/api/legal
Cette opération permet de retrouver les informations légales d'une société à partir de son SIREN.

Paramètres

  • siren : identifiant à 9 digits de la société
  • v : numéro de version de l'API. Mettre "1.0"

Exemple

http://corporama.com/api/legal?v=1.0&siren=521286443&key=XXXXXXXXXX

Réponse

Une structure JSON legal contenant les différents champs de l'entité légale.

response: {
    version: "1.0",
    operation: "legal",
    query: {
        siren: "521286443"
    },
    legal: {
        NAF: "8299Z",
        NAF_label: "Autres activités de soutien aux entreprises n.c.a.",
        TVA_number: "FR24521286443",
        active: 1,
        capital: 538093,
        creation_date: "01/03/2010",
        description: "Recherche, agrégation et veille d'information",
        establishments: [
             {
                 NIC: "00028",
                 active: 0,
                 city: "PARIS 20",
                 main: 1,
                 phone: "0171163116",
                 street: "18-20 rue Soleillet",
                 zip: "75020"
             },
             {
                 NIC: "00036",
                 active: 0,
                 city: "PARIS 20",
                 main: 0,
                 street: "148 Rue DES PYRENEES",
                 zip: "75020"
             },
             {
                 NIC: "00044",
                 active: 1,
                 city: "PARIS 20",
                 coords: {
                     lat: 48.865592,
                     lon: 2.391996
                 },
                 fax: "0972380058",
                 head_count_slice: 3,
                 main: 1,
                 name: "CORPORAMA",
                 phone: "0171163116",
                 street: "18 Rue SOLEILLET",
                 zip: "75020"
             }
        ],
        head_count_group: 203,
        head_count_slice: 11,
        leaders: [
            {
                 firstname: "Alexandre",
                 lastname: "SIDOMMO",
                 position: "Président"
            }
        ],
        name: "CORPORAMA",
        revenue_K: 1994,
        revenue_group: 202,
        revenue_slice: 2,
        revenue_type: "E",
        revenue_year: "2013",
        status: "SAS",
        status_code: 5710,
        website: "corporama.com"
       }
    }
}
          
  • Les champs sans information ne sont pas présents
  • creation_date peut être une date formatée (DD/MM/YYYY) ou une année
  • main spécifie si l'établissement est un siège social (1) ou pas (0)
  • revenue et head_count sont des entiers représentant des tranches dont voici les correspondances:

    Nombre de salariés par tranches d'effectifs:

    Champ head_count_group :

    EntierTranche
    200N/D
    2011 à 5
    2026 à 9
    20310 à 19
    20420 à 49
    20550 à 99
    206100 à 249
    207250 à 999
    2081000 à 4999
    209+ de 5000

    Champ head_count_slice:

    EntierTranche
    0N/D
    11 ou 2
    36 à 9
    1110 à 19
    1220 à 49
    2150 à 99
    22100 à 199
    31200 à 249
    32250 à 499
    41500 à 999
    421000 à 1 999
    512000 à 4 999
    525000 à 9 999
    53+ de 10 000

    Tranches de CA

    Champ revenue_group :

    EntierTranche
    200N/D
    201Moins de 1 million d'euros
    2021 à 2 million d'euros
    2032 à 6 millions d'euros
    2045 à 10 millions d'euros
    20510 à 50 millions d'euros
    20650 à 100 millions d'euros
    207100 à 200 millions d'euros
    208200 à 500 millions d'euros
    209+ de 500 millions d'euros

    Champ revenue_slice :

    EntierTranche
    -1N/D
    0Moins de 0,5 million d'euros
    1De 0,5 à moins de 1 million d'euros
    2De 1 million à moins de 2 millions d'euros
    3De 2 millions à moins de 6 millions d'euros
    4De 6 millions à moins de 10 millions d'euros
    5De 10 millions à moins de 20 millions d'euros
    6De 20 millions à moins de 50 millions d'euros
    7De 50 millions à moins de 100 millions d'euros
    8De 100 millions à moins de 200 millions d'euros
    9200 millions d'euros ou plus

Recherche textuelle

http://corporama.com/api/search
Cette opération permet de retrouver des informations comme si vous faisiez une recherche sur Corporama. La réponse est structurée en plusieurs modules qui correspondent aux rubriques visibles dans la page de résultats. La présence du paramètre company est obligatoire.

Paramètres

N'oubliez de d'
encoder correctement votre requête avant de l'envoyer.
  • v : numéro de version de l'API. Mettre "2"
  • company : nom de la société (raison sociale).
  • sources : la liste des modules dans lesquels faire la recherche, séparés par une virgule. Le seul module interrogeable pour le moment est :
    1. legal: informations légales, retourne une liste de sociétés correspondant à la recherche. Chaque société comprend ses SIREN, NAF, libellé NAF, code postal, nom et forme juridique. Le SIREN peut ensuite être utilisé dans un appel à l'opération legal

      Avec ce module, il est possible de faire de l'autocompletion sur le nom de société en saisissant un format particulier dans le paramètre company avec le suffixe '*', par exemple : corporam* ou air+fr*. La liste de sociétés retournées vous permettra d'afficher une liste à l'utilisateur, lui permettant de sélectionner le SIREN à interroger avec l'API legal pour retrouver les informations détaillées.

Exemple 1 (par société)

http://corporama.com/api/search?v=2&company=corporama&key=XXXXXXXXXX

Réponse

Une structure JSON comprenant les résultats par module.

{"response":
     {"version":"1.0",
      "operation":"search",
      "query":{"company":"corporama"},
      "results":
          {"legal":
               [{"name":"Corporama",
                 "SIREN":"521286443",
                 "NAF":"8299Z",
                 "NAF_label":"Autres activités de soutien aux entreprises n.c.a.",
                 "status_group_label":"SA et SAS",
                 "zip":"75020"}]}
     }
}
          

Erreurs retournées

Erreurs HTTP

Si une erreur intervient en dehors du traitement même des données, une erreur HTTP est retournée:
  • Code 500 - Internal error : un bug de notre côté... normalement nous sommes alertés lorsque celà se produit, mais n'hésitez pas à nous remonter le problème
  • Code 502 - Server temporarily overloaded : nos services subissent un pic de traffic qui perturbent l'accès aux données. Veuillez rééessayer ultérieurement
  • Code 400 - Missing version : vous n'avez pas spécifié le paramètre v
  • Code 400 - Missing company : vous n'avez pas spécifié le paramètre company
  • Code 401 - Missing API key : vous n'avez pas spécifié le paramètre key
  • Code 401 - Bad API key : Votre clef d'API n'est pas reconnue. Soit ce n'est pas la même que celle que nous vous avons fait parvenir, soit nous ne l'avons pas encore activée sur nos serveurs
  • Code 403 - Quota limit exceeded : Vos requêtes sont trop rapprochées
  • Code 403 - Period limit exceeded : Vous avez dépassé le nombre de requêtes autorisées sur la période (jour/mois...)

Erreurs concernant le traitement des données

Si un module ne réussit pas à fournir un résultat pour votre recherche, il retournera une chaîne de caractères explicative dans le JSON à la place de la structure attendue. Par exemple:
{"legal":"SIREN manquant"}
          

Lien avec le compte Corporama

Par défaut les requêtes API effectuées sont comptabilisées puis facturées sur une période donnée ou bien limitées en nombre.

Vous pouvez également faire en sorte que la consommation de requêtes API de vos utilisateurs soit débitée de leur nombre de crédits d'exports s'ils ont des comptes Corporama. Deux manières de procéder :

  1. En passant le mail du compte Corporama dans le paramètre user s'il a été associé à votre clef API au préalable (l'utilisateur doit alors nous contacter)
  2. En passant un token de connexion dans ce même paramètre user. C'est alors à vous de nous contacter pour que nous activions ce mode de synchronisation sur votre clef.

Obtention d'un token

Pour obtenir ce paramètre de connexion, votre application doit envoyer l'utilisateur sur l'URL suivante afin qu'il s'authentifie sur Corporama et autorise votre application à faire le lien avec son compte :
http://corporama.com/login/request_token?hashed_key=<hash de votre clef API>&callback_url=<URL de retour>
          

Détail des paramètres

Après l'authentification

Si l'authentification s'est bien passée, nous redirigeons l'utilisateur vers la callback_url passée en paramètre à l'étape précédente. Nous y ajoutons le paramètre token qui est la valeur à associer au paramètre user dans les appels API.

S'il y a un problème lors de l'appel à la page de login, nous répondrons par un message d'erreur au lieu d'afficher le formulaire

Liens auto-connectés

Avec le token obtenu à l'étape précédente, vous pouvez également fabriquer des liens dans votre CRM ou votre Intranet vers des pages Corporama en auto-connectant vos utilisateurs avec leur compte Corporama. L'usage le plus courant est de créer un lien depuis une fiche société de votre CRM vers la fiche Corporama correspondante en passant le nom de société ou son SIREN

La syntaxe des URL à intégrer est du type
http://corporama.com/login?h=<le hash ou token de l'utilisateur>&uri=<l'URL cible encodée>

Comment encoder l'URL cible :

  1. Soit C le chemin sur corporama.com (depuis /) à encoder
  2. C64 est la version base64 de C
  3. Dans C64, remplacer le caractère "=" par "_" et "+" par "-". On obtient C64_b

Exemple

  • Chemin à encoder C :
    /search?company=EDF
  • Token ou Hash de l’utilisateur :
    b5c7631fa
  • C64 =
    L3NlYXJjaD9jb21wYW55PUVERg==
  • C64_b =
    L3NlYXJjaD9jb21wYW55PUVERg__
Le lien final auto-connecté est donc :
http://corporama.com/login?h=b5c7631fa&uri=L3NlYXJjaD9jb21wYW55PUVERg__

Connectez Corporama à votre CRM

Gagner en temps et en efficacité en connectant Corporama à votre CRM, qu'il soit un outil du marché ou un CRM maison.

Voir nos partenaires CRM

Suivez-nous !

Soyez informé de toute notre actualité.
Restons en contact !