API Corpo search

Contacte con nosotros

¿QUÉ ES LA API CORPO SEARCH ?

Corporama pone a tu disposición un web-service en forma de API REST que permite recuperar el contenido de las fichas de empresa para integrarlas en sus páginas.

Para saber más sobre la API, sobre su modo de utilización o para la obtención de una clave API, no dudes en contactar con nosotros.

CLAVE API

Una vez que haya obtenido la clave, solo tiene que añadir el parámetro key= a todas sus búsquedas HTTP. Cada búsqueda con cada clave puede ser facturada. Por favor, no haga que esta clave sea visible en sus aplicaciones.

USUARIOS

Tu clave API puede servir para varios usuarios. Por ejemplo, si eres un editor de CRM, puedes utilizar la API Corporama para que sus clientes puedan rellenar tus fichas automáticamente. En este caso, puedes enviarnos un argumento suplementario usuario= que nos permitirá hacer un descuento  de búsquedas por usuario.

LIMITACIONES

Para evitar abusos en el servicio, las búsquedas deberán estar separadas por un determinado lapso de tiempo. En función de los contenidos devueltos, este tiempo puede variar.

INFORMACIÓN LEGAL

Esta operación permite encontrar la información legal de una sociedad a partir de su NIF.

http://corporama.com/api/legal

Parámetros

  • nif: identificador de 9 dígitos de la sociedad
  • v : número de versión de la API. <<1.0>>

Respuesta

Una estructura JSON legal que contiene los diferentes campos de la entidad legal.

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

Algunas precisiones

  • Los campos sin información no están presentes.
  • creation_date puede ser una fecha formateada (DD/MM/YYYY) o un año.
  • main especifica si el establecimiento es una sede social (1) o no (0).
  • revenue y head_count son números enteros que representan franjas. Aquí puedes ver las correspondencias:

 

 Número de asalariados por tramo de trabajadores :

Champ head_count_group :

Número Tramo
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

BÚSQUEDA TEXTUAL

http://corporama.com/api/search

Esta operación permite encontrar información como si hicieras una búsqueda en Corporama. La respuesta está estructurada en varios módulos que corresponden a las categorías visibles en la página de resultados. La presencia del parámetro company es obligatorio.

Parámetros:

No olvides codificar correctamente tu búsqueda antes de enviarla.

  • v : número de versión de la API. Poner <<2>>
  • company : nombre de la sociedad (razón social).
  • sources : es la lista de los módulos en los que hacer la búsqueda, separados por una coma. El único módulo accesible por el momento es:
    • legal: información legal. Proporciona una lista de empresas correspondientes a la búsqueda. Cada sociedad incluye su NIF, código CNAE, código postal, nombre y forma jurídica. El NIF, a continuación, puede ser utilizado en una búsqueda de la operación legal.
    • Con este módulo, es posible hacer autocompletar en el nombre de la empresa indicando un formato particular en el parámetro company con el sufijo ‘*, por ejemplo: corporam* o aire+fr*. La lista de empresas que se indiquen permitirá al usuario visualizar una lista, permitiéndole seleccionar el NIF para examinar con la API legal para encontrar la información detallada.

Ejemplo (por empresa)

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

Respuesta

Una estructura JSON que incluye los resultados por módulo.

{"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ÉDITOS

http://corporama.com/api/credits

Esta operación permite recuperar el saldo de créditos de un usuario Corporama.

Parámetros

  • v : Número de versión de la API. Poner 1
  • user : Token del usuario recuperado desde Corporama (ver enlace con la cuenta Corporama=)

Ejemplo

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

Respuesta

Un objeto JSON que contiene el número de créditos restantes.

{“credits”:42}

ERRORES HTTP

Si un error interviene fuera de la gestión propia de los datos, se ha producido un error HTTP:

  • Código 500 Internal error:  un error por nuestra parte… normalmente recibimos una alerta cuando se produce, pero no dudes en indicarnos el problema.
  • Código 502 – Server temporarily overloaded: se está produciendo un alto tráfico de datos que perturba el acceso a los mismos. Inténtelo de nuevo más tarde.
  • Código 400 – Missing version : no has especificado el parámetro v.
  • Código 400 – Missing company : no ha especificado el parámetro companys.
  • Código 401– Missing API key : no ha especificado el parámetro key.
  • Código 401 Bad API key : No se reconoce su clave API. No es la misma que la que le habíamos proporcionado, o no la hemos activado aún en nuestros servidores.
  • Código 403 Quota limit exceeded : Tús búsquedas son demasiado cercanas.
  • Código 403 Period limit exceeded : Has sobrepasado el número de búsquedas autorizadas en el periodo (día/mes…).

ERRORES REFERENTES AL PROCESAMIENTO DE DATOS

Si un módulo no logra proporcionar un resultado para tu búsqueda, mostrará una cadena de caracteres explicativa en su JSON en lugar de la estructura esperada.

Por ejemplo:

{“legal”:”SIREN manquant”}

ERRORES HTTP

Por defecto, las búsquedas API efectuadas se contabilizan y se facturan en un periodo determinado o bien se limitan en número.

Igualmente, puede hacer que el consumo de las búsquedas API de tus usuarios se reste de su número de créditos de exportación si tienen cuentas Corporama. Hay dos formas de proceder:

  1. Indicando el mail de la cuenta Corporama en el parámetro user si ha sido asociado a su clave API anteriormente (entonces el usuario debe contactar con nosotros)
  2. Indicando un token de conexión en este mismo parámetro user. Es entonces cuando debe contactar con nosotros para que activemos este modo de sincronización en su clave.

OBTENCIÓN DE UN TOKEN

Para obtener este parámetro de conexión, tu aplicación debe enviar al usuario a la siguiente URL para que se autentifique en Corporama y autorice su aplicación a hacer el enlace con su cuenta :

http://corporama.com/login/request_token?hashed_key=<hash de tu clave API>&callback_url=<URL de retorno>

 

Detalles de los parámetros

  • hashed_key : se trata del hash SHA-256 de su clave API tal y como está aquí descrito: http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf Por ejemplo, el hash de ABCD est e12e115acf4552b2568b55e93cbd39394c4ef81c82447fafc997882a02d23677
  • callback_url : especifica la URL la que Corporama tiene que redirigir al usuario una vez que se haya autentificado. Añadiremos un parámetro a esta URL en función del resultado de la autentificación (ver más abajo). Atención: esta URL debe estar correctamente URL-codificada.

 

Después de la autentificación

Si la autentificación es correcta, redirigiremos al usuario hacia la callback_url indicada en el parámetro en la etapa precedente. Añadimos el parámetro token que es el valor que asociar al parámetro user en las búsquedas API.

Si hay un problema durante la búsqueda de la página de login, responderemos con un mensaje de error en lugar de mostrar el formulario.

ENLACES AUTOCONECTADOS

Con el token obtenido en la etapa anterior, también puedes crear enlaces en tu CRM o tu Intranet hacia páginas Corporama autoconectando a tus usuarios con tu cuenta Corporama. El uso más corriente es crear un enlace desde una ficha de empresa de tu CRM hacia la ficha Corporama correspondiente indicando el nombre de empresa o tu NIF.

La sintaxis de las URL a integrables es del tipo:

http://corporama.com/login?h=<le hash ou token de l'utilisateur>&uri=<l'URL cible encodée>

 

Como codificar la URL de destino :

O C la ruta en corporama.com (desde/) para codificar.

C64 es la versión base64 de C

 

En C64, remplazar el caracter « = » por « _ » y « + » por « -« . Obtenemos C64_b

 

 

Ejemplo

  • URL a codificar C : /search?company=EDF
  • Token o Hash del usuario : b5c7631fa
  • C64 = L3NlYXJjaD9jb21wYW55PUVERg==
  • C64_b = L3NlYXJjaD9jb21wYW55PUVERg__

El enlace final autoconectado es:

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