Délettrage des écritures comptables

Présentation générale de l'API et finalité fonctionnelle

Cette API permet de supprimer un lettrage existant dans un dossier Cegid Loop :

Délettrage

Elle permet de cibler :

une ou plusieurs lignes d'écriture avec lignes ;
un lot de lettrage complet avec codeLettrage.

POST/Délettrage

Description

Lien vers la documentation technique

Cas d'usage

Délettrer une ou plusieurs lignes d'écritures déjà lettrées
Délettrer complètement un lot de lettrage à partir de son codeLettrage

Points d'attention

Avant d'appeler cette API, utilisez l'API "GET/EcrituresComptables" afin de récupérer les champs "ligneId" et "codeLettrage".

La requête doit fournir exactement l'un des deux champs lignes ou codeLettrage. Une requête contenant les deux, ou aucun des deux, est rejetée.

Le champ lignes est un tableau plat d'UUID (v4 ou v7). Aucun alias ligneIds n'est accepté. Les doublons présents dans lignes sont dédupliqués avant le traitement.

Le dossier est résolu à partir de codeDossier et de la session authentifiée. Ne pas renseigner dans le body un codeDossier différent de celui de la query.

Le traitement n'est pas globalement transactionnel entre plusieurs lots de lettrage. Un lot peut avoir été validé avant l'échec d'un autre. Il ne faut pas relancer automatiquement l'ensemble de la requête après un 409 sans examiner processedCount et warnings.

Un délettrage est refusé lorsque l'écriture est déjà prise en compte dans une déclaration de TVA supervisée (DECLARATION_SUPERVISED) ou lorsque la période de l'écriture est clôturée ou verrouillée (EXERCISE_CLOSED).

Procédure

Il faut appeler un endpoint :

https://api.cegid.com/loop-api-publiques/unreconcile?codeDossier={codeDossier}

Route	Méthode http	Description
/API	POST	Supprime le lettrage des lignes ou du lot ciblé

Paramétrage de l’appel

Méthode http pour la demande : POST

Header(s) attendu(s) obligatoire(s) de la demande

Champ	Description
Ocp-Apim-Subscription-Key	Subscription key
x-apikey	API Key & Secret
Content-Type	application/json

Paramètres de la demande

Champ	Description	obligatoire
codeDossier	Nom du dossier	Oui

Champ	Type	Description	Obligatoire
lignes	string($uuid)[]	Identifiants des lignes d'écriture à délettrer	Oui si `codeLettrage` est absent ; au moins un UUID
codeLettrage	string($uuid)	Identifiant du lot à délettrer complètement	Oui si `lignes` est absent

En mode lignes, seules les dates de lettrage portées par les lignes ciblées sont retirées. Selon la situation comptable, seule une partie d'un lot peut être délettrée.

En mode codeLettrage, le lot correspondant est délettré complètement.

Exemple de body — délettrage par lignes

{
	"lignes": [
		"123e4567-e89b-42d3-a456-426614174000",
		"123e4567-e89b-42d3-a456-426614174001"
	]
}

Exemple de body — délettrage par code de lettrage

{
	"codeLettrage": "123e4567-e89b-42d3-a456-426614174100"
}

Code retour

En cas de succès

Code retour http de la réponse : 200

En cas de d'échec

Lien vers la liste des codes d'erreur

Statut HTTP	Code principal	Description
`200`	`UNRECONCILE_SUCCESS`	Toutes les cibles ont été traitées
`400`	`INVALID_REQUEST`	Requête incomplète, ambiguë ou UUID invalide
`404`	`UNRECONCILE_NOT_FOUND`	Aucune cible trouvée et aucun traitement effectué
`409`	`UNRECONCILE_PARTIAL_SUCCESS`	Une partie des cibles a été traitée
`409`	`UNRECONCILE_CONFLICT`	État métier incompatible, sans traitement utile
`500`	`UNRECONCILE_TECHNICAL_ERROR`	Erreur technique

Les réponses non 2xx contiennent toujours un champ message. Les codes fonctionnels sont stables ; les libellés message sont illustratifs.

Exemple de message d'erreur :

Exactement l'un des paramètres 'lignes' ou 'codeLettrage' doit être fourni.
No entry found for codeLettrage '123e4567-e89b-42d3-a456-426614174100'.
L'écriture est déjà prise en compte dans une déclaration de TVA supervisée.

Structure du retour

Format du retour

Champ	Type	Description
status	string	`SUCCESS`, `PARTIAL_SUCCESS` ou `ERROR`
code	string	Code fonctionnel ou technique
message	string	Description lisible du résultat
targetMode	string ou `null`	`lignes` ou `codeLettrage`
requestedCount	integer	Nombre de cibles uniques demandées
processedCount	integer	Nombre de cibles traitées
warningCount	integer	Nombre d'avertissements
warnings	tableau	Détail des cibles ignorées ou en erreur

Un avertissement contient :

Champ	Type	Description
code	string	`LINE_NOT_FOUND`, `LINE_NOT_LETTERED`, `CODE_LETTRAGE_NOT_FOUND`, `COMMIT_FAILED`, `DECLARATION_SUPERVISED` ou `EXERCISE_CLOSED`
target	string ou `null`	Identifiant de la cible concernée
message	string	Description de l'avertissement

Exemple de retour — succès

{
	"status": "SUCCESS",
	"code": "UNRECONCILE_SUCCESS",
	"message": "Délettrage terminé.",
	"targetMode": "lignes",
	"requestedCount": 2,
	"processedCount": 2,
	"warningCount": 0,
	"warnings": []
}

Exemple de retour — succès partiel

Le statut HTTP 409 indique qu'une partie des cibles a été traitée. Les modifications déjà validées ne sont pas annulées.

{
	"status": "PARTIAL_SUCCESS",
	"code": "UNRECONCILE_PARTIAL_SUCCESS",
	"message": "Délettrage partiellement terminé.",
	"targetMode": "lignes",
	"requestedCount": 2,
	"processedCount": 1,
	"warningCount": 1,
	"warnings": [
		{
			"code": "LINE_NOT_FOUND",
			"target": "123e4567-e89b-42d3-a456-426614174001",
			"message": "No entry found for ligne '123e4567-e89b-42d3-a456-426614174001'."
		}
	]
}

Exemple de retour — requête invalide

{
	"status": "ERROR",
	"code": "INVALID_REQUEST",
	"message": "Exactement l'un des paramètres 'lignes' ou 'codeLettrage' doit être fourni.",
	"targetMode": null,
	"requestedCount": 0,
	"processedCount": 0,
	"warningCount": 0,
	"warnings": []
}

Exemple de retour — cible absente

{
	"status": "ERROR",
	"code": "UNRECONCILE_NOT_FOUND",
	"message": "No entry found for codeLettrage '123e4567-e89b-42d3-a456-426614174100'.",
	"targetMode": "codeLettrage",
	"requestedCount": 1,
	"processedCount": 0,
	"warningCount": 1,
	"warnings": [
		{
			"code": "CODE_LETTRAGE_NOT_FOUND",
			"target": "123e4567-e89b-42d3-a456-426614174100",
			"message": "No entry found for codeLettrage '123e4567-e89b-42d3-a456-426614174100'."
		}
	]
}

Exemple de retour — déclaration TVA supervisée

{
	"status": "ERROR",
	"code": "UNRECONCILE_CONFLICT",
	"message": "L'écriture est déjà prise en compte dans une déclaration de TVA supervisée.",
	"targetMode": "codeLettrage",
	"requestedCount": 1,
	"processedCount": 0,
	"warningCount": 1,
	"warnings": [
		{
			"code": "DECLARATION_SUPERVISED",
			"target": "123e4567-e89b-42d3-a456-426614174100",
			"message": "L'écriture est déjà prise en compte dans une déclaration de TVA supervisée."
		}
	]
}

Exemple de retour — période clôturée ou verrouillée

{
	"status": "PARTIAL_SUCCESS",
	"code": "UNRECONCILE_PARTIAL_SUCCESS",
	"message": "Délettrage partiellement terminé.",
	"targetMode": "lignes",
	"requestedCount": 2,
	"processedCount": 1,
	"warningCount": 1,
	"warnings": [
		{
			"code": "EXERCISE_CLOSED",
			"target": "123e4567-e89b-42d3-a456-426614174001",
			"message": "La période 2024 de l'écriture 123e4567-e89b-42d3-a456-426614174001 est clôturée ou verrouillée, le délettrage n'est pas possible."
		}
	]
}

Table of Contents