API des contacts¶

Structure d’un contact¶

Les routes de création et de modification utilisent les champs suivants. lastname ou company doit être renseigné. D’autres champs peuvent être obligatoires selon le paramétrage des contacts.

Valeur	Type	Obligatoire	Description
`civility`	integer	Non	Identifiant dans `contacts_civilities.id`
`firstname`	string	Non	Prénom
`lastname`	string	Conditionnel	Nom ; obligatoire si `company` est vide
`company`	string	Conditionnel	Société ; obligatoire si `lastname` est vide
`department`	string	Non	Service de la société
`function`	string	Non	Fonction du contact
`addressNumber`	string	Non	Numéro de voie
`addressStreet`	string	Non	Voie
`addressAdditional1`	string	Non	Point de remise
`addressAdditional2`	string	Non	Complément d’acheminement
`addressPostcode`	string	Non	Code postal
`addressTown`	string	Non	Ville
`addressCountry`	string	Non	Pays
`email`	string	Non	Adresse électronique valide
`phone`	string	Non	Numéro de téléphone
`communicationMeans`	object	Non	Moyen Maarch2Maarch : `email` ou `url`, avec `login` et `password` facultatifs
`notes`	string	Non	Notes
`externalId`	object	Non	Identifiants externes, notamment `m2m`
`customFields`	object	Non	Valeurs indexées par identifiant de champ personnalisé
`isConfidential`	boolean	Non	Caractère confidentiel du contact

Les champs texte contrôlés sont limités à 256 caractères. Les droits liés à la confidentialité sont détaillés dans l’index Contacts.

Lister les contacts¶

Route¶

GET /rest/contacts

Cette route nécessite le privilège admin_contacts.

Query string¶

Valeur	Type	Obligatoire	Valeur par défaut	Description
`offset`	integer	Non	`0`	Décalage de pagination
`limit`	integer	Non	`25`	Nombre de contacts retournés
`search`	string	Non		Recherche sur les champs standards et personnalisés
`order`	string	Non		`asc` ou `desc`
`orderBy`	string	Non	`id`	`firstname`, `lastname`, `company` ou `filling`

Retour¶

Code HTTP	Type	Description
`200`	object	Liste paginée dans `contacts` et nombre total dans `count`
`403`	object	Privilège insuffisant

{
  "contacts": [
    {
      "id": 21,
      "firstname": "Clark",
      "lastname": "Kent",
      "company": "Daily Planet",
      "enabled": true,
      "sector": "Paris centre",
      "isUsed": true,
      "filling": {"rate": 75, "thresholdLevel": "second"}
    }
  ],
  "count": 1
}

Créer un contact¶

Route¶

POST /rest/contacts

Cette route nécessite create_contacts ou admin_contacts.

Body¶

Le body suit la structure d’un contact.

{
  "civility": 1,
  "firstname": "Clark",
  "lastname": "Kent",
  "company": "Daily Planet",
  "department": "Rédaction",
  "function": "Reporter",
  "addressNumber": "30",
  "addressStreet": "Rue des avions",
  "addressPostcode": "75001",
  "addressTown": "Paris",
  "addressCountry": "France",
  "email": "clark.kent@daily-planet.example",
  "phone": "+33120212223",
  "communicationMeans": {"url": "https://courrier.example/rest/"},
  "externalId": {"companyId": "123456789"},
  "customFields": {"2": "Fournisseur"},
  "isConfidential": false
}

Pour un utilisateur REST, si un contact possède déjà le même courriel, son identifiant est retourné sans créer de doublon.

Retour¶

Code HTTP	Description	Exemple
`200`	Contact créé ou contact existant retrouvé	`{"id":21,"warning":""}`
`400`	Body ou valeur invalide	`{"errors":"Body lastname or company is mandatory"}`
`403`	Privilège insuffisant ou confidentialité non autorisée	`{"errors":"Service forbidden"}`

Rechercher le secteur d’une adresse¶

Route¶

GET /rest/contacts/sector

Query string¶

Au moins un paramètre doit être fourni. Tous sont des chaînes facultatives.

Valeur	Description
`addressNumber`	Numéro de voie
`addressStreet`	Voie
`addressPostcode`	Code postal
`addressTown`	Ville

Retour¶

Code HTTP	Description
`200`	Secteur correspondant, ou `null` si aucun secteur ne correspond
`400`	Query string absente ou valeur invalide

{"sector":{"id":1,"label":"Paris centre"}}

Consulter un contact¶

Route¶

GET /rest/contacts/{id}

Paramètres¶

Valeur	Emplacement	Type	Obligatoire	Description
`id`	URL	integer	Oui	Identifiant du contact
`resourcesCount`	Query string	boolean	Non	Ajoute le nombre d’utilisations dans les courriers, accusés et pièces jointes

Retour¶

Code HTTP	Description
`200`	Contact complet, avec civilité, créateur, dates, champs personnalisés, taux de complétude et éventuellement `resourcesCount`
`400`	Identifiant invalide ou contact inexistant

{
  "id": 21,
  "civility": {"id": 1, "label": "Monsieur", "abbreviation": "M."},
  "firstname": "Clark",
  "lastname": "Kent",
  "company": "Daily Planet",
  "communicationMeans": {"url": "https://courrier.example/rest/", "login": null},
  "enabled": true,
  "customFields": {"2": "Fournisseur"},
  "externalId": {"companyId": "123456789"},
  "sector": "Paris centre",
  "isConfidential": false,
  "fillingRate": {"rate": 75, "thresholdLevel": "second"}
}

Exporter les contacts¶

Route¶

PUT /rest/contacts/export

Cette route nécessite admin_contacts.

Body¶

Valeur	Type	Obligatoire	Description
`delimiter`	string	Oui	`,`, `;` ou `TAB`
`data`	array	Oui	Colonnes à exporter
`data[].value`	string	Oui	Identifiant du champ
`data[].label`	string	Oui	En-tête de la colonne CSV

Les champs standards de la structure d’un contact sont acceptés, ainsi que id, creator, creatorLabel, creationDate, modificationDate, enabled, sector et contactCustomField_{id}.

{
  "delimiter": ";",
  "data": [
    {"value": "lastname", "label": "Nom"},
    {"value": "email", "label": "Courriel"},
    {"value": "contactCustomField_2", "label": "Type de partenaire"}
  ]
}

Retour¶

Code HTTP	Description
`200`	Fichier `export_maarch.csv`, type `application/vnd.ms-excel`
`400`	Délimiteur, colonne ou champ personnalisé invalide
`403`	Privilège insuffisant

Importer les contacts¶

Route¶

PUT /rest/contacts/import

Cette route nécessite admin_contacts.

Body¶

Valeur	Type	Obligatoire	Description
`contacts`	array	Oui	Contacts à créer ou modifier
`contacts[].id`	integer	Non	Présent pour modifier un contact existant
`contacts[].contactCustomField_{id}`	mixed	Non	Valeur d’un champ personnalisé

Les autres propriétés correspondent aux champs standards. Lors d’une modification, la valeur booléenne false efface le champ concerné. Les champs personnalisés checkbox attendent un tableau ; integer, date, string, select et radio sont validés selon leur type.

{
  "contacts": [
    {
      "lastname": "Kent",
      "firstname": "Clark",
      "email": "clark.kent@daily-planet.example",
      "contactCustomField_2": "Fournisseur"
    }
  ]
}

Retour¶

L’import continue après une ligne invalide et retourne un bilan détaillé.

{
  "success": 1,
  "errors": {"count": 0, "details": []}
}

Code HTTP	Description
`200`	Bilan des créations et modifications
`400`	`contacts` n’est pas un tableau
`403`	Privilège insuffisant

Modifier un contact¶

Route¶

PUT /rest/contacts/{id}

Cette route nécessite update_contacts ou admin_contacts. Le body suit la structure d’un contact.

Warning

Cette opération remplace la représentation du contact. Les champs absents sont enregistrés à null ou réinitialisés ; envoyer les valeurs à conserver.

Retour¶

Code HTTP	Description
`204`	Contact modifié, sans contenu
`200`	Contact modifié avec un avertissement de synchronisation Maarch2Maarch
`400`	Identifiant, format ou champ invalide ; contact inexistant
`403`	Privilège ou droit de confidentialité insuffisant

Supprimer un contact¶

Route¶

DELETE /rest/contacts/{id}

Cette route nécessite admin_contacts.

Paramètres¶

Valeur	Emplacement	Type	Obligatoire	Description
`id`	URL	integer	Oui	Contact à supprimer
`redirect`	Query string	integer	Non	Contact qui reprend les liaisons du contact supprimé

Le contact de redirection doit exister et être différent du contact supprimé. La suppression nettoie les liaisons aux courriers, pièces jointes et groupes ; avec redirect, les liaisons compatibles sont d’abord réaffectées.

Retour¶

Code HTTP	Description
`204`	Contact supprimé, sans contenu
`400`	Identifiant ou redirection invalide ; contact inexistant
`403`	Privilège insuffisant

Activer ou désactiver un contact¶

Route¶

PUT /rest/contacts/{id}/activation

Cette route nécessite admin_contacts.

{"enabled": true}

Une valeur absente ou fausse désactive le contact.

Retour¶

Code HTTP	Description
`204`	Statut modifié, sans contenu
`400`	Identifiant invalide ou contact inexistant
`403`	Privilège insuffisant

Consulter un correspondant au format léger¶

Route¶

GET /rest/formattedContacts/{id}/types/{type}

Paramètre d’URL	Type	Description
`id`	integer	Identifiant du correspondant
`type`	string	`contact`, `user` ou `entity`

Retour¶

Code HTTP	Description
`200`	Objet `contact` adapté au type demandé
`400`	Identifiant invalide, type non reconnu ou correspondant inexistant

{"contact":{"firstname":"Clark","lastname":"Kent","company":"Daily Planet"}}

Lister les départements disponibles pour la BAN¶

Route¶

GET /rest/ban/availableDepartments

La source dépend du paramètre addressSearch : liste nationale en mode online, collections Typesense BAN_* en mode local.

Retour¶

Code HTTP	Description
`200`	Liste `departments` et département `default`, éventuellement `null`
`500`	Serveur d’index local indisponible

{"departments":["01","02","2A","2B","75","971"],"default":"75"}

Rechercher les doublons¶

Route¶

GET /rest/duplicatedContacts

Cette route nécessite admin_contacts.

Query string¶

Valeur	Type	Obligatoire	Valeur par défaut	Description
`criteria[]`	array	Oui		Critères de rapprochement
`limit`	integer	Non	`500`	Nombre maximal de groupes, plafonné à 500
`offset`	integer	Non	`0`	Décalage par groupes de doublons

Critères standards : civility, firstname, lastname, company, addressNumber, addressStreet, addressAdditional1, addressAdditional2, addressPostcode, addressTown, addressCountry, department, function, email, phone et notes. Un champ personnalisé se note contactCustomField_{id}.

Exemple :

GET /rest/duplicatedContacts?criteria[]=lastname&criteria[]=email&limit=50

Retour¶

{
  "returnedCount": 1,
  "realCount": 1,
  "contacts": [
    {"duplicateId": 1, "id": 21, "lastname": "Kent", "email": "clark@example.org"},
    {"duplicateId": 1, "id": 45, "lastname": "Kent", "email": "clark@example.org"}
  ]
}

Code HTTP	Description
`200`	Groupes de doublons paginés
`400`	Critère absent ou inconnu
`403`	Privilège insuffisant

Fusionner des contacts¶

Route¶

PUT /rest/contacts/{id}/merge

Cette route nécessite admin_contacts. id désigne le contact maître.

{"duplicates":[45,46]}

Les champs vides du maître sont complétés depuis les doublons. Les champs personnalisés et identifiants externes sont fusionnés, les liaisons sont transférées, puis les doublons sont supprimés.

Retour¶

Code HTTP	Description
`204`	Fusion effectuée, sans contenu
`400`	Identifiant invalide, tableau absent ou contact inexistant
`403`	Privilège insuffisant

Consulter le paramétrage des contacts¶

Route¶

GET /rest/contactsParameters

Retour¶

Code HTTP	Type	Description
`200`	object	Seuils de complétude, paramètres des champs et état de l’annuaire Maarch2Maarch

Donnée	Type	Description
`contactsFilling.enable`	boolean	Active le calcul de complétude
`contactsFilling.first_threshold`	integer	Premier seuil, en pourcentage
`contactsFilling.second_threshold`	integer	Second seuil, en pourcentage
`contactsParameters[].id`	integer	Identifiant du paramètre
`contactsParameters[].identifier`	string	Champ standard ou `contactCustomField_{id}`
`contactsParameters[].mandatory`	boolean	Champ obligatoire
`contactsParameters[].filling`	boolean	Champ pris en compte dans la complétude
`contactsParameters[].searchable`	boolean	Champ utilisé par l’autocomplétion
`contactsParameters[].displayable`	boolean	Champ affiché par l’autocomplétion
`contactsParameters[].label`	string ou null	Libellé du champ personnalisé
`annuaryEnabled`	boolean	Annuaire Maarch2Maarch activé

{
  "contactsFilling": {"id":1,"enable":true,"first_threshold":33,"second_threshold":66},
  "contactsParameters": [
    {"id":9,"identifier":"lastname","mandatory":true,"filling":true,"searchable":true,"displayable":true,"label":null}
  ],
  "annuaryEnabled": false
}

Modifier le paramétrage des contacts¶

Route¶

PUT /rest/contactsParameters

Cette route nécessite admin_contacts. Le body reprend contactsFilling et contactsParameters retournés par la route de consultation.

Les seuils doivent être des entiers tels que 0 < first_threshold < second_threshold < 100.

Retour¶

Code HTTP	Description	Exemple
`200`	Paramétrage enregistré	`{"success":"success"}`
`400`	Structure ou seuils invalides	`{"errors":"Bad Request"}`
`403`	Privilège insuffisant	`{"errors":"Service forbidden"}`