# Déclarer ce qui a été fourni pour un compte, sur une période

`POST /transactions/v1/coverage-windows` — Transaction Intelligence · [Référence API](https://developer.noryo.app/fr-FR/transaction-intelligence/reference)

Authentification : `txnApiKey` (http bearer).

Une couverture est un fait de compte et de période, pas de transaction. Elle répond à « toutes les opérations de ce compte entre ces deux dates vous ont-elles été fournies ? » — et 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. C'est pour cela qu'elle a sa propre ressource plutôt qu'un champ sur l'enrichissement. Sans elle, nous ne dirons jamais qu'une série est en retard : l'absence d'une échéance ne prouve rien tant que nous ignorons si le compte était observé, et `lifecycle.state` reste `unknown`. Et nous ne vérifions rien : ce que vous déclarez est enregistré comme une affirmation d'appelant (`caller_asserted`). La provenance n'est pas un champ que vous choisissez. L'appel est idempotent par construction : les intervalles qui se touchent fusionnent, donc une synchronisation horaire ne fabrique pas d'intervalles.

## Corps de la requête

`application/json` · requis · Schéma `CoverageWindow`

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `account_hint` | object | oui | Le compte concerné. `iban` quand il en a un, sinon `external_account_id` — votre propre identifiant, pour les cartes, portefeuilles et rails non-SEPA. Au moins l'un des deux. Aucun des deux n'est conservé : nous n'en gardons qu'une empreinte opaque, portée à votre workspace — la même que celle de l'enrichissement, sans quoi la couverture ne croiserait jamais la série qu'elle qualifie. |
| `account_hint.iban` | string | — | Motif : `^[A-Z]{2}[0-9]{2}[A-Z0-9]{10,30}$`. |
| `account_hint.external_account_id` | string · length 1–128 | — | — |
| `covered_from` | string · date | oui | — |
| `covered_to` | string · date | oui | On ne certifie pas ce qui n'a pas encore eu lieu : une date future est refusée. |
| `completeness` | string | — | `complete` signifie quelque chose de précis : vous affirmez que toutes les opérations de ce compte sur cet intervalle nous ont été fournies. C'est la seule valeur qui nous autorise à conclure d'une absence. `partial` et `unknown` n'y autorisent pas — dix appels en octobre peuvent être dix opérations sur cent. Valeurs : `complete`, `partial`, `unknown`. |

## Réponses

| Statut | Description |
| --- | --- |
| `200` | Couverture enregistrée, ou fusionnée avec une voisine. |
| `400` | Corps illisible, ou hôte non déclaré. |
| `401` | Clef absente, inconnue ou révoquée. |
| `403` | Organisation ou workspace inactif. |
| `413` | Corps trop volumineux. |
| `415` | Le corps doit être du application/json. |
| `422` | Schéma fermé : champ inconnu, compte absent ou malformé, jour inexistant, intervalle inversé ou dans le futur, complétude inconnue. `errors[].code` nomme la règle, et la liste est celle du runtime, par construction : `must_be_object`, `unknown_field`, `required`, `malformed_iban`, `must_be_non_empty_string`, `too_long`, `contains_control_character`, `account_identity_required`, `must_be_iso_date`, `after_covered_to`, `unknown_completeness`, `interval_in_future`. `must_be_iso_date` couvre la forme et le calendrier (`2026-02-30` est refusé). `interval_in_future` : `covered_to` au-delà de demain, date du serveur en UTC. `provenance` n'est pas un champ d'entrée : le schéma fermé le refuse `unknown_field`, la base ne le voit jamais. |
| `429` | `rate_limited` : la limite opérationnelle de débit est atteinte, pour cette clef ou pour le workspace (le `detail` le dit). Rien n'a été calculé, rien n'a été rangé, aucun événement n'a été émis. Rejouez après `Retry-After`. Voir `x-noryo-rate-limit`. |
| `500` | Erreur interne. |

### `200` — `CoverageWindowResult`

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `covered_from` | string · date | oui | — |
| `covered_to` | string · date | oui | — |
| `completeness` | string | oui | Valeurs : `complete`, `partial`, `unknown`. |
| `provenance` | string | oui | Toujours `caller_asserted` : nous enregistrons ce que vous affirmez, nous ne le vérifions pas, et vous ne pouvez pas déclarer autre chose. Valeurs : `caller_asserted`. |
| `merged_intervals` | integer ≥ 0 | oui | — |
| `policy_version` | string | oui | — |
| `note` | string | — | — |
| `request_id` | string | oui | — |

Exemple — enregistree

```json
{
  "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…"
}
```

Exemple — Deux déclarations qui se touchent n'en font qu'une.

```json
{
  "covered_from": "2026-07-01",
  "covered_to": "2026-08-15",
  "completeness": "complete",
  "provenance": "caller_asserted",
  "merged_intervals": 1,
  "policy_version": "cov_v1",
  "note": "",
  "request_id": "req_01J9…"
}
```

## Erreurs nommées par le contrat

- [`invalid_api_key`](https://developer.noryo.app/fr-FR/transaction-intelligence/errors/invalid_api_key)
- [`account_inactive`](https://developer.noryo.app/fr-FR/transaction-intelligence/errors/account_inactive)
- [`request_entity_too_large`](https://developer.noryo.app/fr-FR/transaction-intelligence/errors/request_entity_too_large)
- [`unsupported_media_type`](https://developer.noryo.app/fr-FR/transaction-intelligence/errors/unsupported_media_type)
- [`rate_limited`](https://developer.noryo.app/fr-FR/transaction-intelligence/errors/rate_limited)
- [`internal_error`](https://developer.noryo.app/fr-FR/transaction-intelligence/errors/internal_error)

## Limites de débit

Cette opération consomme la limite de débit `debit_ti_v1`.

`debit_ti_v1` — operational_burst_protection · token_bucket

- par clé : 120 requêtes / minute (capacité 120, recharge 2/s)
- par workspace : 600 requêtes / minute (capacité 600, recharge 10/s)

« 120 requetes / minute » est traduit en seau a jetons : capacite 120 (la rafale toleree) rechargee a 2 jetons / seconde (le regime durable). Une clef au repos peut envoyer 120 requetes d'un coup, puis 2 par seconde ; sur la premiere minute apres un repos, jusqu'a 240 passent. Le workspace, lui, borne la somme de toutes ses clefs a 600 / minute (capacite 600, 10 / s) : cent clefs ne font pas cent fois la limite.

Ce n'est pas : `sandbox_lifetime_quota`, `production_usage_quota`, `billing_entitlement`, `commercial_promise`.

## Exemples de requête

cURL

```bash
# The contract publishes no example body for this operation: build it from the request schema.
curl -sS -X POST 'https://api.noryo.app/transactions/v1/coverage-windows' \
  -H "Authorization: Bearer $NORYO_API_KEY"
```

JavaScript

```js
const response = await fetch("https://api.noryo.app/transactions/v1/coverage-windows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
  },
  // The contract publishes no example body for this operation: build it from the request schema.
});
console.log(response.status, await response.text());
```

Python

```python
import os

import requests  # pip install requests

response = requests.post(
    "https://api.noryo.app/transactions/v1/coverage-windows",
    headers={
        "Authorization": "Bearer " + os.environ["NORYO_API_KEY"],
    },
    # The contract publishes no example body for this operation: build it from the request schema.
)
print(response.status_code, response.text)
```

Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	// The contract publishes no example body for this operation: build it from the request schema.
	req, err := http.NewRequest("POST", "https://api.noryo.app/transactions/v1/coverage-windows", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NORYO_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.StatusCode, string(data))
}
```

Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        // The contract publishes no example body for this operation: build it from the request schema.
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.noryo.app/transactions/v1/coverage-windows"))
            .method("POST", HttpRequest.BodyPublishers.noBody())
            .header("Authorization", "Bearer " + System.getenv("NORYO_API_KEY"))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

C#

```csharp
using System;
using System.Net.Http;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.noryo.app/transactions/v1/coverage-windows");
request.Headers.TryAddWithoutValidation("Authorization", "Bearer " + Environment.GetEnvironmentVariable("NORYO_API_KEY"));
// The contract publishes no example body for this operation: build it from the request schema.

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

---

Page canonique : https://developer.noryo.app/fr-FR/transaction-intelligence/reference/declare-coverage-window