Synchroniser les avis

GET /avis a deux modes. Le mode page (dès que q, tri ou page est fourni) est une recherche, limitée à 1 000 résultats. Le mode curseur (celui par défaut) parcourt tous les avis par version croissante : c'est lui qui sert à copier la liste dans votre base, puis à ne redemander que ce qui a changé.

1. Copie complète. Appelez GET /avis?per_page=100 (sans updated_since). Tant que meta.curseur_suivant n'est pas null, rappelez avec curseur=<meta.curseur_suivant>, les mêmes filtres et le même per_page si possible. meta.total (nombre d'avis du parcours) n'est donné que sur la première page. Par défaut seuls les avis ouvert sont servis (statut=clos ou statut=tous pour les autres).
2. Retenez meta.synchronise_jusqu_a de la dernière page.
3. Reprise. Plus tard, rappelez la même boucle avec updated_since=<synchronise_jusqu_a retenu> : vous ne recevez que les avis nouveaux, modifiés ou retirés depuis. Tous les statuts sont servis (statut est refusé avec updated_since). Retenez à nouveau le synchronise_jusqu_a de la dernière page, même quand elle est vide. Un avis déjà copié qui passe clos revient avec statut: "clos" : écrasez-le comme les autres.

BASE=https://publikconnect.fr/api/v1
SINCE=""      # vide pour la copie complète, sinon le synchronise_jusqu_a retenu à la synchronisation précédente
CURSEUR=""
while :; do
  PAGE=$(curl -sf -H "X-API-Key: $PK_API_KEY" -G "$BASE/avis" \
    --data-urlencode "per_page=100" \
    ${SINCE:+--data-urlencode "updated_since=$SINCE"} \
    ${CURSEUR:+--data-urlencode "curseur=$CURSEUR"}) || { echo "arrêt : relancez la même boucle"; exit 1; }
  # À appliquer à votre base : "statut":"retire" => supprimer l'avis par id ; sinon l'écraser par id.
  echo "$PAGE" | jq -c '.data[]' >> changements.jsonl
  CURSEUR=$(echo "$PAGE" | jq -r '.meta.curseur_suivant // empty')
  if [ -z "$CURSEUR" ]; then
    echo "$PAGE" | jq -r '.meta.synchronise_jusqu_a' > prochain_updated_since.txt   # à retenir
    break
  fi
done

Règles :

• Écrasez par id. Un même avis peut revenir (la reprise relit une marge, une page peut être rejouée) : l'écriture doit être idempotente. Comparez au besoin version, un texte à la microseconde (2026-10-08T08:00:00.123456Z) qui avance chaque fois qu'un champ servi change ; comparez-la comme du texte, jamais comme une date.
• Marge de 10 minutes. Aucun avis écrit depuis moins de 10 minutes n'est servi : un avis tout juste publié apparaît en mode curseur au bout de 10 minutes. En contrepartie, synchronise_jusqu_a (« maintenant moins 10 minutes ») ne fait jamais sauter un avis.
• Avis retirés. Avec updated_since, un avis qui n'est plus servi revient sous une forme réduite, à retirer de votre copie : { "id": "…", "statut": "retire", "motif_retrait": "doublon", "canonique_id": "…", "version": "…" }. motif_retrait vaut doublon (l'avis est le doublon d'un autre : canonique_id désigne celui qui le remplace), supprime (l'avis n'existe plus) ou source_coupee (sa source n'est plus servie). Pour les deux derniers, canonique_id est null. Aucun autre champ n'est rendu. Un avis retiré compte comme un enregistrement servi dans le quota.
• Fenêtre de 30 jours. updated_since ne peut pas remonter à plus de 30 jours (la trace d'un avis supprimé n'est gardée que 35 jours) : au-delà, la réponse est un 400 de code resync_required, et il faut refaire une copie complète. Une date dans le futur ou mal formée donne invalid_parameter. updated_since s'écrit en ISO 8601 avec fuseau (2026-10-08T09:50:00Z) ; utilisez la valeur de synchronise_jusqu_a telle quelle.
• Curseur. Il est opaque : ne le fabriquez pas. Il n'est valable qu'avec les filtres (et le même updated_since) de la requête qui l'a produit ; sinon, ou s'il est illisible, la réponse est un 400 de code invalid_cursor et il faut repartir de la première page. Sur la dernière page, curseur_suivant vaut null.
• Sources. Dans ce mode, source accepte aussi le code d'une source coupée, pour que les avis de cette source ressortent « retirés » (source_coupee).