Saltar al contenido principal

Tutorial de inicio rápido

El acceso a la API requiere aprobación

Para usar la API de Legalesign necesitas contactarnos para que se apruebe el uso de la API para tu cuenta.

sugerencia

¿Usando Cursor, Claude u otra herramienta de codificación AI? Conéctala con la documentación de Legalesign para obtener ayuda contextual mientras sigues este tutorial.

En este tutorial completarás las llamadas clave a la API que la mayoría de los desarrolladores necesitan en una integración de firma electrónica: subir un documento y enviarlo para firma.

La API de Legalesign es escalable, versátil y ha sido probada en producción en los sistemas de nuestros clientes durante muchos años. Puedes usarla para un documento simple con un único firmante, o enviar documentos para testigos o aprobaciones, optimizada para lotes, con formularios y más. Puedes integrarla para un solo propósito o incrustarla en tu software para tus clientes - ver integraciones.

La API REST realiza la mayoría de las funciones y es la forma más sencilla para comenzar. Si necesitas más, consulta la interfaz GraphQL. Legalesign es API primero con GraphQL. Puedes usar cualquiera, según prefieras.

Seguiremos estos pasos:

  1. Crear una cuenta + clave API (ver Obtener verificación para acceso API).
  2. Confirmar que las credenciales funcionan y obtener tu ID de equipo.
  3. Subir un documento a través de la aplicación web.
  4. Enviar ese documento para firmar vía API.
  5. Descargarlo después de firmado.
  6. Subir un documento vía API.

La API REST de Legalesign es fácil de usar. La referencia técnica incluye un editor de código. Puedes hacer solicitudes directamente desde la referencia técnica con tu clave API, pero si no, solo copia y pega directamente en tu código.

Imagen del Generador de Código
Figura 1: El editor de código de la API REST.

Bibliotecas cliente

O para la interfaz GraphQL Node.js

sugerencia

Recomendamos que los desarrolladores trabajen directamente con la API en lugar de los SDK. Para ayudar, hay un generador de código de copiar y pegar en la especificación técnica, y tu IA puede producir ejemplos rápidamente usando la especificación OpenAPI. ¿Por qué? La API fuente tiene más funcionalidades que los SDK, de todas formas querrás conocer los endpoints que usas, evitarás sobrecarga de abstracción y dependencias, y—basado en nuestra experiencia—también lo harás más rápido.

1. Crear una cuenta

Ve a registro en legalesign. Usa un correo normal para crear la cuenta (no uses Google), las identidades federadas como Google no funcionarán para la API.

Se te pedirá crear un equipo. Los equipos son la base de Legalesign. Todo el procesamiento de documentos ocurre en un equipo. Necesitas referenciar tu equipo en la mayoría de las llamadas API.

info

Un 'equipo' o un 'grupo' son lo mismo. En la aplicación web hablamos de 'equipos', pero en el esquema API es un grupo.

Contacta soporte para obtener una clave API. Cuéntanos tu caso de uso, experiencia en desarrollo API y algunos detalles para confirmar que eres real (p.ej. detalles de dónde trabajas).

Configuraciones API

Una vez verificado, ve al Panel API. Genera tus credenciales API en la sección Clave API.

Tómate un momento para revisar el Portal de Desarrollo.

Sandbox

En la sección Ambiente, una alerta muestra si estás en modo sandbox o producción.

Sandbox limita dónde puedes enviar tus documentos. Verás un formulario para añadir hasta 5 correos aprobados, añade algunos ahora.

Cuando tu integración esté lista: pasa a modo producción.

sugerencia

Crea un segundo equipo. Usa tu primer equipo para desarrollo y otros para producción. Informa a soporte del nombre de tu equipo de desarrollo para excluirlo de facturación.

Clave API

En la sección Clave API verás los detalles de tus claves API. Solo se muestra la clave en sí cuando creas una.

La sección Inicio rápido contiene ejemplos de copiar y pegar para probar tu clave.

Captura sección Clave API

Webhooks y Registros

Añade webhooks (tus escuchas para eventos Legalesign) y revisa tus registros.

Captura sección Webhooks

2. Una solicitud GET exitosa

La URL raíz siempre es: https://eu-api.legalesign.com/

Comienza con una solicitud GET para confirmar que tus credenciales funcionan. Reemplaza los valores de usuario y secreto en el código abajo.

Curl se usa en los ejemplos, y puedes cambiar entre cURL, Node.js, Python, C# y Go usando las pestañas abajo.

curl -H "Authorization: ApiKey username:secret" -H "Content-Type: application/json" -X GET https://eu-api.legalesign.com/api/v1/group/

Documentación de la API: Referencia API GET group.

Cuando ejecutas la consulta anterior, verás tus grupos devueltos en JSON. Éxito. 👏

Los datos de la respuesta contienen la 'URI de recurso' para tu grupo y se ve como /api/v1/group/:groupId/. Toma nota de esto, lo necesitarás para la mayoría de llamadas API.

sugerencia

Una URI de recurso siempre tendrá el mismo formato. Para un PDF sería '/api/v1/templatepdf/:pdfId/', para un documento enviado será '/api/v1/document/:documentId/'. Nota que todas las URIs terminan con una barra '/', igual que las URLs para tus llamadas API, siempre termina con barra.

Si la solicitud GET falló, verifica que:

  • tu ApiKey esté formateada correctamente (comienza con 'ApiKey'),
  • tengas un header Content-Type para application/json, y
  • tu url termine con una barra.

Consulta también solución de problemas.

3. Subir un documento vía la aplicación web

Para comenzar, subiremos un documento a través de la aplicación web y lo enviaremos mediante la API. Cubriremos cómo subir un documento vía API más adelante.

Ve a la aplicación web y sube tu documento. Agrega un rol de firmante único y arrastra un campo de firma. La página del editor indicará si el documento es 'válido' (un ejemplo de 'inválido' sería si agregas un rol de firmante sin un campo de firma relacionado).

En el editor de formularios, copia el largo ID alfanumérico de la URL, decodifícalo en base64 y descarta las primeras 3 letras (que deberían ser 'tpl'). El resto es un UUID que es tu ID.

En lenguaje REST API, la URI de recurso para este documento es /api/v1/templatepdf/UUID/.

Aprende más acerca de los IDs web y API.

Nuestra nomenclatura es que un documento subido es una 'plantilla' y cuando lo envías creas un 'documento'.

sugerencia

Si deseas archivar una plantilla al enviar el documento, configura 'archive_upon_send' como atributo en la solicitud de subida. Si quieres que la plantilla nunca aparezca y se elimine luego de enviar, ponle el título '[deleted]' - nuestros sistemas de limpieza lo detectarán y lo eliminarán en uno o dos días. También puedes establecer tiempos de retención cortos a nivel de grupo - aprende más.

4. Enviar un documento para firma

Ahora enviaremos esto a través de la API. Recuerda usar un correo en tus emails 'aprobados' en sandbox. Usa las pestañas abajo para obtener la solicitud en tu lenguaje preferido.

curl -H "Authorization: ApiKey [username]:[secret]" -H "Content-Type: application/json" -X POST --data '{ "group": "/api/v1/group/[:groupId]/", "name": "Name of doc", "templatepdf": "/api/v1/templatepdf/UUID/", "signers": [{"firstname": "Joe", "lastname": "Bloggs", "email": "[your@email.com]", "order": 0 }], "do_email": true }' https://eu-api.legalesign.com/api/v1/document/

Actualiza todos los corchetes cuadrados. Referencia API para enviar un documento.

sugerencia

Cuando visites la documentación de referencia para enviar un documento examina bien todos los atributos posibles. Verás muchos que ayudan con las particularidades de una integración: etiquetas para tus propias referencias e IDs (que te retornan en webhooks), un redireccionamiento para firmantes, texto personalizado en el pdf, y más.

Una llamada exitosa retornará código de estado 201.

Obtener el nuevo ID del documento enviado

La parte importante de la respuesta es la cabecera location. Esta contiene el nuevo ID de documento.

sugerencia

Usa atributos de 'tag' del documento y añade tus propias referencias para facilitar la vinculación con tu base de datos.

La cabecera location se verá como /api/v1/status/:documentId/.

La URI 'status' retorna un conjunto breve (y rápido de consultar) de atributos del documento.

Para solicitar todo acerca de un documento usa /api/v1/document/:documentId/.

info

Si una solicitud no es exitosa, el CUERPO de la respuesta generalmente contiene información de error. Si no obtienes un estado de éxito, revisa el CUERPO para texto explicativo. Consulta también solución de problemas.

Aprende más sobre la llamada API Enviar Documento.

5. Descargar el documento firmado

Con el ID de documento enviado que recibiste arriba, realiza una solicitud de descarga PDF en el lenguaje de tu elección:

curl -H "Authorization: ApiKey [username]:[secret]" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/

Referencia API de descarga PDF.

El binario PDF está en el cuerpo de la respuesta. El comando curl '-o' pone el CUERPO de la respuesta directamente en un archivo.

Muchas librerías REST o HTTP tratan los objetos de respuesta HTTP como archivos, en ese caso simplemente guarda tu objeto de respuesta como un archivo normal.

sugerencia

Usa webhooks para ser notificado de un evento de firma y luego descarga el documento. Ver webhooks.

6. Subir un PDF

Haz clic aquí para descargar un PDF con etiquetas de texto de ejemplo, más información sobre campos de formulario PDF a continuación.

Para esta llamada, convierte tu PDF en una cadena codificada en base64. Esto no se hace correctamente dentro del generador de código de la documentación. En su lugar, copia este seudocódigo y tu IA amigable lo convertirá a tu lenguaje preferido:

$data = (
'group': '/api/v1/group/:groupId/',
'title': 'title of pdf',
'pdf_file': base64encode(open('/path/to/file','rb')),
'process_tags': true
)
$headers = (
'Authorization': 'ApiKey username:secret',
'Content-Type': 'application/json'
)
response = httplibrary.post('https://eu-api.legalesign.com/api/v1/templatepdf/', jsonEncode($data), $headers)
assert response.status == 201

pdfId = response.headers['location']

Referencia API de subida PDF.

Como siempre, una respuesta exitosa POST devolverá estatus '201' y el nuevo ID estará en la cabecera 'location' de la respuesta.

assert response.status == 201
pdfId = response.headers['location']

La URI del recurso pdf se verá como /api/v1/templatepdf/:pdfId/.

Enviar el nuevo PDF

Vuelve al código que usaste para enviar tu primer documento y reemplaza el valor templatepdf.

Emite la solicitud nuevamente y listo, enviaste tu PDF para firmar.

Antes de comenzar a codificar, sin embargo, sigue leyendo para aprender más sobre los campos PDF.

¿Y qué hay de los campos PDF?

¿Cómo sabe Legalesign dónde debe firmar la persona en el PDF, o qué secciones cambiar al enviar? La respuesta es que nuestro PDF estaba pre-preparado con etiquetas: ponemos una etiqueta de texto Legalesign dentro del PDF y configuramos 'process_tags' a true en la solicitud de subida PDF.

Descarga un PDF de texto etiquetado de ejemplo.

Las etiquetas de texto son texto especialmente formateado para poner en un PDF. Legalesign analizará el texto en tu archivo, reemplazando las etiquetas con campos de firma y campos de formulario. Para un solo firmante solo necesitas añadir: <<t=signature>>. Legalesign lo identificará y colocará la firma ahí. Aprende sobre etiquetas de texto.

Las etiquetas de texto tienen curva de aprendizaje y requieren ensayo y error. Otros métodos están indicados abajo, pero obtienes toda la capacidad del sistema de formularios Legalesign con esto. Usa la aplicación web para probar etiquetas. Contacta soporte para asistencia y ejemplos.

Aquí hay 4 otras formas de configurar campos:

1. La versión más fácil/rápida. Configura tu PDF usando la aplicación web Legalesign.

Después de subir un PDF irás a la interfaz del editor donde puedes arrastrar y soltar campos de formulario.

Arrastra y suelta una firma, luego toma nota del ID codificado en la dirección web. Esto se verá como algo tipo 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.

Decodifica en base64 este ID y verás que es un UUID prefijado con 'tpl'. La parte UUID (elimina 'tpl') es tu pdfID. Aprende más sobre IDs en Legalesign.

Tu URI recurso API PDF será - /api/v1/templatepdf/:pdfId/.

Pon eso en el atributo 'templatepdf' de la llamada enviar documento.

info

Si planeas enviar este PDF más de una vez, asegúrate que 'Auto archive' esté desactivado. Ver cómo

2. Usa coordenadas x/y para campos.

La forma más simple de empezar con coordenadas x/y es configurar un PDF en la app web y luego hacer una consulta API para esos campos (GET Campos PDF - /api/v1/templatepdf/:pdfId/fields/).

El objeto JSON que obtienes es el mismo esquema JSON que necesitas para crear campos también.

Úsalo como plantilla. Modifica cualquier valor y realiza POST al mismo endpoint (ajustando el ID PDF según corresponda). Endpoint Crear Campo PDF.

3. Incrusta nuestra página de edición PDF. ¡NUEVO!

Usa nuestro componente editor para incrustar nuestro editor PDF directamente en tu propia aplicación. Aprende más sobre el componente editor de documentos.

4. Campos de Formulario PDF ¡NUEVO!

Si tu PDF contiene campos normales de formulario PDF, Legalesign puede importarlos automáticamente.

¡Feliz codificación!

En este tutorial obtuviste credenciales API, consultaste exitosamente tus grupos, enviaste un documento para firmar usando HTML y PDF, y descargaste un documento firmado.

¡Feliz codificación! Estamos aquí para ayudarte, contacta soporte para cualquier asistencia.

sugerencia

Genial, llegaste al final - gracias por leer esto. Nuestra última petición, y consejo, basado en años de experiencia de desarrolladores que integran con esta API, es que tomes un momento para leer todos los atributos en el endpoint crear documento (y también haz clic para ver qué contienen 'signers', 'pdftext' y 'signertext')—es la llamada más importante en tu integración. Crear un documento para firmar.

Próximos pasos: