← Tous les articles

Appliquer un encaissement client

Les encaissements client dans Sage 50 enregistrent l’argent reçu d’un client et l’appliquent aux factures de vente ouvertes. Utilisez POST /api/receipts pour enregistrer un encaissement sur une seule facture.

Prérequis

Avant d’appliquer un encaissement, assurez-vous d’avoir :

Utilisez GET /api/sales pour trouver les factures à payer. Filtrez par customerId et répétez paymentStatus pour les factures impayées et partiellement payées (0 = impayée, 1 = partielle). Vous pouvez aussi limiter la liste avec modifiedSince ou activitySince :

GET /api/sales?customerId=42&paymentStatus=0&paymentStatus=1

modifiedSince retourne les factures dont le contenu a été modifié à partir de cette date et heure (montants, lignes, etc.). Un paiement seul ne compte pas. activitySince retourne les factures avec une mise à jour à partir de ce moment, y compris les paiements.

Chaque résultat inclut invoiceNumber, amountOwing, lastModifiedAt et lastActivityAt. lastModifiedAt est le moment où la facture elle-même a été modifiée pour la dernière fois. lastActivityAt est le moment où quelque chose a changé pour la dernière fois, y compris les paiements. Vous pouvez aussi utiliser GET /api/sales/{saleId} si vous avez déjà l’id de la vente depuis la création de la facture.

Choisissez un compte de dépôt (banque ou caisse) via GET /api/general-accounts. Envoyez le numéro d’affichage du compte dans depositAccountNumber, comme pour accountNumber sur les lignes de journal général.

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/receipts

customerId, invoiceNumber, amount, depositAccountNumber et paymentMethod sont obligatoires. Le paiement doit être supérieur à zéro et ne peut pas dépasser le amountOwing de la facture.

Ce que vous devez réellement envoyer

Champ Obligatoire? Si omis
customerId Oui La requête est rejetée
invoiceNumber Oui La requête est rejetée. Doit correspondre à une facture ouverte du client
amount Oui La requête est rejetée. Doit être ≤ au amountOwing de la facture
depositAccountNumber Oui La requête est rejetée. Compte banque ou caisse où le paiement est déposé
paymentMethod Oui La requête est rejetée. Voir les modes de paiement ci-dessous
date Non Sage utilise la date du jour. La date d’encaissement doit être dans la période fiscale ouverte
chequeNumber Non Référence facultative lorsque paymentMethod est Chèque (1)
creditCardId Oui pour carte de crédit Obligatoire lorsque paymentMethod est CreditCard (2). Utilisez GET /api/creditcards/selectable

Valeurs de paymentMethod :

Valeur Mode
0 Cash
1 Cheque
2 CreditCard
3 DirectPayment

Lorsque paymentMethod est 2 (CreditCard), creditCardId est obligatoire. Lorsqu’il est 1 (Cheque), envoyez chequeNumber si vous voulez la référence du chèque sur l’encaissement.

Corps de la requête

Exemple minimal pour un paiement complet sur une facture ouverte. Seuls les champs obligatoires sont envoyés :

{
  "customerId": 42,
  "invoiceNumber": "INV-1001",
  "amount": 113.0,
  "depositAccountNumber": "10600",
  "paymentMethod": 0
}

Paiement par chèque avec référence :

{
  "customerId": 42,
  "invoiceNumber": "INV-1001",
  "amount": 113.0,
  "depositAccountNumber": "10600",
  "paymentMethod": 1,
  "chequeNumber": "1042"
}

Paiement par carte de crédit (utilisez un id de GET /api/creditcards/selectable) :

{
  "customerId": 42,
  "invoiceNumber": "INV-1001",
  "amount": 113.0,
  "depositAccountNumber": "10600",
  "paymentMethod": 2,
  "creditCardId": 3
}

Exemple cURL

curl -X POST "/api/receipts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": 42,
    "invoiceNumber": "INV-1001",
    "amount": 113.0,
    "depositAccountNumber": "10600",
    "paymentMethod": 0
  }'

Réponse en cas de succès

Une requête réussie renvoie 201 Created avec l’encaissement enregistré :

{
  "id": 88,
  "receiptNumber": "RCT-501",
  "customerId": 42,
  "date": "2026-09-29T00:00:00",
  "amount": 113.0,
  "depositAccountNumber": "10600",
  "paymentMethod": 0,
  "lines": [
    {
      "invoiceNumber": "INV-1001",
      "amount": 113.0
    }
  ]
}

Utilisez l’id renvoyé comme receiptId avec GET /api/receipts/{receiptId} pour récupérer l’encaissement plus tard. Après l’enregistrement, GET /api/sales/{saleId} sur la facture doit afficher un amountOwing plus bas et un paymentStatus mis à jour (0 = impayée, 1 = partielle, 2 = payée).

Réponse en cas d’erreur

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

{
  "title": "Validation failed",
  "status": 400,
  "detail": "Invoice INV-1001 was not found for customer 42.",
  "code": "INVOICE_NOT_FOUND",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Les causes courantes incluent un customerId invalide, une facture déjà payée ou qui n’appartient pas au client, un amount supérieur au amountOwing, un creditCardId manquant lorsque paymentMethod est CreditCard, ou un depositAccountNumber inconnu.

Prochaines étapes