Avvio rapido GraphQL

Questo avvio rapido ti mostra come usare il GraphQL Explorer per:

• confermare che il tuo account funziona con una query semplice
• trovare il tuo groupId e templateId
• inviare un documento di prova con i campi minimi richiesti
• interrogare il report del task per confermare che la creazione del documento è terminata
• spostare lo stesso flusso in Node.js, Python o C#

Prima di iniziare

Ti serve:

• Un account Legalesign a cui puoi accedere
• Almeno un gruppo e un template nel tuo account
• Una API key - come ottenere una API key

Scegli l'autenticazione

L'Explorer usa la tua sessione Legalesign attiva. Nel tuo codice, GraphQL supporta l'autenticazione SRP per l'accesso completo allo schema e le API key per un sottoinsieme supportato.

Modalità	Copertura	Header	Ideale per
SRP	Schema GraphQL completo	Authorization: Bearer <access-token>	Integrazioni complete
API Key	Solo sottoinsieme supportato	Authorization: Bearer <api-key>	Automazioni server-side e flussi comuni di invio/lettura

Questo avvio rapido utilizza l'autenticazione SRP negli esempi di linguaggio perché funziona su tutto lo schema GraphQL. Se usi una API key del Developer Portal, consulta la riferimento GraphQL per API key e i badge di autenticazione sulle pagine di riferimento.

Apri il GraphQL Explorer

Vai al GraphQL Explorer.

informazioni

Se sei loggato in Legalesign, l'autenticazione è automatica nell'Explorer.

Copia e incolla le query qui sotto nel GraphQL Explorer per iniziare. In seguito, userai lo stesso graphql nel tuo codice.

Interroga il tuo utente

Inizia con una query innocua per confermare che l'Explorer funziona:

query MyUser {
  user {
    id
    firstName
    lastName
    email
  }
}

Se ha successo, la tua sessione nell'Explorer funziona e sei pronto a cercare gli ID necessari per un invio.

Interroga i tuoi gruppi

Ora, elenca i gruppi a cui appartiene il tuo utente:

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

Copia l'id del gruppo da cui vuoi inviare. Questo è il tuo groupId.

Interroga i template di quel gruppo

Adesso interroga i template in quel gruppo:

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

Usa queste variabili:

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

Copia l'id del template che vuoi inviare. Questo è il tuo templateId.

Invia il tuo primo documento

Incolla questa mutation nell'Explorer:

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

Aggiungi queste variabili e sostituisci i valori segnaposto:

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

Se l'input non è valido, la mutation restituisce immediatamente un errore di validazione.

Se la mutation ha successo, restituisce un ID task. Legalesign elabora gli invii in modo asincrono, quindi il task avvia il lavoro di invio senza attendere il completamento della consegna.

Interroga il report del task

suggerimento

L'interrogazione a intervalli è ok per iniziare. In produzione, puoi passare alle subscription per tracciare i progressi dell'invio in tempo reale.

Dopo send, usa l'ID task restituito per interrogare la query task:

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

Usa queste variabili:

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

Il campo report ti permette di confermare quando la creazione del documento è terminata dopo che un invio valido ha avviato il task asincrono.

Monitora report.status finché non raggiunge uno stato terminale:

• COMPLETED significa che la creazione del documento è terminata
• FAILED significa che la creazione del documento non è terminata con successo

Mentre il task è ancora in esecuzione, potresti vedere stati intermedi come PENDING o READY.

Per iniziare e prototipare, interrogare task è un modo semplice per verificare i progressi. In produzione, gli aggiornamenti in tempo reale sono meglio gestiti con le subscription.

Consulta:

• query task
• TaskReport
• Risolvi problemi di validazione invii
• Esempi di subscription
• Traccia i task di invio con subscription

suggerimento

Usa un vero indirizzo email destinatario che controlli durante i test, così puoi confermare che l'invio è stato completato correttamente.

suggerimento

Puoi anche estrarre groupId e templateId dagli URL della dashboard e dell'editor di moduli - sono gli unici valori lunghi alfanumerici in quegli URL.

Passa al codice

Per l'accesso programmatico, prima scegli una modalità di autenticazione e ottieni un token o una API key. Vedi Autenticazione con l'API.

Autenticati e invia una richiesta

Una volta che hai il token o la API key, invia una richiesta POST GraphQL con un header 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);

Passi successivi

1. Se ti serve un setup specifico per linguaggio, usa Setup Node.js o Setup C#
2. Se vuoi creare prima un template, segui Carica un file come template
3. Leggi Invia un documento per l'esempio completo in Node.js
4. Consulta il riferimento mutation send