Inicio Rápido de GraphQL
Este inicio rápido te muestra cómo usar el GraphQL Explorer para:
- confirmar que tu cuenta funciona con una consulta simple
- encontrar tu
groupIdytemplateId - enviar un documento de prueba con los campos mínimos requeridos
- sondear el informe de la tarea para confirmar que la creación del documento ha finalizado
- trasladar el mismo flujo a Node.js, Python o C#
Antes de Comenzar
Necesitas:
- Acceso a la API habilitado para tu cuenta. Si aún no lo tienes, contáctanos.
- Una cuenta Legalesign en la que puedas iniciar sesión
- Al menos un grupo y una plantilla en tu cuenta
Elige Autenticación
El Explorer usa tu sesión de Legalesign iniciada. En tu propio código, GraphQL soporta autenticación SRP para acceso completo al esquema y claves API para un subconjunto soportado.
| Modo | Cobertura | Encabezado | Mejor para |
|---|---|---|---|
| SRP | Esquema completo de GraphQL | Authorization: Bearer <access-token> | Integraciones completas |
| Clave API | Solo subconjunto soportado | Authorization: Bearer <api-key> | Automatización del lado del servidor y flujos comunes de envío/lectura |
Este inicio rápido usa autenticación SRP en los ejemplos de lenguaje porque funciona con el esquema completo de GraphQL. Si usas una clave API del Developer Portal, revisa la referencia GraphQL para claves API y los distintivos de autenticación en las páginas de referencia.
Abre el GraphQL Explorer
Ve al GraphQL Explorer.
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 está funcionando y estás listo para buscar las IDs necesarias 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 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 no es vá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 asincrónica, así que la tarea inicia el trabajo de envío en lugar de esperar a que la entrega se complete.
Sondea el Informe de la Tarea
El sondeo está bien para comenzar. Para producción, puedes cambiar a suscripciones para seguir el progreso del envío en tiempo real.
Después de send, usa el ID de tarea devuelto para sondear 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 cuándo la creación del documento se ha completado luego de que un envío válido inició la tarea asincrónica.
Monitorea report.status hasta que alcance un estado terminal:
COMPLETEDsignifica que la creación del documento ha finalizadoFAILEDsignifica que la creación del documento no se completó exitosamente
Mientras la tarea aún está en ejecución, puedes ver estados intermedios como PENDING o READY.
Para comenzar y hacer prototipos, sondear task es una forma sencilla de verificar el progreso. Para producción, las actualizaciones en tiempo real se manejan mejor con suscripciones.
Consulta:
- consulta task
- TaskReport
- Solución de Problemas de Validación de Envío
- Ejemplos de Suscripciones
- Seguimiento de Tareas de Envío con Suscripciones
Usa una dirección de correo electrónico real que controles mientras haces pruebas, así puedes confirmar que el envío se completó como esperabas.
También puedes extraer groupId y templateId de las URL de tu panel de control y del editor de formularios - son los únicos valores alfanuméricos largos en esas URL.
Pasar a Código
Para acceso programático, primero elige un modo de autenticación y obtiene un token o clave API. Consulta Autenticarse con la API.
Autentícate y Realiza una Solicitud
Una vez que tengas tu token o clave API, envía una solicitud POST GraphQL con un encabezado 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);
Próximos Pasos
- Si necesitas configuración específica del lenguaje, usa Configuración de Node.js o Configuración de C#
- Si quieres crear tu propia plantilla primero, sigue Subir un Archivo como Plantilla
- Lee Enviar un Documento para el ejemplo completo de código en Node.js
- Explora la referencia de mutación send