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
groupIdettemplateId - 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.
| Mode | En-tête | Idéal pour |
|---|---|---|
| Clé API | Authorization: Bearer <api-key> | Automatisation côté serveur et flux d’envoi/lecture courants. La façon la plus rapide de commencer |
| OAuth 2.0 | Authorization: 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.
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
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 :
COMPLETEDsignifie que la création du document est terminéeFAILEDsignifie 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 :
- requête task
- TaskReport
- Dépannage de la validation d’envoi
- Exemples d’abonnements
- Suivre les tâches d’envoi avec des abonnements
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.
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 :
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
- Si vous avez besoin d’une configuration spécifique à un langage, utilisez Configuration Node.js ou Configuration C#
- Si vous voulez créer votre propre modèle (template) d’abord, suivez Téléverser un fichier comme modèle
- Lisez Envoyer un document pour l’exemple complet en Node.js
- Parcourez la référence de la mutation send