Recherche, filtres et pagination

Les routes POST /search du Directory Service utilisent une structure commune.

Cette page sert de référence depuis les pages SIREN, SIRET, codes routage et lignes d'annuaire.

Structure d'une recherche

{
  "filters": {
    "siren": {
      "op": "strict",
      "value": "445023427"
    }
  },
  "fields": [
    "siren",
    "businessName",
    "administrativeStatus"
  ],
  "limit": 20,
  "ignore": 0
}

Les principaux éléments sont :

Élément	Rôle
filters	Critères de recherche appliqués à la ressource
sorting	Critères de tri lorsque la ressource le supporte
fields	Champs à retourner
include	Ressources liées à inclure lorsque la route le permet
limit	Nombre maximal de résultats retournés
ignore	Nombre de résultats à ignorer ; utilisé comme offset

Opérateurs

Les exemples présents dans le folder Directory service (AFNOR) de la collection bcs-tenant-public-api utilisent notamment :

Opérateur	Exemple d'usage
strict	SIREN, SIRET, code postal, statut administratif, identifiant de routage ou adresse devant correspondre exactement
contains	Raison sociale, nom d'établissement ou libellé de code routage contenant une chaîne

Le guide Directory mentionne également startWith. Tous les opérateurs ne sont pas nécessairement disponibles sur tous les champs : le Swagger/OpenAPI fait foi.

contains ne nécessite pas de *

La valeur transmise à contains est la chaîne recherchée elle-même.

Correct :

{
  "name": {
    "op": "contains",
    "value": "GPME SERVICES"
  }
}

À ne pas faire :

{
  "name": {
    "op": "contains",
    "value": "*GPME SERVICES*"
  }
}

Combiner plusieurs critères

Les nouveaux exemples Postman montrent des recherches plus précises en combinant plusieurs filtres.

Nom + code postal + statut administratif

{
  "filters": {
    "name": {
      "op": "contains",
      "value": "GPME SERVICES"
    },
    "postalCode": {
      "op": "strict",
      "value": "34090"
    },
    "administrativeStatus": {
      "op": "strict",
      "value": "A"
    }
  },
  "limit": 20,
  "ignore": 0
}

Cette combinaison permet de réduire les ambiguïtés lorsque plusieurs établissements ont des noms proches.

SIRET + identifiant de routage

{
  "filters": {
    "siret": {
      "op": "strict",
      "value": "70204275500240"
    },
    "routingIdentifier": {
      "op": "strict",
      "value": "SERVICE-COMPTA"
    }
  },
  "limit": 20,
  "ignore": 0
}

Cette combinaison permet de cibler un service ou un circuit précis d'un établissement.

Réponse paginée

Une recherche retourne notamment :

{
  "search": {
    "filters": {},
    "fields": [],
    "limit": 20,
    "ignore": 0
  },
  "totalNumberOfResults": 1,
  "results": []
}

• search rappelle les principaux paramètres de la recherche ;
• totalNumberOfResults indique le nombre total de résultats correspondant aux critères ;
• results contient la page retournée.

Pagination

Si totalNumberOfResults dépasse le nombre de résultats de la première réponse, augmentez ignore tout en conservant exactement les mêmes critères de recherche.

Exemple :

{
  "filters": {
    "businessName": {
      "op": "contains",
      "value": "PC PLACE CANDOLLE"
    }
  },
  "limit": 20,
  "ignore": 0
}

puis, uniquement si cette recherche ciblée contient plus de 20 résultats :

{
  "filters": {
    "businessName": {
      "op": "contains",
      "value": "PC PLACE CANDOLLE"
    }
  },
  "limit": 20,
  "ignore": 20
}

La pagination n'autorise pas l'extraction de l'annuaire

limit et ignore servent à parcourir les résultats d'une recherche ciblée.

Ils ne doivent pas être utilisés pour :

• lancer des requêtes sans critère métier afin de récupérer toutes les pages ;
• parcourir les SIREN/SIRET de manière séquentielle ;
• reconstruire localement les données de l'annuaire ;
• alimenter une base commerciale.

Si votre intégration a besoin d'une copie exhaustive ou d'une synchronisation massive, le Directory Service n'est pas le mécanisme approprié.

Bonnes pratiques

• utilisez un filtre aussi précis que possible ;
• utilisez strict lorsque l'identifiant exact est connu ;
• utilisez contains avec la chaîne recherchée, sans caractères joker ;
• combinez les critères métier utiles pour réduire le nombre de résultats ;
• ne demandez dans fields que les champs nécessaires ;
• utilisez include uniquement lorsque les objets liés sont utiles ;
• arrêtez la pagination dès que le besoin métier est satisfait ;
• privilégiez une route GET directe lorsqu'elle existe et que l'identifiant exact est connu ;
• ne faites pas de polling continu du Directory Service.

➡️ Entreprises et établissements
➡️ Codes routage
➡️ Lignes d'annuaire