> For the complete documentation index, see [llms.txt](https://ouvretaferme.gitbook.io/ouvretaferme/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ouvretaferme.gitbook.io/ouvretaferme/endpoints/general/structure/invitations.md).

# Invitations

Les invitations à rejoindre l'équipe de votre structure : rôle attribué à l'arrivée, adresse e-mail destinataire, date d'expiration et nombre d'utilisations. Créer une invitation avec une adresse e-mail l'envoie immédiatement.

## Lister les invitations

> Scope requis : \`general:read\`.

```json
{"openapi":"3.0.3","info":{"title":"API Ouvretaferme","version":"0.1beta"},"tags":[{"name":"Invitations"}],"servers":[{"url":"https://api.ouvretaferme.org/0.1beta"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clé API personnelle ou jeton OAuth2 d'une application tierce, présenté dans l'en-tête `Authorization: Bearer`. Voir la section Authentification."}},"schemas":{"Invite":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"email":{"type":"string","format":"email","nullable":true},"memberRole":{"type":"integer","format":"int64","description":"Rôle attribué au membre lorsque l'invitation est acceptée. Identifiant d'un élément `Role`.","nullable":true},"limit":{"type":"integer","nullable":true,"description":"Limite d'utilisations de l'invitation."},"used":{"type":"integer"},"lastUsedAt":{"type":"string","format":"date","nullable":true},"expiresAt":{"type":"string","format":"date","nullable":true,"description":"Date d'expiration de l'invitation."},"status":{"type":"string","enum":["pending","invalid"]},"link":{"type":"string","format":"uri","description":"Lien à transmettre pour utiliser l'invitation sans e-mail"}},"title":"Invitations","description":"Les invitations à rejoindre l'équipe de votre structure : rôle attribué à l'arrivée, adresse e-mail destinataire, date d'expiration et nombre d'utilisations. Créer une invitation avec une adresse e-mail l'envoie immédiatement."},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","resource_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"}}}},"responses":{"ValidationError":{"description":"Un champ, un filtre ou un argument ne respecte pas les règles de validation, ou le corps n'est pas un objet JSON.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"AuthenticationError":{"description":"Clé API ou jeton absent, invalide, expiré ou révoqué.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"Forbidden":{"description":"Le jeton ne porte pas le scope requis, l'écriture n'est pas ouverte à cette structure, la structure n'a pas l'abonnement qui ouvre l'API, ou la personne qui a créé la clé n'administre plus la structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"RateLimited":{"description":"Trop d'appels. L'en-tête `Retry-After` donne le nombre de secondes à attendre.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant le prochain appel.","schema":{"type":"integer"}}}}}},"paths":{"/inviteList":{"get":{"operationId":"getInviteList","tags":["Invitations"],"summary":"Lister les invitations","description":"Scope requis : `general:read`.","parameters":[{"name":"start","in":"query","required":false,"description":"Rang du premier élément rendu, à partir de 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Nombre d'éléments rendus, 100 par défaut et 500 au plus. À 0, seul le total est rendu.","schema":{"type":"integer","minimum":0,"maximum":500,"default":100}},{"name":"ids","in":"query","required":false,"description":"Ne rend que ces identifiants, 100 au plus, séparés par des virgules.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"integer","format":"int64"},"maxItems":100}},{"name":"afterId","in":"query","required":false,"description":"Ne rend que les éléments d'identifiant supérieur, pour parcourir une liste sans décalage quand elle change pendant la lecture.","schema":{"type":"integer","format":"int64"}},{"name":"beforeId","in":"query","required":false,"description":"Ne rend que les éléments d'identifiant inférieur.","schema":{"type":"integer","format":"int64"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","invalid"]}}],"responses":{"200":{"description":"Liste paginée des invitations.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","description":"Nombre d'éléments que retiennent les filtres, sans tenir compte de la pagination (`start`, `limit`, `afterId`, `beforeId`)."},"list":{"type":"array","items":{"$ref":"#/components/schemas/Invite"}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## Consulter une invitation

> Scope requis : \`general:read\`. Pour lire plusieurs invitations, \`GET /inviteList?ids=12,15,18\` en rend jusqu'à 100, et ne compte que pour un appel.

```json
{"openapi":"3.0.3","info":{"title":"API Ouvretaferme","version":"0.1beta"},"tags":[{"name":"Invitations"}],"servers":[{"url":"https://api.ouvretaferme.org/0.1beta"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clé API personnelle ou jeton OAuth2 d'une application tierce, présenté dans l'en-tête `Authorization: Bearer`. Voir la section Authentification."}},"schemas":{"Invite":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"email":{"type":"string","format":"email","nullable":true},"memberRole":{"type":"integer","format":"int64","description":"Rôle attribué au membre lorsque l'invitation est acceptée. Identifiant d'un élément `Role`.","nullable":true},"limit":{"type":"integer","nullable":true,"description":"Limite d'utilisations de l'invitation."},"used":{"type":"integer"},"lastUsedAt":{"type":"string","format":"date","nullable":true},"expiresAt":{"type":"string","format":"date","nullable":true,"description":"Date d'expiration de l'invitation."},"status":{"type":"string","enum":["pending","invalid"]},"link":{"type":"string","format":"uri","description":"Lien à transmettre pour utiliser l'invitation sans e-mail"}},"title":"Invitations","description":"Les invitations à rejoindre l'équipe de votre structure : rôle attribué à l'arrivée, adresse e-mail destinataire, date d'expiration et nombre d'utilisations. Créer une invitation avec une adresse e-mail l'envoie immédiatement."},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","resource_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"}}}},"responses":{"ValidationError":{"description":"Un champ, un filtre ou un argument ne respecte pas les règles de validation, ou le corps n'est pas un objet JSON.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"AuthenticationError":{"description":"Clé API ou jeton absent, invalide, expiré ou révoqué.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"Forbidden":{"description":"Le jeton ne porte pas le scope requis, l'écriture n'est pas ouverte à cette structure, la structure n'a pas l'abonnement qui ouvre l'API, ou la personne qui a créé la clé n'administre plus la structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"NotFound":{"description":"Aucun élément avec cet identifiant pour votre structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"RateLimited":{"description":"Trop d'appels. L'en-tête `Retry-After` donne le nombre de secondes à attendre.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant le prochain appel.","schema":{"type":"integer"}}}}}},"paths":{"/invite/{id}":{"get":{"operationId":"getInviteById","tags":["Invitations"],"summary":"Consulter une invitation","description":"Scope requis : `general:read`. Pour lire plusieurs invitations, `GET /inviteList?ids=12,15,18` en rend jusqu'à 100, et ne compte que pour un appel.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Invitation demandée.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invite"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## Supprimer une invitation

> Scope requis : \`general:write\`.

```json
{"openapi":"3.0.3","info":{"title":"API Ouvretaferme","version":"0.1beta"},"tags":[{"name":"Invitations"}],"servers":[{"url":"https://api.ouvretaferme.org/0.1beta"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clé API personnelle ou jeton OAuth2 d'une application tierce, présenté dans l'en-tête `Authorization: Bearer`. Voir la section Authentification."}},"responses":{"AuthenticationError":{"description":"Clé API ou jeton absent, invalide, expiré ou révoqué.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"Forbidden":{"description":"Le jeton ne porte pas le scope requis, l'écriture n'est pas ouverte à cette structure, la structure n'a pas l'abonnement qui ouvre l'API, ou la personne qui a créé la clé n'administre plus la structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"NotFound":{"description":"Aucun élément avec cet identifiant pour votre structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"RateLimited":{"description":"Trop d'appels. L'en-tête `Retry-After` donne le nombre de secondes à attendre.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant le prochain appel.","schema":{"type":"integer"}}}}},"schemas":{"Error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","resource_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/invite/{id}":{"delete":{"operationId":"deleteInviteById","tags":["Invitations"],"summary":"Supprimer une invitation","description":"Scope requis : `general:write`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Supprimé. Le corps de la réponse est vide."},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"412":{"description":"Condition métier interdisant la suppression.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## Créer une invitation

> Scope requis : \`general:write\`.

```json
{"openapi":"3.0.3","info":{"title":"API Ouvretaferme","version":"0.1beta"},"tags":[{"name":"Invitations"}],"servers":[{"url":"https://api.ouvretaferme.org/0.1beta"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clé API personnelle ou jeton OAuth2 d'une application tierce, présenté dans l'en-tête `Authorization: Bearer`. Voir la section Authentification."}},"schemas":{"InviteWrite":{"type":"object","properties":{"email":{"type":"string","format":"email","nullable":true},"memberRole":{"type":"integer","format":"int64","description":"Rôle attribué au membre lorsque l'invitation est acceptée. Identifiant d'un élément `Role`.","nullable":true},"limit":{"type":"integer","nullable":true,"description":"Limite d'utilisations de l'invitation."},"expiresAt":{"type":"string","format":"date","nullable":true,"description":"Date d'expiration de l'invitation."}},"description":"Les champs acceptés dépendent de l'élément envoyé : cette liste réunit ceux des différents cas et aucun n'y est obligatoire dans tous. Les invitations à rejoindre l'équipe de votre structure : rôle attribué à l'arrivée, adresse e-mail destinataire, date d'expiration et nombre d'utilisations. Créer une invitation avec une adresse e-mail l'envoie immédiatement."},"Invite":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"email":{"type":"string","format":"email","nullable":true},"memberRole":{"type":"integer","format":"int64","description":"Rôle attribué au membre lorsque l'invitation est acceptée. Identifiant d'un élément `Role`.","nullable":true},"limit":{"type":"integer","nullable":true,"description":"Limite d'utilisations de l'invitation."},"used":{"type":"integer"},"lastUsedAt":{"type":"string","format":"date","nullable":true},"expiresAt":{"type":"string","format":"date","nullable":true,"description":"Date d'expiration de l'invitation."},"status":{"type":"string","enum":["pending","invalid"]},"link":{"type":"string","format":"uri","description":"Lien à transmettre pour utiliser l'invitation sans e-mail"}},"title":"Invitations","description":"Les invitations à rejoindre l'équipe de votre structure : rôle attribué à l'arrivée, adresse e-mail destinataire, date d'expiration et nombre d'utilisations. Créer une invitation avec une adresse e-mail l'envoie immédiatement."},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","resource_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"}}}},"responses":{"ValidationError":{"description":"Un champ, un filtre ou un argument ne respecte pas les règles de validation, ou le corps n'est pas un objet JSON.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"AuthenticationError":{"description":"Clé API ou jeton absent, invalide, expiré ou révoqué.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"Forbidden":{"description":"Le jeton ne porte pas le scope requis, l'écriture n'est pas ouverte à cette structure, la structure n'a pas l'abonnement qui ouvre l'API, ou la personne qui a créé la clé n'administre plus la structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"RateLimited":{"description":"Trop d'appels. L'en-tête `Retry-After` donne le nombre de secondes à attendre.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant le prochain appel.","schema":{"type":"integer"}}}}}},"paths":{"/invite":{"post":{"operationId":"postInvite","tags":["Invitations"],"summary":"Créer une invitation","description":"Scope requis : `general:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteWrite"}}}},"responses":{"201":{"description":"Invitation créée.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invite"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/Forbidden"},"412":{"description":"Condition métier interdisant la création.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```