Entités

Les entités structurent l'organisation et déterminent le périmètre des administrateurs et des utilisateurs. Elles restent soumises à l'authentification et aux autorisations indiquées.

Accès commun

Toutes les routes passent par le middleware REST. Un compte WebService doit aussi disposer du couple méthode et chemin dans authorizedApi lorsque cette liste est définie.

Accès	Routes
Utilisateur authentifié	Consultation simple, types, utilisateurs d'une entité et autocomplétion
Privilège manage_entities	Administration, export, adresse héritée et annuaires
Privilège entities_print_sep_mlb	Génération de séparateurs

Une authentification invalide renvoie 401 avec {"errors":"Authentication Failed"}. Une route absente de authorizedApi renvoie 403.

Lister les entités accessibles

GET /rest/entities

La réponse est limitée aux entités calculées pour l'utilisateur authentifié. Aucun privilège supplémentaire n'est contrôlé.

Code HTTP	Type	Description
200	object	Propriété entities, arbre et indicateur allowed
401	object	Authentification invalide
403	object	Route non autorisée au compte WebService

{
  "entities": [
    {
      "entity_id": "SERVICE_A",
      "entity_label": "Service A",
      "serialId": 12,
      "allowed": true
    }
  ]
}

Consulter une entité

GET /rest/entities/{id}

Paramètre URL	Type	Obligatoire	Description
id	integer	Oui	Identifiant technique

L'api ne vérifie ni manage_entities ni le périmètre sur cette route.

Code HTTP	Type	Description
200	object	Entité
400	object	Entity not found
401	object	Authentification invalide
403	object	Route non autorisée au compte WebService

{
  "id": 12,
  "entity_id": "SERVICE_A",
  "entity_label": "Service A",
  "short_label": "SA",
  "enabled": "Y",
  "parent_entity_id": null
}

Consulter le détail administratif

GET /rest/entities/{id}/details

Paramètre URL	Type	Obligatoire	Description
id	string	Oui	Identifiant métier entities.entity_id

Le privilège manage_entities et l'appartenance au périmètre sont obligatoires. La réponse agrège les types, listes, circuits, modèles, utilisateurs, compteurs d'usage et capacités d'administration.

Code HTTP	Type	Description
200	object	Propriété entity
400	object	Entity not found
403	object	Service forbidden ou Entity out of perimeter

Créer une entité

POST /rest/entities

Le privilège manage_entities est obligatoire.

Valeur du body	Type	Obligatoire	Description
entity_id	string	Oui	Identifiant métier, 32 caractères au maximum, caractères alphanumériques, tiret ou souligné
entity_label	string	Oui	Libellé
short_label	string	Oui	Libellé court
entity_type	string	Oui	Type
parent_entity_id	string	Non	Identifiant métier du parent
email	string	Non	Adresse électronique valide
addressNumber, addressStreet, addressAdditional1, addressAdditional2	string	Non	Adresse
addressPostcode, addressTown, addressCountry	string	Non	Localisation
business_id, ldap_id, entity_full_name	string	Non	Références complémentaires
producerService, fastParapheurSubscriberId	string	Non	Références d'intégration

{
  "entity_id": "SERVICE_A",
  "entity_label": "Service A",
  "short_label": "SA",
  "entity_type": "Service",
  "parent_entity_id": "DIRECTION"
}

Code HTTP	Type	Description
200	object	Propriétés entities et id
400	object	Corps ou champ invalide, courriel invalide ou identifiant déjà utilisé
403	object	Service forbidden

Modifier une entité

PUT /rest/entities/{id}

Le paramètre id est l'identifiant métier. Le privilège manage_entities et le périmètre sont obligatoires. Le body reprend les champs de création : entity_label, short_label et entity_type sont obligatoires. Le parent ne peut pas être un descendant.

{
  "entity_label": "Service A",
  "short_label": "SA",
  "entity_type": "Service",
  "parent_entity_id": "DIRECTION",
  "addressNumber": "",
  "addressStreet": "",
  "addressAdditional1": "",
  "addressAdditional2": "",
  "addressPostcode": "",
  "addressTown": "",
  "addressCountry": "",
  "email": "",
  "business_id": "",
  "entity_full_name": "",
  "producerService": ""
}

Code HTTP	Type	Description
200	object	Propriété entities actualisée
400	object	Entity not found, Bad Request ou parent interdit
403	object	Service forbidden ou Entity out of perimeter

Supprimer une entité inutilisée

DELETE /rest/entities/{id}

Le paramètre id est l'identifiant métier. Le privilège manage_entities et le périmètre sont obligatoires. Une entité encore utilisée par une entité fille, un courrier, un utilisateur, un circuit, une redirection ou un contact ne peut pas être supprimée.

Code HTTP	Type	Description
200	array	Entités accessibles actualisées
400	object	Entity not found, Entity is still used ou erreur d'annuaire
403	object	Accès ou périmètre refusé

Réaffecter puis supprimer une entité

PUT /rest/entities/{id}/reassign/{newEntityId}

Paramètre URL	Type	Obligatoire	Description
id	string	Oui	Identifiant métier source
newEntityId	string	Oui	Identifiant métier de remplacement

Le privilège manage_entities est obligatoire et les deux entités doivent appartenir au périmètre. Les usages sont transférés avant suppression de la source.

Code HTTP	Type	Description
200	array	Entités actualisées
400	object	Entity does not exist ou erreur d'annuaire
403	object	Accès ou périmètre refusé

Activer ou désactiver une branche

PUT /rest/entities/{id}/status

Le paramètre id est l'identifiant métier. manage_entities et le périmètre sont obligatoires. Le statut est appliqué à l'entité et à ses descendantes.

Valeur du body	Type	Obligatoire	Description
method	string	Oui	disable désactive toute autre chaîne non vide active

{
  "method": "disable"
}

Code HTTP	Type	Description
200	object	{"success":"success"}
400	object	Entité absente ou Bad Request
403	object	Accès ou périmètre refusé

Lister les utilisateurs d'une entité

GET /rest/entities/{id}/users?filterAbsentUsers=true

Paramètre	Type	Obligatoire	Description
id (URL)	integer	Oui	Identifiant technique de l'entité
filterAbsentUsers (query)	string	Non	true exclut aussi les absents

Les comptes supprimés et suspendus sont toujours exclus. Aucun privilège supplémentaire n'est contrôlé.

Code HTTP	Type	Description
200	object	Propriété users
400	object	Entity not found

{
  "users": [
    {
      "id": 42,
      "user_id": "utilisateur.exemple",
      "firstname": "Utilisateur",
      "lastname": "Exemple"
    }
  ]
}

Récupérer l'adresse héritée

GET /rest/entities/{id}/parentAddress

Le paramètre id est l'identifiant technique. Le privilège manage_entities est obligatoire. La route remonte jusqu'au premier parent possédant une voie et renvoie null si aucune adresse n'est disponible.

Code HTTP	Type	Description
200	object ou null	Adresse héritée
400	object	Entity does not exist
403	object	Service forbidden

Lister les types d'entités

GET /rest/entityTypes

Aucun privilège supplémentaire n'est contrôlé.

Code HTTP	Type	Description
200	object	Propriété types

La structure détaillée d'un type, produite par EntityModel::getTypes(), n'est pas couverte par un test de contrat dédié.

Rechercher des entités

GET /rest/autocomplete/entities?search=service&serial=true

Paramètre query	Type	Obligatoire	Description
search	string	Oui	Texte recherché dans le libellé
serial	valeur non vide	Non	Utilise l'identifiant technique dans id

La recherche porte sur les entités actives et renvoie au plus 50 résultats.

Code HTTP	Type	Description
200	array	Résultats
400	object	Bad Request

[
  {
    "type": "entity",
    "id": 12,
    "serialId": 12,
    "idToDisplay": "Service A",
    "otherInfo": "SA"
  }
]

Exporter les entités

PUT /rest/entities/export

Le privilège manage_entities est obligatoire. Seules les entités autorisées sont exportées.

Valeur du body	Type	Obligatoire	Description
delimiter	string	Non	Virgule, point-virgule ou TAB, point-virgule par défaut
data	array	Non	Colonnes {"label":"Titre","value":"entityId"}

Les valeurs acceptées couvrent les identifiants, libellés, adresse, type, service producteur, listes, circuits, utilisateurs et modèles.

{
  "delimiter": ";",
  "data": [
    {
      "label": "Identifiant",
      "value": "entityId"
    },
    {
      "label": "Libellé",
      "value": "entityLabel"
    }
  ]
}

Code HTTP	Type	Description
200	binaire	CSV export_maarch.csv, type application/vnd.ms-excel
400	object	no allowed fields selected for entities export
403	object	Service forbidden

Synchroniser une entité avec les annuaires M2M

PUT /rest/entities/{id}/annuaries

Le paramètre id est l'identifiant technique. Le privilège manage_entities est obligatoire et le body est vide. La route construit business_id depuis le paramètre siret, puis met à jour les annuaires LDAP configurés.

Code HTTP	Type	Description
200	object	entitySiret et éventuellement synchronized
400	object	Entité ou SIRET absent, configuration ou opération LDAP en erreur
403	object	Service forbidden

{
  "entitySiret": "<siret>/SERVICE_A",
  "synchronized": true
}

Générer des séparateurs

POST /rest/entitySeparators

Le privilège entities_print_sep_mlb est obligatoire.

Valeur du body	Type	Obligatoire	Description
type	string	Oui	qrcode ou barcode
target	string	Oui	generic ou une autre valeur associée à entities
entities	array de string	Conditionnel	Identifiants métier si la cible n'est pas générique

{
  "type": "qrcode",
  "target": "entities",
  "entities": [
    "SERVICE_A"
  ]
}

Code HTTP	Type	Description
200	string JSON	PDF encodé en base64
400	object	Type ou entités absents ou invalides
403	object	Service forbidden

Le QR code peut être préfixé par MAARCH_ lorsque le paramètre QrCodePrefix vaut 1.

Gérer une liste ou un circuit associé à une entité

Ces contrats appartiennent fonctionnellement aux listes de diffusion et aux circuits, mais restent référencés ici pour préserver les liens documentaires historiques.

Action	Route	Accès	Retour
Créer	POST /rest/listTemplates?admin=true	Selon le type : manage_entities, admin_listmodels ou droits de circuit et l'entité dans le périmètre	200 avec id
Modifier	PUT /rest/listTemplates/{id}	Propriétaire, manage_entities ou admin_listmodels selon le modèle et l'entité dans le périmètre	204
Supprimer	DELETE /rest/listTemplates/{id}	Même contrôle de propriété, privilège et périmètre	204

Le body de création contient entityId (identifiant technique), type, title, description et le tableau items. Le body de modification contient title, description et items.

{
  "entityId": 12,
  "type": "diffusionList",
  "title": "Liste du service",
  "description": "Liste de diffusion",
  "items": [
    {
      "id": 42,
      "type": "user",
      "mode": "dest"
    }
  ]
}

Code HTTP	Type	Description
200	object	Création réussie
204	aucun	Modification ou suppression réussie
400	object	Modèle, type, titre, éléments ou identifiant invalide
403	object	Droits, propriété ou périmètre insuffisants