Ajout documentation

# API SIRENE SIRET

*Oscar* permet d'interroger l'[API SIRENE](https://www.sirene.fr) de l'INSEE afin de compléter automatiquement une fiche d'organisation à partir d'un numéro SIRET ou bien à partir d'une recherche par dénomination légale de l'entité.

## Configuration

La première étape pour faire fonctionner l'API SIRENE consiste à définir sa configuration. Il existe deux possibilités :

 * interroger directement l'API SIRENE (https://portail-api.insee.fr/)

   * Nécessite de se créer un compte pour obtenir une clé d'API

   * Avantages : données toujours à jour

   * Inconvénient : limite du nombre de requêtes par minute (non adapté à un traitement "batch")

 * télécharger les fichiers de données brutes fournis par l'INSEE ([ici](https://www.data.gouv.fr/fr/datasets/base-sirene-des-entreprises-et-de-leurs-etablissements-siren-siret/))

   * Avantages : pas de limites de requêtes par minute (adapté à un traitement "batch")

   * Inconvénient : données pas à jour, nécessite de l'espace disque et un disque rapide en lecture

Pour activer cette API, il faut ajouter les variables suivants dans votre fichier [config/autoload/local.php](../config/autoload/local.php)

```php

<?php

// /config/autoload/local.php

return array(

    'oscar' => [

        'siret' => [

            'chemin_fichier_stock_etablissement' => '/chemin/vers/StockEtablissement_utf8.csv', // StockEtablissement_utf8.csv

            'chemin_fichier_stock_unite_legale' => '/chemin/vers/StockUniteLegale_utf8.csv', // StockUniteLegale_utf8.csv

            'api_key' => '123456-1234-1234-1234-123456789012', // X-INSEE-Api-Key-Integration

        ],

    ]

);

```

Attention, les fichiers doivent être accessibles en lecture à l'utilisateur système du serveur web (www-data) et cet utilisateur doit pouvoir lancer la commande `grep`.

Si vous optez pour une connexion par clé d'API, vous pouvez laisser vide les clés des fichiers. Et inversement si vous optez uniquement pour les sources de données fichiers.

## Vérification de la configuration

Vous pouvez vérifier si la configuration est correctement renseignée à deux endroits dans l'application :

 * Sur la page de création d'une nouvelle organisation, en renseignant un SIRET et en cliquant sur le bouton "Compléter automatiquement"

 * Sur la page de recherche par dénomination d'unité légale, accessible en cliquant sur le bouton "Pré-remplir via une recherche dans les bases de données publiques SIRENE ou ROR" accessible en haut à droite de la page de création d'une nouvelle organisation.

## Fonctionnement interne

Aujourd'hui le fonctionnement est le suivant :

 * pour une recherche par SIRET, si les fichiers sont renseignés dans la configuration, alors le service commence par rechercher dans les fichiers. Si aucune entrée correspondante n'est trouvée et que la clé d'API est renseignée, alors le service interroge l'API.

 * pour une recherche par dénomination d'unité légale, seule l'API est interrogée, en filtrant uniquement sur les établissement situés en France.