Saltar al contenido principal

Guía de inicio rápido

Esta guía le llevará paso a paso por el proceso de integrar Signatura en su aplicación. La API de Signatura permite incorporar firmas electrónicas con validación de identidad de manera sencilla y rápida.

En esta guía, aprenderá a:

  1. Obtener una clave para interactuar con la API de Signatura
  2. Cargar un documento para firmar con diferentes validaciones
  3. Recibir notificaciones en tiempo real a través de webhooks

1. Obtener una clave de API​

El primer paso para interactuar con la API de Signatura es obtener una clave de API. Para ello, debe iniciar sesión con su usuario en connect.signatura.co y dirigirse a la sección Configuración de cuenta ubicada en el menú de usuario de la esquina superior derecha.

Dentro de la sección de configuración, haga clic en el ítem Claves de API del menú ubicado en la barra lateral izquierda. Si no ve esta sección, es posible que no tenga permisos para acceder a la API. Póngase en contacto con el administrador de su cuenta para obtener acceso.

Una vez en la sección de Claves de API, verá una lista de las claves de API existentes. Si es necesario, haga clic en el botón que dice Crear clave en la parte superior derecha e introduzca un nombre para su nueva clave. Recuerde que puede usar múltiples claves para diferentes entornos o aplicaciones.

Una vez creada, puede ver su nueva clave de API en la lista de claves. Su clave debería verse más o menos así:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2NTk2MzcwNjcsImp0aSI6Ilc0QmlzSmdkTUlLaWl5Y3d5SE8rZGlWYWFreHlnYnl6ajJxTWplZmRXSGM9Iiwic3ViIjoiZmVkZXJpY29ib25kIn0.8A7DfculLHfpEhovvJqfCexn22K-S_3cHJvrKTi6Rqw

Recomendamos que use un almacenamiento seguro para sus claves que no las comparta con terceros bajo ninguna circunstancia. Cuando realice una solicitud a la API de Signatura, deberá incluir su clave de API en la cabecera de la siguiente manera:

Authorization: Bearer <apikey>

Para comprobar que su clave está funcionado correctamente, puede utilizar el siguiente comando:

curl -X GET https://connect.signatura.co/api/v2/documents -H "Authorization: Bearer <apikey>"

2. Cargar un documento​

Para cargar un documento a firmar utilizaremos el endpoint POST /api/v2/documents/create. Los documentos en Signatura requieren como mínimo de los siguientes elementos:

  • Título: puede ser visualizado por los firmantes, por lo que es importante que sea descriptivo y claro.
  • Archivo PDF: recomendamos que no supere los 2MB y que no contenga errores de formato.
  • Configuración de los firmantes: definida por el campo signatures, que contiene la lista de firmantes y las validaciones e invitaciones correspondientes.

Ejemplo de un documento con invitación por mail​

A continuación encontrará un ejemplo de cómo crear un documento con las siguientes características:

  • El firmante debe validar email y teléfono
  • Se enviará una invitación a firmar al correo indicado con un enlace que verifica su correo
  • Deberá validar su teléfono mediante un código de verificación enviado por SMS, pudiendo utilizar cualquier número de teléfono
POST /api/v2/documents/create
Content-Type: application/json
Authorization: Bearer <apikey>

{
  "title": "Mi documento a firmar",
  "file_content": "<base64-encoded-file>",
  "signatures": [
    {
      "validations": {"EM": "juan@example.com", "PH": null},
      "invite_channel": ["EM"]
    }
  ]
}

El campo file_content debe contener el contenido del archivo codificado en base64 de acuerdo al RFC 4648.

Ejemplo de un documento con invitación por URL​

En este caso, el firmante realizará validación biométrica y utilizará el enlace que generará Signatura en la respuesta para firmar el documento. Comparta esta URL con el firmante.

POST /api/v2/documents/create
Content-Type: application/json
Authorization: Bearer <apikey>

{
  "title": "Mi documento a firmar",
  "file_content": "<base64-encoded-file>",
  "signatures": [
    {
      "validations": {"BI": null},
    }
  ]
}

Para más información sobre cómo crear un documento, consulte la referencia de la API.

Para consultar el estado de un documento, incluyendo información de los firmantes y sus validaciones, puede hacerlo utilizando el endpoint GET /api/v2/documents/{id}, donde {id} es el identificador del documento devuelto por Signatura al momento de creación. Recuerde conservar este identificador en caso de necesitar reconciliar el estado del documento con su sistema.

Consejo

Evite realizar consultas periódicas a este endpoint para conocer el estado de sus documentos. En su lugar, utilice webhooks para recibir notificaciones en tiempo real sobre los eventos en su cuenta.

3. Recibir notificaciones por webhook​

Los webhooks le permiten recibir notificaciones en tiempo real sobre eventos en su cuenta de Signatura. Por ejemplo, puede configurar un webhook para recibir una notificación cada vez que un firmante haya firmado un documento.

De esta manera, no es necesario que esté consultando periódicamente el estado de los documento pendientes. Tenga en cuenta que los firmantes pueden demorarse horas o incluso días en firmar un documento, o quizás abandonan el proceso completamente. Si el conjunto de documentos pendientes crece sin límites, consumirá recursos innecesarios en su aplicación y es posible que termine excediendo los límites de la API de Signatura.

info

Para más información sobre los límites de frecuencia aplicables a la API de Signatura, consulte la documentación de límites de frecuencia.

Para configurar un webhook, debe iniciar sesión en connect.signatura.co y dirigirse a la sección API > Webhooks desde el menú que se encuentra en la barra lateral izquierda. Allí encontrará los webhooks que tiene configurados y podrá agregar uno nuevo.

Asegúrese de que la URL de su webhook sea accesible por internet, no esté bloqueada por un firewall y que responda con un código de estado 200.

Consejo

Si necesita conocer el estado de la firma inmediatamente después de que un firmante haya firmado un documento, no dude en combinar los webhooks con la consulta de documentos a través de la API.

Ejemplo de código en Python para procesar webhooks​

from flask import Flask, request

app = Flask(__name__)

@app.post("/webhooks/signatura")
def signatura_webhook():
    data = request.json

    if data["notification_action"] == "DS":  # firma completada
        document_id = data["document_id"]
        signature_id = data["signature_id"]
        # procesar documento

    if data["notification_action"] == "SD":  # firma rechazada
        document_id = data["document_id"]
        signature_id = data["signature_id"]
        # procesar documento

    elif data["notification_action"] == "DC":  # documento firmado completamente
        document_id = data["document_id"]
        # procesar documento

    return "Success", 200

Los diferentes eventos que puedes recibir en tu webhook se encuentran en la referencia de la API. Signatura puede agregar nuevos eventos en el futuro, por lo que es importante que tu aplicación esté preparada para manejar eventos desconocidos.

Es importante tener en cuenta las siguientes cuestiones al implementar los webhooks en tu aplicación:

Reintentos​

Si tu aplicación no responde con un código de estado 200, Signatura considerará que el webhook no fue entregado y reintentará el envío una cierta cantidad de veces. Si el webhook sigue fallando después de varios intentos, Signatura dejará de intentar enviarlo. Esto además implica que el orden de los eventos no está garantizado.

Eventos duplicados y fuera de orden​

Problemas en la red pueden causar que recibas un mismo evento varias veces, por lo que tu aplicación debe ser capaz de manejar eventos duplicados o fuera de orden. Para evitar problemas, usa el webhook como un indicio de que hubo un cambio y consulta el estado actualizado a través de la API. Sólo ejecuta los triggers de negocio correspondiente cuando el estado no coincida con el estado anterior.

Ha llegado al final de la guía de inicio rápido. Al completar esta guía, debería contar con la información básica necesario para desarrollar una integración exitosa con Signatura. Si desea explorar en detalle otros temas, consulte la documentación disponible en la barra lateral izquierda.

Si tiene alguna pregunta o necesita ayuda, no dude en ponerse en contacto con nuestro equipo de soporte a través de la dirección de correo help@signatura.co.