Erreurs & santé de connexion

Chaque requête envoyée au terminal — un objet JSON par trame, écrit <json>END_JSON — passe par un pipeline fixe. Chaque étape peut rejeter la requête avec un error_code distinct. Cette page est la référence de ces codes, des enveloppes d’erreur, de la sonde de liveness ping→pong, et de la détection d’un port mort avec reconnexion.

Pipeline de traitement (ordre des contrôles)

Le terminal évalue une requête dans cet ordre exact. La première étape qui échoue produit la réponse ; les étapes suivantes ne s’exécutent pas.

Enveloppes d’erreur

Chaque réponse arrive sur le fil comme un objet JSON terminé par END_JSON. Il existe deux formes d’erreur distinctes. Branchez votre logique sur error_code, jamais sur le texte lisible (certains messages sont en français).

Erreur générique (tous les codes sauf VALIDATION_ERROR) :

{"status":"error","invoice_id":"INV-2026-000123","error_code":"DUPLICATE_INVOICE","error_message":"Invoice already exists with this ID: INV-2026-000123","timestamp":1751362800000,"protocol":"TCP"}END_JSON

Erreur de validation (VALIDATION_ERROR uniquement — porte un tableau errors[] et n’a pas de error_message) :

{"status":"error","error_code":"VALIDATION_ERROR","invoice_id":"INV-2026-000123","errors":[{"field":"recipientPhone","message":"Phone number must be in valid Congo format (+242XXXXXXXXX or 0XXXXXXXXX)"},{"field":"currency","message":"Currency must be XAF, USD, or EUR"}],"timestamp":1751362800000,"protocol":"TCP"}END_JSON

Catalogue des codes d’erreur

Décodage strict des enums → INVALID_PAYLOAD

Cinq champs sont des enums décodés strictement. Toute valeur hors de l’ensemble autorisé interrompt le parsing et donne INVALID_PAYLOAD (avec un préfixe Invalid payload:).

Exemple — envoyer "recipientType":"corporation" produit :

{"status":"error","error_code":"INVALID_PAYLOAD","error_message":"Invalid payload: Invalid value 'corporation' for RecipientType. Allowed: [individual, business, government, foreign]","timestamp":1751362800000,"protocol":"TCP"}END_JSON

Règles de validation (VALIDATION_ERROR)

Toutes les règles sont évaluées ensemble ; chaque violation ajoute une entrée errors[] avec le chemin field et le message exacts.

Identification & lignes

Règles destinataire par recipientType

Formats : NIU = exactement 16 ou 17 caractères · Téléphone Congo ^(\+242\|242)?0[456]\d{7}$ · Téléphone international (FOREIGN) ^\+?[1-9]\d{1,14}$ · Email ^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+$.

Messages notables : Recipient name is required for <label> recipients, NIU is required for <label> recipients, NIU must be exactly 16 or 17 characters, Phone number is required for <label> recipients, Phone number must be in valid Congo format (+242XXXXXXXXX or 0XXXXXXXXX), Phone number must be in valid international format, Email is required for <label> recipients, Invalid email format, Address is required for <label> recipients. (<label> vaut business, government ou foreign.)

Cohérence des montants (anti-fraude, tolérance ±0.01)

DUPLICATE_INVOICE et idempotence

Le contrôle de doublon est fondé uniquement sur invoiceId : si l’id existe déjà, la requête échoue en DUPLICATE_INVOICE et aucun nouveau numéro fiscal n’est frappé.

• Traitez DUPLICATE_INVOICE comme un signal de succès idempotent, pas un échec dur. Conservez le numéro fiscal / QR reçu sur la réponse de succès d’origine ; ne réémettez pas et ne renumérotez pas.
• C’est ce qui rend le retry-après-échec sûr. Après un PROCESSING_TIMEOUT ou un lien coupé, renvoyez la requête identique avec le même invoiceId. Vous obtiendrez soit status:"success" (non persistée), soit DUPLICATE_INVOICE (persistée) — les deux confirment la certification. N’allouez jamais un nouvel invoiceId pour un retry.

Logique de gestion (référence)

def handle_response(resp: dict) -> str:
    status = resp.get("status")
    if status == "success":
        return "certified"          # stocker sfec_number + qr_code
 
    code = resp.get("error_code")
    if code == "DUPLICATE_INVOICE":
        return "already_certified"  # succès idempotent : réconcilier, ne PAS renvoyer
 
    if code in ("PROCESSING_ERROR", "PROCESSING_TIMEOUT"):
        # transitoire : retenter le MÊME invoiceId avec backoff ;
        # un DUPLICATE_INVOICE ultérieur confirme le succès.
        return "retry"
 
    if code == "VALIDATION_ERROR":
        for e in resp.get("errors", []):
            log(f"fix {e['field']}: {e['message']}")
        return "fix_and_resend"     # non retentable inchangé
 
    if code in ("INVALID_PAYLOAD", "MESSAGE_TOO_LARGE"):
        return "fix_payload"        # malformé / surdimensionné / mauvais enum
 
    return "unknown_error"

Santé de connexion — sonde ping → pong

Sur un lien actif, la liveness est gratuite : chaque facture envoyée revient en trame success ou error, ce qui prouve déjà que le port est vivant. Pour prouver activement qu’un lien inactif (idle) est en vie, écrivez une trame ping ; le pont répond par une trame pong.

{"type":"ping","timestamp":"2026-07-01T10:30:45.123Z","source":"erp"}END_JSON
{"type":"pong","timestamp":"2026-07-01T10:30:45.456Z","source":"middleware"}END_JSON

Le timestamp est une chaîne ISO-8601 UTC ; le pont ne la valide pas. source vaut "erp" sur votre ping et "middleware" sur la réponse.

Détection d’un port mort

Depuis le client, il existe exactement trois signaux indépendants. Une intégration robuste gère les trois.

Reconnexion avec backoff

Quand l’un des signaux (a)/(b)/(c) se déclenche, fermez COM10 et rouvrez-le, puis reprenez. Il n’y a rien à attendre après la réouverture : dès que COM10 est rouvert, vous pouvez envoyer.

sur DOWN :
    fermer COM10
    delai = 1s
    boucle :
        essayer : ouvrir COM10 ; sortir
        sinon : dormir(delai) ; delai = min(delai * 2, 30s)   # plafond de backoff
    pour chaque facture non acquittée :                       # même invoiceId à chaque fois
        send_frame(ser, inv) ; enregistrer(read_frame(ser))

• Backoff. Réouverture avec backoff exponentiel plafonné + gigue (1 s → 2 s → 4 s → … → 30 s). Gardez le plafond bas pour rétablir la liaison rapidement.
• Si la réouverture échoue en boucle, le port est réellement absent (signal c) : le pont a été arrêté ou le terminal débranché. Redémarrez le pont fourni.
• Ne renvoyez que les factures non acquittées, en réutilisant le même invoiceId. Un DUPLICATE_INVOICE confirme qu’elle était déjà certifiée — arrêtez de retenter (récupérez le numéro fiscal / QR depuis le success d’origine que vous avez persisté, le terminal ne les réémet pas).

Étape suivante → Exemples de code