Envoyer une facture

Une requête de facture est un seul objet JSON encadré en <json>END_JSON — le texte JSON compact suivi immédiatement du marqueur ASCII littéral END_JSON, sans saut de ligne. Le terminal désérialise le JSON dans le contrat ERPInvoice, le valide, le certifie, et répond par une unique trame <json>END_JSON sur le même lien série COM10.

Règles de format qui façonnent la charge utile

• Les noms de champs sont exactement les propriétés du contrat, en camelCase. Envoyez invoiceId, totalTaxTAmount, unitPrice, etc. — jamais en snake_case.
• La structure est plate. Le destinataire est un ensemble de champs recipient* de premier niveau, pas un objet imbriqué.
• Les champs enum portent des valeurs de chaîne précises (voir le catalogue ci-dessous). Une chaîne enum inconnue est rejetée en INVALID_PAYLOAD avant même la validation.
• Les montants sont des nombres JSON (décimaux). Le taxRate d’une ligne est la seule exception — c’est une chaîne.
• Taille max. de trame : 1 Mo ; au-delà → MESSAGE_TOO_LARGE.

ERPInvoice — champs de premier niveau

Identification

Destinataire (plat)

Montants

Tous de type Double et Obligatoires. Ils sont recoupés par le validateur de cohérence anti-fraude (tolérance ±0.01) — voir « Règles de cohérence des montants ».

Paiement

Vendeur (tous optionnels)

Métadonnées de passage (nullable, défaut null), imprimées/attachées par le terminal : logoImg, sellerBankIban, sellerBankRib, sellerAddress, sellerTaxRegime, cashierName, externalCreditNoteNumber, originalSfecInvoiceNumber, sciet.

Lignes et taxes additionnelles

ERPInvoiceItem — champs de ligne

ERPAdditionalTax — champs de taxe additionnelle

Catalogue d’enums (chaînes JSON exactes)

Envoyez la chaîne JSON exacte ; toute autre valeur fait échouer le parsing avec INVALID_PAYLOAD (le message porte un préfixe Invalid payload: et liste les valeurs autorisées). La correspondance est sensible à la casse et au style.

Invalid payload: Invalid value 'SALE' for InvoiceType. Allowed: [salesInvoice, creditNote]

Règles de cohérence des montants (anti-fraude, tolérance ±0.01)

Votre charge utile est rejetée en VALIDATION_ERROR sauf si toutes ces égalités tiennent (une différence supérieure à 0.01 en valeur absolue est une violation) :

Exemple complet — vente à un individual (passe la validation)

Montré en indenté pour la lisibilité ; sur le fil, envoyez-le en JSON compact suivi immédiatement de END_JSON (sans saut de ligne).

{
  "invoiceId": "INV-2026-000123",
  "invoiceType": "salesInvoice",
  "invoiceSubject": "Retail sale",
  "invoiceDate": "2026-07-01T10:15:00",
  "recipientType": "individual",
  "recipientName": "Jean Dupont",
  "recipientNiu": "M012024051234567",
  "recipientAddress": "12 Avenue de l'Independance, Brazzaville",
  "recipientPhone": "+242061234567",
  "recipientEmail": "jean.dupont@example.cg",
  "isRecipientTaxable": false,
  "subtotal": 20000.00,
  "totalTaxTAmount": 3600.00,
  "totalTaxRAmount": 0.00,
  "totalExemptAmount": 0.00,
  "totalTaxAmount": 3600.00,
  "discountAmount": 0.00,
  "totalLineDiscountAmount": 0.00,
  "additionalCentTax": 0.00,
  "electronicStampDuty": 0.00,
  "totalAmount": 23600.00,
  "amountDue": 23600.00,
  "currency": "XAF",
  "paymentMethod": "cash",
  "notes": "Thank you for your purchase",
  "cashierName": "Marie Kula",
  "sciet": "",
  "items": [
    {
      "designation": "Laptop stand",
      "type": "product",
      "unitPrice": 15000.00,
      "quantity": 1,
      "subtotal": 15000.00,
      "discountAmount": 0.00,
      "discountType": "percentage",
      "netAmount": 15000.00,
      "taxRate": "18",
      "taxAmount": 2700.00,
      "totalAmount": 17700.00
    },
    {
      "designation": "USB-C cable",
      "type": "product",
      "unitPrice": 2500.00,
      "quantity": 2,
      "subtotal": 5000.00,
      "discountAmount": 0.00,
      "discountType": "percentage",
      "netAmount": 5000.00,
      "taxRate": "18",
      "taxAmount": 900.00,
      "totalAmount": 5900.00
    }
  ]
}

Sur le fil, cela devient {"invoiceId":"INV-2026-000123",...}END_JSON.

Vérification de cohérence : sous-totaux de lignes 15000 = 15000×1, 5000 = 2500×2 ; nets = subtotal − 0 ; totaux de lignes 17700 = 15000+2700, 5900 = 5000+900 ; en-tête subtotal 20000 = 15000+5000 ; taxe d’en-tête 3600 = 2700+900 ; totalAmount 23600 = 20000+3600+0−0+0+0.

Avoir (creditNote) avec referenceInvoiceId

Un avoir a la même forme mais fixe invoiceType: "creditNote" et doit porter un referenceInvoiceId non vide pointant vers la facture d’origine. Les champs destinataire optionnels sont omis ici (autorisé pour individual). Les montants doivent rester positifs (unitPrice ≥ 0.01, quantity ≥ 0.001), même pour un avoir.

{
  "invoiceId": "CN-2026-000045",
  "invoiceType": "creditNote",
  "referenceInvoiceId": "INV-2026-000042",
  "recipientType": "individual",
  "recipientName": "Jean Dupont",
  "isRecipientTaxable": false,
  "subtotal": 2500.00,
  "totalTaxTAmount": 450.00,
  "totalTaxRAmount": 0.00,
  "totalExemptAmount": 0.00,
  "totalTaxAmount": 450.00,
  "discountAmount": 0.00,
  "totalLineDiscountAmount": 0.00,
  "additionalCentTax": 0.00,
  "electronicStampDuty": 0.00,
  "totalAmount": 2950.00,
  "amountDue": 2950.00,
  "currency": "XAF",
  "paymentMethod": "cash",
  "items": [
    {
      "designation": "Refund - USB-C cable",
      "type": "product",
      "unitPrice": 2500.00,
      "quantity": 1,
      "subtotal": 2500.00,
      "discountAmount": 0.00,
      "discountType": "percentage",
      "netAmount": 2500.00,
      "taxRate": "18",
      "taxAmount": 450.00,
      "totalAmount": 2950.00
    }
  ]
}

Sérialiser et envoyer (encadrement END_JSON)

Sérialisez la facture en JSON compact, ajoutez le marqueur END_JSON, écrivez sur COM10, puis lisez la réponse jusqu’à voir END_JSON et retirez-le.

import json
import serial  # pip install pyserial
 
DELIM = b"END_JSON"
 
def send_invoice(port: str, invoice: dict, timeout: float = 35.0) -> str:
    payload = json.dumps(invoice, separators=(",", ":")).encode("utf-8")  # compact
    with serial.Serial(
        port,
        baudrate=115200,
        bytesize=serial.EIGHTBITS,
        parity=serial.PARITY_NONE,
        stopbits=serial.STOPBITS_ONE,
        timeout=timeout,
    ) as ser:
        ser.write(payload + DELIM)          # un objet JSON + END_JSON, sans saut de ligne
        ser.flush()
        buffer = bytearray()
        while DELIM not in buffer:           # accumuler jusqu'à l'arrivée du marqueur
            chunk = ser.read(64)
            if not chunk:
                raise TimeoutError("No response frame before timeout")
            buffer += chunk
        frame, _, _ = buffer.partition(DELIM)
        return frame.decode("utf-8")         # le JSON avant END_JSON

Rejets courants liés à cette charge utile : INVALID_PAYLOAD (JSON malformé ou chaîne enum inconnue), VALIDATION_ERROR (échec de champ/format/cohérence, avec un tableau errors par champ), DUPLICATE_INVOICE (invoiceId répété), MESSAGE_TOO_LARGE (trame > 1 Mo). Les formes de réponse sont détaillées dans les pages suivantes.

Étape suivante → Lire la réponse