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
groupIdytemplateId - 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.
| Modo | Cabecera | Mejor para |
|---|---|---|
| Clave API | Authorization: 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.0 | Authorization: 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.
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
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:
COMPLETEDsignifica que la creación del documento ha terminadoFAILEDsignifica 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:
- consulta task
- TaskReport
- Solucionar problemas de validación de envíos
- Ejemplos de suscripciones
- Seguimiento de tareas de envío con suscripciones
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.
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:
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 por lenguaje, usa Configuración Node.js o Configuración C#
- Si quieres crear tu propia plantilla primero, sigue Subir un archivo como plantilla
- Lee Enviar un documento para el ejemplo completo en Node.js
- Consulta la referencia de la mutación send