Aller au contenu principal

Démarrage rapide GraphQL

Ce démarrage rapide vous montre comment utiliser l’Explorateur GraphQL pour :

  • confirmer que votre compte fonctionne avec une requête simple
  • trouver votre groupId et templateId
  • envoyer un document test avec les champs minimum requis
  • interroger le rapport de tâche pour confirmer que la création du document est terminée
  • transférer le même flux vers Node.js, Python ou C#

Avant de commencer​

Vous avez besoin de :

  • Un compte Legalesign auquel vous pouvez vous connecter
  • Au moins un groupe et un modèle (template) dans votre compte
  • Une clé API – comment obtenir une clé API

Choisissez l’authentification​

L’Explorateur utilise votre session Legalesign connectée. Dans votre propre code, GraphQL accepte les clés API et les jetons d’accès OAuth 2.0.

ModeEn-têteIdéal pour
Clé APIAuthorization: Bearer <api-key>Automatisation côté serveur et flux d’envoi/lecture courants. La façon la plus rapide de commencer
OAuth 2.0Authorization: Bearer <access-token>Applications que vous créez pour les utilisateurs de votre organisation, où chaque personne se connecte en son nom propre. Voir Intégration client OAuth 2.0

Les deux donnent accès à un sous-ensemble pris en charge du schéma GraphQL. Vérifiez les opérations GraphQL prises en charge et les badges d’authentification sur les pages de référence pour voir quelles opérations vous pouvez utiliser. Les exemples de langage de ce démarrage rapide fonctionnent avec les deux.

Ouvrir l’Explorateur GraphQL​

Allez à l’Explorateur GraphQL.

info

Si vous êtes connecté à Legalesign, l’authentification est automatique dans l’Explorateur.

Copiez et collez les requêtes ci-dessous dans l’Explorateur GraphQL pour commencer. Plus tard, vous utiliserez le même graphql dans votre propre code.

Interrogez votre utilisateur​

Commencez par une requête inoffensive pour confirmer que l’Explorateur fonctionne :

query MyUser {
user {
id
firstName
lastName
email
}
}

Si cela réussit, votre session Explorateur fonctionne et vous êtes prêt à rechercher les identifiants nécessaires pour un envoi.

Interrogez vos groupes​

Ensuite, listez les groupes auxquels votre utilisateur appartient :

query MyGroups {
user {
memberConnection(first: 10) {
groupMembers {
group {
id
name
}
}
}
}
}

Copiez l’id du groupe à partir duquel vous souhaitez envoyer. C’est votre groupId.

Interrogez les modèles de ce groupe​

Interrogez maintenant les modèles dans ce groupe :

query GroupTemplates($groupId: ID!) {
group(id: $groupId) {
id
name
templateConnection(first: 10) {
templates {
id
title
}
}
}
}

Utilisez ces variables :

{
"groupId": "<your-group-id>"
}

Copiez l’id du modèle que vous souhaitez envoyer. C’est votre templateId.

Envoyez votre premier document​

Collez cette mutation dans l’Explorateur :

mutation SendDocument($input: DocumentSendSettingsInput!) {
send(input: $input)
}

Ajoutez ces variables et remplacez les valeurs de l’espace réservé :

{
"input": {
"groupId": "<your-group-id>",
"templateId": "<your-template-id>",
"title": "Test Document",
"recipients": [
{
"firstName": "Jane",
"lastName": "Smith",
"email": "jane@example.com",
"order": 0
}
]
}
}

Si l’entrée est invalide, la mutation retourne immédiatement une erreur de validation.

Si la mutation réussit, elle renvoie un ID de tâche. Legalesign traite les envois de manière asynchrone, donc la tâche démarre le travail d’envoi plutôt que d’attendre que la livraison soit terminée.

Interrogez le rapport de tâche​

astuce

L’interrogation (polling) est acceptable pour commencer. En production, vous pouvez passer à des abonnements pour suivre la progression d’envoi en temps réel.

Après send, utilisez l’ID de tâche retourné pour interroger la requête task :

query GetTask($id: ID!) {
task(id: $id) {
data
report {
status
batchId
documents
errors
}
}
}

Utilisez ces variables :

{
"id": "<task-id-from-send>"
}

Le champ report vous permet de confirmer quand la création du document est terminée après qu’un envoi valide ait démarré la tâche asynchrone.

Surveillez report.status jusqu’à ce qu’il atteigne un état terminal :

  • COMPLETED signifie que la création du document est terminée
  • FAILED signifie que la création du document n’a pas réussi

Pendant que la tâche est en cours, vous pouvez voir des statuts intermédiaires comme PENDING ou READY.

Pour commencer et prototyper, interroger task est une façon simple de vérifier la progression. En production, les mises à jour en temps réel sont mieux gérées avec des abonnements.

Voir :

astuce

Utilisez une adresse email réelle de destinataire que vous contrôlez lors des tests, afin de pouvoir confirmer que l’envoi s’est terminé comme prévu.

astuce

Vous pouvez aussi extraire groupId et templateId depuis les URLs de votre tableau de bord et éditeur de formulaires – ce sont les seules longues chaînes alphanumériques dans ces URLs.

Passez au code​

Pour un accès programmatique, choisissez d’abord un mode d’authentification et obtenez un jeton ou une clé API. Voir Authentifiez-vous avec l’API.

Authentifiez-vous et faites une requête​

Une fois que vous avez votre jeton ou clé API, envoyez une requête POST GraphQL avec un en-tête Authorization :

index.js
const GRAPHQL_ENDPOINT = 'https://graphql.uk.legalesign.com/graphql';
const TOKEN = '<token-or-api-key>';

async function graphql(token, query, variables = {}) {
const response = await fetch(GRAPHQL_ENDPOINT, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({ query, variables })
});

return response.json();
}

async function main() {
const result = await graphql(TOKEN, `
query {
user {
id
firstName
lastName
email
}
}
`);

console.log(JSON.stringify(result, null, 2));
}

main().catch(console.error);

Étapes suivantes​

  1. Si vous avez besoin d’une configuration spécifique à un langage, utilisez Configuration Node.js ou Configuration C#
  2. Si vous voulez créer votre propre modèle (template) d’abord, suivez Téléverser un fichier comme modèle
  3. Lisez Envoyer un document pour l’exemple complet en Node.js
  4. Parcourez la référence de la mutation send