Recherche et consultation

GET /api/ccfn/v1/object retourne les objets accessibles dans l’organisation du compte. Il fournit une liste paginée, triée par date de dépôt décroissante. Le droit de liste est distinct du droit de comptage et du droit de lecture du fichier.

Définir les attributs avant le dépôt

metadata contient les informations descriptives de l’objet. search_attributes contient les critères qui doivent être recherchables explicitement : type de document, référence de dossier, code client ou exercice, par exemple.

{
  "external_id": "FACTURE-2026-0042",
  "metadata": {"source": "ERP", "description": "Facture finale"},
  "search_attributes": {"document_type": "invoice", "customer_id": "C-0042", "year": "2026"}
}

Choisissez des valeurs stables et un type constant pour chaque attribut. Les recherches utilisent une normalisation technique : les espaces de début et de fin d’une chaîne sont retirés avant indexation. Utiliser systématiquement des chaînes évite les ambiguïtés entre booléens, nombres et leur représentation dans une URL.

Contraintes des attributs de recherche

Un dépôt et une recherche acceptent jusqu’à 25 attributs. Une clé comporte de 1 à 100 caractères, commence par une lettre ou un chiffre et n’utilise ensuite que lettres ASCII, chiffres, point, tiret ou soulignement. Les valeurs sont scalaires ; les chaînes ne doivent pas dépasser 512 caractères. Les tableaux imbriqués et les valeurs nulles ne sont pas des valeurs de recherche acceptées.

Les attributs metadata ne deviennent pas automatiquement des filtres. Le contenu du document n’est pas indexé en plein texte par cette API.

Filtres de liste et de comptage

Paramètre	Sens
`space_id`	UUID de l’espace
`external_id`	Égalité sur la référence métier, après normalisation
`search_attributes[cle]`	Égalité sur un attribut indexé
`deposited_from`, `deposited_to`	Bornes inclusives de date de dépôt
`retention_from`, `retention_to`	Bornes inclusives de date d’échéance
`page`	Numéro de page, à partir de 1
`per_page`	25 par défaut, 100 maximum

Les critères sont combinés par ET. Aucune recherche par préfixe, intervalle d’identifiants métier, expression régulière ou route /search séparée n’est exposée.

curl --get --user "$CCFN_USER" \
  --data-urlencode 'search_attributes[document_type]=invoice' \
  --data-urlencode 'search_attributes[customer_id]=C-0042' \
  --data-urlencode 'deposited_from=2026-01-01T00:00:00+00:00' \
  --data-urlencode 'per_page=100' \
  "$CCFN_BASE_URL/api/ccfn/v1/object"

Encodez les paramètres d’URL : le signe + d’un fuseau doit notamment être transmis correctement. Pour viser une journée entière avec une borne haute inclusive, transmettez son heure de fin ; une date seule peut être interprétée à minuit.

Pagination et comptage

La réponse de liste contient data et pagination avec total, per_page, current_page, last_page. Parcourez les pages jusqu’à last_page pour récupérer l’ensemble des résultats. Pendant des dépôts concurrents, une pagination par numéro de page ne fournit pas un instantané immuable : dédupliquez les UUID lors d’un export important.

GET /api/ccfn/v1/object/count applique les mêmes filtres métier et retourne data.count. page et per_page ne limitent pas ce total. Le compte doit disposer de CCFN_USER_COUNT, même s’il possède déjà le droit de liste.

Confidentialité et portée

Les recherches exactes sur références et attributs utilisent des index dérivés. Dans un espace chiffré, cette méthode permet de rechercher sans stocker les valeurs métier en clair dans ces index. Les identifiants techniques, clés d’attributs et données de gestion ne deviennent pas pour autant tous confidentiels par ce seul mécanisme.

Les recherches sont limitées à l’organisation. Les métadonnées retournées peuvent elles-mêmes contenir des données sensibles : leur accès et leur export doivent suivre votre politique d’habilitation.

À lire ensuite : Lire et restituer les documents.