doclinc — Guide d'intégration API

REST API · JWT HS256 · Authentification 2FA

Guide d'intégration de l'API doclinc

L'API doclinc permet de créer des transactions de transfert de documents sécurisés, de téléverser les fichiers sur des URL signées et de déclencher une notification par courriel avec authentification 2FA côté destinataire.

4 appels API JWT → création → upload → confirmation

SMS / voix / secret méthodes d'authentification du destinataire

URL signée S3 upload direct, expiration configurable

Vue d'ensemble

Périmètre fonctionnel de l'API dans un flux d'envoi de documents sensibles.

Contexte

Ce que fait l'API

Crée et gère des transactions de transfert de documents.
Génère des URL d'upload signées (S3) par document.
Produit une bannière HTML à insérer dans le courriel de l'expéditeur.
Authentifie le destinataire par SMS, appel vocal ou question secrète avant l'accès au document.

Ce que l'API ne fait pas

N'envoie pas de courriel — l'expéditeur utilise sa propre infrastructure SMTP.
Ne gère pas la mise en page du courriel — seule la bannière HTML est fournie.
Ne stocke pas les documents indéfiniment — le lien expire selon linkExpirationDays.

Point clé : l'expéditeur conserve le contrôle total de l'expérience courriel — expéditeur, objet, corps du message. doclinc fournit uniquement la couche sécurisée, le stockage et le parcours d'authentification du destinataire.

Flux en 4 étapes

Chaque envoi de document sensible suit ce processus, du jeton d'autorisation jusqu'à la confirmation.

Vue d'ensemble

Créer le jeton JWT

Générez un JWT signé en HS256, à usage unique, contenant votre tenantId et un identifiant de transaction unique.

Créer la transaction

Envoyez les informations du destinataire et le nom du document. L'API retourne une URL d'upload sécurisée et une bannière HTML.

Téléverser le document

Chargez le fichier sur le canal sécurisé via l'URL temporaire fournie (valide urlTimeToLive secondes).

Confirmer & envoyer

Confirmez la transaction, puis intégrez la bannière HTML dans votre courriel et envoyez-le via votre propre serveur de messagerie.

Prérequis

Identifiants à obtenir auprès de doclinc et informations nécessaires pour chaque destinataire.

Configuration

Identifiant locataire

tenantId

Identifie votre organisation dans le système doclinc. Fourni à la souscription.

Clé API secrète

apiKey

Utilisée pour signer les jetons JWT. À stocker dans un gestionnaire de secrets — jamais dans le code source.

Par destinataire

Adresse courriel
Numéro de cellulaire ou fixe
Code pays ISO (ex. CA pour le Canada)
Méthode d'authentification : sms ou voice

Méthodes d'authentification

Deux options sont disponibles selon votre contexte :

SMS / appel vocal — via /transactions/cells
Secret partagé — via /transactions/secrets (ex. numéro d'employé)

⚠️ Sécurité : Ne stockez jamais votre clé API dans le code source. Utilisez des variables d'environnement ou un gestionnaire de secrets (Azure Key Vault, AWS Secrets Manager, etc.).

Happy path — envoi par SMS

Séquence nominale des appels API pour envoyer un document sensible à un destinataire avec authentification SMS.

Happy path

1 Créer et signer le jeton d'autorisation

Construisez un JWT HS256 à partir de votre tenantId et d'un identifiant unique (jti), encodez-le en Base64 et signez-le avec votre clé API doclinc. Ce jeton est valide au plus 2 heures et doit être recréé pour chaque transaction.

// En-tête JWT
{
  "alg": "HS256",
  "typ": "JWT"
}

// Corps JWT (payload)
{
  "tenantId": "BA686425FBF403B23F3FC4ABE5A98A",
  "jti":      "pay-1773793968",  // préfixe + timestamp Unix
  "iat":      1773793968,         // heure d'émission (GMT)
  "exp":      1773801168          // expiration ≤ iat + 7200 s
}

// Clé API (exemple fictif)
F1F5BCBE71F46FC5E704E53469F5A77A55646F293E6568EA5F978FA6A4629450

// Jeton signé résultant (Base64)
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJ
ZCCI6IkJBNjg2NDI1RkJGNDAzQjIzRjNGQzRBQkU1QTk4QSIs
Imp0aSI6InBheS0xNzczNzkzOTY4IiwiaWF0IjoxNzczNzkzOT
Y4LCJleHAiOjE3NzM4MDExNjh9.63NKWGi7Zt1Xn9kfkeh9ku
02CxZ0w1fUFq3BgPhz5jM

Règles importantes

Le champ jti doit être unique à chaque appel. Utilisez un préfixe fixe suivi du timestamp Unix (ex. "pay-" + Date.now()).
L'expiration (exp) ne peut pas dépasser 2 heures après iat.
Encodez en Base64 et signez avec votre clé API.
Un jeton utilisé une fois est révoqué automatiquement.

2 Créer la transaction

Envoyez les informations du destinataire (courriel, numéro de cellulaire) et le nom du document. L'API retourne une URL d'upload sécurisée unique par document, une bannière HTML à insérer dans votre courriel, ainsi que les commandes de confirmation et d'annulation.

POST /transactions/cells

// En-tête — utiliser le jeton généré à l'étape 1
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

// Corps de la requête
{
  "transactionType":        "send",
  "transactionLanguageRef": "FR", // langue côté expéditeur
  "subjectLanguageRef":     "FR", // langue côté destinataire
  "linkExpirationDays":     14,   // durée de validité du lien
  "isLinkReusable":         true,
  "contacts": [
    {
      "recipientEmail":      "employe@exemple.com",
      "countryCode":         "CA",
      "recipientCell":       "8191234567",
      "authenticationMethod": "sms"
    }
  ],
  "documents": [ // plusieurs documents possibles
    {
      "name": "document-sensible.pdf"
    }
  ]
}

// Réponse de l'API
{
  "sendTransaction": {
    "documents": [
      { // URL unique par document
        "url": "https://uploadDomain/...",
        "urlTimeToLive": 3600
      }
    ]
  },
  // Bannière HTML à ajouter au courriel
  "banner": "<HTML>...</HTML>",
  "commands": [
    {
      "href":   "/transactions/cell/6c89a4fd23ae1224d0b754a551bf755a6c35",
      "method": "POST",
      "rel":    "Confirm" // confirmer avec cet endpoint
    },
    {
      "href":   "/transactions/cell/6c89a4fd23ae1224d0b754a551bf755a6c35",
      "method": "Delete",
      "rel":    "Cancel"
    }
  ]
}

À propos des documents

Un ou plusieurs documents peuvent être inclus dans une même transaction.
Chaque document reçoit sa propre URL d'upload unique.
La bannière HTML remplace les pièces jointes — c'est elle qui contient le lien de téléchargement sécurisé.

À propos des commandes

Les deux commandes permettent de confirmer ou d'annuler l'ensemble de la transaction.
Les documents d'une transaction non confirmée ne sont pas accessibles au destinataire.
Il est possible d'annuler une transaction même après confirmation.

Code	Statut	Description
201	CREATED	Succès — transaction créée
400	BAD REQUEST	JSON invalide ou code pays incorrect
401	UNAUTHORIZED	Jeton d'autorisation invalide
461	INVALID SUB	Abonnement non valide
463	DUPLICATE	Numéro de cellulaire en double dans la liste
470	FEATURE NOT AVAILABLE	Fonctionnalité non incluse dans votre plan
500	SERVER ERROR	Erreur inattendue côté serveur

3 Téléverser le document sensible

Téléversez les documents en utilisant les URLs reçues à l'étape 2, via la bibliothèque HTTP native de votre langage. Utilisez une URL par document, dans le même ordre que celui spécifié dans la requête de transaction.

PUT {url retournée à l'étape 2}

// Exemple cURL
curl -X PUT \
  "https://beta-prod-documenttransfer.s3.ca-central-1.amazonaws.com/..." \
  --upload-file "./document-sensible.pdf"

Durée de validité de l'URL

Le lien d'upload est valide pour la période définie par urlTimeToLive (3 600 secondes dans cet exemple). Utiliser le lien après cette période générera une erreur. Effectuez l'upload sans délai après la création de la transaction.

Limites de taille

Votre abonnement impose une limite sur la taille totale des documents par transaction. Cette limite s'applique à la somme de tous les fichiers téléversés et est vérifiée au moment de la confirmation (étape 4).

Important : le document n'est jamais transmis par courriel. Il est stocké de façon sécurisée et n'est accessible qu'après que le destinataire ait complété l'authentification 2FA depuis la bannière dans votre courriel.

4 Confirmer la transaction

Une fois le document téléversé, confirmez la transaction en utilisant le href dynamique de la commande Confirm reçu à l'étape 2. La confirmation retourne un 200 OK. Ensuite, intégrez la bannière HTML dans le corps de votre courriel et envoyez-le via votre propre infrastructure de messagerie.

POST /transactions/cell/6c89a4fd23ae1224d0b754a551bf755a6c35

// Exemple cURL — utiliser le href dynamique reçu à l'étape 2
curl -X POST \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  "https://api.doclinc.io/transactions/cell/6c89a4fd23ae1224d0b754a551bf755a6c35"

Code	Statut	Description
200	SUCCESS	Transaction confirmée
401	UNAUTHORIZED	Jeton invalide
404	NOT FOUND	Transaction ou document introuvable
465	DOCUMENT SIZE EXCEEDED	La taille totale des documents dépasse la capacité de votre abonnement
500	SERVER ERROR	Erreur inattendue

Alternative path — Consulter un contact existant

L'API enregistre automatiquement les coordonnées du destinataire à chaque transaction. Il est possible de consulter ces informations avant de créer une nouvelle transaction.

Alternative path

Utilisation de `GET /transactions/contacts/{email}`

Cet endpoint retourne la langue préférée, la méthode d'authentification par cellulaire et les informations de secret enregistrées pour un destinataire donné. Ces valeurs peuvent être utilisées directement dans la création de la transaction suivante, notamment le champ secretAnswerRef pour réutiliser un secret existant.

Si le contact n'est pas trouvé, le endpoint retourne 404.

GET /transactions/contacts/{email}

// Exemple
GET /transactions/contacts/email@example.com

// Réponse type
{
  "languageRef": "FR",
  "cellContact": {
    "countryCode":         "CA",
    "cell":                "8191234567",
    "authenticationMethod": "sms"
  },
  "secretContact": { // peut être vide
    "secretQuestion":  "Numéro d'employé ?",
    "secretAnswerRef": "5a7574b08771edfc1ba8c87493dfd01a45424c57"
    // Réponse réutilisée encryptée si elle existe
  }
}

Code	Statut	Description
200	SUCCESS	OK
401	UNAUTHORIZED	Autorisation invalide
404	NOT FOUND	Contact introuvable
461	INVALID SUB	Abonnement invalide
500	SERVER ERROR	Erreur inattendue

Alternative path — Authentification par secret partagé

Alternative à l'authentification par cellulaire : le destinataire répond à une question secrète pour accéder au document.

Alternative path

`secretAnswer` — nouveau secret

Utilisé pour définir un nouveau mot de passe lors de la transaction. La valeur est transmise en clair dans la requête et stockée de façon encryptée par l'API.

`secretAnswerRef` — secret pré-enregistré

Utilisé pour réutiliser un secret existant. La valeur est obtenue via GET /transactions/contacts/{email} — c'est la valeur encryptée déjà stockée.

POST /transactions/secrets

{
  "transactionType":        "send",
  "transactionLanguageRef": "FR",
  "subjectLanguageRef":     "FR",
  "linkExpirationDays":     14,
  "isLinkReusable":         true,
  "secretQuestion":         "Quel est votre numéro d'employé ?",
  "contacts": [
    {
      "recipientEmail": "employe@exemple.com",
      "secretAnswer":   "EMP-00142",  // nouveau secret — OU null si secretAnswerRef fourni
      "secretAnswerRef": null            // ref. encryptée obtenue via GET /contacts
    }
  ],
  "documents": [
    { "name": "document-sensible.pdf" }
  ]
}

Note : soit secretAnswer soit secretAnswerRef est fourni — jamais les deux simultanément. Le reste du flux (upload + confirmation) est identique au happy path. Cette méthode est temporairement limitée à un seul destinataire par transaction.

Référence API complète

Tous les points d'accès disponibles avec leurs codes de réponse.

Référence

G Récupérer les coordonnées d'un destinataire

Retourne les informations d'authentification préenregistrées pour un contact. L'API enregistre automatiquement les coordonnées du destinataire à chaque transaction créée — cet endpoint permet de les consulter avant de créer une nouvelle transaction.

GET /transactions/contacts/{email}

// Exemple
GET /transactions/contacts/email@example.com

// Réponse type
{
  "languageRef": "FR",
  "cellContact": {
    "countryCode":         "CA",
    "cell":                "8191234567",
    "authenticationMethod": "sms"
  },
  "secretContact": { // peut être vide
    "secretQuestion":  "Numéro d'employé ?",
    "secretAnswerRef": "5a7574b08771edfc1ba8c87493dfd01a45424c57"
    // Réponse réutilisée encryptée si elle existe
  }
}

Code	Statut	Description
200	SUCCESS	OK
401	UNAUTHORIZED	Autorisation invalide
404	NOT FOUND	Contact introuvable
461	INVALID SUB	Abonnement invalide
500	SERVER ERROR	Erreur inattendue

1 Créer une transaction — Authentification par cellulaire

Initialise une transaction sécurisée avec authentification par SMS ou appel vocal. Retourne les URLs d'upload pour chaque document ainsi que l'identifiant de la transaction.

POST /transactions/cells

// Corps de la requête
{
  "transactionType":        "send",
  "transactionLanguageRef": "FR",  // langue interface expéditeur
  "subjectLanguageRef":     "FR",  // langue interface destinataire
  "linkExpirationDays":     14,   // durée de validité du lien (jours)
  "isLinkReusable":         true,
  "contacts": [
    {
      "recipientEmail":       "employe@exemple.com",
      "countryCode":          "CA",   // code pays ISO
      "recipientCell":        "8191234567",   // cellulaire pour 2FA
      "authenticationMethod": "sms"  // "sms" ou "voice"
    }
  ],
  "documents": [
    { "name": "document-sensible.pdf" }
  ]
}

// Réponse
{
  "sendTransaction": {
    "documents": [
      {
        "url":           "https://uploadDomain/...",
        "urlTimeToLive": 3600  // secondes
      }
    ]
  },
  "banner":   "Html code to insert in email",
  "commands": [
    { "href": "/transactions/cell/{id}", "method": "POST",   "rel": "Confirm" },
    { "href": "/transactions/cell/{id}", "method": "Delete",  "rel": "Cancel"  }
  ]
}

Code	Statut	Description
201	CREATED	OK
400	BAD REQUEST	JSON invalide ou code pays/cellulaire incorrect
401	UNAUTHORIZED	Autorisation invalide
461	INVALID SUB	Abonnement non valide
463	DUPLICATE	Numéro de cellulaire en double dans la liste
470	FEATURE NOT AVAILABLE	Fonctionnalité non incluse dans votre plan
500	SERVER ERROR	Erreur inattendue

2 Créer une transaction — Authentification par secret partagé

Initialise une transaction sécurisée avec authentification par question secrète. Fournir soit secretAnswer (nouveau secret) soit secretAnswerRef (secret pré-enregistré) — jamais les deux. Limité à un seul destinataire par transaction.

POST /transactions/secrets

// Corps de la requête
{
  "transactionType":        "send",
  "transactionLanguageRef": "FR",  // langue interface expéditeur
  "subjectLanguageRef":     "FR",  // langue interface destinataire
  "linkExpirationDays":     14,
  "isLinkReusable":         true,
  "secretQuestion":         "Quel est votre numéro d'employé ?",
  "contacts": [
    {
      "recipientEmail":  "employe@exemple.com",
      "secretAnswer":   "EMP-00142",  // nouveau secret
      "secretAnswerRef": null            // OU ref. encryptée via GET /contacts
    }
  ],
  "documents": [
    { "name": "document-sensible.pdf" }
  ]
}

// Réponse — même structure que /transactions/cells
{
  "sendTransaction": {
    "documents": [
      {
        "url":           "https://uploadDomain/...",
        "urlTimeToLive": 3600
      }
    ]
  },
  "banner":   "Html code to insert in email",
  "commands": [
    { "href": "/transactions/cell/{id}", "method": "POST",   "rel": "Confirm" },
    { "href": "/transactions/cell/{id}", "method": "Delete",  "rel": "Cancel"  }
  ]
}

Code	Statut	Description
201	CREATED	OK
400	BAD REQUEST	Corps de requête invalide
401	UNAUTHORIZED	Autorisation invalide
461	INVALID SUB	Abonnement non valide
470	FEATURE NOT AVAILABLE	Fonctionnalité non incluse dans votre plan
500	SERVER ERROR	Erreur inattendue

✓ Confirmer une transaction

POST /transactions/{id}

Code	Statut	Description
200	SUCCESS	Transaction confirmée
401	UNAUTHORIZED	Autorisation invalide
404	NOT FOUND	Transaction ou document introuvable
465	DOCUMENT SIZE EXCEEDED	Taille totale des documents dépassée
500	SERVER ERROR	Erreur inattendue

✕ Annuler une transaction

Annule la transaction. Notez qu'il est permis d'annuler une transaction même après confirmation.

DELETE /transactions/{id}

Code	Statut	Description
204	DELETED	Transaction annulée avec succès
401	UNAUTHORIZED	Autorisation invalide
404	NOT FOUND	Identifiant de transaction introuvable
500	SERVER ERROR	Erreur inattendue

Guide d'intégration de l'API doclinc

Vue d'ensemble

Ce que fait l'API

Ce que l'API ne fait pas

Flux en 4 étapes

Créer le jeton JWT

Créer la transaction

Téléverser le document

Confirmer & envoyer

Prérequis

Par destinataire

Méthodes d'authentification

Happy path — envoi par SMS

1 Créer et signer le jeton d'autorisation

Règles importantes

2 Créer la transaction

À propos des documents

À propos des commandes

3 Téléverser le document sensible

Durée de validité de l'URL

Limites de taille

4 Confirmer la transaction

Alternative path — Consulter un contact existant

Utilisation de GET /transactions/contacts/{email}

Alternative path — Authentification par secret partagé

secretAnswer — nouveau secret

secretAnswerRef — secret pré-enregistré

Référence API complète

G Récupérer les coordonnées d'un destinataire

1 Créer une transaction — Authentification par cellulaire

2 Créer une transaction — Authentification par secret partagé

✓ Confirmer une transaction

✕ Annuler une transaction

Privacy Center

Manage cookie preferences

Utilisation de `GET /transactions/contacts/{email}`

`secretAnswer` — nouveau secret

`secretAnswerRef` — secret pré-enregistré