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://es.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úmeroTramo
    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
    23 à 5
    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

    BÚSQUEDA TEXTUAL

    http://es.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://es.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://es.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://es.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://es.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://es.corporama.com/login?h=<el hash o token del usuario>&uri=<La URL del objeto codificado>

     

    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__