Saltar al contenido principal

Introducción rápida a GraphQL

Esta introducción rápida te muestra cómo usar el GraphQL Explorer para:

  • confirmar que tu cuenta funciona con una consulta simple
  • encontrar tu groupId y templateId
  • enviar un documento de prueba con los campos mínimos requeridos
  • hacer polling del informe de tarea para confirmar que la creación del documento se ha completado
  • trasladar el mismo flujo a Node.js, Python o C#

Antes de empezar​

Necesitas:

  • Una cuenta de Legalesign a la que puedas iniciar sesión
  • Al menos un grupo y una plantilla en tu cuenta
  • Una clave API - cómo obtener una clave API

Elegir autenticación​

El Explorer usa tu sesión de Legalesign iniciada. En tu propio código, GraphQL acepta claves API y tokens de acceso OAuth 2.0.

ModoCabeceraMejor para
Clave APIAuthorization: Bearer <api-key>Automatización del lado del servidor y flujos comunes de envío/lectura. La forma más rápida de comenzar
OAuth 2.0Authorization: Bearer <access-token>Apps que construyes para los usuarios de tu organización, donde cada persona inicia sesión como sí misma. Ver Integración de Cliente OAuth 2.0

Ambos dan acceso a un subconjunto soportado del esquema GraphQL. Consulta las operaciones GraphQL soportadas y las insignias de autenticación en las páginas de referencia para ver qué operaciones puedes usar. Los ejemplos en este quickstart funcionan con cualquiera de los dos.

Abrir el GraphQL Explorer​

Ve al GraphQL Explorer.

info

Si has iniciado sesión en Legalesign, la autenticación es automática en el Explorer.

Copia y pega las consultas a continuación en el GraphQL Explorer para comenzar. Más adelante, usarás el mismo graphql en tu propio código.

Consulta tu usuario​

Comienza con una consulta inofensiva para confirmar que el Explorer funciona:

query MyUser {
user {
id
firstName
lastName
email
}
}

Si esto tiene éxito, tu sesión en el Explorer funciona y estás listo para buscar los IDs necesarios para un envío.

Consulta tus grupos​

A continuación, lista los grupos a los que pertenece tu usuario:

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

Copia el id del grupo desde el que quieres enviar. Este es tu groupId.

Consulta las plantillas en ese grupo​

Ahora consulta las plantillas en ese grupo:

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

Usa estas variables:

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

Copia el id de la plantilla que quieres enviar. Este es tu templateId.

Envía tu primer documento​

Pega esta mutación en el Explorer:

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

Agrega estas variables y reemplaza los valores de marcador de posición:

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

Si la entrada es inválida, la mutación devuelve un error de validación inmediatamente.

Si la mutación tiene éxito, devuelve un ID de tarea. Legalesign procesa los envíos de forma asíncrona, por lo que la tarea inicia el trabajo de envío en lugar de esperar a que la entrega se complete.

Haz polling del informe de tarea​

sugerencia

El polling está bien para comenzar. Para producción, puedes cambiar a suscripciones para seguir el progreso del envío en tiempo real en su lugar.

Después de send, usa el ID de tarea devuelto para hacer polling de la consulta task:

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

Usa estas variables:

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

El campo report te permite confirmar cuando la creación del documento ha terminado tras que un envío válido haya iniciado la tarea asíncrona.

Monitorea report.status hasta que alcance un estado terminal:

  • COMPLETED significa que la creación del documento ha terminado
  • FAILED significa que la creación del documento no se completó exitosamente

Mientras la tarea todavía está en ejecución, puedes ver estados intermedios como PENDING o READY.

Para comenzar y prototipar, hacer polling de task es una forma simple de chequear el progreso. Para producción, las actualizaciones en tiempo real se manejan mejor con suscripciones.

Ver:

sugerencia

Usa una dirección de correo electrónico de destinatario real que controles mientras pruebas, para que puedas confirmar que el envío se completó como esperabas.

sugerencia

También puedes extraer groupId y templateId de las URLs de tu panel y editor de formularios: son los únicos códigos alfanuméricos largos en esas URLs.

Pasar al código​

Para acceso programático, primero elige un modo de autenticación y obtiene un token o clave API. Ver Autenticarse con la API.

Autenticarse y hacer una solicitud​

Una vez que tengas tu token o clave API, envía una solicitud POST GraphQL con una cabecera 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);

Próximos pasos​

  1. Si necesitas configuración específica por lenguaje, usa Configuración Node.js o Configuración C#
  2. Si quieres crear tu propia plantilla primero, sigue Subir un archivo como plantilla
  3. Lee Enviar un documento para el ejemplo completo en Node.js
  4. Consulta la referencia de la mutación send