Fonctionnalités
prix
documentation

Documentation API

Documentation API – Customer Invoice

Customer Invoice API

Gérez les factures clients à travers différents systèmes ERP avec une API REST unifiée.
Créez et lisez les factures pour Acomba, QuickBooks Online, Avantage et autres systèmes ERP.

GET/Entity/CustomerInvoice
POST/Entity/CustomerInvoice

Aperçu

L’entité CustomerInvoice représente une facture client dans votre système ERP.
Cette API permet d’effectuer des opérations de lecture (GET) et de création (POST) sur les factures
de manière standardisée, peu importe le système ERP sous-jacent.

L’API utilise des endpoints REST standards avec les méthodes HTTP appropriées :

  • GET /Entity/CustomerInvoice – Récupérer une liste de factures
  • GET /Entity/CustomerInvoice/{id} – Récupérer une facture spécifique
  • POST /Entity/CustomerInvoice – Créer une nouvelle facture
💡 Note importante

Les champs disponibles et requis varient selon le système ERP. Les factures incluent généralement un en-tête avec les informations client et vendeur, ainsi que des lignes de détail pour chaque produit/service.

Matrice de Support

Opérations supportées pour l’entité CustomerInvoice par système ERP :

Système ERP GET POST PUT
Acomba ✓ Oui ✓ Oui ✗ Non
QuickBooks Online ✓ Oui ✓ Oui ✗ Non
Avantage ✓ Oui ✗ Non ✗ Non
Sage 50 ✗ Non ✗ Non ✗ Non
Servex ✗ Non ✗ Non ✗ Non
Servicentre ✗ Non ✗ Non ✗ Non
⚠️ Limitation importante

La modification (PUT/UPDATE) des factures n’est supportée par aucun système ERP pour préserver l’intégrité comptable et respecter les règles d’audit. Une fois créée, une facture ne peut généralement pas être modifiée – il faut plutôt créer une note de crédit ou une facture d’ajustement.

GET CustomerInvoice

Récupère une liste de factures avec support de filtrage, pagination et sélection de champs.

GET/Entity/CustomerInvoice

Paramètres de requêtes

Paramètre Type Requis Description
$filter string Optionnel Expression de filtrage de style OData
$select string Optionnel Champs à retourner (séparés par des virgules)
$expand string Optionnel Champs à épandre
$orderby string Optionnel Permet de trier les résultats
$top integer Optionnel Nombre maximum de résultats
$skip integer Optionnel Nombre de résultats à ignorer (pagination)
💡 Note importante

Pour plus de détails sur la composition des requêtes, consultez : Composer une requête à l’API d’ERP Connector

Get CustomerInvoice
GET /Entity/CustomerInvoice?$filter=DateFacture ge '2024-01-01'&$select=NoFacture,DateFacture,TotalFacture,InfoClientFacturerA
Host: https://v4.api.onlineerp.solution.quebec/api
Content-Type: application/json
Response (200 OK)
[
    {
        "NoFacture": "F-2024-001",
        "DateFacture": "2024-01-15T00:00:00",
        "TotalFacture": 1456.75,
        "SousTotalFacture": 1250.00,
        "InfoClientFacturerA": {
            "NoClient": "C001",
            "NomClient": "Acme Corporation",
            "EmailPrincipal_Adresse": "contact@acme.com"
        },
        "LigneFacture": [
            {
                "NoLigneFacture": 1,
                "strNoProduit": "PROD-001",
                "DescriptionLigne": "Service de consultation",
                "QteFacture": 10,
                "PrixFinal": 125.00,
                "Montant_SousTotalLigne": 1250.00
            }
        ]
    },
    {
        "NoFacture": "F-2024-002",
        "DateFacture": "2024-01-16T00:00:00",
        "TotalFacture": 567.90,
        "SousTotalFacture": 500.00,
        "InfoClientFacturerA": {
            "NoClient": "C002",
            "NomClient": "Tech Industries",
            "EmailPrincipal_Adresse": "info@tech-ind.com"
        },
        "LigneFacture": [
            {
                "NoLigneFacture": 1,
                "strNoProduit": "PROD-002",
                "DescriptionLigne": "Maintenance serveur",
                "QteFacture": 5,
                "PrixFinal": 100.00,
                "Montant_SousTotalLigne": 500.00
            }
        ]
    }
]

POST CustomerInvoice (Création)

Crée une nouvelle facture dans le système ERP. La facture doit inclure au moins une ligne de détail.

POST/Entity/CustomerInvoice
💡 Headers recommandés

Utilisez le header If-None-Match: * pour garantir que la création échouera si l’entité existe déjà.

Champs requis par ERP

Champ Type Acomba QuickBooks Description
NoFacture string ✓ Required Optional Numéro de la facture (obligatoire pour Acomba)
DateFacture datetime ✓ Required ✓ Required Date de la facture
InfoClientFacturerA object ✓ Required ✓ Required Informations du client à facturer
LigneFacture array ✓ Required ✓ Required Liste des lignes de détail de la facture

Structure d’une ligne de détail

Champ Type Requis Description
strNoProduit string ✓ Required Numéro du produit à facturer
QteFacture decimal ✓ Required Quantité facturée
PrixFinal decimal ✓ Required Prix unitaire final
DescriptionLigne string Optional Description personnalisée de la ligne
Créer une facture
POST /Entity/CustomerInvoice
Host: https://v4.api.onlineerp.solution.quebec/api
Content-Type: application/json
If-None-Match: *

{
  "Facture": {
    "TypeDoc": "FACTURES", // Type doc est important! : 'FACTURES','COMMANDES','SOUMISSIONS','ACHATS'"Référence": "From OERP", 
    "Description": "From OERP",
    "DateFacture": "2024-04-24", // La date de la commande// Les informations sur le client attaché à la commande"InfoClientFacturerA": { 
      "NoClient": "0Comptoir"
    },

    /***************************************************/// Array des LIGNES de la commande à créer. Comme toutes les autres transactions, il y a plusieurs types de lignes possibles"LigneFacture": [
      { // La version ici est ultra simple : NoProduit et Qté. La description et toute autre info sera ramassée dans Acomba
        "QteFacture": 4,
        "strNoProduit": "CAThermo"
      },
      { // Une simple ligne de commentaire
        "DescriptionLigne": "Il est aussi possible de simplement pousser une ligne de texte"
      },
      { // Une ligne d'espace vide
        "DescriptionLigne": ""
      }, 
      { // Ici, on va facturer un GROUPE DE PRODUIT directement, sans utiliser un code de produit
        "QteFacture": 1,
        "QteCommande": 1,
        "strNoGroupeProduit": "115", 
        "DescriptionLigne": "Il est aussi possible de ne facturer que sur le Groupe de produit",
        "PrixFinal": 26.09
      },
      { // La ligne ici montre un exemple où l'on assigne aussi le champ QteFacture. Cela permet de marquer que la ligne a été "Expédié" au client. Aucun mouvement d'inventaire n'est généré avec cela"QteCommande": 3,
        "QteFacture": 3, // donc reste 0 BO
        "strNoProduit": "SCIE-10"
      }
    ] 
    /***************************************************/
  },
  
  "ListeModePaiements": null,

  // ReturnFullTransaction : peut être omis. Demande au Connecteur de nous retourner 100% du payload de la transaction créée. Inutile si vous n'avez besoin que du # de facture!"ReturnFullTransaction": true
}
Response (201 Created)
{
  "OrigRemoteTaskID": 129014,
  "ResultType": "Success",
  "ErrorType": "None",
  "ResultMessage": "Tâche terminée avec succès",
  "ResultPayload": {
    "Message": "OK - Facture créée sous le numéro : 10044",
    "NoFacture": "10044",
    "ResultatPaiement": "OK - Aucun paiement appliqué",
    "RecCardPos": "115",
    "SousTotal": 1039.06,
    "Total": 1195.17,
    "FullTransaction": {
      "NoFacture": "10044",
      "NoUniqueSystemeSource": "115",
      "TypeDoc": 1,
      "Référence": "From OERP",
      "Description": "From OERP",
      "DateFacture": "2024-04-24T00:00:00",
      "SousTotalFacture": 1039.06,
      "TotalFacture": 1195.17,
      "MontantNonPaye": 1195.17,
      "ListeDesTaxes": [
        {
          "Taxe_Numero": "T.P.S. 100%",
          "Taxe_Description": "Taxe sur les produits et services",
          "MontantTaxe": 72.73,
          "Taxe_NumeroLegalGouv": "RT100393939933"
        },
        {
          "Taxe_Numero": "T.V.Q. 100%",
          "Taxe_Description": "Taxe de Vente Québec",
          "MontantTaxe": 83.38,
          "Taxe_NumeroLegalGouv": "TQ1000292929922"
        }
      ],
      "InfoClientFacturerA": {
        "NoClient": "0Comptoir",
        "NomClient": "Ventes au comptoir",
        "NoUniqueSystemeSource": "1",
        "Adresse": "",
        "Ville": "",
        "CodePostal": "",
        "Pays": "CA"
      },
      "LigneFacture": [
        {
          "NoLigneFacture": 1,
          "strNoProduit": "CAThermo",
          "strNoGroupeProduit": "115",
          "DescriptionLigne": "Armoire en Thermo-plastique",
          "QteFacture": 4,
          "QteCommande": 4,
          "PrixFinal": 122,
          "PrixCoutant": 35,
          "Montant_SousTotalLigne": 488,
          "Montant_TotalLigne": 561.322
        },
        {
          "NoLigneFacture": 2,
          "strNoProduit": "",
          "DescriptionLigne": "Il est aussi possible de simplement pousser une ligne de texte",
          "QteFacture": 0,
          "Montant_SousTotalLigne": 0
        },
        {
          "NoLigneFacture": 3,
          "strNoProduit": "",
          "DescriptionLigne": "",
          "QteFacture": 0,
          "Montant_SousTotalLigne": 0
        },
        {
          "NoLigneFacture": 4,
          "strNoProduit": "",
          "strNoGroupeProduit": "115",
          "DescriptionLigne": "Il est aussi possible de ne facturer que sur le Groupe de produit",
          "QteFacture": 1,
          "QteCommande": 0,
          "PrixFinal": 26.09,
          "Montant_SousTotalLigne": 26.09,
          "Montant_TotalLigne": 30.0100225
        },
        {
          "NoLigneFacture": 5,
          "strNoProduit": "SCIE-10",
          "strNoGroupeProduit": "126",
          "DescriptionLigne": "Scie à onglets 10\" avec guide de coupe à laser",
          "QteFacture": 3,
          "QteCommande": 3,
          "PrixFinal": 174.99,
          "PrixCoutant": 89.99,
          "Montant_SousTotalLigne": 524.97,
          "Montant_TotalLigne": 603.8467425
        }
      ],
      "NbLignes": 5
    }
  },
  "IsTaskCompleted": true
}
⚠️ Important

Pour Acomba, le NoFacture est obligatoire. Pour QuickBooks, il est généré automatiquement. Les taxes sont calculées automatiquement selon le groupe de taxes (NoGroupeTaxe) configuré dans le système.

Modèle de Données Complet

En-tête de Facture (FicheTransactions)

Champ Type Description
NoFacture string Numéro de la facture
NoUniqueSystemeSource string Identifiant unique du système source ERP
TypeDoc enum Type de document (FACTURES, COMMANDES, SOUMISSIONS)
DateFacture datetime Date de la facture
Référence string Numéro de référence ou de bon de commande
Description string Description générale de la facture
TotalFacture decimal? Montant total incluant les taxes
SousTotalFacture decimal? Sous-total avant taxes
MontantNonPaye decimal Solde restant à payer
FraisDeTransport decimal Frais de livraison ou de transport
InfoClientFacturerA FicheClient Informations du client à facturer
InfoClientLivrerA FicheClient Informations du client pour la livraison
NoVendeur string Numéro du vendeur assigné
NoTerritoire string Numéro du territoire de vente
TermeDePaiement TermeDePaiement Conditions de paiement (Net 30, Net 60, etc.)
NoProjet string Numéro de projet associé
LigneFacture List<LigneTransactions> Liste des lignes de détail de la facture
ListeDesTaxes List<InfoTaxe> Détail des taxes calculées
ListeReglement List<ARPayment> Liste des paiements reçus
NoCommandeRéférence string Numéro de commande de référence
NoSoumissionRéférence string Numéro de soumission de référence
EstActif bool Indique si la facture est active
EstInversee bool Indique si la facture a été inversée (annulée)

Lignes de Détail (LigneTransactions)

Champ Type Description
NoLigneFacture int Numéro de séquence de la ligne
strNoProduit string Numéro du produit
DescriptionLigne string Description de la ligne (peut être vide pour ligne de commentaire)
QteFacture decimal Quantité facturée (expédiée)
QteCommande decimal Quantité commandée
PrixOrig decimal Prix unitaire original avant rabais
PrixFinal decimal Prix unitaire final après rabais
PrixCoutant decimal Prix coûtant du produit
MontantRabais_pct decimal Pourcentage de rabais appliqué
Montant_SousTotalLigne decimal Sous-total de la ligne avant taxes
Montant_TotalLigne decimal Montant total de la ligne incluant les taxes
NoGroupeTaxe string Numéro du groupe de taxes à appliquer
NoCompteGL string Numéro de compte du Grand Livre
NoProjet string Numéro de projet associé à la ligne
UniteMesure string Unité de mesure (unité, kg, m², etc.)
TypeLigne enum Type de ligne (produit, commentaire, sous-total, etc.)
FicheProduit FicheProduits Objet complet du produit associé
ListeDesTaxes List<InfoTaxe> Détail des taxes calculées pour cette ligne
💡 ExtendedProperties

Les objets FicheTransactions et LigneTransactions supportent également un dictionnaire ExtendedProperties pour des propriétés personnalisées ou spécifiques à un ERP.