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 è stata completata
• spostare lo stesso flusso in Node.js, Python, o C#

Prima di Iniziare

Hai bisogno di:

• accesso API abilitato per il tuo account. Se non lo hai ancora, contattaci.
• un account Legalesign a cui puoi accedere
• almeno un gruppo e un template nel tuo account

Scegli l’Autenticazione

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

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

Questo avvio rapido usa l’autenticazione SRP negli esempi di linguaggio perché funziona sull’intero schema GraphQL. Se usi una Developer Portal API key, consulta il riferimento GraphQL per API key e i badge di autenticazione nelle pagine di riferimento.

Apri il GraphQL Explorer

Vai al GraphQL Explorer.

informazioni

Se sei autenticato in Legalesign, l’autenticazione è automatica nell’Explorer.

Copia e incolla le query qui sotto nel GraphQL Explorer per iniziare. Più tardi userai lo stesso graphql nel tuo codice.

Query sul 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 Explorer funziona ed sei pronto a cercare gli ID necessari per un invio.

Query sui tuoi Gruppi

Prossimo passo, elenca i gruppi a cui appartieni:

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

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

Query sui Template nel Gruppo

Ora interrogate 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 ritorna immediatamente un errore di validazione.

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

Interroga il Report del Task

suggerimento

Il polling va bene per iniziare. In produzione, puoi passare alle subscription per tracciare il progresso 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 consente di confermare quando la creazione del documento è stata completata dopo che un invio valido ha avviato il task asincrono.

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

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

Durante l’esecuzione del task, potresti vedere stati intermedi come PENDING o READY.

Per iniziare e per prototipazione, fare polling di task è un modo semplice per controllare il progresso. Per la produzione, gli aggiornamenti in tempo reale sono meglio gestiti con le subscription.

Vedi:

• query task
• TaskReport
• Risolvi i Problemi di Validazione Invio
• Esempi di Subscription
• Traccia i Task di Invio con Subscription

suggerimento

Usa un indirizzo email reale di un destinatario che controlli durante il test, così puoi confermare che l’invio è stato completato come previsto.

suggerimento

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

Passa al Codice

Per l’accesso programmato, scegli prima una modalità di autenticazione e ottieni un token o una API key. Vedi Autenticarsi con l’API.

Autenticati e Fai una Richiesta

Una volta ottenuto 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 una configurazione specifica per linguaggio, usa Configurazione Node.js o Configurazione C#
2. Se vuoi prima creare il tuo template, segui Carica un File come Template
3. Leggi Inviare un Documento per l'esempio completo in Node.js
4. Consulta il riferimento mutation send