API Corpo search

Nous contacter

Qu'est-ce que l'API Corpo Search ?

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 de 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.

Informations légales

Cette opération permet de retrouver les informations légales d’une société à partir de son SIREN.

http://corporama.com/api/legal

Paramètres

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

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"
       }
    }
}

Quelques précisions

  • 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 :

Entier Tranche
200 N/D
201 1 à 5
202 6 à 9
203 10 à 19
204 20 à 49
205 50 à 99
206 100 à 249
207 250 à 999
208 1000 à 4999
209 + de 5000

 

Champ head_count_slice :

Entier Tranche
0 N/D
1 1 ou 2
2 3 à 5
3 6 à 9
11 10 à 19
12 20 à 49
21 50 à 99
22 100 à 199
31 200 à 249
32 250 à 499
41 500 à 999
42 1000 à 1 999
51 2000 à 4 999
52 5000 à 9 999
53 + de 10 000

 

Tranches de CA

Champ revenue_group :

Entier Tranche
200 N/D
201 Moins de 1 million d’euros
202 1 à 2 million d’euros
203 2 à 6 millions d’euros
204 5 à 10 millions d’euros
205 10 à 50 millions d’euros
206 50 à 100 millions d’euros
207 100 à 200 millions d’euros
208 200 à 500 millions d’euros
209 + de 500 millions d’euros

 

Champ revenue_slice :

Entier Tranche
-1 N/D
0 Moins de 0,5 million d’euros
1 De 0,5 à moins de 1 million d’euros
2 De 1 million à moins de 2 millions d’euros
3 De 2 millions à moins de 6 millions d’euros
4 De 6 millions à moins de 10 millions d’euros
5 De 10 millions à moins de 20 millions d’euros
6 De 20 millions à moins de 50 millions d’euros
7 De 50 millions à moins de 100 millions d’euros
8 De 100 millions à moins de 200 millions d’euros
9 200 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 :
    • 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 (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"}]}
     }
}

Crédits

http://corporama.com/api/credits

Cette opération permet de récupérer le solde de crédits d’un utilisateur Corporama.

Paramètres

  • v : Numéro de version de l’API. Mettre 1
  • user : Token de l’utilisateur récupéré depuis Corporama (voir Lien avec le compte Corporama)

Exemple

http://corporama.com/api/credits?v=1&user=ZZZZZZ&key=XXXXXXXXXX

 

Réponse

Un objet JSON contenant le nombre de crédits restants.

{« credits »:42}

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 »}

Erreurs HTTP

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

  • hashed_key : Il s’agit du hash SHA-256 de votre clef API tel que décrit ici : http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf Par exemple, le hash de ABCD est e12e115acf4552b2568b55e93cbd39394c4ef81c82447fafc997882a02d23677
  • callback_url : Spécifie l’URL où Corporama doit rediriger l’utilisateur une fois qu’il s’est authentifié. Nous ajouterons un paramètre à cette URL en fonction du résultat de l’authentification (voir plus bas). Attention : cette URL doit être correctement URL-encodée.

 

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 :

Soit C le chemin sur corporama.com (depuis /) à encoder

C64 est la version base64 de C

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__