Créer et corriger une écriture de journal général

Les écritures de journal général dans Sage 50 sont enregistrées par l’API Journaux généraux. Utilisez POST /api/general-journals pour créer une écriture équilibrée, et PUT /api/general-journals/{journalId} pour corriger une écriture existante de l’exercice en cours.

Prérequis

Avant d’enregistrer une écriture de journal général, assurez-vous d’avoir :

Une clé API valide configurée sur le serveur
La base de données de la compagnie Sage 50 ouverte (utilisez GET /api/database pour vérifier l’état)
Des numéros d’affichage de comptes du grand livre valides obtenus via GET /api/general-accounts

Authentification

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

x-api-key: YOUR_API_KEY

Points de terminaison

POST /api/general-journals
PUT  /api/general-journals/{journalId}

Chaque écriture doit comporter au moins deux lignes, et le total des débits doit être égal au total des crédits. Utilisez les numéros d’affichage du plan comptable, et non les valeurs internes accountId.

Ce que vous devez réellement envoyer

Vous devez envoyer date, source et au moins deux lignes équilibrées. Les commentaires d’en-tête et de ligne sont facultatifs.

Champ	Requis?	Si omis
`date`	Oui	La requête est rejetée. La date doit se situer dans la période fiscale ouverte de la compagnie
`source`	Oui	Sage rejette l’écriture. Utilisez une référence comme `"ADJ-001"` ou une source numérique
`lines`	Oui	La requête est rejetée. Au moins deux lignes sont requises
`accountNumber`	Oui (par ligne)	Utilisez le numéro d’affichage obtenu via `GET /api/general-accounts`
`debitAmount`	Oui (par ligne)	Mettez `0` sur les lignes de crédit
`creditAmount`	Oui (par ligne)	Mettez `0` sur les lignes de débit
`comment`	Non	Le commentaire d’en-tête est facultatif
`comment` (ligne)	Non	Le commentaire de ligne est facultatif
`lineNumber`	Non	Attribué automatiquement selon l’ordre des éléments dans `lines`
`currencyCode`	Non	Sage utilise la devise de base de la compagnie
`exchangeRate`	Non	Requis seulement pour une écriture en devise étrangère

Le total des débits sur toutes les lignes doit être égal au total des crédits. Chaque ligne doit porter un débit ou un crédit, pas les deux.

Consultez les numéros de compte avec GET /api/general-accounts avant d’enregistrer l’écriture. Les exemples ci-dessous utilisent des comptes d’une compagnie de démonstration (57400 Autre, 10600 Banque Régal : Courant). Votre plan comptable sera différent.

Corps de la requête

Exemple minimal avec deux lignes équilibrées. date, source et les montants des lignes sont requis :

{
  "date": "2025-03-15T00:00:00",
  "source": "997",
  "lines": [
    {
      "accountNumber": 57400,
      "debitAmount": 1.0,
      "creditAmount": 0
    },
    {
      "accountNumber": 10600,
      "debitAmount": 0,
      "creditAmount": 1.0
    }
  ]
}

Exemple complet avec champs d’en-tête et commentaires de ligne :

{
  "date": "2025-03-15T00:00:00",
  "source": "ADJ-001",
  "comment": "Monthly accrual",
  "lines": [
    {
      "accountNumber": 57400,
      "debitAmount": 2.0,
      "creditAmount": 0,
      "comment": "Expense accrual"
    },
    {
      "accountNumber": 10600,
      "debitAmount": 0,
      "creditAmount": 2.0,
      "comment": "Offset to bank"
    }
  ]
}

Pour une écriture en devise étrangère, ajoutez currencyCode et exchangeRate à l’en-tête :

{
  "date": "2025-03-15T00:00:00",
  "source": "FX-001",
  "comment": "USD adjustment",
  "currencyCode": "USD",
  "exchangeRate": 1.35,
  "lines": [
    {
      "accountNumber": 57400,
      "debitAmount": 100.0,
      "creditAmount": 0
    },
    {
      "accountNumber": 10600,
      "debitAmount": 0,
      "creditAmount": 100.0
    }
  ]
}

Exemple cURL

Créer une écriture de journal général :

curl -X POST "/api/general-journals" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "date": "2025-03-15T00:00:00",
    "source": "ADJ-001",
    "comment": "Monthly accrual",
    "lines": [
      {
        "accountNumber": 57400,
        "debitAmount": 2.0,
        "creditAmount": 0,
        "comment": "Expense accrual"
      },
      {
        "accountNumber": 10600,
        "debitAmount": 0,
        "creditAmount": 2.0,
        "comment": "Offset to bank"
      }
    ]
  }'

Corriger une écriture

Un PUT ne modifie pas l’écriture d’origine. Sage enregistre une nouvelle écriture avec les montants corrigés et retourne un nouvel id. L’écriture d’origine reste telle qu’enregistrée.

Envoyez l’en-tête et les lignes corrigés complets dans le corps de la requête. {journalId} est l’id de l’écriture d’origine obtenu à la création ou via GET.

Corriger une écriture existante de l’exercice en cours :

curl -X PUT "/api/general-journals/541" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "date": "2025-03-15T00:00:00",
    "source": "996",
    "comment": "Corrected amount",
    "lines": [
      {
        "accountNumber": 57400,
        "debitAmount": 4.0,
        "creditAmount": 0,
        "comment": "Corrected debit"
      },
      {
        "accountNumber": 10600,
        "debitAmount": 0,
        "creditAmount": 4.0,
        "comment": "Corrected credit"
      }
    ]
  }'

Utilisez l’id de la réponse de création comme {journalId}. Après un PUT réussi, utilisez le nouvel id de la réponse, et non le {journalId} d’origine, pour récupérer l’écriture de correction. L’écriture d’origine reste inchangée.

Réponse en cas de succès

Une création réussie retourne 201 Created avec l’écriture de journal général enregistrée :

{
  "id": 535,
  "isLastYear": false,
  "date": "2025-03-15T00:00:00",
  "source": "997",
  "comment": "",
  "debitTotal": 5.0,
  "creditTotal": 5.0,
  "lines": [
    {
      "lineNumber": 1,
      "accountNumber": 57400,
      "debitAmount": 5.0,
      "creditAmount": 0.0,
      "comment": "Line one note"
    },
    {
      "lineNumber": 2,
      "accountNumber": 10600,
      "debitAmount": 0.0,
      "creditAmount": 5.0,
      "comment": "Line two note"
    }
  ]
}

Une correction réussie retourne 200 OK avec la nouvelle écriture de correction. L’id est différent du {journalId} envoyé dans l’URL :

{
  "id": 543,
  "isLastYear": false,
  "date": "2025-03-15T00:00:00",
  "source": "996",
  "comment": "Corrected amount",
  "debitTotal": 4.0,
  "creditTotal": 4.0,
  "lines": [
    {
      "lineNumber": 1,
      "accountNumber": 57400,
      "debitAmount": 4.0,
      "creditAmount": 0.0,
      "comment": "Corrected debit"
    },
    {
      "lineNumber": 2,
      "accountNumber": 10600,
      "debitAmount": 0.0,
      "creditAmount": 4.0,
      "comment": "Corrected credit"
    }
  ]
}

Si vous faites un GET sur l’écriture d’origine (541 dans cet exemple), elle affiche toujours les montants de la première écriture. Faites un GET sur le nouvel id de la réponse PUT pour lire l’écriture de correction.

Réponse en cas d’erreur

Si la requête est invalide ou si Sage rejette l’écriture, l’API retourne une erreur avec un corps ProblemDetails. Les échecs de validation et les règles métier Sage retournent souvent 500 avec un message detail :

{
  "title": "An error has occurred on the server",
  "status": 500,
  "detail": "Total debits must equal total credits.\r\nParameter name: dto",
  "code": "500",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Les valeurs courantes de detail incluent "Date is required.", "This transaction must have a source code.", un message de plage de période fiscale lorsque la date est hors limites, "At least two journal lines are required." et "General journal {id} could not be opened for adjustment." lorsqu’un PUT de correction n’est pas autorisé.

Prochaines étapes

Consultez la référence API pour tous les points de terminaison Journaux généraux
Utilisez GET /api/general-journals/{journalId} pour récupérer une écriture. Après un PUT, récupérez l’id d’origine et le nouvel id de correction si vous avez besoin de l’historique complet
Utilisez GET /api/general-accounts pour consulter les numéros d’affichage de votre plan comptable