SOMMAIRE

1 Intégration de règlements

Intégration de règlements

L'action pour l'intégration externe de règlements : integration_reglement

Balise de paramètres (parameters)	Niveau	Contenu	Obligatoire	Remarques

Balise de paramètres (parameters)	Niveau	Contenu	Obligatoire	Remarques
dos	1	Dossier achat-vente	NON	Par défaut selon utilisateur
doscpt	1	Dossier comptable	NON	Par défaut selon utilisateur
etb	1	Etablissement	NON	Par défaut selon utilisateur

Balise du corps (data)	Niveau	Contenu	Obligatoire	Remarques

Balise du corps (data)	Niveau	Contenu	Obligatoire	Remarques
EnteteReglementtb	1	Tableau de règlements	OUI	Liste d’entêtes de règlements
EnteteReglement	2	Entête de règlement	OUI
“nomChamp1”:”valeur1”, ”nomChamp2”:valeur2”	3	Liste des champs d’un entête de règlement avec les valeurs	OUI
DetailReglementtb	3	Tableau de détails des règlements	OUI	Pour identifier la facture et le montant du règlement
DetailReglement	4	Détail de règlement	OUI	Permet de préciser les différences de règlements éventuellement associées par échéance et de préciser les éventuels acomptes
“nomChamp1”:”valeur1”, ”nomChamp2”:valeur2”	5	Liste des champs d’un détail de règlement avec les valeurs	OUI

Retrouvez également des informations dans la page du traitement d’intégration des règlements concernant les règles métier : Espace produit (par exemple Divalto infinity 10.11 -> Gérer ses règlements > Utilitaires et traitements du module règlement

Un mapping existe entre les noms de champs du dictionnaire et les noms de balise à utiliser

Table RGLTJNLENT (EnteteReglement)

Nom de balise	Nom de champ	Obligatoire	Remarque

Nom de balise	Nom de champ	Obligatoire	Remarque
PAYMENTTYPE	reglttyp	OUI	ENCASHMENT=1, DISBURSEMENT=2
THIRDPARTY	tiers	OUI
AMOUNT	MtDev	OUI	Montant en devise
LABEL	LibEcr		Libellé de l'écriture associée à la transaction crée
DATE	transacDt		Date de la transaction. Si absente date de traitement du fichier
CURRENCY	Dev	OUI
FINALSTATEMENT	EtatFin	OUI	Etat final CHECK=C30, CHECKINBANK=C50, TRANSFERT=V30, TRANSFERTINBANK=V50, SEPATRANSFERT=S30, SEPATRANSFERTINBANK=S50, INTERNATIONALVIREMENT=I30, INTERNATIONALVIREMENTINBANK=I50, DIRECTDEBIT=D30, DIRECTDEBITINBANK=D50
CHGETAT	CHGETAT	OUI	Code du changement d'état à utiliser
TRANSAC			Voir le chapitre dédié plus bas. Attention usage selon règlement (factures ou remise en banque)
NOORDRE

Table RGLTJNLDET (DetailReglement)

Nom de balise	Nom de champ	Obligatoire	Remarque

Nom de balise	Nom de champ	Obligatoire	Remarque
THIRDPARTY	tiers	OUI
AMOUNT	MTDEVFIN	OUI
OPERATION	NatureOperation	OUI	PAYMENT=(blank), RegltDiff=WDR, ChangeDiff=WDC, Escompte=WE, Acompte=WAR, PARTIALPAYMENT=WPA
PREFIX	PrefPiece	OUI	Obligatoire si gestion des prefixes
PIECE	Piece	OUI
DUEDATE	EchOriDt
TRANSAC			Voir le chapitre dédié plus bas. Attention usage selon règlement (factures ou remise en banque)
NOORDRE

Intégration de facture

La constitution d’une fichier d’intégration de facture doit suivre les règles métier.

Quelques précisions

La somme des détails doit toujours être égal au montant de l'échéance d’origine de la facture
Le NatureOperation = ' ' dans un détail indique de prendre la nature du règlement prévu
Les champs TRANSAC et NOORDRE de l’entête de règlement ont un impact fort sur l’intégration
- Un numéro TRANSAC différent (par exemple 1 puis 2) donnera un traitement distinct des transactions pour obtenir des écritures séparées
- Un numéro NOORDRE permet d’indiquer une chronologie au sein d’un même TRANSAC

Exemple de corps

'data':{
	'EnteteReglementtb': 
	[
		{
		'EnteteReglement': 
			{
			'ETB'			: '',
			'TRANSACDT'	: '20210320',
			'DEV'			: 'EUR',
			'TIERS'		: 'C0000007',
			'MTDEV'			: '5995',
			'LIB'			: 'Règlement',	
			'RegltTyp'	: '1',		
			'ChgEtat'	: 'PORCHQ',
			'EtatFin'	: 'C30',
			'DetailReglementtb': 
				[
					{
					'DetailReglement': 
						{
						'MTDEVFIN'			: '3595',
						'PREFPIECE'			: ' ',
						'PIECE'				: '87',	
						'TIERS'				: 'C0000007',
						'NatureOperation'	: ' '
						}
					},
					{
					'DetailReglement': 
						{
						'MTDEVFIN'			: '2400',
						'PREFPIECE'			: ' ',
						'PIECE'				: '86',	
						'TIERS'				: 'C0000007',
						'NatureOperation'	: ' '
						}
					},
					{
					'DetailReglement': 
						{
						'MTDEVFIN'			: '5',
						'PREFPIECE'			: ' ',
						'PIECE'				: '87',	
						'TIERS'				: 'C0000007',
						'NatureOperation'	: 'WDR'
						}
					}
				]
					
			}
		},
		{
		'EnteteReglement': 
			{
			'ETB'			: '',
			'TRANSACDT'	: '20210320',
			'DEV'			: 'EUR',
			'TIERS'		: 'C0000003',
			'MTDEV'			: '5000',
			'LIB'			: 'Règlement',	
			'RegltTyp'	: '1',		
			'ChgEtat'	: 'PORCHQ',
			'EtatFin'	: 'C30',
			'DetailReglementtb': 
				[
					{
					'DetailReglement': 
						{
						'MTDEVFIN'			: '5000',
						'PREFPIECE'			: ' ',
						'PIECE'				: '',	
						'TIERS'				: 'C0000003',
						'NatureOperation'	: 'WAR'
						}
					}
				]				
			}
		}
	]
}

Exemple complet flux JSON

{ 
    "action":"WEB_SERVICE_INFINITY",
    "access_token":"{{TOKEN}}",
    "param":"
        {
        'action': {
			'swinfinity': 'integration_reglement',
			'parameters': 
              {
				'doscpt': '998',
				'dos': '998',
			  'etb': '1'}
			  }
  ,
  'data':{
		'EnteteReglementtb': 
		[
			{
			'EnteteReglement': 
				{
				'ETB'			: '',
				'TRANSACDT'	: '20210320',
				'DEV'			: 'EUR',
				'TIERS'		: 'C0000007',
				'MTDEV'			: '5995',
				'LIB'			: 'Règlement',	
				'RegltTyp'	: '1',		
				'ChgEtat'	: 'PORCHQ',
				'EtatFin'	: 'C30',
				'DetailReglementtb': 
					[
						{
						'DetailReglement': 
							{
							'MTDEVFIN'			: '3595',
							'PREFPIECE'			: ' ',
							'PIECE'				: '87',	
							'TIERS'				: 'C0000007',
							'NatureOperation'	: ' '
							}
						},
						{
						'DetailReglement': 
							{
							'MTDEVFIN'			: '2400',
							'PREFPIECE'			: ' ',
							'PIECE'				: '86',	
							'TIERS'				: 'C0000007',
							'NatureOperation'	: ' '
							}
						},
						{
						'DetailReglement': 
							{
							'MTDEVFIN'			: '5',
							'PREFPIECE'			: ' ',
							'PIECE'				: '87',	
							'TIERS'				: 'C0000007',
							'NatureOperation'	: 'WDR'
							}
						}
					]
						
				}
			},
			{
			'EnteteReglement': 
				{
				'ETB'			: '',
				'TRANSACDT'	: '20210320',
				'DEV'			: 'EUR',
				'TIERS'		: 'C0000003',
				'MTDEV'			: '5000',
				'LIB'			: 'Règlement',	
				'RegltTyp'	: '1',		
				'ChgEtat'	: 'PORCHQ',
				'EtatFin'	: 'C30',
				'DetailReglementtb': 
					[
						{
						'DetailReglement': 
							{
							'MTDEVFIN'			: '5000',
							'PREFPIECE'			: ' ',
							'PIECE'				: '',	
							'TIERS'				: 'C0000003',
							'NatureOperation'	: 'WAR'
							}
						}
					]				
				}
			}
		]
      }
  }"
}

Compléments intégration facture - règlement multiple

Exemple d’utilisation TRANSAC et NOORDRE

Dans le cas de 2 entêtes de règlement dans le même fichier JSON pour régler une même facture, par exemple 1900€ à régler avec 1000€ espèce et 900 par chèque, il faudra

Regrouper nécessairement les 2 entêtes dans un même numéro TRANSAC
Utiliser le NOORDRE pour imposer l’ordre de traitement (donc 1 puis 2)
Donner le premier entête avec le premier règlement (dans l’exemple 1000€ espèce) ET un reste WPA de l'écart au montant de l'échéance d’origine (ici 900€ de WPA)
Donner le second entête avec le second règlement (dans l’exemple 900€ chèque)

Exemple flux complet JSON pour deux règlements

{
'action': {'swinfinity': 'integration_reglement',
'parameters': 
        {
	'doscpt': '998',
	'dos': '998',
          'etb': '1'
    }        
},
  'data':
      {
          'EnteteReglementtb': 
          [
              {
              'EnteteReglement': 
                  {
                  'ETB'			: '',
                  'TRANSACDT'	: '20241020',
                  'DEV'			: 'EUR',
                  'TIERS'		: 'C0000004',
                  'MTDEV'			: '1000',
                  'LIB'			: 'Règlement 1',	
                  'RegltTyp'	: '1',		
                  'ChgEtat'	: 'PORESP',
                  'EtatFin'	: 'E30',
				  'Transac'	: '1',
				  'Noordre'	: '1',
                  'DetailReglementtb': 
                      [
                          {
                          'DetailReglement': 
                              {
                              'MTDEVFIN'			: '1000',
                              'PREFPIECE'			: ' ',
                              'PIECE'				: '10002797',	
                              'TIERS'				: 'C0000004',
                              'NatureOperation'	: ' '
                              }
                          },
                          {
                          'DetailReglement': 
                              {
                              'MTDEVFIN'			: '900',
                              'PREFPIECE'			: ' ',
                              'PIECE'				: '10002797',	
                              'TIERS'				: 'C0000004',
                              'NatureOperation'	: 'WPA'
                              }
                          },
                      ]
                          
                  }
              },
              {
              'EnteteReglement': 
                  {
                  'ETB'			: '',
                  'TRANSACDT'	: '20241020',
                  'DEV'			: 'EUR',
                  'TIERS'		: 'C0000004',
                  'MTDEV'			: '900',
                  'LIB'			: 'Règlement 2',	
                  'RegltTyp'	: '1',		
                  'ChgEtat'	: 'PORCHQ',
                  'EtatFin'	: 'C30',
				  'Transac'	: '1',
				  'Noordre'	: '2',
                  'DetailReglementtb': 
                      [
                          {
                          'DetailReglement': 
                              {
                              'MTDEVFIN'			: '900',
                              'PREFPIECE'			: ' ',
                              'PIECE'				: '10002797',	
                              'TIERS'				: 'C0000004',
                              'NatureOperation'	: ''
                              }
                          }
                      ]				
                  }
              }
          ]
      }
  }

Exemple flux complet JSON pour deux règlements avec escompte

A noter que dans ce exemple, le TRANSAC est différent, ce qui donnera 2 transactions distinctes

Compléments intégration facture - règlement en devises (V10.11)

Le règlement en devises par l’intégration de règlements suit quelques règles

Gestion des montants total du règlement dans l’entête du règlement (EnteteReglement)
- Si le règlement est en devise différente de la devise du dossier, le montant total du règlement en devise MTDEV dans l’entête est obligatoire.
- Si le montant total dans la devise du dossier MT est renseigné, on considère le règlement à taux de change bloqué et il sera égal au rapport entre les montants. Si le règlement n’est pas dans la devise des factures, il faut obligatoirement faire le traitement à devise bloquée.
- Sinon, le taux de change sera récupéré dans la table des taux de change
Gestion des montants dans les détails de règlement(DetailReglement)
- Description des champs montants
  - MTDEVREGLE est le montant effectif du règlement dans la devise du règlement
  - MTREGLE est le montant effectif du règlement dans la devise du dossier
  - AMOUNT est le montant dans la devise de la facture que l’on va régler
- Cas 1 : le règlement est à taux de change bloqué
  - Les montants effectifs du règlement (MTDEVREGLE, MTREGLE) sont obligatoires
- Cas 2 : le règlement n’est pas à taux de change bloqué
  - On considère dans ce cas là que la devise du règlement est dans la devise de la facture. Et donc le montant du règlement est égal au montant à régler (MTDEVREGLE = AMOUNT) et le montant à régler dans la devise du dossier est calculé en automatique à partir du taux de change à date.
Si le règlement est dans la devise du dossier, alors l’un des deux champs MTDEVREGLE ou MTREGLE suffit (l'autre sera copié à l’identique), mais dans tous les cas les deux champs MTREGLE et MTDEVREGLE doivent être égaux (erreur si différents ou non renseignés)

Exemple flux complet JSON pour règlement en devise

Dans l’exemple, règlement de 2400 TND pour 2 factures en TND avec un escompte pour chaque facture

Format de la réponse :

Balise	Contenu

Balise

Contenu

error

Anomalie technique de l’appel du service web

0 = pas n’anomalie, autre valeur = anomalie

Dans ce cas la balise txterr indique le message d’erreur

result

Détail du résultat fonctionnel de l’appel du service web

resultcode= 0 => pas d’anomalie fonctionnelle la demande est bien traitée

resultcode<>0 => anomalie fonctionnelle/métier dont la raison est indiquée dans errormessage

La response contient notamment la réponse avec les éventuelles erreurs errormessage et la transaction générée dans transactionId

Exemple de réponse

Voir le chapitre ci-dessous qui impacte la réponse Intégration de règlements (V10.7) (JSON) | Retour d’erreur multiples (V10.12)

Intégration de remise en banque

L’intégration par fichier JSON de transaction de type remise en banque est disponible, par exemple une opération de type C30 → C50 (remise en banque de chèques en portefeuille)

à partir de la version X.7 service pack 217e
à partir de la version X.9 service pack 219c
à partir de la version X.10 service pack 220b
à partir de la version X.11 service pack 221a

Si l'état final de type n’est pas un virement et est associé à un bordereau, il faudra passer par l'étape de confection du bordereau pour générer l'écriture associée à la transaction créée.
Si l'état final de type remise est un virement ou n'est pas associé à un bordereau, l'écriture associée à la transaction créée est générée lors du traitement du fichier JSON .

Le mécanisme général est identique à l’intégration ci-dessus, mais voici quelques précisions pour le cas de la remise en banque

Donnée à mettre dans le fichier JSON

Dans RGLTJNLENT (EnteteReglement) on doit définir

La devise et le montant total de la transaction à effectuer (Facultatif ). Si présent le total des transactions (DetailReglement) sera comparé à ce montant.
Le type de règlement (PAYMENTTYPE) 1 Encaissement, 2 décaissement. (Obligatoire)
le code du changement d'état à utilisé (Obligatoire)
la banque de destination (Obligatoire)

Dans RGLTJNLDET (DetailReglement) Il faut renseigner

soit un n° de transaction existant correspondant à le remise en portefeuille
- TRANSAC : le n° de la transaction qui à permis la passage de la position 1 à la position 2 (Ex : transaction de remise en portefeuille de chèque)
- NOORDRE : le n° d’ordre n’est pas obligatoire (N° 1 pris par défaut)
soit des informations permettant de retrouver la transaction. Si plusieurs transactions correspondent aux critères fournis on prend celle avec le N° le plus petit
- TIERS (THIRDPARTY) : Code tiers
- ETATORI : Etat des règlements à traiter. Doit correspondre à un des état d’entrées possible pour le changement d'état précisé dans l’entête
- MTORI : Montant de la transaction en devise du dossier
- ou MTDEVORI (AMOUNT) montant en devise et DEV (CURRENCY) : devise

Exemple de fichier

Remise en banque avec N° de transaction

Remise en banque sans n° de transaction

Retour d’erreur multiples (V10.12)

Jusqu’en version 10.12, le retour (dans la réponse) se faisait dans un format unique, c’est à dire que seul une seule information remontait, par exemple le dernier numéro de transaction ou un message d’erreur unique en cas d’anomalie.

La version 10.12 introduit une modification

dans la réponse, qui retourne un TABLEAU JSON dans la “response”
dans la demande, qui peut indiquer un numéro pour faire le lien entre une demande et la réponse

Lors de la demande, la balise “REGLEMENTNUM” (numérique) peut être ajoutée dans l’entête EnteteReglement. Son utilisation aura pour effet

d'être sauvegardé dans l’entête de journal de la transaction générée dans l’onglet Identifiant sous le nom “N° de règlement JSON”
d'être retourné dans la réponse

Le numéro REGLEMENTNUM doit au minimum être un incrément d’unicité à l’intérieur d’une demande JSON ; idéalement un numéro chrono chez l’appelant permet une meilleure traçabilité

Exemple de corps de demande avec REGLEMENTNUM en entête (ici 17 et 18)

Exemple de réponse à ce REGLEMENTNUM en entête (ici deux erreurs sur 17 et 18)

Le message est sous la forme :

Réussite : Règlement n°$1 : OK - La transaction $2 a été générée.
Echec : Règlement n°$1 : message d’erreur