Référence des commandes

Légende : {} requis · [] optionnel · | choisir une valeur · XXh octet hexadécimal. Les champs de DATA sont séparés par des virgules ; appliquez l’échappement aux valeurs (voir Format des trames). Les réponses sont la chaîne DATA de la trame de réponse.

Liste des commandes

C1h — Status Query

Interroge l’état courant du dispositif. Sert aussi à tester la connexion.

• DATA : aucune
• REPLY : {result}[,{niu},{terminal_identifier},{TAXT},{TAXR},{TAXE},{verify_url}]

Voir Connexion pour les paramètres et exemples.

C0h — Start New Invoice

Initialise une nouvelle transaction de facture et déclare son type.

• DATA : {invoice_type} [,{reference_invoice_id}] [,{notes}]
• REPLY : {result}[,{reason}]

Exemples de DATA :
  salesInvoice
  salesInvoice,,note message2
  creditNote,INV-2025-20
  creditNote,INV-2025-20,note message1

Exemples de REPLY :
  1
  0,invoice no exist

C3h — Customer Information (vente)

Enregistre le client pour une facture de vente.

• DATA : {recipient_type},{recipient_name},[{recipient_niu}],[{recipient_rccm}],[{recipient_address}],[{recipient_phone}],[{recipient_email}],{is_recipient_taxable}
• REPLY : {result}[,{reason}]

Exemples de DATA (verbatim) :
  1,John Doe,,,,,0
  2,John Doe,NIU67890,,,,,1
  1,John Doe,NIU67890,RCCM12345,,,,0
  2,John Doe,NIU67890,RCCM12345,123 Main St^x2c;New York,,,1
  2,John Doe,NIU67890,RCCM12345,123 Main St^x2c;New York,1234567890,,0
  2,John Doe,NIU67890,RCCM12345,123 Main St^x2c;New York,1234567890,john.doe@example.com,0

Exemples de REPLY :
  1
  0,err message

Notez la virgule échappée dans l’adresse (123 Main St^x2c;New York).

31h — Register New Item

Ajoute une ligne produit ou service à la facture de vente courante. À répéter une fois par item.

• DATA : {designation},[{classification_code}],{type},{unit_price},{quantity},{discount_value},{discount_type},{tax_type}
• REPLY : {result},{subtotal},{net_amount},{tax_amount},{total_amount}

Exemple de DATA :
  apple,,product,99.99,1,5,fixed,T

Exemples de REPLY :
  1,99.99,94.99,10,104.99
  0,error message

33h — Subtotal

Applique une remise globale (au niveau de la facture) et renvoie les totaux calculés de la facture. À appeler après tous les items 31h.

• DATA : {discount_amount},{discount_type}
• REPLY : {result},{subtotal},{total_tax_t_amount},{total_tax_r_amount},{total_exempt_amount},{total_tax_amount},{discount_amount},{total_line_discount_amount},{additional_cent_tax},{electronic_stamp_duty},{total_amount},{amount_due}

35h — Payment

Enregistre le mode de paiement. Doit être envoyée avant 38h.

• DATA : {payment_method}
• REPLY : {result}[,{reason}]

payment_method vaut l’une de : cash, mobile_money, cheque, bank_transfer, card.

Exemples de DATA :        Exemples de REPLY :
  cash                      1
  mobile_money              0,err message
  cheque
  bank_transfer
  card

38h — End Invoice

Finalise la facture et la soumet. Doit être envoyée après 35h (vente) ou 43h (avoir).

• DATA : aucune
• REPLY : {result},{receipt_NO},{qrcode}

Exemple de REPLY (succès) :
  1,1,?sign=5c0f97f79a323cf8ff9f112e05490f623bb26fd80c0f150e8ac69e9a5127cf4d^amphmac=da27855ad5a41aca26fb8f746cc8bcbe8eba356f911944f63a21c593d44bfcfe

Exemple de REPLY (échec) :
  0,err message

Voir Construction du QR code — notez l’échappement ^amp; dans la valeur qrcode.

C9h — Cancel Invoice

Annule la transaction en cours (voir Annulation pour les moments où c’est autorisé).

• DATA : aucune
• REPLY : {result}[,{reason}] — 1 en cas de succès, 0,err message en cas d’échec

Commandes de relecture d’avoir

Pour un avoir, vous relisez la facture d’origine depuis le dispositif au lieu de la ressaisir.

C4h — Original Customer Information

• DATA : aucune
• REPLY : {result},{recipient_type},{recipient_name},[{recipient_niu}],[{recipient_rccm}],[{recipient_address}],[{recipient_phone}],[{recipient_email}],{is_recipient_taxable}
• recipient_type : 1 = Individual, 2 = Company. is_recipient_taxable : 0 = Non, 1 = Oui.

Exemple de REPLY (succès) :
  1,2,John Doe,NIU67890,RCCM12345,123 Main St^x2c;New York,1234567890,john.doe@example.com,0
Exemple de REPLY (échec) :
  0,err message

41h — Get Original Items

À appeler de façon répétée pour parcourir les items de la facture d’origine jusqu’à épuisement.

• DATA : aucune
• REPLY : {result},{designation},[{classification_code}],{type},{unit_price},{quantity},{discount_amount},{discount_type},{tax_rate},{subtotal},{net_amount},{tax_amount},{total_amount}
• result : 0 = échec, 1 = succès (un item suit), 2 = terminé (plus d’items). type : product | service. discount_type : fixed | percentage. tax_rate : T | R | E.

Exemples de REPLY :
  1,apple,,product,99.99,1,5,fixed,T,99.99,94.99,10,104.99
  2,finish
  0,err message

Boucle : continuez d’appeler 41h tant que result = 1 ; arrêtez quand result = 2.

43h — Get Original Subtotal

• DATA : aucune
• REPLY : même structure que 33h ({result},{subtotal},{total_tax_t_amount},…,{amount_due})

Codes de résultat

• result est le premier champ de chaque réponse : 0 = échec, 1 = succès. 41h renvoie en plus 2 = plus d’items (terminateur de boucle).
• En cas d’échec, la réponse est typiquement 0,{reason} (ou 0:{reason} pour C1h), ex. 0,invoice no exist, ou 0:No activation information (C1h). Montrez reason à l’opérateur et arrêtez la transaction (ou annulez avec C9h).
• Une erreur de CRC sur une réponse signifie une trame corrompue ou mal lue — écartez-la, puis renvoyez la commande (avec un nouveau SEQ) ou resynchronisez en lisant jusqu’au prochain ETX.
• Aucune réponse (timeout) signifie que le dispositif est injoignable ou occupé — vérifiez le port, le câblage et les réglages série, puis confirmez avec C1h.
• Vérifiez toujours result avant d’envoyer la commande suivante de la transaction ; une étape en échec empêche la séquence de continuer.

Construction du QR code

Le QR code du reçu fiscal encode une URL de vérification :

QR content = verify_url  +  unescape(qrcode)

• verify_url provient de la réponse de statut C1h (ex. https://dev-pgsfec.akieni.tech/verify-invoice/).
• qrcode provient de la réponse de clôture 38h (ex. ?sign=...^amphmac=...).
• Déséchappez le qrcode avant de l’ajouter (^amp; → &, ainsi que tout autre échappement), transformant ?sign=5c0f...^amphmac=da27... en ?sign=5c0f...&hmac=da27....

Résultat après résolution de l’esperluette :

https://dev-pgsfec.akieni.tech/verify-invoice/?sign=5c0f97f79a323cf8ff9f112e05490f623bb26fd80c0f150e8ac69e9a5127cf4d&hmac=da27855ad5a41aca26fb8f746cc8bcbe8eba356f911944f63a21c593d44bfcfe

Encodez cette chaîne sous forme de QR code sur le reçu imprimé.

Énumérations et codes

Étape suivante → Exemple complet