Certifier une facture

Cet endpoint certifie une facture en temps réel via l’API ERP. Le SFEC génère la signature, le numéro de certification et le QR code, puis les renvoie dans la réponse.

Authentification : X-API-Key - voir Authentification

OpenAPI / Swagger

Explorateur OpenAPI interactif

Endpoint

URL : POST /api/v1/invoices
Authentification : X-API-Key


POST https://api.sfec.gouv.cg/api/v1/invoices
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Paramètres de requête

Identification et statut

Paramètre	Type	Description	Obligatoire
`invoice_id`	string	Identifiant unique de la facture (ex: INV-2025-12)	✅
`invoice_type`	string	Type de facture (`salesInvoice`, `creditNote`)	✅
`taxpayer_niu`	string\|null	NIU du contribuable (vendeur) — max 20 caractères. Le vendeur est identifié par la clé API.	❌
`invoice_subject`	string\|null	Sujet ou description de la facture	❌
`invoice_due_date`	string\|null	Date d’échéance au format ISO 8601	❌
`reference_invoice_id`	string\|null	ID de la facture de référence (pour avoirs)	❌
`sciet`	string\|null	Numéro SCiET (identifiant interne SFEC)	❌

Pour créer une facture d’avoir :

Définissez invoice_type à creditNote
Définissez reference_invoice_id avec le numéro de la facture de vente originale

Informations destinataire

Paramètre	Type	Description	Obligatoire
`recipient_type`	string	Type du destinataire (`business`, `individual`, `government`, `foreign`)	✅
`recipient_name`	string	Nom ou raison sociale du destinataire	Conditionnel
`recipient_niu`	string\|null	Numéro d’identification fiscale du destinataire	Conditionnel
`recipient_rccm`	string\|null	Numéro RCCM du destinataire	❌
`recipient_address`	string\|null	Adresse physique complète	Conditionnel
`recipient_phone`	string\|null	Numéro de téléphone du destinataire	Conditionnel
`recipient_email`	string\|null	Adresse e-mail du destinataire	Conditionnel
`is_recipient_taxable`	boolean	Indique si le destinataire est assujetti à la TVA	✅

Champs conditionnels selon recipient_type : recipient_name est requis pour business, government et foreign ; recipient_niu pour business et government (16 ou 17 caractères) ; recipient_phone, recipient_email et recipient_address pour government et foreign. Pour individual, ces champs sont optionnels.

Montants et totaux

Tous les montants sont exprimés en valeur numérique simple, sans devise.

Paramètre	Type	Description	Obligatoire
`subtotal`	number	Montant hors taxe total	✅
`total_tax_t_amount`	number	TVA au taux normal [T] (18%)	✅
`total_tax_r_amount`	number	TVA au taux réduit [R] (5%)	✅
`total_exempt_amount`	number	Montant total exonéré	✅
`total_tax_amount`	number	Total de la TVA (`total_tax_t_amount` + `total_tax_r_amount`)	✅
`discount_amount`	number	Escompte — remise globale de la facture, appliquée uniquement sur `amount_due`	✅
`total_line_discount_amount`	number	Somme des remises de tous les articles (`Σ items[].discount_amount`)	✅
`additional_cent_tax`	number	Taxe additionnelle en centimes	✅
`electronic_stamp_duty`	number	Timbre fiscal électronique — doit être défini à `0` (voir note ci-dessous)	✅
`total_amount`	number	Montant global TTC	✅
`amount_due`	number	Montant total à payer	✅

⚠️

Timbre électronique : Après signature du décret, le champ electronic_stamp_duty doit être défini à 0. Le timbre électronique n’est plus calculé par le contribuable.

discount_amount (Escompte) et total_line_discount_amount (Total Remises) sont deux remises distinctes, affichées sur deux lignes séparées de la facture. total_line_discount_amount doit être la somme des remises de tous les articles (Σ items[].discount_amount), pas celle d’un seul article.

Taxes additionnelles

Le champ additional_taxes permet de spécifier des taxes additionnelles applicables à la facture. Ce champ est optionnel.

Paramètre	Type	Description	Obligatoire
`additional_taxes`	array	Liste des taxes additionnelles	❌

Chaque élément de additional_taxes contient :

Paramètre	Type	Description	Obligatoire
`tax_code`	string	Code de la taxe (ex: `"TAR"`)	✅
`tax_label`	string\|null	Libellé de la taxe (ex: “Taxe sur les activités rémunérées”)	❌
`tax_amount`	number	Montant de la taxe	✅
`tax_rate`	number\|null	Taux de la taxe (en pourcentage)	❌

Paiement

Paramètre	Type	Description	Obligatoire
`currency`	string	Code de devise (`XAF`, `USD`)	✅
`payment_method`	string	Méthode de paiement (`bank_transfer`, `card`, `cash`, `mobile_money`, `cheque`)	✅
`payment_reference`	string\|null	Référence du paiement	❌
`payment_date`	string\|null	Date du paiement au format ISO 8601	❌

Autres champs optionnels : notes (texte libre).

Champs générés par le SFEC (ne pas envoyer)

Les champs de certification — certification_number, signature, short_signature, qr_code, certification_date, invoice_number — sont générés automatiquement par le SFEC et renvoyés dans la réponse. Ne les incluez pas dans votre requête.

Articles (`items`)

Chaque article de la facture doit contenir :

Paramètre	Type	Description	Obligatoire
`designation`	string	Nom du produit ou service	✅
`classification_code`	string\|null	Code de classification (C01, S01, etc.)	❌
`type`	string	Type d’article (`product`, `service`)	✅
`unit_price`	number	Prix unitaire hors taxe	✅
`quantity`	number	Quantité vendue	✅
`subtotal`	number	Montant HT pour l’article	✅
`discount_amount`	number	Remise appliquée sur cet article	✅
`discount_type`	string	Type de remise (`fixed`, `percentage`)	✅
`net_amount`	number	Montant net après remise (`subtotal − discount_amount`)	✅
`tax_rate`	string	Taux de TVA applicable (`0`, `18`, etc.)	✅
`tax_amount`	number	Montant de taxe pour cet article	✅
`total_amount`	number	Montant TTC de la ligne	✅

Exemple de requête


{
  "invoice_id": "INV-2025-12",
  "taxpayer_niu": "M25000000561080T",
  "invoice_type": "salesInvoice",
  "invoice_subject": "Vente matériel informatique",
  "invoice_due_date": "2025-02-15T00:00:00Z",
  "reference_invoice_id": null,
  "sciet": "SFEC-API-001",
  "subtotal": 13280,
  "total_tax_t_amount": 2390.4,
  "total_tax_r_amount": 0,
  "total_exempt_amount": 0,
  "total_tax_amount": 2390.4,
  "discount_amount": 0,
  "amount_due": 15670.4,
  "total_line_discount_amount": 2000,
  "additional_cent_tax": 0,
  "electronic_stamp_duty": 0,
  "total_amount": 15670.4,
  "currency": "XAF",
  "recipient_type": "business",
  "recipient_name": "Test Buyer Company",
  "recipient_niu": "BUYER123456789",
  "recipient_rccm": "CG-BZV-2025-B-001",
  "recipient_address": "123 Buyer Street, Brazzaville",
  "recipient_phone": "+237123456789",
  "recipient_email": "contact@buyer.com",
  "is_recipient_taxable": true,
  "payment_method": "bank_transfer",
  "payment_reference": "PAY-2025-001",
  "payment_date": "2025-01-15T14:30:00Z",
  "notes": "Facture API pour test d'intégration",
  "additional_taxes": [
    {
      "tax_code": "TAR",
      "tax_label": "Taxe sur les activités rémunérées",
      "tax_amount": 500,
      "tax_rate": 2.5
    }
  ],
  "items": [
    {
      "designation": "iPhone 16 Pro",
      "classification_code": "C01",
      "discount_amount": 1000,
      "discount_type": "fixed",
      "net_amount": 3320,
      "quantity": 6,
      "subtotal": 4320,
      "tax_amount": 597.6,
      "tax_rate": "18",
      "total_amount": 3917.6,
      "type": "product",
      "unit_price": 720
    },
    {
      "designation": "MacBook Pro M3",
      "classification_code": "C01",
      "discount_amount": 1000,
      "discount_type": "fixed",
      "net_amount": 7960,
      "quantity": 6,
      "subtotal": 8960,
      "tax_amount": 1792.8,
      "tax_rate": "18",
      "total_amount": 11752.8,
      "type": "product",
      "unit_price": 1493.33
    }
  ]
}

Réponse

Réponse de succès (`201 Created`)

Paramètre	Type	Description
`certification_number`	string	Numéro de certification SFEC officiel unique
`signature`	string	Signature cryptographique complète
`short_signature`	string	Version courte de la signature pour affichage
`invoice_number`	string	Numéro de facture confirmé par le système
`certification_date`	string	Date/heure de certification au format ISO 8601
`identifier`	string	Référence interne de la facture SFEC
`qr_code`	string	Code QR au format base64

Exemple de réponse


{
  "certification_number": "SFEC-API-2025-0000123456",
  "invoice_number": "INV-2025-12",
  "certification_date": "2025-01-15T10:30:00.000Z",
  "signature": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "short_signature": "SFEC-API-2025-001",
  "identifier": "SFEC-REF-2025-0000123456",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEA..."
}

Codes d’erreur

Code	Description
`400`	Données invalides (format incorrect, champs manquants, incohérences dans les totaux)
`401`	Clé d’authentification invalide ou manquante
`422`	Erreur de validation des données métier (règles ou incohérences des montants)
`409`	Facture déjà certifiée (numéro de facture en doublon)
`500`	Erreur interne du serveur

⚠️

Assurez-vous que tous les montants sont cohérents et que les totaux correspondent à la somme des articles avant soumission.

Étape suivante → Lister les factures