< API Partenaires

< Descriptif des entités

API Partenaire : Connecteur Planitech (import des aides en nature)

Présentation des API partenaires Planitech

Contexte

EN TANT QU’ Agent

JE PEUX disposer d’une documentation d’API sur le connecteur Planitech

AFIN DE déposer des fichiers Planitech et récupérer des rapports d’exécution

MGDIS met à disposition une API partenaire permettant de déposer jusqu’à 15 fichiers Planitech d’une taille maximale de 500 Mo, ainsi que trois API partenaires pour récupérer la liste des rapports, un rapport d’exécution et un rapport des erreurs d’un worker.

Table des matières

Dépôt des fichiers Planitech

Route

L’accès au connecteur Planitech permet d’accéder à la route ci dessous :

Dépôt des fichiers Planitech URL /pda-semi-public-api/api/tenants/{tenantId}/connecteur-aides-en-nature/documents/file
Verbe POST : Dépôt des fichiers Planitech (15 maximum par requête d'une taille limitée à 500 Mo chacun)
Headers Content-Type application/json
Authorization Basic login:mdp
Corps de la requête
 DepotType
Code retour
Code de réponse
 Description Schéma de la réponse
200 Le résultat du traitement est en cours/terminé DepotResponseType
400 Le nombre maximum de fichiers est dépassé et/ou la taille d'un des fichiers dépasse la limite autorisée
401 Non autorisé
403 L'utilisateur courant n'a pas les droits d'accéder à la ressource
500 Une erreur est survenue au niveau du serveur

Types des objets

DepotType

Le corps de la requête pour déposer des fichiers Planitech (15 maximum par requête d'une taille limitée à 500 Mo chacun) devra respecter le schéma DepotType suivant :

Nom Type Contenu Obligatoire Exemple
file text Le fichier Planitech oui "reservations_planitech.csv"

DepotResponseType

Lorsque la requête de dépôt des fichiers est lancée avec succès, le corps de la réponse respecte le schéma DepotResponseType suivant :

Nom Type Contenu Exemple
status number
 Le code de retour 200

Récupération des rapports d'exécution

Routes

L’accès au connecteur Planitech permet d’accéder aux routes ci dessous :

Récupération de la liste des rapports d'exécution URL /pda-semi-public-api/api/tenants/{tenantId}/connecteur-aides-en-nature/reports/last-seven-reports
Verbe GET : Récupération des derniers rapports (sept maximum)
Headers Content-Type application/json
text/html
Authorization Basic login:mdp
Code retour
Code de réponse
 Description Schéma de la réponse
200 Le résultat du traitement est en cours/terminé ReportsListResponseType
400 Requête incorrecte
401 Non autorisé
403 L'utilisateur courant n'a pas les droits d'accéder à la ressource
500 Une erreur est survenue au niveau du serveur
Récupération d'un rapport d'exécution URL /pda-semi-public-api/api/tenants/{tenantId}/connecteur-aides-en-nature/reports/{reportId}
Verbe GET : Récupération d'un rapport avec tous les workers
Headers Content-Type application/json
Authorization Basic login:mdp
Code retour
Code de réponse
 Description Schéma de la réponse
200 Le résultat du traitement est en cours/terminé ReportResponseType
400 Requête incorrecte
401 Non autorisé
403 L'utilisateur courant n'a pas les droits d'accéder à la ressource
404 Le rapport n'a pas été trouvé
500 Une erreur est survenue au niveau du serveur
Récupération du rapport d'un worker URL /pda-semi-public-api/api/tenants/{tenantId}/connecteur-aides-en-nature/reports/{reportId}/{typeWorker}/{typeTreatment}/errors
Verbe GET : Récupération d'un rapport des erreurs pour un worker
Headers Content-Type application/json
Authorization Basic login:mdp
Code retour
Code de réponse
 Description Schéma de la réponse
200 Le résultat du traitement est en cours/terminé ReportErrorsListResponseType
400 Requête incorrecte
401 Non autorisé
403 L'utilisateur courant n'a pas les droits d'accéder à la ressource
404 Le rapport n'a pas été trouvé
500 Une erreur est survenue au niveau du serveur

Type des objets

ReportsListResponseType

Lorsque la requête de récupération des derniers rapports d'exécution (sept maximum) est lancée avec succès, le corps de la réponse respecte le schéma ReportsListResponseType suivant :

Nom Type Contenu Exemple
Array<ReportType> Il s'agit d'un tableau où chaque item représente un rapport d'exécution. Tous les rapports d'exécution conservés (sept maximum) sont renvoyés
cas d'erreur
code number
 Le code d'erreur 403.1
message string
 Le message d'erreur "Access is denied"

ReportType

Lorsque la requête de récupération des derniers rapports d'exécution (sept maximum) est lancée avec succès, un item dans le tableau renvoyé respecte le schéma ReportType suivant :

Nom Type Contenu Exemple
id string
 L'identifiant du rapport "/connecteur-aides-en-nature/api/tenants/test/reports/1"
reference string La référence du rapport "1"
title string Le titre du rapport "test rapport 1"
status string Le statut du rapport (INPROGRESS, FINISHED ou FAILED) "INPROGRESS"
tenant string Le tenant de l'environnement "test"
date string La date de création du rapport (équivalente au lancement du premier worker) "2024-12-23T09:01:24.871Z"

ReportResponseType

Lorsque la requête de récupération d'un rapport d'exécution est lancée avec succès, le corps de la réponse respecte le schéma ReportResponseType suivant :

Nom Type Contenu Exemple
id string L'identifiant du rapport "/connecteur-aides-en-nature/api/tenants/test/reports/1"
title string Le titre du rapport "test rapport 1"
status string Le statut du rapport (INPROGRESS, FINISHED ou FAILED) "FINISHED"
tenant string Le tenant de l'environnement "test"
date string La date de création du rapport (équivalente au lancement du premier worker) "23/12/2024 09:01:24"
items Array<ReportItemType> Il s'agit d'un tableau où chaque item représente le rapport d'exécution d'un worker
cas d'erreur
code number
 Le code d'erreur 403.1
message string
 Le message d'erreur "Access is denied"

ReportItemType

Lorsque la requête de récupération d'un rapport d'exécution est lancée avec succès, un item dans le tableau renvoyé respecte le schéma ReportItemType suivant :

Nom Type Contenu Exemple
id string
 L'identifiant du rapport de l'item "/connecteur-aides-en-nature/api/tenants/test/reports/item/1"
typeWorker string Le nom du worker (INITIALIZER, ASSISTANT, COMPARER ou IMPORTER) "INITIALIZER"
status string Le statut du rapport de l'item (INPROGRESS, FINISHED ou FAILED) "FINISHED"
date string La date de création du rapport de l'item (équivalente au lancement du worker) "23/12/2024 13:02:32"
details Array<ReportItemDetailsType> Il s'agit d'un tableau avec les détails de l'exécution d'un worker
uniquement pour le worker COMPARER
totalItems number
 Le nombre total d'aides en nature comparées 6003
totalItemsToDelete number
 Le nombre d'aides en nature à supprimer 0
totalItemsToUpdate number
 Le nombre d'aides en nature à modifier 19
totalItemsToCreate number
 Le nombre d'aides en nature à importer 5981
totalItemsIdentical number
 Le nombre d'aides en nature identiques entre celles issues des fichiers Planitech et celles existantes dans AIDEN 3
uniquement pour le worker IMPORTER
totalItems number
 Le nombre total d'aides en nature 6003
totalItemsDeleted number
 Le nombre d'aides en nature supprimées 0
totalItemsUpdated number
 Le nombre d'aides en nature modifiées 17
totalItemsCreated number
 Le nombre d'aides en nature importées 5981
totalItemsFailed number
 Le nombre d'aides en nature en erreur (traitement échouée) 2
totalItemsIgnored number
 Le nombre d'aides en nature ignorées (identiques entre celles issues des fichiers Planitech et celles existantes dans AIDEN) 3

ReportItemDetailsType

Lorsque la requête de récupération d'un rapport d'exécution est lancée avec succès, les détails de l'exécution d'un worker respectent le schéma ReportItemDetailsType suivant :

Nom Type Contenu Exemple
success Array<object> Il s'agit d'un tableau avec les messages de succès 
"success": [
  {"success": "20800 lignes planitech récupérées."},
  {"success": "7369 aides AIDEN récupérées."},
  {"success": "486 tiers AIDEN récupérés."}
]
uniquement pour le worker INITIALIZER (les autres workers fournissent un url vers le rapport des erreurs)
errors Array<object> Il s'agit d'un tableau avec les messages d'erreurs 
"errors": [
  {"error": "Le(s) fichier(s) d'entrée ne contiennent aucune donnée."}
]
pour tous les workers sauf INITIALIZER
urlReportErrorDescription string
 La description du champ urlReportError "Pour accéder aux erreurs, utilisez l'URL ci-dessous : "
urlReportError string
 L'URL du rapport des erreurs "https://mgdis-env.mgdis.ovh/pda-semi-public-api/api/tenants/test/connecteur-aides-en-nature/reports/1/assistant/created/errors"
uniquement pour le worker IMPORTER
typeTreatment string
 Le type de traitement des aides en nature (DELETED, UPDATED ou CREATED) "UPDATED"

Exemple de rapport d’exécution :

				
					{
    "tenant": "test",
    "id": "/connecteur-aides-en-nature/api/tenants/test/reports/1",
    "title": "test rapport 1",
    "date": "23/12/2024 09:01:24",
    "status": "FINISHED",
    "items": [
        {
            "id": "/connecteur-aides-en-nature/api/tenants/test/reports/item/1",
            "typeWorker": "INITIALIZER",
            "date": "23/12/2024 09:01:24",
            "status":"FINISHED",
            "details": [
                {
                    "success": [
                        {
                            "success": "20800 lignes planitech récupérées."
                        },
                        {
                            "success": "7369 aides AIDEN récupérées."
                        },
                        {
                            "success": "486 tiers AIDEN récupérés."
                        }
                    ]
                }
            ]
        },
        {
            "id": "/connecteur-aides-en-nature/api/tenants/saumur/reports/item/2",
            "typeWorker": "ASSISTANT",
            "date": "23/12/2024 09:07:00",
            "status": "FINISHED",
            "details": [
                {
                    "success": [
                        {
                            "success": "7369 aides Aiden récupérées (après suppression des doublons)."
                        },
                        {
                            "success": "12560 aides planitech à comparer."
                        }
                    ],
                    "urlReportErrorDescription": "Pour accéder aux erreurs, utilisez l'URL ci-dessous : ",
                    "urlReportError": "https://mgdis-env.mgdis.ovh/pda-semi-public-api/api/tenants/test/connecteur-aides-en-nature/reports/1/assistant/created/errors"
                }
            ]
        },
        {
            "id": "/connecteur-aides-en-nature/api/tenants/test/reports/item/3",
            "typeWorker": "COMPARER",
            "date": "23/12/2024 09:16:09",
            "status": "FINISHED",
            "details": [],
            "totalItemsToDelete": 0,
            "totalItemsToUpdate": 2096,
            "totalItemsToCreate": 5186,
            "totalItemsIdentical": 5278,
            "totalItems": 12560
        },
        {
            "id": "/connecteur-aides-en-nature/api/tenants/test/reports/item/4",
            "typeWorker": "IMPORTER",
            "date": "23/12/2024 09:31:00",
            "status": "FINISHED",
            "details": [
                {
                    "typeTreatment": "DELETED"
                },
                {
                    "typeTreatment": "UPDATED",
                    "urlReportErrorDescription": "Pour accéder aux erreurs, utilisez l'URL ci-dessous : ",
                    "urlReportError": "https://mgdis-env.mgdis.ovh/pda-semi-public-api/api/tenants/test/connecteur-aides-en-nature/reports/1/importer/updated/errors"
                },
                {
                    "typeTreatment": "CREATED"
                }
            ],
            "totalItems": 12560,
            "totalItemsDeleted": 0,
            "totalItemsUpdated": 2094,
            "totalItemsCreated": 5186,
            "totalItemsFailed": 2,
            "totalItemsIgnored": 5278
        }
    ]
}

D’autres exemples par worker : ici

ReportErrorsListResponseType

Lorsque la requête de récupération d'un rapport des erreurs est lancée avec succès, le corps de la réponse respecte le schéma ReportErrorsListResponseType suivant :

Nom Type Contenu Exemple
Array<ErrorType> Il s'agit d'un tableau où chaque item représente une erreur
cas d'erreur
code number
 Le code d'erreur 403.1
message string
 Le message d'erreur "Access is denied"

ErrorType

Lorsque la requête de récupération d'un rapport des erreurs est lancée avec succès, un item dans le tableau renvoyé respecte le schéma ErrorType suivant :

Nom Type Contenu Exemple
message string
 Le message d'erreur Exemple pour le worker ASSISTANT :
"Réservation en erreur : au moins un champ obligatoire n'est pas rempli sur cette ligne. Toutes les lignes de cette réservation ont donc été ignorées."

Exemple pour le worker IMPORTER :
"Fichier /tmp/temporary/differentiel-1.csv non importé. Erreur : Le type d'aide correspondant à la référence /referentiel-financement/api/tenants/test/types-aide-nature/ville n'existe pas ou est inactif."
pour les erreurs du worker ASSISTANT
referenceAdministrativeAIDENTiers string La référence administrative AIDEN du tiers associée à la ligne de réservation en erreur dans le fichier Planitech null
siren string Le siren du tiers associé à la ligne de réservation en erreur dans le fichier Planitech null
nic string Le nic du tiers associé à la ligne de réservation en erreur dans le fichier Planitech "00000"
codeRNA string Le code RNA du tiers associé à la ligne de réservation en erreur dans le fichier Planitech null
identifiantDuGap string L'identifiant du gap associé à la ligne de réservation en erreur dans le fichier Planitech "271205"
identifiantDeLaReservation string L'identifiant de la réservation associé à la ligne de réservation en erreur dans le fichier Planitech "1594"
environnementExtraction string L'environnement d'extraction associé à la ligne de réservation en erreur dans le fichier Planitech "environnementTest"
organisme string L'organisme attributaire associé à la ligne de réservation en erreur dans le fichier Planitech "organismeTest"
tiers object Les tiers multiples ou non trouvés dans AIDEN (issus des fichiers Planitech) 
"tiers": {
  "0": {
    "referenceAdministrativeAIDENTiers": "azerty",
    "siren": "123456789",
    "nic": "12345",
    "codeRNA": "W000000000"
  },
  "1": {
    "referenceAdministrativeAIDENTiers": "qwerty",
    "siren": "987654321",
    "nic": "54321",
    "codeRNA": "W111111111"
  }
}

Exemple de rapport des erreurs :

				
					[
    {
        "message": "Réservation en erreur : au moins un champ obligatoire n'est pas rempli sur cette ligne. Toutes les lignes de cette réservation ont donc été ignorées.",
        "identifiantDuGap": "271205",
        "ReferenceAdministrativeAIDENTiers": null,
        "siren": null,
        "nic": "00000",
        "codeRNA": null,
        "identifiantDeLaReservation": "1594",
        "environnementExtraction": "environnementTest",
        "organisme": "organismeTest"
    },
    {
        "message": "Réservation en erreur : au moins une valeur n'est pas au bon format sur cette ligne. Toutes les lignes provenant de la même réservation ont donc été ignorées.",
        "identifiantDuGap": "116249",
        "ReferenceAdministrativeAIDENTiers": "abc123?",
        "siren": "986754231",
        "nic": "0",
        "codeRNA": "T456",
        "identifiantDeLaReservation": "2638",
        "environnementExtraction": "environnementTest",
        "organisme": "organismeTest"
    }
    {
        "message": "Réservation en erreur : au moins un champ obligatoire n'est pas rempli, et au moins une valeur n'est pas au bon format sur cette ligne. Toutes les lignes provenant de la même réservation ont donc été ignorées.",
        "identifiantDuGap": "270195",
        "ReferenceAdministrativeAIDENTiers": null,
        "siren": null,
        "nic": "00000",
        "codeRNA": null,
        "identifiantDeLaReservation": "17839",
        "environnementExtraction": "environnementTest",
        "organisme": "organismeTest"
    },
    {
        "message": "Les tiers suivants n'ont pas été reconnus, les aides en Nature correspondantes ne peuvent pas être créées : ",
        "tiers": {
            "0": {
                "referenceAdministrativeAIDENTiers": "azerty",
                "siren": "123456789",
                "nic": "12345",
                "codeRNA": "W000000000"
            }
        }
    },
    {
        "message": "Il existe plusieurs tiers au statut SUPPORTED avec la même référence administrative, le même SIRET ou le même codeRNA, les aides en Nature correspondantes ne peuvent pas être créées : ",
        "tiers": {
            "0": {
                "referenceAdministrativeAIDENTiers": "qwerty",
                "siren": "987654321",
                "nic": "54321",
                "codeRNA": "W111111111"
            }
        }
    }
]