> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corelink.dhi-cm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Polling (Banque → Connecteur)

> Le polling permet à la Banque d’interroger périodiquement le Connecteur afin de récupérer les ordres de paiement prêts à être traités, lorsque le mode Push / Callback n’est pas utilisé ou en complément.

Dans ce mode, la Banque **tire (pull)** les ordres de paiement depuis le Connecteur via une API REST sécurisée.

<Warning>
  **Le polling implique obligatoirement un Callback Push** pour notifier les statuts finaux, car le Connecteur ne peut pas déduire seul l’issue du traitement bancaire.
</Warning>

## A. Principe fondamental du polling

* Le polling est **basé sur un curseur temporel**
* L’`offset` **N’EST PAS un index**, mais une **date d’initiation (**`beforeAt`**)**
* La Banque **contrôle entièrement la progression du curseur**
* La Banque **garantit l’idempotence métier**

> Ce mécanisme est robuste face aux changements de statut asynchrones.

## B. Endpoint de requête d’ordres (côté Connecteur)

La Banque interroge le Connecteur via une requête **HTTP GET sécurisée**.

```bash theme={null}
GET /payment-orders
```

### En-têtes requis

La requête inclut l’ensemble des en-têtes de sécurité suivants :

| En-tête             | Description                         |
| :------------------ | :---------------------------------- |
| `X-Client-Id`       | Identifiant technique du connecteur |
| `X-Request-Id`      | Identifiant de la requête           |
| `X-Timestamp`       | Horodatage ISO 8601 UTC             |
| `X-Nonce`           | Identifiant unique anti-rejeu       |
| `X-Idempotency-Key` | Clé d’idempotence métier            |
| `X-Signature`       | Signature cryptographique du corps  |
| `Authorization`     | OAuth2 (Bearer / DPoP )             |
| `Content-Type`      | `application/json`                  |

Toute requête non signée ou invalide est rejetée.

### Paramètres de requête (Query Params)

| Paramètre | Type               | Obligatoire | Description                                     |
| :-------- | :----------------- | :---------- | :---------------------------------------------- |
| `status`  | string             | Oui         | `INITIATED` ou `PENDING`                        |
| `limit`   | integer            | Oui         | Nombre maximal d’ordres retournés               |
| `offset`  | Instant (ISO-8601) | Oui         | **Date d’initiation minimale (**`beforeAt`**)** |

### Exemple

```bash theme={null}
GET /payment-orders?status=READY&limit=50&offset=2025-11-19T06:00:00Z
```

## C. Réponse du Connecteur

| Code               | Signification       |
| :----------------- | :------------------ |
| **200 OK**         | Ordres disponibles  |
| **204 No Content** | Aucun ordre         |
| **4xx / 5xx**      | Erreur standardisée |

```json theme={null}
{

  "offset": "2025-11-19T06:00:00Z",
  "limit": 50,
  "size": 50,
  "total_elements": 142,
  "content": [
    {
      "reference": "PAY-2025-0001",
      "initiated_at": "2025-11-19T06:05:00Z",
      "reason": "Paiement frais scolaires",
      "type": "DIRECT_DEBIT",
      "debtor": {
        "name": "Jean Dupont",
        "iban": "CM123..."
      },
      "creditors": [
        {
          "name": "École ABC",
          "iban": "CM456...",
          "bank_code": "BANK01",
          "amount": "15000.00",
          "reason": "Tranche 1"
        }
      ],
      "total_amount": "15000.00",
      "currency": "XAF",
      "metadata": {
        "initiator": "school-portal"
      }
    }
  ]
}
```

## D. Gestion de l’offset (Responsabilité Banque)

La Banque :

* **GÈRE elle-même la valeur de l’offset**
* Met à jour l’offset avec :
  * la \*\*plus grande valeur de \*\*`initiated_at`**traitée**
* Garantit :
  * la **non-redemande**
  * la **déduplication**
  * l’**idempotence métier**

> Le Connecteur **ne stocke aucun état de consommation**.

## E. Callback Push OBLIGATOIRE en mode polling

### Règle contractuelle

> **Le Callback Push (Banque → Connecteur) est OBLIGATOIRE lorsque le polling est utilisé.**

### Justification

* Le Connecteur ne sait pas :
  * quand l’ordre est traité
  * s’il a échoué ou réussi
* **Seule la Banque est source de vérité du résultat final**

Sans callback signé :

* l’ordre reste indéfiniment en statut `READY` ou `PENDING`
* l’intégration est considérée comme **non conforme**

## F. Exemple de requêtes de pulling

### cURL

```bash theme={null}
curl -X GET "https://connector.example.com/dhi/payment-orders?status=READY&limit=50&offset=2025-11-19T06:00:00Z" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Timestamp: 2025-11-19T07:05:00Z" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Signature: <signature>"
```