Documentation de l’API

Bienvenue dans la documentation de l’API de Run My Service !

L’API est accessible à :

https://api-public.runmyservice.com

Sommaire

Activation de la fonctionnalité API
Autorisation
Limitations d’usage
Format des requêtes et des réponses
Index des modules

Activation de la fonctionnalité API

Pour avoir accès à l’API Run My Service, il faut activer cette option dans votre abonnement. Contactez votre conseiller Run My Service pour l’activer.

Une fois activée, l’administrateur du compte doit naviguer vers app.runmyservice.com et ouvrir le menu Paramètres puis API.

Écran Paramètres > API de app.runmyservice.com listant les clés d’accès actives et le bouton Ajouter

Ici se trouvent toutes les clés d’accès actives pour votre compte. Ces clés sont sensibles et peuvent à tout moment être supprimées. Si vous pensez avoir divulgué une clé par erreur, vous pouvez la supprimer via cette interface et en créer une nouvelle.

Cliquez sur Ajouter afin de créer une nouvelle clé.

Fenêtre de création d’une clé d’API affichant l’identifiant et la clé privée, visible une seule fois

Notez bien l’identifiant ainsi que la clé privée. Cette dernière ne sera affichée qu’une seule fois : sauvegardez-la immédiatement.

Autorisation

Chaque requête auprès de l’API doit être accompagnée d’un jeton au format JWT (JSON Web Token), passé dans l’en-tête Authorization de la requête HTTPS (précédé du mot Bearer) :

Exemple d’en-tête HTTP Authorization contenant le mot Bearer suivi du jeton JWT

Commencez par demander le jeton JWT à l’URL suivante, en envoyant l’identifiant (identifier) et la clé privée (secret) obtenus sur app.runmyservice.com :

POST https://api-public.runmyservice.com/v1/login
# le corps du message, au format JSON :
{
	"identifier": "61b23cc92353a3894886aa36",
	"secret": "04c533ca35344d5ebba37f9070f404c9f7b9a9cdca5a439988b795c240795eda"
}

La réponse à cette requête est la suivante (au format JSON) :

{
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...."
}

Pour toutes les requêtes suivantes, ajoutez le texte du champ jwt à l’en-tête Authorization, par exemple : Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

À noter : chaque jeton n’est valable qu’une heure. Si votre jeton a expiré, l’API retourne une réponse avec le code 403 et, dans le corps de la réponse, la structure suivante :

{
    "errorCode": 403,
    "code": "auth/token-expired",
    "message": "Token expired. Use the /login endpoint again to get a new token."
}

Dans ce cas, il suffit de demander un nouveau jeton en renvoyant une requête à /login avec vos identifiants d’accès.

Limitations d’usage

L’API est en lecture seule. Vous pouvez l’interroger, mais aucune modification n’est autorisée.

Afin de garantir une qualité de service équilibrée, l’API limite le taux de requêtes à 10 par seconde. Au-delà, vous recevrez l’erreur suivante :

{
    "errorCode": 429,
    "code": "auth/rate-limit-exceeded",
    "message": "Rate limit exceeded, retry after XXX seconds."
}

Format des requêtes et des réponses

Toutes les requêtes de cette API respectent un format standardisé selon le type de requête HTTP :

POST : obtenir une liste de fiches selon des critères de pagination, en appliquant des filtres et en retournant des champs précis. Ces critères sont passés dans le corps du message, au format JSON.
GET : obtenir une fiche précise à partir de son ID.

À noter : dans le reste de cette documentation, les chemins indiqués sont relatifs à https://api-public.runmyservice.com.

Requêtes `POST`

Voici un exemple de requête POST pour obtenir une liste d’intervenants :

POST /v1/data/animator
# corps du message :
{
  "limit": 10,
  "page": 0,
  "orderBy": [{
    "key": "uniqueIndex",
    "dir": "desc"
  }],
  "filters": [
    {
      "key": "familyName",
      "op": "like",
      "values": ["nàme1"]
    }
  ],
  "fields": ["uniqueIndex", "email"]
}

Les champs possibles sont :

Champ	Type	Description
limit	number	(facultatif, défaut = 10) Le nombre de fiches à retourner (attention, nous imposons un maximum de 50 fiches par requête)
page	number	(facultatif, défaut = 0) Le numéro de la page à récupérer, en tenant compte de la limite et l’ordre
orderBy	object ou object[]	(facultatif) Une liste de structures pour trier les fiches
orderBy.key	string	Le nom du champ de la fiche à utiliser pour faire le tri. Vous pouvez désigner des champs de sous-objets en utilisant des points, par exemple : `address.region`
orderBy.dir	enum(string)	La direction du tri. Valeurs possibles : `asc` (croissant), `desc` (décroissant)
filters	object ou object[]	(facultatif) Une liste de structures pour filtrer les résultats
filters.key	string	Le nom du champ de la fiche à utiliser pour filtrer. Vous pouvez désigner des champs de sous-objets en utilisant des points, par exemple : `address.region`
filters.op	enum(string)	Le type d’opérateur à utiliser pour effectuer le filtre. Valeurs possibles : `like` (similaire à, sans tenir compte des accents ni de la casse), `gt` (supérieur à), `lt` (inférieur à), `gte` (supérieur ou égal à), `lte` (inférieur ou égal à), `betweenEq` (entre deux valeurs, inclusif), `between` (entre deux valeurs, exclusif), `in` (parmi les valeurs données), `nin` (pas parmi les valeurs données), `ne` (différent de), `eq` (égal à), `empty` (le champ est vide ou n’existe pas)
fields	string[]	(facultatif) Une liste de champs à retourner ; à défaut, tous les champs de la fiche sont retournés. Utilisez ce champ afin d’optimiser vos requêtes en demandant seulement les champs qui vous intéressent.

La requête retourne des données du format suivant :

{
    "page": 0,
    "limit": 10,
    "orderBy": [
        {
            "key": "uniqueIndex",
            "dir": "asc"
        }
    ],
    "filter": [],
    "count": 11,
    "docs": [
        {
            "id": "616fded96682f80889a0ecba",
            "data": {
                "_id": "616fded96682f80889a0ecba",
                "uniqueIndex": 1,
                "userId": "drilgb0vIOWfz4h6aI52rj5BUmI3",
                "status": "active",
                "displayName": "Name1 Surname1",
                "familyName": "Surname1",
                "givenName": "Name1",
                "maidenName": "Maiden Name 1",
                ...

            }
        },
        {
            "id": ...,
            "data": { ... }
        }
    ]
}

Champ	Type	Description
page	number	La page retournée
limit	number	La limite imposée pour les données retournées
count	number	Le nombre total de fiches trouvées selon les critères. Utile pour implémenter un système de pagination.
orderBy	object	Les paramètres du tri appliqué (normalement une copie des paramètres de la requête)
filter	object	Les paramètres des filtres appliqués (normalement une copie des paramètres de la requête)
docs	object[]	La liste des documents retournés
docs.*.id	string	L’identifiant unique de la fiche
docs.*.data	object	Les données brutes de la fiche. Cette documentation contient une description détaillée de chaque module.

Requêtes `GET`

Obtenir une fiche précise, par exemple :

# Obtenir un intervenant précis, en remplaçant :id avec un identifiant
GET /v1/data/animator/:id

# Exemple
GET /v1/data/animator/616fded96682f80889a0ecba

La requête retourne des données du format suivant :

{
  "id": "616fded96682f80889a0ecba",
  "data": {
      "_id": "616fded96682f80889a0ecba",
      "uniqueIndex": 1,
      "userId": "drilgb0vIOWfz4h6aI52rj5BUmI3",
      "status": "active",
      "displayName": "Name1 Surname1",
      "familyName": "Surname1",
      "givenName": "Name1",
      "maidenName": "Maiden Name 1",
      ...

  }
}

À noter : si la fiche n’existe pas, ou si le ou les ID passés en paramètre ne sont pas reconnus, la réponse retourne un statut 404.

Schéma

Le schéma suivant représente les relations entre les différents modules. Nous indiquons uniquement les champs concernés par les relations. Consultez la documentation de chaque module pour la liste exhaustive des champs.

Schéma des relations entre les collections de l’API : Delegate, Animator, Customer, Action et leurs sous-collections

Les identifiants et clés étrangères sont volontairement redondants d’une collection à l’autre, afin de simplifier les requêtes sans devoir enchaîner les jointures.

Les collections sont :

Delegate : la liste d’utilisateurs de app.runmyservice.com. Chaque utilisateur a un rôle avec les autorisations associées.
Animator : la liste d’intervenants
AnimatorCompany : la liste des structures de type personne morale (pour les intervenants de ce statut)
Service : la liste de prestations
Customer : la liste de comptes
CustomerBudget : les enveloppes des comptes de type subvention
CustomerContact : les contacts des comptes
Team : la liste des équipes
Action : la liste d’interventions
ActionCustomer : la liste de comptes associés à chaque intervention
ActionEvent : la liste d’événements associés à chaque intervention
ActionEventAnimator : la liste d’intervenants associés à chaque événement
ActionEventService : la liste de prestations associées à chaque événement
ActionDelegate : la liste d’utilisateurs associés à chaque intervention
ActionTeam : la liste d’équipes associées à chaque intervention
CustomField : la liste de champs personnalisés configurés sur votre compte
Role : la liste de rôles au sein de votre organisation

Index des modules

Intervenants
- Personne morale d’un intervenant
Comptes
- Enveloppes d’un compte
- Contacts d’un compte
Prestations
Interventions
Utilisateurs
Équipes
Rôles
Champs personnalisés
Ressources
Tâches et notifications
Structures transversales
- Fichiers
- Dates
- Fiche contact
- Adresse

Intervenants

Accès à la collection Animator.

# Obtenir une liste d'intervenants
POST /v1/data/animator

# Obtenir un intervenant précis
GET /v1/data/animator/:id

# Obtenir une liste de ressources d'un intervenant
POST /v1/data/animator/:id/resource

# Télécharger le fichier associé à une ressource
GET /v1/data/animator/:id/resource/:resourceId
# Télécharger les métadonnées du fichier associé à une ressource
GET /v1/data/animator/:id/resource/:resourceId?meta=1

# Obtenir une liste de tâches d'un intervenant
POST /v1/data/animator/:id/task
# Obtenir une liste de notifications d'un intervenant
POST /v1/data/animator/:id/notification

Le tableau suivant indique les champs possibles d’une fiche intervenant.

Champ	Type	Description
_id	string	Identifiant unique
uniqueIndex	number	Numéro unique attaché à cette fiche
status	enum(string)	L’état de l’intervenant. Valeurs possibles : `draft` (brouillon), `active` (disponible), `inactive` (indisponible), `archived` (archivé), `blacklisted` (liste noire).
displayName	string	La combinaison des différents éléments du nom de l’intervenant (prénom, nom d’usage, entreprise, etc.). Calculé automatiquement.
familyName	string	Nom d’usage
givenName	string	Prénom
maidenName	string	Nom de naissance
gender	enum(string)	Civilité. Valeurs possibles : `male` (Monsieur), `female` (Madame), `unknown` (Inconnue)
emails	string[]	Liste d’adresses e-mail alternatives
telephones	string[]	Liste de numéros de téléphone
address	object(Adresse)	L’adresse de l’intervenant
customAddressWhenPM	bool	Si l’intervenant est une personne morale, `true` pour utiliser une adresse autre que celle de la personne morale.
zones	object(Adresse)[]	Liste d’adresses où l’intervenant accepte d’intervenir.
available	object(Disponibilité)	Objet contenant les disponibilités et indisponibilités de l’intervenant
bank	object(Banque)	Objet contenant les coordonnées bancaires de l’intervenant
custom	object	Objet contenant les champs personnalisés de l’intervenant.
color	string	La couleur associée à l’intervenant
personalData	object(État civil)	Objet contenant l’état civil de l’intervenant
contracts	object(Période d’engagement)[]	La liste des périodes d’engagement de l’intervenant.
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche
email	string	L’identifiant de l’intervenant pour se connecter à Run My Service.

Disponibilité

Cette structure regroupe les disponibilités générales de l’intervenant ainsi que les dates précises où l’intervenant est indisponible (la page Disponibilité de la fiche intervenant sur app.runmyservice.com).

Champ	Type	Description
available	object[]	Liste des disponibilités générales de l’intervenant (jours de la semaine, heures par jour)
available.*.mon	bool	`true` si l’intervenant est disponible les lundis
available.*.tue	bool	`true` si l’intervenant est disponible les mardis
available.*.wed	bool	`true` si l’intervenant est disponible les mercredis
available.*.thu	bool	`true` si l’intervenant est disponible les jeudis
available.*.fri	bool	`true` si l’intervenant est disponible les vendredis
available.*.sat	bool	`true` si l’intervenant est disponible les samedis
available.*.sun	bool	`true` si l’intervenant est disponible les dimanches
available.*.startHour	number	L’heure de départ de sa disponibilité sur les jours indiqués dans cette structure
available.*.startMinute	number	La minute de départ de sa disponibilité sur les jours indiqués dans cette structure
available.*.endHour	number	L’heure de fin de sa disponibilité sur les jours indiqués dans cette structure
available.*.endMinute	number	La minute de fin de sa disponibilité sur les jours indiqués dans cette structure
unavailable	object[]	Liste des dates où l’intervenant est indisponible
unavailable.*.reason	string	Le motif de son indisponibilité
unavailable.*.start	object(Date)	Le départ de son indisponibilité
unavailable.*.end	object(Date)	La fin de son indisponibilité
unavailable.*.allDay	bool	`true` si indisponible toute la journée

État civil

Une structure regroupant l’état civil de l’intervenant.

Champ	Type	Description
birthDate	object(Date)	La date de naissance de l’intervenant
birthArea	string	Le lieu de naissance de l’intervenant
birthDepartment	string	Le département de naissance : le code du département français, sur 2 ou 3 chiffres, de `01` (l’Ain) à `99` (l’étranger), ainsi que les territoires ultramarins
birthCountry	string	Le pays de naissance : le code du pays sur 2 lettres, selon la norme ISO 3166-1.
nationality	string	Nationalité
idnumber	string	Numéro d’identité ou autre numéro
socialSecurity	string	Numéro de sécurité sociale

Banque

Une structure regroupant les coordonnées bancaires de l’intervenant.

Champ	Type	Description
iban	string	Le code IBAN
bic	string	Le code BIC
agencyAddress	string	L’adresse de l’agence

Période d’engagement

Une période d’engagement indique une période réelle ou théorique d’embauche ou de participation de l’intervenant dans votre organisation. Cette période précise la date d’entrée et, le cas échéant, de sortie de l’intervenant, ainsi que d’autres détails comme le statut de son embauche (CDI, CDD, stagiaire, etc.), son tarif horaire ou son forfait par événement.

Ces informations servent à remplir automatiquement le tarif (ou forfait) lorsqu’on affecte un intervenant à un événement, ainsi que dans la rédaction des contrats pour l’intervenant.

Champ	Type	Description
id	string	Un identifiant unique pour cette période d’engagement
displayName	string	Le nom de la période d’engagement (statut + dates)
statut	enum(string)	Le statut d’embauche. Valeurs possibles : `cdi` (CDI), `cdd` (CDD), `pp` (prestataire, personne physique), `pm` (prestataire, personne morale), `volunteer` (bénévole), `civicvolunteer` (volontaire en service civique), `intern` (stagiaire), `apprentice` (apprenti), `interim` (intérimaire), `cee` (CEE)
hourlyRate	number	Tarif horaire
tarifType	enum(string)	Le type de compensation. Valeurs possibles : `tarif` (tarif), `indemnity` (indemnité), `companyRate` (facturé), `none` (aucun)
flatFee	number	Le forfait par événement
startDate	object(Date)	Le début de cette période d’engagement
startDateUTC	number	Le début de la période d’engagement en UTC
startDateOpen	bool	`true` si le début n’est pas connu
endDate	object(Date)	(facultatif) La fin de cette période d’engagement
endDateOpen	bool	`true` si la période d’engagement n’a pas de date de fin (fin ouverte)
endDateUTC	number	La fin de la période d’engagement en UTC
trialEndDate	object(Date)	La fin de la période d’essai
jobTitle	string	Fonction
jobDescription	string	Missions
weeklyHours	number	Durée hebdomadaire (heures)
pp	object	Si le statut est `pp` (prestataire personne physique), cette structure contient plus d’informations concernant le prestataire
pp.statut	enum(string)	Le statut du prestataire personne physique. Valeurs possibles : `micro_entreprise` (micro-entreprise), `independant` (indépendant)
pp.siret	string	Le SIRET du prestataire personne physique
pp.ape	string	Le code APE du prestataire personne physique
pp.tva	bool	`true` si le prestataire personne physique est assujetti à la TVA
pm	object	Si le statut est `pm` (personne morale), cette structure contient plus d’informations concernant la personne morale
pm.companyId	string	L’ID du document de la collection `AnimatorCompany` à laquelle cet intervenant appartient
pm.usePeriodHourlyRate	bool	`true` si le tarif horaire de la personne morale doit être utilisé à la place d’un tarif horaire personnalisé de l’intervenant.
legalRep	object(Contact)	Le représentant légal (si statut de type `intern`)
tutor	object(Contact)	Le tuteur (si statut de type `intern`)

Personne morale d’un intervenant

Accès à la collection AnimatorCompany. Plusieurs intervenants peuvent être attachés à la même personne morale via cette collection.

# Obtenir une liste de personnes morales
POST /v1/data/animatorCompany

# Obtenir une personne morale précise
GET /v1/data/animatorCompany/:id

Le tableau suivant indique les champs possibles :

Champ	Type	Description
_id	string	Identifiant unique
statut	enum(string)	Le statut de la personne morale. Valeurs possibles : `societe` (société), `association` (association), `autre` (autre).
name	string	Nom de la personne morale
siret	string	SIRET de la personne morale
ape	string	Code APE de la personne morale
address	object(Adresse)	Adresse
tva	bool	`true` si la personne morale est assujettie à la TVA
representative	object(Contact)	Représentant légal de la personne morale
hourlyRate	number	Le tarif horaire de la personne morale.
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Comptes

Accès à la collection Customer.

# Obtenir une liste de comptes
POST /v1/data/customer

# Obtenir un compte précis
GET /v1/data/customer/:id

# Obtenir une liste d'enveloppes d'un compte
POST /v1/data/customer/:id/budget

# Obtenir une enveloppe d'un compte précis
GET /v1/data/customer/:id/budget/:budgetId

# Obtenir une liste de ressources d'un compte
POST /v1/data/customer/:id/resource

# Télécharger le fichier associé à une ressource
GET /v1/data/customer/:id/resource/:resourceId
# Télécharger les métadonnées du fichier associé à une ressource
GET /v1/data/customer/:id/resource/:resourceId?meta=1

# Obtenir une liste de tâches d'un compte
POST /v1/data/customer/:id/task
# Obtenir une liste de notifications d'un compte
POST /v1/data/customer/:id/notification

Le tableau suivant indique les champs possibles :

Champ	Type	Description
_id	string	Identifiant unique
uniqueIndex	number	Numéro unique attaché à cette fiche
status	enum(string)	L’état du compte. Valeurs possibles : `draft` (brouillon), `active` (actif), `inactive` (inactif), `archived` (archivé), `blacklisted` (liste noire).
type	enum(string)	Type de l’organisation. Valeurs possibles : `pp` (personne physique), `pm` (personne morale)
displayName	string	Le nom affiché (créé automatiquement selon le type)
familyName	string	Si une personne physique, le nom d’usage de la personne
givenName	string	Si une personne physique, le prénom de la personne
emails	object[]	Si une personne physique, une liste d’adresses e-mail
emails.*.description	string	Une description de l’adresse e-mail
emails.*.value	string	L’adresse e-mail
emails.*.type	enum(string)	Le type de coordonnée. Valeurs possibles : `telephone` (numéro de téléphone) et `email` (adresse e-mail)
telephones	object[]	Si une personne physique, une liste de numéros de téléphone
telephones.*.description	string	Une description du numéro de téléphone
telephones.*.value	string	Le numéro de téléphone
telephones.*.type	enum(string)	Le type de coordonnée. Valeurs possibles : `telephone` (numéro de téléphone) et `email` (adresse e-mail)
name	string	Si une personne morale, le nom de la structure
department	string	Si une personne morale, le nom du département au sein de la structure
siret	string	Si une personne morale, son numéro SIRET
url	string	Si une personne morale, l’adresse de son site web
legalRepresentativeId	string	L’ID qui référence la liste `CustomerContact`, désignant le représentant légal de la personne morale
billingType	enum(string)	Type de facturation. Valeurs possibles : `invoice` (facturation), `grant` (subvention), `donation` (contribution volontaire). Si `grant`, ce compte peut avoir des enveloppes dans la collection `CustomerBudget`.
billingFrequency	enum(string)	Échéance. Valeurs possibles : `monthly` (mensuel), `trimester` (trimestriel), `halfway` (mi-parcours), `endofaction` (fin de l’intervention), `endofproject` (fin du projet).
billingMedium	enum(string)	Mode d’envoi. Valeurs possibles : `email` (e-mail), `post` (courrier), `halfway` (mi-parcours), `digital` (dématérialisé).
address	object(Adresse)	L’adresse
actionAvailableCategories	object[]	Une liste de catégories permettant de classer les interventions de ce compte. Les catégories définies ici peuvent être référencées dans `ActionCustomer.actionAssignedCategories`.
actionAvailableCategories.*.id	string	L’ID de la catégorie (à utiliser pour affecter cette catégorie dans `ActionCustomer.actionAssignedCategories`)
actionAvailableCategories.*.tag	string	Le nom de la catégorie
custom	object	Objet contenant les champs personnalisés
color	string	La couleur associée à la fiche
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Enveloppes d’un compte

Accès à la collection CustomerBudget pour les comptes dont le type de facturation est Subvention (grant).

# Obtenir une liste d'enveloppes
POST /v1/data/customerBudget

# Obtenir une enveloppe précise
GET /v1/data/customerBudget/:id

# Obtenir une liste d'enveloppes d'un compte
POST /v1/data/customer/:id/budget

# Obtenir une enveloppe précise d'un compte précis
GET /v1/data/customer/:id/budget/:budgetId

Le tableau suivant indique les champs possibles :

Champ	Type	Description
_id	string	Identifiant unique
uniqueIndex	number	Numéro unique attaché à cette fiche
customerId	string	L’ID du compte auquel cette enveloppe est attachée.
status	enum(string)	L’état de l’enveloppe. Valeurs possibles : `draft` (brouillon), `active` (actif), `inactive` (inactif), `archived` (archivé).
name	string	Nom
reference	string	Référence
description	string	Description
amount	number	Montant
contact	object(Contact)	Le contact en charge de l’enveloppe
consumed	number	Calculé automatiquement : le total consommé de cette enveloppe
balance	number	Calculé automatiquement : le solde de cette enveloppe
items	object[]	Liste des interventions ou missions imputées sur cette enveloppe
items.*.type	enum(string)	Soit `action` (intervention), soit `mission` (mission)
items.*.budget	number	Le montant de cet élément
items.*.actionId	string	Si `action`, l’ID de l’intervention
items.*.missionId	string	Si `mission`, l’ID de la mission
custom	object	Objet contenant les champs personnalisés
color	string	La couleur associée à la fiche
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Contacts d’un compte

Accès à la collection CustomerContact pour les comptes.

# Obtenir une liste de contacts
POST /v1/data/customerContact

# Obtenir un contact précis
GET /v1/data/customerContact/:id

Le tableau suivant indique les champs possibles :

Champ	Type	Description
_id	string	Identifiant unique
uniqueIndex	number	Numéro unique attaché à cette fiche
customerId	string	L’ID du compte auquel ce contact est attaché.
status	enum(string)	L’état du contact. Valeurs possibles : `draft` (brouillon), `active` (actif), `inactive` (inactif), `archived` (archivé), `blacklisted` (liste noire).
familyName	string	Nom d’usage
givenName	string	Prénom
displayName	string	Prénom et nom réunis
gender	enum(string)	Civilité. Valeurs possibles : `male` (Monsieur), `female` (Madame), `unknown` (Inconnue)
jobTitle	string	Qualité
email	string	Adresse e-mail
telephone	string	Numéro de téléphone
telephoneAlt	string	Numéro de téléphone alternatif
custom	object	Objet contenant les champs personnalisés
color	string	La couleur associée à la fiche
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Prestations

Accès à la collection Service.

# Obtenir une liste de prestations
POST /v1/data/service

# Obtenir une prestation précise
GET /v1/data/service/:id

# Obtenir une liste de ressources d'une prestation
POST /v1/data/service/:id/resource

# Télécharger le fichier associé à une ressource
GET /v1/data/service/:id/resource/:resourceId
# Télécharger les métadonnées du fichier associé à une ressource
GET /v1/data/service/:id/resource/:resourceId?meta=1

# Obtenir une liste de tâches d'une prestation
POST /v1/data/service/:id/task
# Obtenir une liste de notifications d'une prestation
POST /v1/data/service/:id/notification

Le tableau suivant indique les champs possibles :

Champ	Type	Description
_id	string	Identifiant unique
uniqueIndex	number	Numéro unique attaché à cette fiche
status	enum(string)	L’état de la prestation. Valeurs possibles : `draft` (brouillon), `active` (active), `inactive` (inactive), `archived` (archivée).
name	string	Nom
objectives	string	Objectifs
description	string	Description
suggestedPrice	number	Prix conseillé
repeat	enum(string)	Récurrence. Valeurs possibles : `once` (une seule fois), `multiple` (multiple), `manual` (sur mesure)
events	number	Nombre d’événements conseillés
eventDurationHours	number	Nombre d’heures
eventDurationMinutes	number	Nombre de minutes
logistics	string	Logistique
custom	object	Objet contenant les champs personnalisés
color	string	La couleur associée à la fiche
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Interventions

Accès à la collection Action. Une intervention se compose d’un ensemble d’événements. On peut y attacher des comptes, des intervenants et des prestations.

Dans sa forme la plus basique, une intervention est une fiche simple. Les autres modules s’y rattachent par une structure relationnelle : les collections ActionCustomer, ActionEvent, ActionEventAnimator et ActionEventService, qui utilisent la clé étrangère actionId pour référencer la fiche intervention.

# Obtenir une liste d'interventions
POST /v1/data/action

# Obtenir une intervention précise
GET /v1/data/action/:id

# Obtenir une liste d'interventions avec un statut particulier
POST /v1/data/action
# ... avec le corps du message suivant, au format JSON
{
  "filters": [
    {
      "key": "state",
      "op": "in",
      "values": ["confirmed", "busy"]
    }
  ]
}

# Obtenir une liste de ressources d'une intervention
POST /v1/data/action/:id/resource

# Télécharger le fichier associé à une ressource
GET /v1/data/action/:id/resource/:resourceId
# Télécharger les métadonnées du fichier associé à une ressource
GET /v1/data/action/:id/resource/:resourceId?meta=1

# Obtenir une liste de tâches d'une intervention
POST /v1/data/action/:id/task
# Obtenir une liste de notifications d'une intervention
POST /v1/data/action/:id/notification

À noter : les ressources d’une intervention sont une jointure entre les collections Resource et ActionResource ; la structure retournée diffère donc de celle d’une ressource classique. La réponse contient les informations de la jointure, auxquelles nous ajoutons un sous-objet resource qui contient la fiche ressource elle-même.

Le tableau suivant indique les champs possibles d’une fiche intervention.

Champ	Type	Description
_id	string	Identifiant unique
uniqueIndex	number	Numéro unique attaché à cette fiche
name	string	Nom de l’intervention
state	enum(string)	L’état de l’intervention. Valeurs possibles : `draft` (brouillon), `confirmed` (confirmée), `busy` (en cours), `finished` (terminée — toutes les dates sont passées mais il reste des tâches à faire), `done` (finalisée — dates passées et tâches terminées), `canceled` (annulée).
description	string	Description
address	object(Adresse)	L’adresse de l’intervention
contacts	object(Contact)[]	Une liste de contacts sur place
budget	number	Montant HT
hasEvents	bool	`true` si l’intervention a des événements dans son planning
start	object(Date)	La date de début (en heure locale) de l’intervention
startUTC	number	La date de début (en UTC)
end	object(Date)	La date de fin (en heure locale) de l’intervention
endUTC	number	La date de fin (en UTC)
cache	object(Cache d’une intervention)	Un cache des données relationnelles pour faciliter les requêtes
custom	object	Objet contenant les champs personnalisés de l’intervention
color	string	La couleur associée à l’intervention
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Le cache d’une intervention

Afin d’optimiser les requêtes transversales, nous construisons et maintenons une structure pour chaque intervention regroupant les liens entre les différents modules. Le cache est mis à jour de façon asynchrone, et il peut y avoir une latence entre la mise à jour d’une fiche et la mise à jour de l’objet en cache.

L’objet cache a les sous-objets suivants :

action : des informations qui résument l’avancement de l’intervention (utilisées dans l’onglet À propos de l’interface Run My Service)
users : une liste des personnes impliquées dans l’intervention, qu’il s’agisse d’utilisateurs ou d’intervenants
animators : une liste d’intervenants impliqués dans l’intervention
delegates : une liste d’utilisateurs impliqués dans l’intervention
customers : une liste de comptes associés à l’intervention
services : une liste de prestations fournies pendant l’intervention
events : une liste d’événements de l’intervention

Les objets users, animators, delegates, customers et services ont le format suivant :

{
  "display": "2|Name2 Surname2",
  "instances": [
      {
          "id": "616fdf2f6682f80889a0ecbb",
          "userId": "TQhzDmqNCYVSilFAlsgnoq98p5B3",
          "uniqueIndex": 2,
          "display": "2|Name2 Surname2",
          "data": {
              "state": "confirmed",
              "color": "hsl(275.016,70%,65%)"
          },
          ...
      }
  ]
}

Champ	Type	Description
display	string	Un texte qui résume l’ensemble des informations de la structure
instances	object[]	Une liste d’objets avec l’essentiel de chaque fiche (notamment son nom, son ID et son `uniqueIndex`)
instances.*.id	string	L’ID de la fiche du module correspondant
instances.*.display	string	La valeur à afficher associée à la fiche

Le cache permet de faire facilement et rapidement des requêtes qui demanderaient autrement des jointures. Par exemple, pour chercher la liste des interventions d’un compte en particulier :

# Obtenir une liste d'interventions pour un compte en particulier (avec ID 616fe22a6682f80889a0ecc7)
POST /v1/data/action
# ... avec le corps du message suivant :
{
  "filters": [
    {
      "key": "cache.customers.instances.id",
      "op": "eq",
      "values": ["616fe22a6682f80889a0ecc7"]
    }
  ]
}

Ou pour obtenir la liste des interventions de plusieurs personnes :

# Obtenir une liste d'interventions pour plusieurs utilisateurs (intervenant ou utilisateur)
POST /v1/data/action
# ... avec le corps du message suivant :
{
  "filters": [
    {
      "key": "cache.users.instances.id",
      "op": "in",
      "values": ["617012813f86ff122a8cf738", "6171615626d39e2171b8f0cf"]
    }
  ]
}

Comptes d’une intervention

Récupérez la liste de comptes attachés à une intervention (la collection ActionCustomer).

# Obtenir une liste de comptes attachés à une intervention avec un :id
POST /v1/data/action/:id/customer

# Obtenir un compte précis attaché à une intervention
GET /v1/data/action/:id/customer/:customerId

Champ	Type	Description
_id	string	Identifiant unique
actionId	string	L’ID de l’intervention référencée
customerId	string	L’ID du compte référencé
amount	number	Le montant de contribution de ce compte au budget total de l’intervention
state	enum(string)	L’état de cette participation à l’intervention. Valeurs possibles : `confirmed` (confirmée), `canceled` (annulée).
discounts	object[]	Les remises accordées au compte
discounts.*.id	string	L’ID de la remise parmi la liste
discounts.*.amount	number	Le montant de la remise
discounts.*.reason	string	Le motif de la remise
envelopes	{ envelopeId: string, amount: number }[]	L’ID de l’enveloppe référencée par cette intervention (clé étrangère vers `CustomerBudget`) ainsi que le montant consommé sur cette enveloppe.
quotes	object(Fichier)[]	Une liste de devis
actionAssignedCategories	string[]	Une liste d’ID qui font référence au champ `actionAvailableCategories` de la fiche compte (afin de préciser les catégories)
actionContacts	string[]	Une liste d’ID qui font référence au champ `contacts` de l’intervention, pour préciser qui est le contact sur place.
cancelation	object	Informations concernant l’annulation si l’intervention est annulée
cancelation.reason	string	Le motif de l’annulation
cancelation.date	string	La date de l’annulation
cancelation.invoice	bool	`true` s’il faut facturer le compte malgré l’annulation
customer	object(Compte)	Nous incluons automatiquement la fiche compte pour faciliter vos requêtes
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Événements d’une intervention

Récupérez la liste d’événements attachés à une intervention (la collection ActionEvent).

# Obtenir une liste d'événements attachés à une intervention avec un :id
POST /v1/data/action/:id/event

# Obtenir un événement précis
GET /v1/data/action/:id/event/:eventId

Champ	Type	Description
_id	string	Identifiant unique
actionId	string	L’ID de l’intervention référencée
name	string	Le nom de cet événement
localStart	object(Date)	La date de début (en heure locale) de l’événement
startUTC	number	La date de début (en UTC)
localEnd	object(Date)	La date de fin (en heure locale) de l’événement
endUTC	number	La date de fin (en UTC)
state	enum(string)	L’état de l’événement. Valeurs possibles : `confirmed` (confirmé), `busy` (en cours), `finished` (terminé), `canceled` (annulé).
cancelation	object	Informations concernant l’annulation si l’événement ou l’intervention est annulé(e)
cancelation.id	string	Un identifiant unique
cancelation.reason	string	Le motif de l’annulation
cancelation.date	string	La date de l’annulation
cache	object(Cache d’un événement)	Un cache des données relationnelles pour faciliter les requêtes
custom	object	Objet contenant les champs personnalisés de l’événement.
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Le cache d’un événement

Afin d’optimiser les requêtes transversales, nous construisons et maintenons une structure pour chaque événement regroupant les liens entre les différents modules. Le cache est mis à jour de façon asynchrone, et il peut y avoir une latence entre la mise à jour d’une fiche et la mise à jour de l’objet en cache.

L’objet cache a les sous-objets suivants :

action : de l’information concernant l’intervention à laquelle l’événement est attaché
users : une liste des personnes impliquées dans l’événement, qu’il s’agisse d’utilisateurs ou d’intervenants
animators : une liste d’intervenants impliqués dans l’événement
delegates : une liste d’utilisateurs impliqués dans l’événement
customers : une liste de comptes associés à l’intervention
services : une liste de prestations fournies pendant l’événement

Voir le cache d’une intervention pour savoir comment exploiter le cache dans vos requêtes.

Intervenants d’un événement

Récupérez la liste d’intervenants attachés à un événement (la collection ActionEventAnimator).

# Obtenir une liste d'intervenants attachés à un événement avec un :id
POST /v1/data/action/:id/event/:eventId/animator

# Obtenir un intervenant précis, à partir des ID de l'intervention, de l'événement et de l'intervenant
GET /v1/data/action/:id/event/:eventId/animator/:animatorId

Champ	Type	Description
_id	string	Identifiant unique
actionId	string	L’ID de l’intervention référencée
eventId	string	L’ID de l’événement référencé
animatorId	string	L’ID de l’intervenant référencé
fixedHourlyRate	number	Le tarif horaire enregistré pour cet événement.
fixedFlatFee	number	Le forfait enregistré pour cet événement.
state	enum(string)	L’état de la participation de l’intervenant à cet événement. Valeurs possibles : `confirmed` (confirmée), `canceled` (annulée).
extraHours	object[]	Une liste d’heures complémentaires
extraHours.*.id	string	L’ID de l’heure complémentaire
extraHours.*.description	string	Le libellé de l’heure complémentaire
extraHours.*.hours	number	Le nombre d’heures à enregistrer comme complémentaire
extraFees	object[]	Une liste de frais complémentaires
extraFees.*.id	string	L’ID du frais complémentaire
extraFees.*.description	string	Le libellé du frais
extraFees.*.amount	number	Le montant
extraFees.*.receipts	object(Fichier)[]	Les justificatifs de ce frais
cancelation	object	Informations concernant l’annulation si la participation de l’intervenant à l’événement est annulée
cancelation.id	string	Un identifiant unique
cancelation.reason	string	Le motif de l’annulation
cancelation.date	string	La date de l’annulation
cancelation.hoursBeforeCancel	number	Le nombre d’heures avant l’annulation
cancelation.hours	number	Le nombre d’heures de compensation suite à l’annulation
cancelation.flatFee	number	Le forfait à payer suite à l’annulation
cancelation.fixedHourlyRate	number	Le tarif horaire enregistré au moment de l’annulation
cancelation.fixedFlatFee	number	Le forfait enregistré au moment de l’annulation
cancelation.extraHours	object[]	Les heures complémentaires suite à l’annulation
cancelation.extraFees	object[]	Les frais complémentaires suite à l’annulation
animator	object(Intervenant)	Nous incluons automatiquement la fiche intervenant pour faciliter vos requêtes
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Prestations d’un événement

Récupérez la liste de prestations attachées à un événement (la collection ActionEventService).

# Obtenir une liste de prestations attachées à un événement avec un :id
POST /v1/data/action/:id/event/:eventId/service

# Obtenir une prestation précise, à partir des ID de l'intervention, de l'événement et de la prestation
GET /v1/data/action/:id/event/:eventId/service/:serviceId

Champ	Type	Description
_id	string	Identifiant unique
actionId	string	L’ID de l’intervention référencée
eventId	string	L’ID de l’événement référencé
serviceId	string	L’ID de la prestation référencée
service	object(Prestation)	Nous incluons automatiquement la fiche prestation pour faciliter vos requêtes
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

À noter : il n’est pas encore possible de récupérer la liste des ressources attachées à une prestation d’un événement. Cette fonctionnalité est à venir.

Équipe d’une intervention

Récupérez la liste des utilisateurs mobilisés sur l’intervention (listés dans l’onglet Équipe de l’interface Run My Service).

# Obtenir une liste d'utilisateurs mobilisés sur une intervention
POST /v1/data/action/:id/delegate

# Obtenir un utilisateur précis
GET /v1/data/action/:id/delegate/:delegateId

Champ	Type	Description
_id	string	Identifiant unique
actionId	string	L’ID de l’intervention référencée
delegateId	string	L’ID de l’utilisateur référencé (de la collection `Delegate`)
roleId	string	L’ID du rôle de l’utilisateur dans l’intervention
teamId	string	(facultatif) L’ID de l’équipe de l’utilisateur, s’il a été ajouté au titre d’une équipe
delegate	object	Nous incluons automatiquement la fiche d’utilisateur pour faciliter vos requêtes
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Vous pouvez aussi récupérer la liste des équipes attachées à une intervention :

# Obtenir une liste d'équipes attachées à une intervention
POST /v1/data/action/:id/team

# Obtenir une équipe précise
GET /v1/data/action/:id/team/:teamId

Champ	Type	Description
_id	string	Identifiant unique
actionId	string	L’ID de l’intervention référencée
teamId	string	L’ID de l’équipe
team	object(Équipe)	Nous incluons automatiquement la fiche de l’équipe
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Utilisateurs

Accès à la collection Delegate qui représente tous les utilisateurs de Run My Service (hors intervenants).

# Obtenir une liste d'utilisateurs
POST /v1/data/delegate

# Obtenir un utilisateur précis
GET /v1/data/delegate/:id

# Obtenir une liste de tâches de l'utilisateur
POST /v1/data/delegate/:id/task
# Obtenir une liste de notifications de l'utilisateur
POST /v1/data/delegate/:id/notification

Le tableau suivant indique les champs possibles d’une fiche utilisateur.

Champ	Type	Description
_id	string	Identifiant unique
uniqueIndex	number	Numéro unique attaché à cette fiche
status	enum(string)	L’état de l’utilisateur. Valeurs possibles : `active` (disponible), `inactive` (désactivé)
type	enum(string)	Le type d’utilisateur. Valeurs possibles : `human` (utilisateur normal), `test` (utilisateur de test créé par l’équipe Run My Service pour intervenir sur votre compte, non facturé), `api` (utilisateur de type robot créé par l’équipe Run My Service pour effectuer les tâches automatiques, non facturé).
roleId	string	L’ID du rôle de l’utilisateur
altEmail	string	Une adresse e-mail alternative à afficher, liée à l’identifiant de l’utilisateur
custom	object	Objet contenant les champs personnalisés de l’utilisateur.
color	string	La couleur associée à l’utilisateur
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche
email	string	L’identifiant de l’utilisateur pour se connecter à Run My Service
familyName	string	Nom d’usage
givenName	string	Prénom
displayName	string	Prénom et nom réunis
gender	enum(string)	Civilité. Valeurs possibles : `male` (Monsieur), `female` (Madame), `unknown` (Inconnue)

Équipes

Accès à la collection Team qui représente les équipes de gestion des interventions (accessible dans l’onglet Équipe).

# Obtenir une liste d'équipes
POST /v1/data/team

# Obtenir une équipe précise
GET /v1/data/team/:id

Le tableau suivant indique les champs possibles d’une fiche équipe.

Champ	Type	Description
_id	string	Identifiant unique
name	string	Le nom de l’équipe
delegates	object[]	Une liste d’utilisateurs et leurs rôles de gestion dans l’équipe
delegates.*.id	string	Identifiant unique de cette entrée dans la liste
delegates.*.delegateId	string	L’ID qui référence la collection `Delegate` de l’utilisateur
delegates.*.roleId	string	L’ID du rôle joué par cet utilisateur au sein de l’équipe (peut être différent de son rôle global)
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Rôles

Accès à la collection Role. Cette collection contient les fiches des rôles des utilisateurs. Ces fiches sont référencées à plusieurs endroits :

pour autoriser l’accès aux ressources selon le rôle
pour programmer des tâches ou envoyer des notifications selon le rôle
pour inclure les utilisateurs dans la gestion des interventions
etc.

De façon générale, un rôle est référencé via une clé étrangère du nom roleId dans les autres modules.

# Obtenir une liste de rôles
POST /v1/data/role

# Obtenir un rôle précis
GET /v1/data/role/:id

Le tableau suivant indique les champs possibles :

Champ	Type	Description
_id	string	Identifiant unique
name	string	Nom
subcategory	enum(string)	La catégorie du rôle. Valeurs possibles : `admin` (administrateur), `delegate` (utilisateur), `animator` (intervenant), `api` (api)
description	string	Description
isActionRole	bool	`true` si le rôle figure dans la gestion des interventions
accessAllResources	bool	`true` si le rôle a toujours accès à toutes les ressources
limitPerspectiveToSelf	bool	`true` si ce rôle ne voit que les interventions qui le concernent (et n’a donc pas l’option « Tous » en haut des pages)
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Champs personnalisés

Plusieurs fiches de Run My Service contiennent le champ custom, un objet composé de diverses clés et valeurs. Cet objet est extensible selon les préférences de l’administrateur de votre compte Run My Service (menu Paramètres puis Champs personnalisés).

La liste des clés possibles pour les champs personnalisés est définie dans la collection CustomField. Chaque champ personnalisé précise un ID, un nom, le type de données contenues dans ce champ, et le nom du module, du menu et de l’encart dans lesquels ce champ s’affiche dans l’interface Run My Service.

Par exemple, imaginons un champ personnalisé de type « texte court » qui existe dans CustomField avec la définition suivante :

{
    "_id" : "616fe15f6682f80889a0ecc4",    // ***> Notez cette clé
    "name" : "Text field",
    "type" : "string",
    "module" : "service",
    "screen" : "general",
    "group" : "Custom",
    ...
}

Un champ sera créé dans l’interface Run My Service, dans le module Prestations → À propos, sous l’encart Custom. Une valeur saisie dans ce champ sera enregistrée dans la fiche correspondante de la collection des prestations (Service), dans l’objet custom, sous la clé du champ personnalisé :

// Fiche prestation
{
  "_id": "6152e22c6661b240c350d160",
  "uniqueIndex": 34,
  ...
  "custom": {
    // ***> Ici, la clé utilisée est l'ID de la définition
    "616fe15f6682f80889a0ecc4": "La valeur du champ personnalisé"
  }
}

Pour parfaitement comprendre l’objet custom dans les modules de Run My Service, il est donc important de commencer par récupérer la liste des champs personnalisés.

# Obtenir une liste de champs personnalisés
POST /v1/data/customField

# Obtenir un champ personnalisé précis
GET /v1/data/customField/:id

Le tableau suivant indique les champs possibles :

Champ	Type	Description
_id	string	Identifiant unique
name	string	Nom du champ (libellé dans l’interface Run My Service)
type	enum(string)	Le type de données à stocker. Valeurs possibles : `string` (texte simple), `number` (valeur numérique), `text` (paragraphe), `date` (date), `bool` (case à cocher), `options` (liste déroulante - choix unique), `tag` (tags - choix multiples), `image` (fichier de type image), `file` (fichier)
module	string	Le nom du module auquel ce champ est attaché. Les principaux modules sont : `animator` (Intervenant), `customer` (Compte), `service` (Prestation), `action` (Intervention), `mission` (Mission)
screen	string	Le code de l’écran sur lequel le champ apparaît, utilisé par l’interface Run My Service
group	string	Le nom de l’encart dans lequel se trouve le champ dans l’interface Run My Service
options	object[]	Une liste d’options pour les champs de type `options` ou `tag`.
options.*.value	string	L’ID de l’option, et la valeur stockée dans l’objet `custom` si cette option est choisie
options.*.display	string	Le texte à afficher pour cette option
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Le format de stockage des données dans chaque champ custom dépend de son type :

Type	Format
`string`	Chaîne de caractères sans saut de ligne
`number`	Valeur numérique
`text`	Chaîne de caractères pouvant contenir des balises HTML de mise en forme (gras, italique, etc.)
`date`	Structure Date
`bool`	`true` ou `false`
`options`	Un `string` contenant l’ID de l’option choisie parmi la liste `options` de la définition du champ personnalisé
`tag`	Une liste de `string` (donc `string[]`) contenant les ID des options choisies parmi la liste `options` de la définition du champ personnalisé
`image`	Un objet de type Fichier
`file`	Un objet de type Fichier

Ressources

Chaque module intègre une liste de ressources associées à chaque fiche. Par exemple, chaque intervenant a sa propre liste de ressources. Les ressources sont accessibles à travers la fiche correspondante :

# Obtenir une liste de ressources d'un intervenant
POST /v1/data/animator/:id/resource

# Télécharger le fichier associé à une ressource
GET /v1/data/animator/:id/resource/:resourceId

# Télécharger les métadonnées du fichier associé à une ressource
GET /v1/data/animator/:id/resource/:resourceId?meta=1

Consultez la documentation de chaque module afin de trouver les chemins d’accès pour les ressources correspondantes.

À noter : le chemin de téléchargement d’un fichier, GET /v1/data/MODULE/:id/resource/:resourceId, retourne des données binaires si la ressource existe et si un fichier lui est associé. Sinon, une réponse de code 404 est retournée. Ce chemin est soumis aux mêmes règles d’autorisation que le reste de l’API, c’est-à-dire l’en-tête Authorization. Les ressources ne sont donc pas accessibles depuis un navigateur web par ce chemin.

Il existe plusieurs types de fiches ressources, indiqués par le champ type :

file : la fiche ressource pointe vers un fichier (mais un fichier n’est pas obligatoire)
physical : la fiche ressource indique plutôt un dispositif physique (par exemple, un kakemono)
folder : la fiche ressource représente un dossier dans la hiérarchie des ressources pour le module
globalFolder : la fiche ressource représente un dossier global dans la hiérarchie des ressources pour le module

La liste des ressources est plate en interne chez Run My Service. Une hiérarchie virtuelle est maintenue entre les différentes ressources de type folder. Chaque fiche ressource contient un champ parentId indiquant l’ID de la ressource parente, ainsi qu’un champ path qui contient toutes les ressources parentes jusqu’à la racine. Pour reconstruire la hiérarchie, il faut simplement recréer l’arborescence à partir de ces informations.

Champ	Type	Description
_id	string	Identifiant unique de la ressource
uniqueIndex	number	Numéro unique attaché à cette fiche
name	string	Nom lisible de la ressource
description	string	Description de la ressource
type	enum(string)	Type de ressource. Valeurs possibles : `file` (fichier), `physical` (dispositif physique), `folder` (dossier), `globalFolder` (dossier global)
file	object	(facultatif) Une structure concernant le fichier attaché à cette ressource
file.filename	string	Nom du fichier
file.storageReference	string	Chemin unique de la ressource dans le stockage cloud utilisé par Run My Service
file.size	string	Taille de la ressource en octets
file.type	string	Type MIME de la ressource
file.uid	string	Identifiant unique de la ressource utilisé dans le `storageReference`
customerId	string	(facultatif) L’ID de la fiche compte (`Customer`) à laquelle cette ressource appartient
animatorId	string	(facultatif) L’ID de la fiche intervenant (`Animator`) à laquelle cette ressource appartient
serviceId	string	(facultatif) L’ID de la fiche prestation (`Service`) à laquelle cette ressource appartient
actionId	string	(facultatif) L’ID de la fiche intervention (`Action`) à laquelle cette ressource appartient
actionEventServiceId	string	(facultatif) L’ID de la fiche événement/prestation (`ActionEventService`) à laquelle cette ressource appartient
missionId	string	(facultatif) L’ID de la fiche mission (`Mission`) à laquelle cette ressource appartient
custom	object	Objet contenant les champs personnalisés de la ressource
access	object	Structure contenant les permissions d’accès de cette ressource
access.roleIds	string[]	Les ID des rôles (`Role`) qui ont accès en lecture et en écriture
access.disableDownloadsForIds	string[]	Les ID des rôles (`Role`) qui peuvent consulter la fiche ressource, mais ne peuvent pas télécharger le fichier
access.allowWriteSubFolders	bool	Si de type `folder` ou `globalFolder`, la valeur `true` permet de créer des sous-dossiers et fichiers.
parentId	string	(facultatif) L’ID de la fiche ressource qui est le parent de cette ressource dans la hiérarchie. Une valeur inexistante ou vide indique que la ressource est à la racine de la hiérarchie.
path	string[]	(facultatif) Les ID des ressources ancêtres dans la hiérarchie.
tags	string[]	Étiquettes supplémentaires permettant d’affiner le filtrage des ressources.
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Il est possible de récupérer uniquement les métadonnées du fichier, en ajoutant le paramètre d’URL ?meta=1. La requête retournera la structure suivante :

{
    "storageReference": "client/5f0600aeef7ba500106f1fc0/service/5f3e395208d0f10010d8ec61/resource/4016973b-8602-460d-851d-d591b42eb6bf/images.jpeg",
    "exists": true,
    "contentType": "image/jpeg",
    "hash": "a03LcOxLedgc8Tu4hg9fbw==",
    "size": "9701"
}

Champ	Type	Description
storageReference	string	Chemin unique de la ressource dans le stockage cloud utilisé par Run My Service
exists	bool	`true` si le fichier est présent, sinon `false`
contentType	string	Le type MIME de ce fichier
hash	string	Le hachage du fichier, utile pour détecter si le fichier a changé
size	number	La taille en octets du fichier.

Tâches et notifications

Chaque module intègre une liste de tâches et de notifications associées à chaque fiche. Par exemple, chaque intervenant a sa propre liste de tâches. Les tâches et les notifications sont accessibles à travers la fiche correspondante :

# Obtenir une liste de tâches d'un intervenant
POST /v1/data/animator/:id/task
# Obtenir une liste de notifications d'un intervenant
POST /v1/data/animator/:id/notification

Consultez la documentation de chaque module afin de trouver les chemins d’accès pour les tâches et notifications correspondantes.

Champ	Type	Description
_id	string	Identifiant unique de la tâche
uniqueIndex	number	Numéro unique attaché à cette fiche
name	string	Nom lisible de la tâche
description	string	Description de la tâche
notes	string	Commentaires de la tâche
state	enum(string)	L’état de la tâche ou de la notification. Valeurs possibles pour les tâches : `draft` (brouillon), `pending` (à faire), `busy` (en cours), `done` (terminée), `canceled` (annulée). Valeurs possibles pour les notifications : `active` (activée), `canceled` (annulée), `draft` (brouillon)
deadline	object(Date)	La date butoir de la tâche ou notification
timezoneId	string	Le fuseau horaire de cette tâche
deadlineUtc	number	La date butoir de la tâche, au format UTC
notify	bool	`true` si la tâche/notification doit envoyer un e-mail à la date butoir
team	object[]	Structure pour affecter des utilisateurs (`Delegate`) ou intervenants (`Animator`) à la tâche
team.*.delegateId	string	(facultatif) L’ID de l’utilisateur (collection `Delegate`) si le coéquipier est un utilisateur
team.*.animatorId	string	(facultatif) L’ID de l’intervenant (collection `Animator`) si le coéquipier est un intervenant
referenceType	string	Le nom du module auquel cette tâche appartient
`module`Id	string	L’ID de la fiche associée (par exemple, `serviceId` ou `animatorId`)
custom	object	Objet contenant les champs personnalisés de la tâche.
createdAtUtc	number	La date de création de cette fiche, au format UTC
updatedAtUtc	number	La date de la dernière mise à jour de cette fiche, au format UTC
createdBy	string	L’ID de l’utilisateur qui a créé cette fiche
updatedBy	string	L’ID de l’utilisateur qui a mis à jour cette fiche

Structures transversales

Fichiers

Plusieurs fiches peuvent référencer des fichiers déposés sur Run My Service : les ressources, mais aussi certains types de champs personnalisés (file, image) ainsi que les devis dans Interventions → Montants et Comptes.

Les fichiers ne sont pas stockés au sein de chaque fiche, mais plutôt dans un dépôt optimisé pour le stockage du contenu statique. Chaque fiche stocke donc une structure de référence vers le fichier dans le dépôt :

  {
    "filename" : "images.png",
    "storageReference" : "client/616fd3e36682f80889a0ecb9/action/616fe50c6682f80889a0ed63/custom/fdf1eb6b-62f3-4bca-9fc0-a680567c2b1a/images.png",
    "size" : 2504,
    "type" : "image/png",
    "isNew" : true,
    "uid" : "bbc3a4c8-7e02-4254-985b-339956e7bda3",
  }

Le champ le plus important est storageReference, qui est la clé à utiliser pour télécharger le fichier. Vous pouvez donc invoquer le chemin suivant pour récupérer le fichier :

# Télécharger un fichier
POST /v1/data/file
# OU
POST /v1/data/file?meta=1

# Dans le corps du message, au format JSON :
{
  "storageReference" : "client/616fd3e36682f80889a0ecb9/action/616fe50c6682f80889a0ed63/custom/fdf1eb6b-62f3-4bca-9fc0-a680567c2b1a/images.png"
}

L’API répond avec le contenu du fichier au format binaire.

Il est possible de récupérer uniquement les métadonnées du fichier, en ajoutant le paramètre d’URL ?meta=1. La requête retournera la structure suivante :

{
    "storageReference": "client/5f0600aeef7ba500106f1fc0/service/5f3e395208d0f10010d8ec61/resource/4016973b-8602-460d-851d-d591b42eb6bf/images.jpeg",
    "exists": true,
    "contentType": "image/jpeg",
    "hash": "a03LcOxLedgc8Tu4hg9fbw==",
    "size": "9701"
}

Champ	Type	Description
storageReference	string	Chemin unique de la ressource dans le stockage cloud utilisé par Run My Service
exists	bool	`true` si le fichier est présent, sinon `false`
contentType	string	Le type MIME de ce fichier
hash	string	Le hachage du fichier, utile pour détecter si le fichier a changé
size	number	La taille en octets du fichier.

Nous recommandons de commencer par une requête meta avant de procéder au téléchargement. Vous évitez ainsi des téléchargements inutiles, par exemple si vous possédez déjà un fichier avec le même hachage.

Dates

La structure qui stocke la date, l’heure et la minute en heure locale, avec l’identifiant du fuseau horaire dans lequel l’heure doit être interprétée.

Champ	Type	Description
year	number	L’année
month	number	Le mois
day	number	Le jour
hour	number	L’heure (en temps local)
minute	number	La minute (en temps local)
tz	string	L’identifiant du fuseau horaire, par exemple `Europe/Paris`
utc	number	(facultatif) La valeur UTC de la date indiquée par cette structure.

Fiche contact

Structure qui stocke les coordonnées d’un représentant officiel ou d’un contact tiers.

Champ	Type	Description
id	string	Identifiant unique de la structure
familyName	string	Nom d’usage
givenName	string	Prénom
maidenName	string	Nom de naissance
gender	enum(string)	Civilité. Valeurs possibles : `male` (Monsieur), `female` (Madame), `unknown` (Inconnue)
jobTitle	string	Qualité
email	string	Adresse e-mail
telephone	string	Numéro de téléphone
telephoneAlt	string	Numéro de téléphone alternatif
notes	string	Commentaires

Adresse

Structure standard de représentation des adresses.

Champ	Type	Description
formatted	string	Un rassemblement des éléments de l’adresse en une ligne.
number	string	Numéro
street	string	Rue, boulevard, etc.
city	string	Ville
country	enum(string)	Le code du pays sur 2 lettres, selon la norme ISO 3166-1. À noter : les territoires ultramarins français ont toujours le code `FR`, avec la région et le département correspondants.
region	enum(Régions françaises)	Le code de la région française
department	enum(string)	Le code du département français, sur 2 ou 3 chiffres, de `01` (l’Ain) à `99` (l’étranger), ainsi que les territoires ultramarins
code	string	Code postal
extra	string	Complément d’adresse
coords	object(Coordonnées GPS)	Les coordonnées GPS de cette adresse.
timezoneId	string	L’identifiant du fuseau horaire de cette adresse
timezoneName	string	Le nom lisible du fuseau horaire de cette adresse
googleId	string	L’identifiant Google Maps de cette adresse

Coordonnées GPS

Champ	Type	Description
latitude	number	Latitude
longitude	number	Longitude

Régions françaises

Code	Région
ARA	Auvergne-Rhône-Alpes
BFC	Bourgogne-Franche-Comté
BRE	Bretagne
CVL	Centre-Val de Loire
COR	Corse
GES	Grand Est
GUA	Guadeloupe
HDF	Hauts-de-France
IDF	Île-de-France
MAY	Mayotte
NOR	Normandie
NAQ	Nouvelle-Aquitaine
OCC	Occitanie
PDL	Pays de la Loire
PAC	Provence-Alpes-Côte d’Azur
LRE	La Réunion
MQ	Martinique
GF	Guyane
SPM	Saint-Pierre-et-Miquelon
WEF	Wallis-et-Futuna
PYF	Polynésie française
NCL	Nouvelle-Calédonie
SBT	Saint-Barthélemy
SMT	Saint-Martin
ETR	Étranger

Territoires ultramarins

Code	Département
971	Guadeloupe
972	Martinique
973	Guyane
974	La Réunion
975	Saint-Pierre-et-Miquelon
976	Mayotte
977	Saint-Barthélemy
986	Wallis-et-Futuna
987	Polynésie française
988	Nouvelle-Calédonie

Activation de la fonctionnalité API

Autorisation

Limitations d’usage

Format des requêtes et des réponses

Requêtes POST

Requêtes GET

Schéma

Index des modules

Intervenants

Disponibilité

État civil

Banque

Période d’engagement

Personne morale d’un intervenant

Comptes

Enveloppes d’un compte

Contacts d’un compte

Prestations

Interventions

Le cache d’une intervention

Comptes d’une intervention

Événements d’une intervention

Le cache d’un événement

Intervenants d’un événement

Prestations d’un événement

Équipe d’une intervention

Utilisateurs

Équipes

Rôles

Champs personnalisés

Ressources

Tâches et notifications

Structures transversales

Fichiers

Dates

Fiche contact

Adresse

Coordonnées GPS

Régions françaises

Territoires ultramarins

Requêtes `POST`

Requêtes `GET`