Statuts de paiement d'une facture (API)

De Wiki1000
Version du 16 septembre 2026 à 13:29 par Cesru (discuter | contributions)
(diff) ← Version précédente | Voir la version courante (diff) | Version suivante → (diff)

Cette page décrit comment une gestion commerciale externe peut récupérer les statuts Encaissée générés dans FRP 1000 pour une facture comptable.

L'application externe utilise ces informations pour piloter et réaliser elle-même la transmission des statuts vers son propre destinataire. L'API SData est consultée en lecture seule.

Sommaire

Principe

FRP 1000 génère un événement de cycle de vie `212`, correspondant au statut Encaissée, pour chaque règlement lettré sur une facture.

Une facture peut posséder :

  • un règlement unique ;
  • plusieurs règlements partiels ;
  • un événement d'annulation après délettrage d'un règlement.

La réponse doit donc être traitée comme un historique d'événements, et non comme le statut courant unique de la facture.

Pré-requis

  • Connaître la référence de la facture (`oid`, `numeroPiece`, `reference`, `referenceExterne`, etc.).
  • La pièce doit appartenir au flux e-invoicing.

Identifier la facture

Dans les exemples à venir, la requête recherche une facture grâce à `referenceOrigine`.

Cette valeur doit être celle fournie par la gestion commerciale lors de l'intégration de la facture dans FRP 1000. En pratique, il s'agit généralement du numéro de facture de la gestion commerciale.

Exemple : si la facture externe porte le numéro `FAC-2026-000123`, la pièce FRP 1000 doit avoir : 

TPiece.referenceOrigine = 'FAC-2026-000123'

Requête SData 

GET http://localhost:8080/sdata/cptmouvement/tpiece?
  where=typeFlux eq 1
    and codeStatut eq '212'
    and referenceOrigine eq 'FAC-2026-000123'
  &select=referenceOrigine,
    idStatut as StatutFEList.oid,
    dateStatut as StatutFEList.DateStatut,
    codeStatut as StatutFEList.StatutCycleVie.code,
    idStatutAnnule as StatutFEList.oidStatutAnnule,
    StatutFEList.dataContent
  &orderBy=StatutFEList.DateStatut

Cette présentation est destinée à la lisibilité.

Paramètres de requête

Paramètre Rôle
where Filtre les pièces du flux `e-invoicing`, les statuts « Encaissé » et la référence externe de facture.
select Limite la réponse aux informations utiles au consommateur.
orderBy Trie les événements par date de statut croissante.

Informations retournées

Champ Description Usage par l'application externe
referenceOrigine Référence externe de la facture. Rattacher l'événement à la facture de la gestion commerciale.
idStatut Identifiant unique du statut de paiement. Identifiant d'idempotence : conserver les statuts déjà transmis.
dateStatut Date et heure de création du statut dans FRP 1000. Ordonner l'historique des événements.
codeStatut Code du statut de cycle de vie. Vaut `212` pour « Encaissée ».
idStatutAnnule Identifiant du statut d'encaissement annulé. Présent uniquement pour une annulation.
dataContent Snapshot JSON du règlement. Désérialiser pour obtenir les informations à transmettre.

Contenu de `dataContent`

`dataContent` est une chaîne contenant un tableau JSON. Il fournit notamment :

Propriété Description
InvoiceID Identifiant de la facture.
isCreditNote Indique si la facture est un avoir.
isDiscount Indique si le règlement est un escompte.
isDownpayment Indique si la facture est un acompte.
isPurchase Indique si la facture relève d'un flux d'achat.
isSale Indique si la facture relève d'un flux de vente.
IssueDate Date de la facture.
Payment.Amount Montant encaissé.
Payment.Currency Devise du règlement.
Payment.Date Date du règlement.
Payment.SubTotals Ventilation TVA.
typeCode Code du type de flux, par exemple `MEN`.

Exemple de contenu : 

[
  {
    "InvoiceID": "FAC-2026-000123",
    "isCreditNote": false,
    "isDiscount": false,
    "isDownpayment": false,
    "isPurchase": 0,
    "isSale": 1,
    "IssueDate": "2026-09-14",
    "Payment": {
      "Amount": 1000.0000,
      "Currency": "EUR",
      "Date": "2026-09-14",
      "SubTotals": [
        {
          "Percent": 20.00,
          "TaxableAmount": 1000.00
        }
      ]
    },
    "typeCode": "MEN"
  }
]

Cas 1 — Facture réglée en une fois

La facture `FAC-2026-000123` possède un encaissement de 1000 EUR. 

GET http://localhost:8080/sdata/cptmouvement/tpiece?
  where=typeFlux eq 1
    and codeStatut eq '212'
    and referenceOrigine eq 'FAC-2026-000123'
  &select=referenceOrigine,
    idStatut as StatutFEList.oid,
    dateStatut as StatutFEList.DateStatut,
    codeStatut as StatutFEList.StatutCycleVie.code,
    idStatutAnnule as StatutFEList.oidStatutAnnule,
    StatutFEList.dataContent
  &orderBy=StatutFEList.DateStatut

Response: 200 OK
{
  "$baseUrl": "http://localhost:8080/sdata/cptmouvement/",
  "$title": "TPiece - -",
  "$updated": "2026-09-16T10:46:51.428+02:00",
  "$resources": [
    {
      "$url": "TPiece('860D26D2C52800A007CC0000240A0053')",
      "$title": "860D26D2C52800A007CC0000240A0053",
      "$updated": "2026-09-14T17:45:10.000+02:00",
      "$etag": "860D26D2C52800A007CC0000240A0053-000028B2000000EA",
      "$shareId": "860D26D2C52800A007220000024D000B",
      "$shareInfo": "S1",
      "$shareLevel": 2,
      "$key": "860D26D2C52800A007CC0000240A0053",
      "stamp": "000028B2000000EA",
      "codeStatut": "212",
      "dataContent": "[{\"InvoiceID\":\"FAC-2026-000123\",\"isCreditNote\":false,\"isDiscount\":false,\"isDownpayment\":false,\"isPurchase\":0,\"isSale\":1,\"IssueDate\":\"2026-09-14\",\"Payment\":{\"Amount\":1000.0000,\"Currency\":\"EUR\",\"Date\":\"2026-09-14\",\"SubTotals\":[{\"Percent\":20.00,\"TaxableAmount\":1000.00}]},\"typeCode\":\"MEN\"}]",
      "dateStatut": "2026-09-14T18:02:43.000+02:00",
      "idStatut": "860D26D2C52800A072AB0000240A0090",
      "referenceOrigine": "FAC-2026-000123"
    }
  ]
}

Cas 2 — Facture réglée en plusieurs fois

La facture `FAC-2026-000123` est réglée par deux encaissements : 1 000 EUR, puis 200 EUR. 

GET http://localhost:8080/sdata/cptmouvement/tpiece?
  where=typeFlux eq 1
    and codeStatut eq '212'
    and referenceOrigine eq 'FAC-2026-000123'
  &select=referenceOrigine,
    idStatut as StatutFEList.oid,
    dateStatut as StatutFEList.DateStatut,
    codeStatut as StatutFEList.StatutCycleVie.code,
    idStatutAnnule as StatutFEList.oidStatutAnnule,
    StatutFEList.dataContent
  &orderBy=StatutFEList.DateStatut

Response: 200 OK
{
  "$baseUrl": "http://localhost:8080/sdata/cptmouvement/",
  "$title": "TPiece - -",
  "$updated": "2026-09-16T10:46:18.876+02:00",
  "$resources": [
    {
      "$url": "TPiece('860D26D2C52800A007CC0000240B000C')",
      "$title": "860D26D2C52800A007CC0000240B000C",
      "$updated": "2026-09-15T14:59:32.000+02:00",
      "$etag": "860D26D2C52800A007CC0000240B000C-000028B300000057",
      "$shareId": "860D26D2C52800A007220000024D000B",
      "$shareInfo": "S1",
      "$shareLevel": 2,
      "$key": "860D26D2C52800A007CC0000240B000C",
      "stamp": "000028B300000057",
      "codeStatut": "212",
      "dataContent": "[{\"InvoiceID\":\"FAC-2026-000123\",\"isCreditNote\":false,\"isDiscount\":false,\"isDownpayment\":false,\"isPurchase\":0,\"isSale\":1,\"IssueDate\":\"2026-09-14\",\"Payment\":{\"Amount\":1000.0000,\"Currency\":\"EUR\",\"Date\":\"2026-09-14\",\"SubTotals\":[{\"Percent\":20.00,\"TaxableAmount\":1000.00}]},\"typeCode\":\"MEN\"}]",
      "dateStatut": "2026-09-15T15:01:18.000+02:00",
      "idStatut": "860D26D2C52800A072AB0000240B002B",
      "referenceOrigine": "FAC-2026-000123"
    },
    {
      "$url": "TPiece('860D26D2C52800A007CC0000240B000C')",
      "$title": "860D26D2C52800A007CC0000240B000C",
      "$updated": "2026-09-15T14:59:32.000+02:00",
      "$etag": "860D26D2C52800A007CC0000240B000C-000028B300000057",
      "$shareId": "860D26D2C52800A007220000024D000B",
      "$shareInfo": "S1",
      "$shareLevel": 2,
      "$key": "860D26D2C52800A007CC0000240B000C",
      "stamp": "000028B300000057",
      "codeStatut": "212",
      "dataContent": "[{\"InvoiceID\":\"FAC-2026-000123\",\"isCreditNote\":false,\"isDiscount\":false,\"isDownpayment\":false,\"isPurchase\":0,\"isSale\":1,\"IssueDate\":\"2026-09-14\",\"Payment\":{\"Amount\":200.0000,\"Currency\":\"EUR\",\"Date\":\"2026-09-15\",\"SubTotals\":[{\"Percent\":20.00,\"TaxableAmount\":200.00}]},\"typeCode\":\"MEN\"}]",
      "dateStatut": "2026-09-15T15:02:24.000+02:00",
      "idStatut": "860D26D2C52800A072AB0000240B0032",
      "referenceOrigine": "FAC-2026-000123"
    }
  ]
}

Les deux éléments sont deux événements distincts. Le second encaissement ne remplace pas le premier.

Cas 3 — Annulation d'un paiement

Une annulation est produite lorsque le règlement précédemment lettré est délettré, puis que la tâche Génération des statuts de paiement est exécutée.

La réponse contient alors :

  • le statut d'encaissement initial ;
  • un nouveau statut `212` ;
  • la propriété `idStatutAnnule`, qui référence l'identifiant du statut initial. 
GET http://localhost:8080/sdata/cptmouvement/tpiece?
  where=typeFlux eq 1
    and codeStatut eq '212'
    and referenceOrigine eq 'FAC-2026-000123'
  &select=referenceOrigine,
    idStatut as StatutFEList.oid,
    dateStatut as StatutFEList.DateStatut,
    codeStatut as StatutFEList.StatutCycleVie.code,
    idStatutAnnule as StatutFEList.oidStatutAnnule,
    StatutFEList.dataContent
  &orderBy=StatutFEList.DateStatut

Response: 200 OK
{
  "$baseUrl": "http://localhost:8080/sdata/cptmouvement/",
  "$title": "TPiece - -",
  "$updated": "2026-09-16T10:45:31.403+02:00",
  "$resources": [
    {
      "$url": "TPiece('860D26D2C52800A007CC0000240B0035')",
      "$title": "860D26D2C52800A007CC0000240B0035",
      "$updated": "2026-09-16T10:31:27.000+02:00",
      "$etag": "860D26D2C52800A007CC0000240B0035-000028B300000095",
      "$shareId": "860D26D2C52800A007220000024D000B",
      "$shareInfo": "S1",
      "$shareLevel": 2,
      "$key": "860D26D2C52800A007CC0000240B0035",
      "stamp": "000028B300000095",
      "codeStatut": "212",
      "dataContent": "[{\"InvoiceID\":\"FAC-2026-000123\",\"isCreditNote\":false,\"isDiscount\":false,\"isDownpayment\":false,\"isPurchase\":0,\"isSale\":1,\"IssueDate\":\"2026-09-16\",\"Payment\":{\"Amount\":1000.0000,\"Currency\":\"EUR\",\"Date\":\"2026-09-16\",\"SubTotals\":[{\"Percent\":20.00,\"TaxableAmount\":1000.0000}]},\"typeCode\":\"MEN\"}]",
      "dateStatut": "2026-09-16T10:32:53.000+02:00",
      "idStatut": "860D26D2C52800A072AB0000240B004F",
      "referenceOrigine": "FAC-2026-000123"
    },
    {
      "$url": "TPiece('860D26D2C52800A007CC0000240B0035')",
      "$title": "860D26D2C52800A007CC0000240B0035",
      "$updated": "2026-09-16T10:31:27.000+02:00",
      "$etag": "860D26D2C52800A007CC0000240B0035-000028B300000095",
      "$shareId": "860D26D2C52800A007220000024D000B",
      "$shareInfo": "S1",
      "$shareLevel": 2,
      "$key": "860D26D2C52800A007CC0000240B0035",
      "stamp": "000028B300000095",
      "codeStatut": "212",
      "dataContent": "[{\"InvoiceID\":\"FAC-2026-000123\",\"isCreditNote\":false,\"isDiscount\":false,\"isDownpayment\":false,\"isPurchase\":0,\"isSale\":1,\"IssueDate\":\"2026-09-16\",\"Payment\":{\"Amount\":1000.0000,\"Currency\":\"EUR\",\"Date\":\"2026-09-16\",\"SubTotals\":[{\"Percent\":20.00,\"TaxableAmount\":1000.0000}]},\"typeCode\":\"MEN\"}]",
      "dateStatut": "2026-09-16T10:35:13.000+02:00",
      "idStatut": "860D26D2C52800A072AB0000240B0051",
      "idStatutAnnule": "860D26D2C52800A072AB0000240B004F",
      "referenceOrigine": "FAC-2026-000123"
    }
  ]
}

Dans cet exemple, le statut `860D...004F` est annulé par le statut `860D...0051`.

L'application externe doit transmettre l'annulation selon son propre protocole et conserver les deux événements dans son historique.

Cas sans encaissement

Lorsqu'aucun statut `Encaissé` (`212`) ne correspond à la facture recherchée, la réponse HTTP est réussie (`200`) et le tableau `$resources` est vide : 

Response: 200 OK
{
  "$baseUrl": "http://localhost:8080/sdata/cptmouvement/",
  "$title": "TPiece - -",
  "$updated": "2026-09-16T11:47:32.384+02:00",
  "$resources": []
}




Whos here now:   Members 0   Guests 0   Bots & Crawlers 1
 
Récupérée de « https://frp.sage.fr/wiki1000/index.php?title=Statuts_de_paiement_d%27une_facture_(API)&oldid=14902 »
Outils personnels