Prévisualisation

Recevez des événements Molink dans votre connecteur de moteur de prévisualisation

Écoutez les événements de votre compte Molink sur votre connecteur de moteur de prévisualisation afin que votre intégration puisse déclencher automatiquement le calcul de la hauteur des avis nécrologiques.

Pourquoi utiliser les moteurs de prévisualisation ?

Lors de la création de votre compte client au sein de Molink, vous allez devoir renseigner votre connecteur de votre API de moteur de prévisualisation afin que vos systèmes backend puissent retourner des informations concernant la hauteur de l'avis ainsi que celles des options (symbole, image).

Pour activer les événements vers votre API de moteur de prévisualisation vous devez enregistrer le connecteur du moteur de prévisualisation. Après l'avoir enregistré, Molink peut transmettre les données d'un avis en temps réel lors de la saisie de celui-ci au connecteur du moteur de prévisualisation.

La réception d'événements de Molink vers votre connecteur de votre moteur de prévisualisation est particulièrement utile pour écouter des événements asynchrones lors de la saisie d'avis au sein de Molink. Par exemple lorsqu'un membre de votre entreprise saisit un avis, Molink va pouvoir récupérer la hauteur fournie par votre moteur de prévisualisation et fournir une tarification en fonction de votre système de tarification intégré dans Molink.

Schéma de prévisualisation

Schéma de prévisualisation

Aperçu de l'événement

Molink génère des évènement que nous pouvons envoyer à votre moteur de Prévisualisation permettant ainsi de communiquer à Molink la hauteur de l'avis.

Lorsqu'un avis est saisi Molink génère un objet de l'avis en cours de saisie vers votre moteur de prévisualisation.

En enregistrant le point de terminaison de votre moteur de prévisualisation dans votre projet Molink, vous permettez à Molink d'envoyer automatiquement des événements par requêtre HTTP en POST sur le connecteur de votre moteur de prévisualisation hébergé par votre application. Une fois que votre connecteur de votre moteur de prévisualisation a reçu l'événement, votre application peut exécuter des actions backend (par exemple, appeler les API de votre transporteur pour planifier une expédition après avoir reçu un événement).

Exemple de l'objet envoyé

Lors de la saisie d'avis, Molink enverra une requête HTTP en POST sur le connecteur de votre moteur de prévisualisation fournie dans votre projet Molink avec en body un objet propre à Molink sous format JSON.

L'exemple de code suivant représente l'objet JSON qui sera transmis dans le BODY de la requête HTTP POST vers votre moteur de prévisualisation :

{
    "notice": {
        "id": 4000653,
        "ceremony": {
            "id": 1,
            "occured_at": "2024-02-03T00:00:00+01:00",
            "location": {
                "id": 1,
                "label": "A la cathédrale Saint-Pierre de Nantes",
                "town": {
                    "id": 37448,
                    "name": "Nantes",
                    "insee": "44109",
                    "postal_code": [
                        "44000",
                        "44100",
                        "44200",
                        "44300"
                    ],
                },
            },
        },
        "type": {
            "id": 2,
            "code": "AD",
            "label": "Avis de décès"
        },
        "category": {
            "id": 1,
            "code": "AF",
            "label": "Avis de famille"
        },
        "model": {
            "id": 4,
            "code": "AD_PART_AVANT"
        },
        "options": [
            {
                "id": 3,
                "code": "ETOILE",
                "label": "Un symbole"
            }
        ],
        "composition_fields": [
            {
                "id": 3924,
                "content": "Clisson",
                "release": 2,
                "type": {
                    "id": 1,
                    "code": "AD_PART_AVANT_COMMUNES",
                    "label": "Communes",
                    "group": {
                        "id": 1,
                        "code": "COH",
                        "label": "Contenu Haut"
                    },
                    "order": 1
                }
            },
            {
                "id": 3692,
                "content": "",
                "release": 1,
                "type": {
                    "id": 166,
                    "code": "AD_PART_APRES_COMMUNES",
                    "label": "Communes",
                    "group": {
                        "id": 1,
                        "code": "COH",
                        "label": "Contenu Haut"
                    },
                    "order": 1
                }
            },
            {
                "id": 3693,
                "content": "« Tu seras à jamais dans nos cœurs. »",
                "release": 1,
                "type": {
                    "id": 167,
                    "code": "AD_PART_APRES_CITATION",
                    "label": "Citation",
                    "group": {
                        "id": 1,
                        "code": "COH",
                        "label": "Contenu Haut"
                    },
                    "order": 2
                }
            },
            {
                "id": 3694,
                "content": "",
                "release": 1,
                "type": {
                    "id": 168,
                    "code": "AD_PART_APRES_ANNONCE_DECES",
                    "label": "Annonce du décès",
                    "group": {
                        "id": 1,
                        "code": "COH",
                        "label": "Contenu Haut"
                    },
                    "order": 3
                }
            }
        ]
    },
    "title": {
        "id": 1,
        "code": "TITLE_CODE",
        "label": "Title Code"
    }
}

Aperçu de la réponse de l'évènement

Molink a besoin de recevoir une réponse de votre connecteur pour chaque événement reçu par appel HTTP en POST vers votre connecteur. Molink enregistre dans sa base de données la hauteur de l'avis et de ses options calculée par votre moteur de prévisualisation. Les différentes hauteurs enregistrées par Molink permettent de fournir une tarification précise auprès des clients du projet à partir de votre système de tarification.

Exemple de la réponse attendue

Pour que nos applications fonctionnent correctement Molink attend une réponse précise en format JSON de la part de votre moteur de prévisualisation.

Voici un exemple d'une réponse précise concernant la réponse du moteur prévisualisation enregistrée au sein de votre projet Molink :

  {
    "$schema": 1,
    "notice": {
      "height": {
        "value": 43.5,
        "unit": "cm"
      },
      "preview": "<<blob>>",
      "operator": {
        "properties": {
          "print_mark": {
            "height": {
              "value": 5.5,
              "unit": "cm"
            }
          }
        }
      },
      "options": [
        {
          "kind": "symbol",
          "height": {
            "value": 7.5,
            "unit": "cm"
          }
        },
        {
          "kind": "picture",
          "height": {
            "value": 7.5,
            "unit": "cm"
          }
        },
        {
          "kind": "two_columns",
          "height": {
            "value": 7.5,
            "unit": "cm"
          }
        }
      ]
    }
  }

Voici quelques précisions sur le format de données attendu :

CléDescription
notice.heightLa taille intégrale de l'avis
notice.previewBLOB base64 d'une image PNG ou d'un fichier PDF attendue
notice.operator.properties.print_mark.heightLa taille de la griffe du déclarant dans l'avis
options[].heightLa taille de l'option (image, symbole, deux colonnes ...)

Pour commencer...

Pour commencer à recevoir des événements dans votre connecteur de prévisualisation, créez et enregistrez un connecteur vers votre moteur de prévisualisation en suivant les étapes ci-dessous :

  1. Créez un connecteur pour recevoir les requêtes POST ;
  2. Testez votre connecteur localement à l'aide ngrok ;
  3. Enregistrez votre connecteur dans Molink à l'aide du tableau de bord ou de l'API ;
  4. Sécurisez votre connecteur avec votre clé secrète.

1. Créer un connecteur

Configurez une connexion HTTP ou HTTPS vers votre connecteur qui peut accepter les requêtes de votre moteur de prévisualisation avec une méthode POST. Si vous développez encore votre connecteur sur votre ordinateur local, elle peut utiliser HTTP. Une fois accessible publiquement, le connecteur de votre moteur de prévisualisation doit utiliser HTTPS.

Configurez votre connecteur pour qu'il :

  1. Gère les requêtes POST avec en body un JSON type ;
  2. Renvoie rapidement un code d'état réussi ( 2xx) avant toute logique complexe susceptible de provoquer un délai d'attente inutile.
// This example uses Express to receive event from Molink
const express = require('express');
const app = express();

// Match the raw body to content type application/json
// If you are using Express v4 - v4.16 you need to use body-parser, not express, to retrieve the request body
app.post('/preview-engines', express.json({type: 'application/json'}), (request, response) => {
  const event = request.body;

  // Do something

  // Return a response to acknowledge receipt of the event
  response.json({received: true});
});

app.listen(8000, () => console.log('Running on port 8000'));

2. Tester son gestionnaire

Avant de mettre en service votre connecteur vers votre moteur de prévisualisation nous vous recommandons de tester l'intégration de votre application. Vous pouvez le faire en configurant un écouteur local pour envoyer des événements à votre ordinateur local et en envoyant des événements de test. Vous pouvez utiliser ngrok pour tester.

Transférer les événements vers un connecteur local

Pour transférer des événements vers votre connecteur local, exécutez la commande suivante avec ngrok pour configurer un écouteur local.

ngrok http 8000

3. Enregistrer votre connecteur dans Molink

Après avoir testé votre connecteur vers votre moteur de prévisualisation, enregistrez l'URL accessible du connecteur à l'aide de la section Paramètres > Développeurs > Moteur de prévisualisation du tableau de bord du développeur ou de l'API afin que Molink sache où diffuser les événements vers votre connecteur. Le connecteur de votre connecteur enregistré doit être une URL HTTPS accessible au public.

Format d'URL de votre connecteur

Le format d'URL pour enregistrer un connecteur de votre moteur de prévisualisation est le suivant :

https://<your-website>/<your-preview-engine-endpoint>

Par exemple, si votre domaine est https://mycompanysite.comet que l'itinéraire vers votre connecteur de votre moteur de prévisualisation est @app.route('/preview-engines', methods=['POST']), spécifiez https://mycompanysite.com/preivew-engine-comme URL du connecteur.

Ajouter un connecteur avec l'interface Molink

Suivez les étapes suivantes pour enregistrer un connecteur vers votre moteur de prévisualisation dans le tableau de bord des développeurs. Vous pouvez enregistrer un seul connecteur sur chaque projet Molink.

📘

Information

Cette page n'est pas encore disponible. Nous faisons tout notre possible pour proposer ce parcours utilisateurs et nous vous fournissons la documentation dès que le parcours sera disponible.

Enregistrer un connecteur avec l'API Molink

Vous pouvez également par programmation enregistrer votre connecteur de votre moteur de prévisualisation.

curl --request POST \
     --url https://api.molink.fr/v2/preview-engines \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "Preview engine",
  "url": "https://<your-website>/<your-preview-engine-endpoint>"
}
'

4. Sécuriser votre connecteur

Nous vous recommandons fortement de sécuriser votre intégration en vous assurant que votre gestionnaire vérifie que tous les appels sont bien envoyés par Molink. Il est possible de vérifier un appel vers votre moteur de prévisualisation grâce à la clé secrète qui est auto-générée lors de l'enregistrement de votre connecteur au sein de Molink.

// server.js
//
// 1) Paste this code into a new file (server.js)
//
// 2) Install dependencies
//   npm install express
//
// 3) Run the server on http://localhost:4242
//   node server.js
const express = require('express');
const app = express();


// This is your preview-engine secret.
const endpointSecret = "prv_sk_2cjINofCTVYWPj5JLRldvTFMGtK";

app.post('/preview-engine', express.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['molink-signature'];

  let event;

  if (sig === endpointSecret) {
	  // Handle the event
  	console.log(`Unhandled event type ${event.type}`);

  	// Return a 200 response to acknowledge receipt of the event
  	response.send();
  } else {
  	// Handle error
  }
});

app.listen(8000, () => console.log('Running on port 8000'));

Rafraichir la clé secrète

Si votre clé secrète fuit il sera possible de la rafraichir à partir de l'interface graphique.

📘

Information

Cette page n'est pas encore disponible. Nous faisons tout notre possible pour proposer ce parcours utilisateurs et nous vous fournissons la documentation dès que le parcours sera disponible.

Rafraichir la clé secrète avec l'API Molink

Vous pouvez également par programmation rafraichir votre connecteur de votre moteur de prévisualisation.

curl --request POST \
     --url https://api.molink.fr/v2/preview-engines/id/refresh-secret-key \
     --header 'accept: application/json'

Déboguer les intégrations de votre moteur de prévisualisation

Plusieurs types de problèmes peuvent survenir lors de la transmission d’événements à votre connecteur vers votre moteur de prévisualisation :

  • Molink pourrait ne pas être en mesure de transmettre un événement à votre connecteur ;
  • Votre connecteur peut avoir un problème SSL ;
  • Votre connectivité réseau est intermittente ;
  • Votre connecteur ne reçoit pas les événements que vous attendez.

Corriger les codes d'état HTTP

Lorsqu'un événement affiche le code d'état 200, cela indique une livraison réussie au connecteur du moteur de prévisualisation. Vous pouvez également recevoir un code d'état autre que 200. Consultez le tableau ci-dessous pour obtenir une liste des codes d'état HTTP courants et des solutions recommandées.

STATUTDESCRIPTIONRÉPARER
(Impossible de se connecter) ERRNous ne parvenons pas à établir une connexion avec le serveur de destination.Assurez-vous que votre domaine hôte est publiquement accessible sur Internet.
( 302) ERR (ou autre 3xx statut)Le serveur de destination a tenté de rediriger la demande vers un autre emplacement. Nous considérons les réponses de redirection aux requêtes vers votre moteur de prévisualisation comme des échecs.Définissez la destination du connecteur du moteur de prévisualisation sur l'URL résolue par la redirection.
( 400) ERR (ou autre 4xx statut)Le serveur de destination ne peut pas ou ne veut pas traiter la demande. Cela peut se produire lorsque le serveur détecte une erreur ( 400), lorsque l'URL de destination a des restrictions d'accès ( 401, 403) ou lorsque l'URL de destination n'existe pas ( 404).Assurez-vous que votre connecteur est publiquement accessible sur Internet.
Assurez-vous que votre connecteur accepte une méthode HTTP POST.
( 500) ERR (ou autre 5xx statut)Le serveur de destination a rencontré une erreur lors du traitement de la demande.Consultez les journaux de votre application pour comprendre pourquoi elle renvoie une 500erreur.
(Erreur TLS) ERREURNous n'avons pas pu établir une connexion sécurisée avec le serveur de destination. Ces erreurs sont généralement causées par un problème avec le certificat SSL/TLS ou un certificat intermédiaire dans la chaîne de certificats du serveur de destination.Effectuez un test du serveur SSL pour détecter les problèmes susceptibles de provoquer cette erreur.
(Délai expiré) ERRLe serveur de destination a mis plus de 5 secondes à répondre à la demande de Molink.Assurez-vous de différer la logique complexe et de renvoyer immédiatement une réponse réussie dans votre code de gestion du moteur de prévisualisation.

What’s Next