Couverture d'observation

Une couverture d'observation (coverage window) est une déclaration : « toutes les opérations de ce compte, entre ces deux dates, vous ont été fournies ». C'est un fait de compte et de période, pas de transaction. Elle a sa propre ressource, POST /transactions/v1/coverage-windows, et non un champ de POST /transactions/v1/enrichments, parce qu'elle existe précisément quand il n'y a aucune transaction à envoyer : un mois sans prélèvement est le cas où la déclaration compte le plus.

Pourquoi une absence ne prouve rien

Transaction Intelligence sait dire qu'une échéance attendue n'est pas arrivée. Il ne sait pas, seul, si elle n'a pas eu lieu ou si personne ne la lui a envoyée. Sans cette distinction, « le client a cessé d'appeler l'API » et « l'abonnement a cessé de prélever » seraient une seule et même chose.

La couverture ne se déduit jamais du trafic : dix appels en octobre peuvent être dix opérations sur cent. Elle exige une déclaration explicite par compte et par période. Tant qu'elle manque, lifecycle.state reste unknown, jamais late : « je n'ai rien vu » ne devient pas « il n'y a rien eu ».

Déclarer une couverture

Le corps est un CoverageWindow, schéma fermé : tout champ inconnu est refusé (422).

Le compte se nomme par account_hint : iban quand il en a un, sinon external_account_id, votre propre identifiant pour les cartes, portefeuilles et rails sans IBAN. Au moins l'un des deux est requis (account_identity_required). Aucun des deux n'est conservé : Noryo n'en garde qu'une empreinte opaque, portée à votre workspace, la même que celle calculée sur l'enrichissement. Employez le même account_hint dans les deux appels : une transaction envoyée sans lui n'a pas de source, et aucune couverture ne la croisera.

covered_from et covered_to sont des dates de la forme 2026-07-01. Un jour inexistant est refusé (must_be_iso_date), un intervalle inversé aussi (after_covered_to). On ne certifie pas ce qui n'a pas encore eu lieu : un covered_to au-delà de demain, date du serveur en UTC, est refusé (interval_in_future).

Le sens exact de completeness

complete a un sens précis : toutes les opérations du compte sur l'intervalle ont été transmises, y compris quand il n'y en avait aucune. C'est la seule valeur qui autorise à lire une absence comme un manque.

La provenance n'est pas une entrée

La réponse porte provenance: caller_asserted, toujours. Ce n'est pas un champ que vous choisissez : Noryo enregistre ce que vous affirmez, ne le vérifie pas, et vous ne pouvez pas déclarer autre chose. Envoyer provenance dans le corps est refusé comme unknown_field.

Réponse et fusion d'intervalles

La réponse est un 200 dans les deux cas, enregistrée seule ou fusionnée avec une voisine. covered_from et covered_to sont les bornes après fusion. merged_intervals compte les intervalles préexistants que la déclaration a absorbés :

Deux intervalles du même compte qui se touchent ou se chevauchent n'en font qu'un : une synchronisation horaire ne fabrique pas d'intervalles, et un rejeu exact rend 1 parce que la déclaration absorbe sa propre copie. L'appel est idempotent par construction, sans en-tête Idempotency-Key.

Ce que la couverture change dans une série

La couverture agit sur l'axe lifecycle d'une série récurrente (voir Cycle de vie d'une série). Pour chaque échéance close, Noryo vérifie que chaque source de la série était couverte complete sur toute la fenêtre attendue (expected_next_window, de from à to) ; une couverture qui n'en contient qu'une partie ne permet pas de conclure.

consecutive_misses n'avance que sous couverture complète. ended n'est jamais produit par une accumulation d'absences, avec ou sans couverture : il exige une preuve terminale explicite.

Ce que la couverture ne change pas : status (à quel point c'est une série) et history_coverage.sufficiency (peut-on croire la cadence). Ces deux lectures dépendent des occurrences observées, pas de vos déclarations.

Ce que Noryo ne vérifie pas

Noryo n'interroge pas votre banque et ne compare pas vos déclarations à vos envois. Une couverture complete déclarée sur une période où des opérations manquaient produira des late et des inactive qui n'existent pas : la déclaration engage l'appelant. Le contrat n'expose ni lecture ni retrait d'une déclaration : déclarez ce que vous savez, au rythme de votre synchronisation.

Exemples

Un compte SEPA, juillet fourni intégralement :

curl -X POST https://api.noryo.app/transactions/v1/coverage-windows \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_hint": { "iban": "FR7630006000011234567890189" },
    "covered_from": "2026-07-01",
    "covered_to": "2026-07-31",
    "completeness": "complete"
  }'

{
  "covered_from": "2026-07-01",
  "covered_to": "2026-07-31",
  "completeness": "complete",
  "provenance": "caller_asserted",
  "merged_intervals": 0,
  "policy_version": "cov_v1",
  "note": "",
  "request_id": "req_01J9…"
}

Une carte prépayée, nommée par votre identifiant, synchronisation partielle :

const response = await fetch("https://api.noryo.app/transactions/v1/coverage-windows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account_hint: { external_account_id: "carte-4970" },
    covered_from: "2026-08-01",
    covered_to: "2026-08-31",
    completeness: "partial",
  }),
});

const coverage = await response.json();
console.log(response.status, coverage.merged_intervals, response.headers.get("noryo-request-id"));

Refus propres à cette route

Un 422 rend un Problem de type invalid_input, dont errors[].code nomme la règle : unknown_field (champ hors schéma, provenance compris), required (account_hint absent ou qui n'est pas un objet), account_identity_required, malformed_iban, must_be_iso_date (date absente, mal formée ou jour inexistant), after_covered_to, interval_in_future, unknown_completeness. La liste complète, must_be_object, must_be_non_empty_string, too_long et contains_control_character compris, figure dans l'opération ci-dessus et sur /errors/invalid_input.

Les autres réponses (400, 401, 403, 413, 415, 429, 500) sont communes à l'API. Cette route compte dans les limites de débit ; un 422 consomme un jeton, la clé ayant été validée. Catalogue complet : Erreurs.