Aller au contenu

Système de hook

Fonctionnement général

Flow des Hook
Principe de fonctionnement des hook AGATA CONSENT

Déroulé

Le fonctionnement des Hook d'AGATA CONSENT est très similaire au principe du paiement en ligne type e-commerce. Au cours d'une souscription à un abonnement numérique, un applicatif externe nécessite de vérifier et/ou faire signer un ensemble de consentements au partage des données.

  1. Pour cela, il fait un appel à un web-service d'authentification (Documentation)

  2. Il envoie ensuite une demande de transaction à AGATA CONSENT en regroupant ces demandes de consentements via un appel de Webservice (après s'être authentifié). (Documentation)

  3. Le lancement du traitement des hooks se fait dans une pop-up grâce au code suivant que vous devez rajouter dans l'application : 

    <script>
const popup = window.open(
    "[URL_HOOK]?transaction_id=[TRANSACTION_ID]&token=[TOKEN]",
    "Gestion des consentements",
    `width=${window.innerWidth * 0.9},height=${window.innerHeight * 0.9}`
  );
</script>
    Il fait appel au hook (URLs) avec les paramètres suivants : 
      [URL_HOOK] # Url des hooks (dépendant de l'environnement preprod/prod)
  [TRANSACTION_ID] # Identifiant de la transaction
  [TOKEN] # Le token d'authentification

  4. AGATA CONSENT réceptionne cette transaction. Pour chacune des demandes de consentements la constituant, AGATA vérifie automatiquement l'existence d'un consentement signé ayant les mêmes caractéristiques (Famille, Usage, Bénéficiaire, Ayant Droit) et valide sur la temporalité indiquée dans la transaction.
    sample screenshot

  5. En cas de complétude sur l'intégralité des consentements demandés, AGATA CONSENT redonne automatiquement la main à l'applicatif externe après en avoir informé l'Ayant Droit. sample screenshot

  6. Dans le cas où au moins un consentement est absent, AGATA CONSENT propose à la signature cette demande de consentement. Une fois fait, l'utilisateur est informé du bon enregistrement des signatures et redirigé vers l'applicatif externe. sample screenshot

  7. Un écran de refus est affiché en cas de refus par l'Ayant-Droit de signer une ou plusieurs demandes de consentements. Après la confirmation de son refus, il est redirigé vers l'applicatif externe. sample screenshot

  8. Le processus d'abonnement au sein de l'applicatif externe se poursuit selon son fonctionnement prévu.

Redirection

Une fois la gestion des consentements terminée, la pop-up est fermée automatiquement. Pour ajouter un traitement supplémentaire il faut modifier le code précédent : 

<script>
  window.addEventListener("message", (event) => {
    if (event.data === "HOOK_CLOSED") {
      console.log("Popup fermée via message !");
      // Lancer la suite du traitement ici
    }
  });

const popup = window.open(
    "[URL_HOOK]?transaction_id=[TRANSACTION_ID]&token=[TOKEN]",
    "Gestion des consentements",
    `width=${window.innerWidth * 0.9},height=${window.innerHeight * 0.9}`
  );

</script>

Diagramme de séquence

sequenceDiagram
    Application->>Serveur authentification: Authentification via client_id/secret_id
    Serveur authentification-->>Application: TOKEN
    Application->>API: Création de la transaction
    API-->>Application: ID transaction
    Application->+Hook: Appel de l'url (iFrame, nouvel onglet)
    Note right of Hook: Traitement des consentements
    Hook->-Application: Redirection

Appels API

Authentification

L'application peut s’authentifier en utilisant le type de grant « client_credentials » associé à un client_id et un secret. Pour récupérer ces informations, il faut se rapprocher de l'équipe d'Agata-Consent.

curl --location --request POST 'https://keycloak.agata-consent.com/auth/realms/sgc/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: KEYCLOAK_LOCALE=fr' \
--data-urlencode 'client_id=<client id>' \
--data-urlencode 'client_secret=<client secret>' \
--data-urlencode 'grant_type=client_credentials'

Récupération de la transaction

Appel

GET /transactions/{transaction_id}

Cette méthode permet d'obtenir les informations d'une transaction.

Body Type Obligatoire Description Exemple
transaction_id * string Oui Identifiant unique de la transaction 08b55957-5c80-4564-a2fd-3038c624f347
Exemple de requête
curl 
  --location 'https://api.agata-consent.com/transactions/08b55957-5c80-4564-a2fd-3038c624f347'
  --header 'accept: application/json'

Réponse

Code Titre Description
201 OK Retourne la transaction
401 Not Authenticate L'utilisateur n'est pas authentifié
403 Unauthorized L'entreprise n'a pas les droits nécessaires pour utiliser cette API
404 Not Found La transaction n'a pas été trouvée

TransactionGetModel

Body Type Description
id string Identifiant unique de la transaction (UUID)
application ApplicationGetModel Application
holder CompanyGetModel Détenteur des données
starting_date string Date de début des demandes de consentement
ending_date string Date de fin des demandes de consentement
created_at string Date de création de la transaction
accepted_at string Date à laquelle la transaction à été acceptée. Null à la création
rejected_at string Date à laquelle la transaction à été refusée. Null à la création
closed_at string Date de cloture de la transaction
consents_requested array<TransactionDetailGetModel> Consentements requis par l'application
signature_uri string Url de signature de la transaction

TransactionDetailGetModel

Body Type Description
id string Identifiant unique de la demande de consentement (UUID)
family FamilyLightGetModel Famille de données
usage UsageLightGetModel Usage des données
required bool Indique si le consentement est obligatoire pour pouvoir valider la transaction
created_at string Date de création de la transaction
consents ConsentGetModel Consentements / Demandes de consentement associés à la demande indiquée dans la transaction. Null à la création

ApplicationGetModel

Body Type Description
id string Identifiant unique de l'application (UUID)
company CompanyGetModel Entreprise
name string Dénomination de l'application
description string Description de l'application
app_key string Clé de l'application
callback_uri string Url de retour
created_at string Date de création de l'application
closed_at string Date de clôture de l'application
Exemple de réponse
  {
    "id": "08b55957-5c80-4564-a2fd-3038c624f347",
    "application": {
      "id": "c2472ea7-5a66-44f2-9f10-c65cd2108d32",
      "company": {
        "id": "ad97c8bb-af72-4f2d-9664-70fd9785f54t",
        "corporate_name": "Entreprise Test",
        "address": "Rue de la tulipe",
        "postal_code": "01250",
        "city": "Ceyzeriat",
        "identifier_type": "SIRET",
        "business_identifier": "73282932000074"
      },
      "name": "Agri Maker",
      "description": "Agri Maker est le portail des agriculteurs. Acceptez les consentements pour pouvoir accéder à vos services.",
      "app_key": "hook-app-example",
      "callback_url": "https://api.agri-maker.com/consent-callback",
      "created_at": "2023-10-07T09:37:43.993Z",
      "closed_at": null
    },
    "holder": {
      "type": "OWNER",
      "id": "678df96b-b61e-4adf-9912-0efd1181d057",
      "business_identifier": "FR35167340",
      "siret": "73282932000074",
      "name": "SAS Dupond Martin",
      "address": "Rue de la tulipe",
      "postal_code": "79200",
      "city": "Ville-sur-mer"
    },
    "starting_date": "2023-10-07T10:37:43.993Z",
    "ending_date": null,
    "created_at": "2023-10-07T09:37:43.993Z",
    "accepted_at": null,
    "rejected_at": null,
    "closed_at": null,
    "consents_requested": [
      {
        "id": "08b55957-5c80-4564-a2fd-3038c624f347",
        "family": {
          "id": "5a978f05-ce36-4a66-a271-b09c202c0f13",
          "name": "Registre sanitaire d'un bovin",
          "business_identifier": "san-registre-bovin"
        },
        "usage": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Tableau de bord pour technicien",
          "description": "Fabrication des indicateurs de suivi du tableau de bord Technicien conseil en élevage",
          "business_identifier": "idx-tdb-tk-cl"
        },
        "required": true,
        "created_at": "2023-10-07T09:37:43.993Z",
        "consents": null
      }
    ],
    "signature_uri": "null"
  }

Infos complémentaires

La recherche de la transaction se fait via son id ET l'id de l'entreprise connectée via l'application

Création de la transaction

Appel

POST /transactions

Cette méthode permet de créer une nouvelle transaction liée à une application.

Body Type Obligatoire Description Exemple
app_key * string Oui Clé applicative hook-app-exemple
holder_id * string Oui Identifiant unique du détenteur des données 678df96b-b61e-4adf-9912-0efd1181d057
starting_date * string Oui Date de début des demandes de consentement 2024-03-07T10:37:43.993Z
ending_date string Non Date de fin des demandes de consentement 2025-03-07T10:37:43.993Z
consents_requested * array Oui Consentements requis par l'application

consents_requested

Body Type Obligatoire Description Exemple
family_id * string Oui Identifiant unique de la famille de données 5a978f05-ce36-4a66-a271-b09c202c0f13
usage_id * string Oui Identifiant unique de l'usage des données 3fa85f64-5717-4562-b3fc-2c963f66afa6
required bool Non Indique si le consentement est obligatoire pour pouvoir valider la transaction (défaut: true) true
Exemple de requête
curl 
  --location 'https://api.agata-consent.com/transactions'
  --header 'accept: application/json'
  --data-raw '{
    "app_key": "hook-app-example",
    "holder_id": "678df96b-b61e-4adf-9912-0efd1181d057",
    "starting_date": "2024-03-07T10:37:43.993Z",
    "ending_date": null,
    "consents_requested": [
      {
        "family_id": "5a978f05-ce36-4a66-a271-b09c202c0f13",
        "usage_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        "required": true
      },
      {
        "family_id": "4a4a06c9-c72b-43db-9d2f-2a7dd741f7cc",
        "usage_id": "d2423881-c407-4c04-ba43-14a752d912c1"
        "required": false
      }
    ]
  }'

Réponse

Code Titre Description
201 OK Retourne la transaction
401 Not Authenticate L'utilisateur n'est pas authentifié
403 Unauthorized L'entreprise n'a pas les droits nécessaires pour utiliser cette API
400 Bad Request Une des familles indiquée n'existe pas
400 Bad Request Un des usages indiqué n'existe pas
400 Bad Request Le détenteur n'existe pas
400 Bad Request L'application n'existe pas

TransactionGetModel

Body Type Description
id string Identifiant unique de la transaction (UUID)
application ApplicationGetModel Application
holder CompanyGetModel Détenteur des données
starting_date string Date de début des demandes de consentement
ending_date string Date de fin des demandes de consentement
created_at string Date de création de la transaction
accepted_at string Date à laquelle la transaction à été acceptée. Null à la création
rejected_at string Date à laquelle la transaction à été refusée. Null à la création
closed_at string Date de cloture de la transaction
consents_requested array<TransactionDetailGetModel> Consentements requis par l'application
signature_uri string Url de signature de la transaction

TransactionDetailGetModel

Body Type Description
id string Identifiant unique de la demande de consentement (UUID)
family FamilyLightGetModel Famille de données
usage UsageLightGetModel Usage des données
required bool Indique si le consentement est obligatoire pour pouvoir valider la transaction
created_at string Date de création de la transaction
consents ConsentGetModel Consentements / Demandes de consentement associés à la demande indiquée dans la transaction. Null à la création

ApplicationGetModel

Body Type Description
id string Identifiant unique de l'application (UUID)
company CompanyGetModel Entreprise
name string Dénomination de l'application
description string Description de l'application
app_key string Clé de l'application
callback_uri string Url de retour
created_at string Date de création de l'application
closed_at string Date de clôture de l'application
Exemple de réponse
  {
    "id": "08b55957-5c80-4564-a2fd-3038c624f347",
    "application": {
      "id": "c2472ea7-5a66-44f2-9f10-c65cd2108d32",
      "company": {
        "id": "ad97c8bb-af72-4f2d-9664-70fd9785f54t",
        "corporate_name": "Entreprise Test",
        "address": "Rue de la tulipe",
        "postal_code": "01250",
        "city": "Ceyzeriat",
        "identifier_type": "SIRET",
        "business_identifier": "73282932000074"
      },
      "name": "Agri Maker",
      "description": "Agri Maker est le portail des agriculteurs. Acceptez les consentements pour pouvoir accéder à vos services.",
      "app_key": "hook-app-example",
      "callback_url": "https://api.agri-maker.com/consent-callback",
      "created_at": "2023-10-07T09:37:43.993Z",
      "closed_at": null
    },
    "holder": {
      "type": "OWNER",
      "id": "678df96b-b61e-4adf-9912-0efd1181d057",
      "business_identifier": "FR35167340",
      "siret": "73282932000074",
      "name": "SAS Dupond Martin",
      "address": "Rue de la tulipe",
      "postal_code": "79200",
      "city": "Ville-sur-mer"
    },
    "starting_date": "2023-10-07T10:37:43.993Z",
    "ending_date": null,
    "created_at": "2023-10-07T09:37:43.993Z",
    "accepted_at": null,
    "rejected_at": null,
    "closed_at": null,
    "consents_requested": [
      {
        "id": "08b55957-5c80-4564-a2fd-3038c624f347",
        "family": {
          "id": "5a978f05-ce36-4a66-a271-b09c202c0f13",
          "name": "Registre sanitaire d'un bovin",
          "business_identifier": "san-registre-bovin"
        },
        "usage": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Tableau de bord pour technicien",
          "description": "Fabrication des indicateurs de suivi du tableau de bord Technicien conseil en élevage",
          "business_identifier": "idx-tdb-tk-cl"
        },
        "required": true,
        "created_at": "2023-10-07T09:37:43.993Z",
        "consents": null
      }
    ],
    "signature_uri": "https://sign.agata-consent.com/9d8ee04cd09548b39e5a05b95f0d7b58/08b55957-5c80-4564-a2fd-3038c624f347"
  }

Infos complémentaires

La signature Uri est composée de [Url application de signature] / [Application Key] / [transaction ID]

Création de la transaction dénormalisée

Appel

POST /denormalizedTransactions

Cette méthode permet de créer une nouvelle transaction liée à une application. La spécificité de cette méthode c'est qu'elle va utiliser les identifiants métier.

Body Type Obligatoire Description Exemple
app_key * string Oui Clé applicative hook-app-exemple
holder_business_identifier * string Oui Identifiant métier du détenteur des données FR35167340
starting_date * string Oui Date de début des demandes de consentement 2024-03-07T10:37:43.993Z
ending_date string Non Date de fin des demandes de consentement 2025-03-07T10:37:43.993Z
consents_requested * array Oui Consentements requis par l'application

consents_requested

Body Type Obligatoire Description Exemple
domain_business_identifier * string Oui Identifiant unique du domaine de données zootechnique
family_business_identifier * string Oui Identifiant unique de la famille de données san-registre-bovin
usage_business_identifier * string Oui Identifiant unique de l'usage des données idx-tdb-tk-cl
required bool Non Indique si le consentement est obligatoire pour pouvoir valider la transaction (défaut: true) true
Exemple de requête
curl 
  --location 'https://api.agata-consent.com/transactions'
  --header 'accept: application/json'
  --data-raw '{
    "app_key": "hook-app-example",
    "holder_business_identifier": "FR35167340",
    "starting_date": "2024-03-07T10:37:43.993Z",
    "ending_date": null,
    "consents_requested": [
      {
        "domain_business_identifier": "zootechnique",
        "family_business_identifier": "san-registre-bovin",
        "usage_business_identifier": "idx-tdb-tk-cl"
        "required": true
      }
    ]
  }'

Réponse

Code Titre Description
201 OK Retourne la transaction
401 Not Authenticate L'utilisateur n'est pas authentifié
403 Unauthorized L'entreprise n'a pas les droits nécessaires pour utiliser cette API
400 Bad Request Une des familles indiquée n'existe pas
400 Bad Request Un des usages indiqué n'existe pas
400 Bad Request Le détenteur n'existe pas
400 Bad Request L'application n'existe pas

TransactionGetModel

Body Type Description
id string Identifiant unique de la transaction (UUID)
application ApplicationGetModel Application
holder CompanyGetModel Détenteur des données
starting_date string Date de début des demandes de consentement
ending_date string Date de fin des demandes de consentement
created_at string Date de création de la transaction
accepted_at string Date à laquelle la transaction à été acceptée. Null à la création
rejected_at string Date à laquelle la transaction à été refusée. Null à la création
closed_at string Date de cloture de la transaction
consents_requested array<TransactionDetailGetModel> Consentements requis par l'application
signature_uri string Url de signature de la transaction

TransactionDetailGetModel

Body Type Description
id string Identifiant unique de la demande de consentement (UUID)
family FamilyLightGetModel Famille de données
usage UsageLightGetModel Usage des données
required bool Indique si le consentement est obligatoire pour pouvoir valider la transaction
created_at string Date de création de la transaction
consents ConsentGetModel Consentements / Demandes de consentement associés à la demande indiquée dans la transaction. Null à la création

ApplicationGetModel

Body Type Description
id string Identifiant unique de l'application (UUID)
company CompanyGetModel Entreprise
name string Dénomination de l'application
description string Description de l'application
app_key string Clé de l'application
callback_uri string Url de retour
created_at string Date de création de l'application
closed_at string Date de clôture de l'application
Exemple de réponse
  {
    "id": "08b55957-5c80-4564-a2fd-3038c624f347",
    "application": {
      "id": "c2472ea7-5a66-44f2-9f10-c65cd2108d32",
      "company": {
        "id": "ad97c8bb-af72-4f2d-9664-70fd9785f54t",
        "corporate_name": "Entreprise Test",
        "address": "Rue de la tulipe",
        "postal_code": "01250",
        "city": "Ceyzeriat",
        "identifier_type": "SIRET",
        "business_identifier": "73282932000074"
      },
      "name": "Agri Maker",
      "description": "Agri Maker est le portail des agriculteurs. Acceptez les consentements pour pouvoir accéder à vos services.",
      "app_key": "hook-app-example",
      "callback_url": "https://api.agri-maker.com/consent-callback",
      "created_at": "2023-10-07T09:37:43.993Z",
      "closed_at": null
    },
    "holder": {
      "type": "OWNER",
      "id": "678df96b-b61e-4adf-9912-0efd1181d057",
      "business_identifier": "FR35167340",
      "siret": "73282932000074",
      "name": "SAS Dupond Martin",
      "address": "Rue de la tulipe",
      "postal_code": "79200",
      "city": "Ville-sur-mer"
    },
    "starting_date": "2023-10-07T10:37:43.993Z",
    "ending_date": null,
    "created_at": "2023-10-07T09:37:43.993Z",
    "accepted_at": null,
    "rejected_at": null,
    "closed_at": null,
    "consents_requested": [
      {
        "id": "08b55957-5c80-4564-a2fd-3038c624f347",
        "family": {
          "id": "5a978f05-ce36-4a66-a271-b09c202c0f13",
          "name": "Registre sanitaire d'un bovin",
          "business_identifier": "san-registre-bovin"
        },
        "usage": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Tableau de bord pour technicien",
          "description": "Fabrication des indicateurs de suivi du tableau de bord Technicien conseil en élevage",
          "business_identifier": "idx-tdb-tk-cl"
        },
        "required": true,
        "created_at": "2023-10-07T09:37:43.993Z",
        "consents": null
      }
    ],
    "signature_uri": "https://sign.agata-consent.com/9d8ee04cd09548b39e5a05b95f0d7b58/08b55957-5c80-4564-a2fd-3038c624f347"
  }

Fermer une transaction

Appel

DELETE /transactions/{transaction_id}

Cette méthode permet de fermer tous les consentements d'une transaction validée.

QueryParam Type Obligatoire Description Exemple
transaction_id * string Oui Identifiant unique de la transaction 08b55957-5c80-4564-a2fd-3038c624f347
Exemple de requête
curl 
  --location 'https://api.agata-consent.com/transactions/08b55957-5c80-4564-a2fd-3038c624f347'
  --header 'accept: application/json'

Réponse

Code Titre Description
201 OK Retourne la transaction
401 Not Authenticate L'utilisateur n'est pas authentifié
403 Unauthorized L'entreprise n'a pas les droits nécessaires pour utiliser cette API
404 Not Found La transaction indiquée n'existe pas

TransactionGetModel

Body Type Description
id string Identifiant unique de la transaction (UUID)
application ApplicationGetModel Application
holder CompanyGetModel Détenteur des données
starting_date string Date de début des demandes de consentement
ending_date string Date de fin des demandes de consentement
created_at string Date de création de la transaction
accepted_at string Date à laquelle la transaction à été acceptée. Null à la création
rejected_at string Date à laquelle la transaction à été refusée. Null à la création
closed_at string Date de cloture de la transaction
consents_requested array<TransactionDetailGetModel> Consentements requis par l'application
signature_uri string Url de signature de la transaction

TransactionDetailGetModel

Body Type Description
id string Identifiant unique de la demande de consentement (UUID)
family FamilyLightGetModel Famille de données
usage UsageLightGetModel Usage des données
required bool Indique si le consentement est obligatoire pour pouvoir valider la transaction
created_at string Date de création de la transaction
consents ConsentGetModel Consentements / Demandes de consentement associés à la demande indiquée dans la transaction. Null à la création

ApplicationGetModel

Body Type Description
id string Identifiant unique de l'application (UUID)
company CompanyGetModel Entreprise
name string Dénomination de l'application
description string Description de l'application
app_key string Clé de l'application
callback_uri string Url de retour
created_at string Date de création de l'application
closed_at string Date de clôture de l'application
Exemple de réponse
  {
    "id": "08b55957-5c80-4564-a2fd-3038c624f347",
    "application": {
      "id": "c2472ea7-5a66-44f2-9f10-c65cd2108d32",
      "company": {
        "id": "ad97c8bb-af72-4f2d-9664-70fd9785f54t",
        "corporate_name": "Entreprise Test",
        "address": "Rue de la tulipe",
        "postal_code": "01250",
        "city": "Ceyzeriat",
        "identifier_type": "SIRET",
        "business_identifier": "73282932000074"
      },
      "name": "Agri Maker",
      "description": "Agri Maker est le portail des agriculteurs. Acceptez les consentements pour pouvoir accéder à vos services.",
      "app_key": "hook-app-example",
      "callback_url": "https://api.agri-maker.com/consent-callback",
      "created_at": "2023-10-07T09:37:43.993Z",
      "closed_at": null
    },
    "holder": {
      "type": "OWNER",
      "id": "678df96b-b61e-4adf-9912-0efd1181d057",
      "business_identifier": "FR35167340",
      "siret": "73282932000074",
      "name": "SAS Dupond Martin",
      "address": "Rue de la tulipe",
      "postal_code": "79200",
      "city": "Ville-sur-mer"
    },
    "starting_date": "2023-10-07T10:37:43.993Z",
    "ending_date": null,
    "created_at": "2023-10-07T09:37:43.993Z",
    "accepted_at": null,
    "rejected_at": null,
    "closed_at": null,
    "consents_requested": [
      {
        "id": "08b55957-5c80-4564-a2fd-3038c624f347",
        "family": {
          "id": "5a978f05-ce36-4a66-a271-b09c202c0f13",
          "name": "Registre sanitaire d'un bovin",
          "business_identifier": "san-registre-bovin"
        },
        "usage": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Tableau de bord pour technicien",
          "description": "Fabrication des indicateurs de suivi du tableau de bord Technicien conseil en élevage",
          "business_identifier": "idx-tdb-tk-cl"
        },
        "required": true,
        "created_at": "2023-10-07T09:37:43.993Z",
        "consents": [
          {
            "id": "e69ed05d-0a95-42db-b3df-f8614bebcb82",
            "assignee": {
              "type": "OWNER",
              "id": "678df96b-b61e-4adf-9912-0efd1181d057",
              "business_identifier": "FR35167340",
              "siret": "73282932000074",
              "name": "SAS Dupond Martin",
              "address": "Rue de la tulipe",
              "postal_code": "79200",
              "city": "Ville-sur-mer"
            },
            "beneficiary": {
              "type": "ACTOR",
              "id": "3fa85f64-b61e-4adf-b3fc-2c963f66afa6",
              "business_identifier": "FR35167340",
              "siret": "73282932000074",
              "name": "SAS Dupond Martin",
              "address": "Rue de la tulipe",
              "postal_code": "79200",
              "city": "Ville-sur-mer"
            },
            "owner": {
              "type": "OWNER",
              "id": "678df96b-b61e-4adf-9912-0efd1181d057",
              "business_identifier": "FR35167340",
              "siret": "73282932000074",
              "name": "SAS Dupond Martin",
              "address": "Rue de la tulipe",
              "postal_code": "79200",
              "city": "Ville-sur-mer"
            },
            "creator": {
              "type": "ACTOR",
              "id": "3fa85f64-b61e-4adf-b3fc-2c963f66afa6",
              "business_identifier": "FR35167340",
              "siret": "73282932000074",
              "name": "SAS Dupond Martin",
              "address": "Rue de la tulipe",
              "postal_code": "79200",
              "city": "Ville-sur-mer"
            },
            "family": {
              "id": "5a978f05-ce36-4a66-a271-b09c202c0f13",
              "name": "Registre sanitaire d'un bovin",
              "business_identifier": "san-registre-bovin"
            },
            "usage": {
              "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "name": "Tableau de bord pour technicien",
              "description": "Fabrication des indicateurs de suivi du tableau de bord Technicien conseil en élevage",
              "business_identifier": "idx-tdb-tk-cl"
            },
            "domain": {
              "id": "c6fea1f4-eb41-4783-871e-84fcd73e334c",
              "name": "Zootechnique",
              "business_identifier": "zootechnique"
            },
            "state": "REVOKED",
            "starting_date": "2023-10-07T10:37:43.993Z",
            "ending_date": "2024-04-03T17:56:00.000Z",
            "validation_date": "2023-10-07T09:40:02.056Z",
            "creation_date": "2023-10-07T09:37:43.993Z",
            "last_update_date": "2024-04-03T17:56:00.000Z"
          }
        ]
      }
    ],
    "signature_uri": "null"
  }

Infos complémentaires

La recherche de la transaction se fait via son id ET l'id de l'entreprise connectée via l'application

Cette méthode à pour objectif de permettre à un acteur bénéficiaire d'AGATA CONSENT de fermer des consentements à la place du détenteur des données. Par exemple lorsque le détenteur clos un contrat avec l'entreprise bénéficiaire ou lors du désabonnement à un service par le détenteur.

La méthode applique les contrôles d'accès et de cohérence des données puis pour chaque ligne de détail va clore à la date du jour, tous les consentements "actifs" ou "futurs" qui lui sont rattachés.

Après ce traitement, la date de cloture de transaction est renseignée à la date du jour et la transaction est enregistrée en base de données.

Lancer le traitement d'une transaction

Appel

GET /applications/{app_key}/transactions/{transaction_id}

Cette méthode permet de lancer l'analyse d'une transaction, la création des demandes de consentement si nécessaire puis d'obtenir la transaction complétée.

QueryParam Type Obligatoire Description Exemple
app_key * string Oui Clé d'api utilisée pour faire desdemandes de transaction ainsi que dans la construction de l'url d'appel du portail de signature des consentements hook-app-example
transaction_id * string Oui Identifiant unique de la transaction 08b55957-5c80-4564-a2fd-3038c624f347
Exemple de requête
curl 
  --location 
  --request GET 'https://api.agata-consent.com/applications/hook-app-example/transactions/08b55957-5c80-4564-a2fd-3038c624f347'
  --header 'accept: application/json'

Réponse

Code Titre Description
200 OK Retourne la transaction complétée
204 No Content La transaction à été complétée dans besoin de signature
404 Not Found Le couple app_key / transaction_id n'a retournée aucune transaction
404 Not Found La transaction indiquée a déjà été acceptée ou refusée

TransactionGetModel

Body Type Description
id string Identifiant unique de la transaction (UUID)
application ApplicationGetModel Application
holder CompanyGetModel Détenteur des données
starting_date string Date de début des demandes de consentement
ending_date string Date de fin des demandes de consentement
created_at string Date de création de la transaction
accepted_at string Date à laquelle la transaction à été acceptée. Null à la création
rejected_at string Date à laquelle la transaction à été refusée. Null à la création
closed_at string Date de cloture de la transaction
consents_requested array<TransactionDetailGetModel> Consentements requis par l'application
signature_uri string Url de signature de la transaction. Uniquement disponible si la transaction n'a été ni acceptée, ni refusée

TransactionDetailGetModel

Body Type Description
id string Identifiant unique de la demande de consentement (UUID)
family FamilyLightGetModel Famille de données
usage UsageLightGetModel Usage des données
required bool Indique si le consentement est obligatoire pour pouvoir valider la transaction
created_at string Date de création de la transaction
consents ConsentGetModel Consentements / Demandes de consentement associés à la demande indiquée dans la transaction.

ApplicationGetModel

Body Type Description
id string Identifiant unique de l'application (UUID)
company CompanyGetModel Entreprise
name string Dénomination de l'application
description string Description de l'application
app_key string Clé de l'application
callback_uri string Url de retour
created_at string Date de création de l'application
closed_at string Date de clôture de l'application
Exemple de réponse
  {
    "id": "08b55957-5c80-4564-a2fd-3038c624f347",
    "application": {
      "id": "c2472ea7-5a66-44f2-9f10-c65cd2108d32",
      "company": {
        "id": "ad97c8bb-af72-4f2d-9664-70fd9785f54t",
        "corporate_name": "Entreprise Test",
        "address": "Rue de la tulipe",
        "postal_code": "01250",
        "city": "Ceyzeriat",
        "identifier_type": "SIRET",
        "business_identifier": "73282932000074"
      },
      "name": "Agri Maker",
      "description": "Agri Maker est le portail des agriculteurs. Acceptez les consentements pour pouvoir accéder à vos services.",
      "app_key": "hook-app-example",
      "callback_url": "https://api.agri-maker.com/consent-callback",
      "created_at": "2023-10-07T09:37:43.993Z",
      "closed_at": null
    },
    "holder": {
      "type": "OWNER",
      "id": "678df96b-b61e-4adf-9912-0efd1181d057",
      "business_identifier": "FR35167340",
      "siret": "73282932000074",
      "name": "SAS Dupond Martin",
      "address": "Rue de la tulipe",
      "postal_code": "79200",
      "city": "Ville-sur-mer"
    },
    "starting_date": "2023-10-07T10:37:43.993Z",
    "ending_date": null,
    "created_at": "2023-10-07T09:37:43.993Z",
    "accepted_at": null,
    "rejected_at": null,
    "closed_at": null,
    "consents_requested": [
      {
        "id": "08b55957-5c80-4564-a2fd-3038c624f347",
        "family": {
          "id": "5a978f05-ce36-4a66-a271-b09c202c0f13",
          "name": "Registre sanitaire d'un bovin",
          "business_identifier": "san-registre-bovin"
        },
        "usage": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Tableau de bord pour technicien",
          "description": "Fabrication des indicateurs de suivi du tableau de bord Technicien conseil en élevage",
          "business_identifier": "idx-tdb-tk-cl"
        },
        "required": true,
        "created_at": "2023-10-07T09:37:43.993Z",
        "consents": [
          {
            "id": "e69ed05d-0a95-42db-b3df-f8614bebcb82",
            "assignee": {
              "type": "OWNER",
              "id": "678df96b-b61e-4adf-9912-0efd1181d057",
              "business_identifier": "FR35167340",
              "siret": "73282932000074",
              "name": "SAS Dupond Martin",
              "address": "Rue de la tulipe",
              "postal_code": "79200",
              "city": "Ville-sur-mer"
            },
            "beneficiary": {
              "type": "ACTOR",
              "id": "3fa85f64-b61e-4adf-b3fc-2c963f66afa6",
              "business_identifier": "FR35167340",
              "siret": "73282932000074",
              "name": "SAS Dupond Martin",
              "address": "Rue de la tulipe",
              "postal_code": "79200",
              "city": "Ville-sur-mer"
            },
            "owner": {
              "type": "OWNER",
              "id": "678df96b-b61e-4adf-9912-0efd1181d057",
              "business_identifier": "FR35167340",
              "siret": "73282932000074",
              "name": "SAS Dupond Martin",
              "address": "Rue de la tulipe",
              "postal_code": "79200",
              "city": "Ville-sur-mer"
            },
            "creator": {
              "type": "ACTOR",
              "id": "3fa85f64-b61e-4adf-b3fc-2c963f66afa6",
              "business_identifier": "FR35167340",
              "siret": "73282932000074",
              "name": "SAS Dupond Martin",
              "address": "Rue de la tulipe",
              "postal_code": "79200",
              "city": "Ville-sur-mer"
            },
            "family": {
              "id": "5a978f05-ce36-4a66-a271-b09c202c0f13",
              "name": "Registre sanitaire d'un bovin",
              "business_identifier": "san-registre-bovin"
            },
            "usage": {
              "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "name": "Tableau de bord pour technicien",
              "description": "Fabrication des indicateurs de suivi du tableau de bord Technicien conseil en élevage",
              "business_identifier": "idx-tdb-tk-cl"
            },
            "domain": {
              "id": "c6fea1f4-eb41-4783-871e-84fcd73e334c",
              "name": "Zootechnique",
              "business_identifier": "zootechnique"
            },
            "state": "VALIDATED",
            "starting_date": "2023-10-07T10:37:43.993Z",
            "creation_date": "2023-10-07T09:37:43.993Z"
          }
        ]
      }
    ],
    "signature_uri": "null"
  }

Infos complémentaires

La recherche de la transaction se fait via son id ET l'id de l'entreprise connectée via l'application

Cette méthode a pour objectif de traiter la liste des consentements existant afin de sélectionner les consentements/ demandes actifs sur la période de la transaction tout en créant les demandes de consentements "intercalaires".

Accepter / Refuser une transaction

Appel

PATCH /applications/{app_key}/transactions/{transaction_id}

Cette méthode permet d'accepter ou refuser les consentements d'une transaction. A l'exception des lignes de détails optionnelles qui peuvent être refusées unitairement, le choix d'accepter ou refuser les consentements se fait sur l'ensemble de la transaction.

QueryParam Type Obligatoire Description Exemple
app_key * string Oui Indique si les consentements de la transaction ont été acceptés true
transaction_id * string Oui Identifiant unique de la transaction 08b55957-5c80-4564-a2fd-3038c624f347
Body Type Obligatoire Description Exemple
transaction_is_accepted * bool Oui Clé d'api utilisée pour faire desdemandes de transaction ainsi que dans la construction de l'url d'appel du portail de signature des consentements hook-app-example
refusal_reason * string Oui/Non Cause de refus. Obligatoire si la transaction est refusée Je ne souhaite pas partager mes données.
rejected_optional_detail_ids * Array string Non Identifiants des lignes optionnelles de détail refusées par l'utilisateur [e69ed05d-0a95-42db-b3dff8614bebcb82]
Exemple de requête
curl 
  --location 
  --request PATCH 'https://api.agata-consent.com/applications/hook-app-example/transactions/08b55957-5c80-4564-a2fd-3038c624f347'
  --header 'accept: application/json'
  --data-raw '{
    "transaction_is_accepted": true,
    "refusal_reason": null,
    "rejected_optional_detail_ids": ["e69ed05d-0a95-42db-b3df-f8614bebcb82"]
  }'

Réponse

Code Titre Description
204 No Content La transaction à été traitée avec succès
404 Not Found Le couple app_key / transaction_id n'a retournée aucune transaction
404 Not Found La transaction indiquée a déjà été acceptée ou refusée

Infos complémentaires

La recherche de la transaction se fait via son id ET l'id de l'entreprise connectée via l'application

Cette méthode doit modifier les demandes de consentements associées à chaque ligne de détail de la transaction pour prendre en compte le choix de l'utilisateur (accepter / refuser). Seules les demandes doivent être modifiées (consentements sans date de validation, refus ou clôture).

Dans le cas d'une validation de la transaction, il est possible d'indiquer dans le champ RejectedOptionalDetailIds une liste d'ID de lignes de détails ayant la propriété required à false. Dans ce cas les demandes de consentements associées à ces lignes de détail seront refusées avec pour motif "Demande optionnelle refusée lors de la validation de la transaction", les autres demandes de consentements seront validées.

Une fois que les demandes de consentements sont mises à jour, il faut modifier la transaction pour indiquer une date d'acceptation (accepted_at) ou une date de refus (rejected_at).

Après la mise à jour en base de données, il reste à faire appel à l'url de "callback" indiquée dans l'application.

POST https://mon-url-de-callback.mon-application.com?seckey=.....

Exemple de requête
curl 
  --location 
  --request POST 'https://mon-url-de-callback.mon-application.com?seckey=....'
  --header 'accept: application/json'
  --data-raw '{
    "transaction_id": "e69ed05d-0a95-42db-b3df-f8614bebcb82",
    "transaction_is_accepted": true,
    "refusal_reason": null
  }'