← Tous les articles

Créer une facture client

Les factures client dans Sage 50 sont créées comme des écritures du journal des ventes par l’API Ventes. Utilisez POST /api/sales pour créer une facture avec des lignes d’articles.

Prérequis

Avant de créer une facture, assurez-vous d’avoir :

Authentification

Passez votre clé API dans l’en-tête de requête x-api-key :

x-api-key: YOUR_API_KEY

Point de terminaison

POST /api/sales

Seul customerId est requis par l’API. La plupart des autres champs sont facultatifs. Sage applique les valeurs par défaut du client, de l’article ou de la compagnie lorsque vous les omettez.

Ce que vous devez réellement envoyer

Vous n’avez pas besoin d’envoyer les conditions de paiement, les codes de taxe, les comptes du grand livre, les numéros de facture ou les champs de devise, sauf si vous voulez remplacer les valeurs par défaut de Sage.

Champ Requis? Si omis
customerId Oui La requête est rejetée
lines En pratique oui Sage a besoin d’au moins une ligne pour enregistrer l’écriture
itemNumber itemNumber ou accountNumber par ligne Utilisez itemNumber pour les articles en inventaire
quantity Oui (par ligne) Requis pour chaque ligne
price Oui (par ligne) Requis pour chaque ligne
accountNumber Non Sage utilise le compte de revenus configuré sur l’article
taxCode Non Sage utilise les paramètres de taxe configurés sur l’article
termDiscNetDay Non Sage utilise les conditions de paiement configurées sur le client
invoiceNumber Non Sage attribue automatiquement le prochain numéro de facture
date Non Sage utilise la date du jour. La date de la facture doit se situer dans la période fiscale ouverte de la compagnie
description Non Sage peut utiliser le nom de l’article, ou la ligne peut être descriptive seulement
lineNumber Non Attribué automatiquement selon l’ordre des éléments dans lines
amount Non Ignoré à la création. Sage le calcule à partir de la quantité × le prix

Vous n’avez pas besoin de définir lineNumber sur chaque ligne. L’API numérote les lignes séquentiellement selon leur position dans le tableau lines (le premier élément est la ligne 1, le second est la ligne 2, et ainsi de suite).

Si vous omettez date, Sage utilise la date du jour. Qu’elle soit par défaut ou envoyée explicitement, la date de la facture doit se situer dans la période fiscale ouverte de la compagnie.

Corps de la requête

Exemple minimal avec un article en inventaire. Seuls customerId, quantity, price et itemNumber sont envoyés. Sage remplit le compte, la taxe et les conditions de paiement :

{
  "customerId": 42,
  "lines": [
    {
      "itemNumber": "WIDGET-01",
      "quantity": 2,
      "price": 50.0
    }
  ]
}

Pour une ligne de service sans article en inventaire, utilisez accountNumber au lieu de itemNumber :

{
  "customerId": 42,
  "lines": [
    {
      "description": "Consulting services",
      "quantity": 1,
      "price": 100.0,
      "accountNumber": "4000"
    }
  ]
}

Lignes vides et lignes descriptives seulement

Les factures Sage acceptent des lignes vides pour l’espacement et des lignes informatives sans montant. Vous pouvez les mélanger avec des lignes d’articles régulières dans la même requête.

Une ligne vide est une ligne d’espacement sans article, quantité ni prix. Passez une description vide :

{
  "description": ""
}

Une ligne descriptive seulement est utile pour des notes, des noms de projet ou des en-têtes de section. Définissez description avec du texte et videz taxCode et accountNumber pour que Sage n’applique pas les valeurs par défaut des articles :

{
  "description": "Project: Example Site",
  "taxCode": "",
  "accountNumber": ""
}

Exemple de facture avec un en-tête descriptif, une ligne de produit et une ligne vide entre les sections :

{
  "customerId": 42,
  "lines": [
    {
      "description": "September delivery",
      "taxCode": "",
      "accountNumber": ""
    },
    {
      "itemNumber": "WIDGET-01",
      "quantity": 2,
      "price": 50.0
    },
    {
      "description": ""
    },
    {
      "itemNumber": "WIDGET-02",
      "quantity": 1,
      "price": 25.0
    }
  ]
}

Exemple cURL

curl -X POST "/api/sales" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": 42,
    "lines": [
      {
        "itemNumber": "WIDGET-01",
        "quantity": 2,
        "price": 50.0
      }
    ]
  }'

Réponse en cas de succès

Une requête réussie retourne 201 Created avec l’écriture du journal des ventes créée. Les champs que vous n’avez pas envoyés sont remplis par Sage :

{
  "id": 456,
  "customerId": 42,
  "date": "2026-09-11T00:00:00",
  "customerName": "Acme Corp",
  "invoiceNumber": "INV-1001",
  "termDiscNetDay": 30,
  "totalAmount": 113.0,
  "amountOwing": 113.0,
  "paymentStatus": 0,
  "dueDate": "2026-10-11T00:00:00",
  "lines": [
    {
      "lineNumber": 1,
      "itemNumber": "WIDGET-01",
      "accountNumber": "4000",
      "description": "Premium widget",
      "quantity": 2.0,
      "price": 50.0,
      "amount": 100.0,
      "taxCode": "HST"
    }
  ]
}

Valeurs de paymentStatus : 0 = impayé, 1 = partiel, 2 = payé. totalAmount inclut la taxe calculée par Sage. termDiscNetDay, accountNumber et taxCode dans la réponse proviennent des valeurs par défaut du client et de l’article, même s’ils n’étaient pas dans la requête.

Réponse en cas d’erreur

Si la requête est invalide ou si Sage rejette l’écriture, l’API retourne 400 Bad Request :

{
  "title": "Validation failed",
  "status": 400,
  "detail": "Customer with id 42 was not found.",
  "code": "CUSTOMER_NOT_FOUND",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Les causes courantes incluent un customerId invalide, un itemNumber inconnu ou une ligne sans quantité et prix.

Prochaines étapes