API du relais

Les trois routes partagent la même adresse et la même clé : seule la fin du chemin change.

Règles communes

• Clé : en-tête x-functions-key: <clé>, ou paramètre ?code=<clé>. Avec RELAY_EXTRA_API_KEY, ajoutez l'en-tête x-relay-key.
• Corps : JSON. Envoyez l'en-tête Content-Type: application/json.
• Noms de champs : la casse est indifférente (subject ou Subject).
• Types stricts : un nombre ou un booléen entre guillemets, ou une chaîne à la place d'une liste, donne 400 Invalid JSON body, sans nom de champ. C'est l'erreur la plus fréquente avec les outils sans code.
• Code HTTP : pour les réponses du relais, il est égal au champ status du corps. Les refus d'Azure (clé absente ou invalide, route inconnue) n'ont pas de corps.
• Ordre des contrôles : x-relay-key, puis le JSON, puis la configuration du relais (500), puis les champs (400). Un relais mal configuré répond donc 500, même à un corps invalide.

POST /api/enveloppe

Crée un lien que vous transmettez à quelqu'un pour recevoir des documents de sa part. Le relais ne l'envoie pas : c'est à vous de transmettre le lien.

Champ	Type	Rôle
subject	texte	Obligatoire. Sujet de l'enveloppe, visible par le destinataire.
destination	texte	Obligatoire. Un seul courriel : appelez la route une fois par destinataire.
culture	texte	fr-CA ou en-CA, pour cet appel. Par défaut, SE_DEFAULT_CULTURE.
notifyWhenRead	booléen	Avertit la personne qui a répondu quand vous ouvrez sa réponse. Défaut : true.
replyExpirationHours	entier	Durée de validité de l'enveloppe, en heures. Défaut : 24, dans la limite de conservation de votre licence.
maximumReplyOpenTime	entier	Nombre de fois où vous pourrez ouvrir la réponse, de 1 à 99. Défaut : 1.
authorizedExtensions	liste	Extensions acceptées, par exemple [".pdf", ".jpg"], toujours en liste JSON. Mises en minuscules, point ajouté, doublons retirés. Absent : toutes.
callBackParameters	texte	Données rattachées à la réponse, par exemple un numéro de dossier. Conservées seulement si votre organisation utilise SESAR. Rien de confidentiel.
replyToAPI	booléen	Obsolète et sans effet.

curl -s -X POST "https://<hôte>/api/enveloppe" -H "x-functions-key: <clé>" -H "Content-Type: application/json" -d '{"subject":"Documents demandés","destination":"client@example.com","replyExpirationHours":72,"authorizedExtensions":[".pdf"]}'

{
  "status": 200,
  "url": "https://www.secure-exchanges.com/...&enveloppe=true",
  "repId": "00000000-0000-0000-0000-000000000000",
  "error": null
}

url est le lien à transmettre ; repId identifie la réponse attendue.

Code	Quand
400	subject and destination are required, ou corps invalide
500	Relay is not configured, ou erreur interne
502	Pas de réponse utilisable de Secure Exchanges, souvent le mauvais environnement
Autre 4xx ou 5xx	Code renvoyé tel quel par Secure Exchanges

POST /api/message

Envoie un message sécurisé. Secure Exchanges expédie le courriel : chaque destinataire reçoit son propre lien, et tous partagent le mot de passe.

Champ	Type	Rôle
subject	texte	Obligatoire. Sujet du courriel.
message	texte	Obligatoire. Corps du message.
recipients	liste	Obligatoire, au moins un : [{"email": "...", "phone": "+15145551234"}]. Un destinataire sans courriel n'est accepté qu'en msgSMSOnly.
password	texte	Mot de passe du message, partagé par tous les destinataires. Transmettez-le par un autre canal.
sendMode	texte	onlyEmail par défaut. msgSMSOnly, msgSMSCodeEmail et msgEmailCodeSms exigent un téléphone pour chaque destinataire.
culture	texte	fr-CA ou en-CA, pour cet appel.
notifyWhenRead	booléen	Vous êtes averti à l'ouverture. Défaut : true.
clearTextNotification	booléen	Avis d'ouverture en clair plutôt que chiffré. Défaut : false.
maximumOpenTime	entier	Nombre d'ouvertures avant destruction, de 1 à 99. Défaut : 5.
expirationMinutes	entier	Durée de vie du message, supérieure à 0. Défaut : 50 400, soit 35 jours.
senderName	texte	Nom affiché comme expéditeur.
callBackParameters	texte	Données restituées à la lecture. Rien de confidentiel.

curl -s -X POST "https://<hôte>/api/message" -H "x-functions-key: <clé>" -H "Content-Type: application/json" -d '{"subject":"Vos documents","message":"Bonjour, vos documents sont prêts.","recipients":[{"email":"client@example.com"}]}'

{
  "status": 200,
  "recipients": [
    {
      "email": "client@example.com",
      "status": 200,
      "url": "https://www.secure-exchanges.com/...",
      "messageId": "...",
      "trackingId": "00000000-0000-0000-0000-000000000000",
      "openingCode": null
    }
  ],
  "error": null
}

Vérifiez le status de chaque destinataire, et pas seulement celui de premier niveau. Le relais valide d'abord tous les destinataires : une erreur nomme la ligne fautive, par exemple recipients[1]: email is required (only sendMode msgSMSOnly accepts a phone-only recipient), l'indice commençant à 0. Si Secure Exchanges refuse ensuite un destinataire, l'envoi peut s'arrêter là : la réponse est alors en erreur, et recipients liste ceux déjà servis.

Le courriel est déjà parti : url est donné pour information. Ne le redistribuez pas, il donne accès au message.

Code	Quand
400	Champ obligatoire absent, sendMode inconnu, maximumOpenTime hors de 1 à 99, expirationMinutes nul ou négatif, destinataire invalide, corps invalide
500	Relay is not configured, ou erreur interne
502	Pas de réponse utilisable de Secure Exchanges
Autre 4xx ou 5xx	Code renvoyé tel quel par Secure Exchanges, par exemple 403 avec le mauvais environnement

GET /api/version

Aucun corps. Indique la version installée et la dernière version publiée.

{
  "status": 200,
  "version": "1.2.0",
  "publishedVersion": "1.2.0",
  "updateAvailable": false,
  "operations": ["POST /api/enveloppe", "POST /api/message", "GET /api/version"],
  "error": null
}

Cette route n'appelle pas Secure Exchanges et ne lit pas vos identifiants : une réponse 200 prouve que le code est installé et que la clé est valide, pas que la configuration est correcte. Elle répond 200, ou 401 avec RELAY_EXTRA_API_KEY.

publishedVersion et updateAvailable valent null quand le fichier de version publié n'a pas pu être lu : adresse RELAY_PACKAGE_URL absente, délai de 5 secondes dépassé ou contenu illisible. Le reste fonctionne normalement.