API Corpo search

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 ou bien de la passer dans un en-tête Authorization de type Bearer. 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 supplémentaire 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.

https://corporama.com/api/legal

PARAMÈTRES

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

EXEMPLE

https://corporama.com/api/legal?v=3&siren=521286443&key=XXXXXXXXXX

RÉPONSE

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

{
        "response": {
            "version": "3",
            "operation": "legal",
            "query": {
                "siren": "521286443"
            },
            "legal": {
                "active": 1,
                "capital": 538093,
                "creation_date": "25/03/2010",
                "description": "Recherche, agrégation et veille d'information",
                "mails": "contact@corporama.com",
                "NAF": "8299Z",
                "NAF_label": "Autres activités de soutien aux entreprises n.c.a.",
                "name":"CORPORAMA",
                "establishments": [
                    {
                        "NIC": "00010",
                        "active": 0,
                        "head_count_slice": 1,
                        "main": 0,
                        "street": "6 Rue DU NORD",
                        "zip": "92160",
                        "city":"ANTONY" 
                    },
                    {
                        "NIC": "00028",
                        "active": 0,
                        "head_count_slice": 3,
                        "main": 0,
                        "street": "5 Cité GERMAIN PILON",
                        "zip": "75018",
                        "city": "PARIS 18"
                    },
                    {
                        "NIC": "00036",
                        "active": 0,
                        "head_count_slice": 2,
                        "main": 0,
                        "street": "148 Rue DES PYRENEES",
                        "street2": "148 AU 154",
                        "zip": "75020",
                        "city": "PARIS 20"
                    },
                    {
                        "NIC": "00044",
                        "active": 0,
                        "coords": {
                            "lat": 48.829498291015625,
                            "lon": 2.261229991912842
                        },
                        "fax": "09 72 38 00 58",
                        "head_count_slice": 11,
                        "main": 1,
                        "name": "CORPORAMA",
                        "street": "18 Rue SOLEILLET",
                        "street2": "18-20",
                        "zip": "75020",
                        "city": "PARIS 20"
                    },
                    {
                        "NIC": "00051",
                        "active": 1,
                        "coords": {
                            "lat": 48.828777,
                            "lon": 2.2635214
                        },
                        "head_count_slice": 11,
                        "main": 1,
                        "name": "CORPORAMA",
                        "phone": "01 71 16 31 16",
                        "street": "8 Rue ROUGET DE LISLE",
                        "street2": "AXE SEINE IMM A",
                        "zip": "92130",
                        "city": "ISSY LES MOULINEAUX"
                    }
                ],
                "head_count_slice": 11,
                "leaders": [
                    {
                        "gender": "M.",
                        "firstname": "Alexandre",
                        "lastname": "SIDOMMO",
                        "position": "Président",
                        "position_code": "1300"
                    },
                    {
                        "company": "SOCIETE MAZARS",
                        "position": "Commissaire aux comptes titulaire",
                        "position_code": "300"
                    },
                    {
                        "gender": "M.",
                        "firstname": "Guy",
                        "lastname": "ISIMAT-MIRIN",
                        "position": "Commissaire aux comptes suppléant",
                        "position_code": "303"
                    }
                ],
                "revenue_K": 2101,
                "revenue_p_export": "1.72",
                "revenue_slice": 3,
                "revenue_type": "R",
                "EBE": 621529,
                "equity": "411915.00",
                "revenue_year": "2016",
                "SIRET": "52128644300051",
                "status": "SAS",
                "status_code": 5710,
                "street": "8 Rue ROUGET DE LISLE",
                "street2": "AXE SEINE IMM A",
                "zip": "92130",
                "city": "ISSY LES MOULINEAUX",
                "VAT_number": "FR24521286443",
                "website": "https://corporama.com"
            }
        }
}

QUELQUES PRÉCISIONS

• Les champs sans information ne sont pas présents
• La liste détaillée des champs correspondant à votre clef API peut être récupérée à l’addresse https://corporama.com/api/legal/doc?v=3&key=XXXXX
• 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_XXX et head_count_XXX sont des entiers représentant des tranches dont voici les correspondances :

Nombre de salariés par tranches d’effectifs :

Champ head_count_group :

Champ head_count_slice :

Tranches de CA

Champ revenue_group :

Champ revenue_slice :

Recherches textuelles

https://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É)

https://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

https://corporama.com/api/credits

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

PARAMÈTRES

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

EXEMPLE

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

RÉPONSE

Un objet JSON contenant le nombre de crédits restants si un paramètre user a été passé :

{"credits":42}

ou bien un objet JSON contenant le détail de consommation de la clef API. La section « used » décrit l’utilisation dans la période et la section « allowed » le maximum autorisé dans la période. « forever » signifie « pas de limite de temps » 

{
  "used": {
    "legal": 95764
  },
  "allowed": {
    "search": "no_limit",
    "legal": {
      "145474": "forever"
    }
  }
}

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 – No credit left : Le compte utilisé n’a plus de crédits
• 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 »}

Paramétrer user

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 :

https://corporama.com/login/request_token?hashed_key=&callback_url=

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

Paramétrer user

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

https://corporama.com/login?h=&uri=

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 :

https://corporama.com/login?h=b5c7631fa&uri=L3NlYXJjaD9jb21wYW55PUVERg__