Crear una clave de API

Las claves de API permiten que otro sistema controle AssinaJá: su ERP creando documentos, o un asistente de IA trabajando a través de la interfaz MCP. Cree una para cada sistema externo o asistente de IA, con los accesos limitados a lo que necesita esa integración.

Configuración → Desarrolladores tiene las pestañas General, Claves de API, Webhooks, Integraciones y Almacenamiento; las dos últimas, solo para el Propietario y el Administrador. General se abre primero, con las direcciones de la API pública y del Servidor MCP y el enlace Abrir la documentación de la API.

Las claves están en Claves de API, y solo el Propietario de la organización las gestiona. Con otro rol, la pestaña se abre pero no muestra las claves.

Una clave por integración

Cree una clave para cada sistema externo que se integre con la API pública (cabecera X-Api-Key). Cada clave puede suspenderse o eliminarse por separado, sin afectar al resto de integraciones.

Esa es la razón de la regla: una clave compartida no se puede revocar sin romper todo lo que la usa. Una clave por sistema permite cortar una integración y dejar las demás funcionando.

Crear una

Elija Nueva clave de API.

1. Nombre: póngale el nombre del sistema que la va a usar, por ejemplo ERP Primavera. Si lo desea, añada una Descripción.
2. Fecha de caducidad: “La clave es válida hasta esta fecha incluida (deja de autenticar al final de ese día).”
3. Accesos: marque solo lo que necesita esta integración. Es obligatorio al menos uno: “Seleccione al menos un acceso: la clave solo puede hacer lo que esté marcado.”
4. Crear clave.

La clave se muestra una sola vez

Copie y guarde esta clave ahora: es la única vez que se muestra y no queda guardada en ningún sitio. Si la pierde, use «Rotar clave» para generar otra con los mismos accesos.

No hay forma de recuperarla después. Junto a Copiar está Copiar como variable de entorno, que copia ASSINAJA_API_KEY= seguido de la clave, lista para pegar en un archivo de configuración. El diálogo solo se cierra después de marcar He guardado la clave en un lugar seguro.

Accesos

Acceso	Qué permite
Plantillas: consultar	Listar y consultar plantillas, incluidos los firmantes y los campos de relleno.
Documentos: consultar	Listar documentos, seguir el progreso de las firmas y descargar archivos e informes.
Documentos: enlaces de firma	Obtener los enlaces de firma de los firmantes pendientes. Quien tenga el enlace firma en nombre del firmante: es una credencial, no una consulta.
Documentos: crear	Crear documentos a partir de plantillas, de DOCX (MailMerge) o de un PDF propio.
Documentos: publicar	Publicar borradores: envía emails a los firmantes y es irreversible.
Documentos: archivar/eliminar	Archivar y eliminar documentos.
Organización: consultar	Ver los datos de la organización, el plan activo y las funcionalidades disponibles.
Analítica: consultar	Leer las métricas agregadas de la organización: uso, embudo de firma y adopción. Nunca por persona. Solo funciona si Configuración → Políticas → Acceso de la IA a la analítica también lo permite.
Webhooks: secreto de firma	Leer y rotar el secreto con el que firmamos los webhooks que enviamos, para que el sistema de destino pueda validar la cabecera X-AssinaJa-Signature. Concédalo solo a quien integre webhooks: con este secreto es posible firmar eventos.
Catálogo de plantillas	Solo en el plan Enterprise; véase más abajo.

Publicar es lo peligroso

Documentos: publicar envía emails a los firmantes y es irreversible. Crear y publicar son accesos separados a propósito, para que una integración pueda preparar borradores para que una persona los revise, sin poder enviarlos nunca. Concédalo solo cuando el sistema realmente deba enviar por sí solo.

Para un asistente de IA, empiece sin el acceso de publicar

En una primera conexión por MCP, marque Plantillas: consultar, Documentos: consultar y Documentos: crear, y deje fuera Documentos: publicar. El asistente lo prepara todo y deja el documento en borrador; enviar sigue siendo una acción suya, en la aplicación. Cuando haya visto cómo se comporta, añada el acceso de publicar si lo desea.

Documentos: consultar no da los enlaces de firma: tienen su propio acceso, Documentos: enlaces de firma, porque quien tiene un enlace firma por el firmante. Concédalo solo a una integración que realmente necesite entregar los enlaces.

Analítica: consultar necesita además la política de la organización; consulte Acceso de la IA a la analítica.

El acceso al catálogo de plantillas

Catálogo de plantillas: servir a otras organizaciones es distinto de los demás:

Permite que otras organizaciones generen documentos a partir del catálogo de plantillas de esta organización (cabecera X-Api-Key-TemplateCatalog). No da ningún otro acceso.

Usa su propia cabecera y no concede nada más. Está Disponible solo en el plan Enterprise.

Una clave con este acceso se comparte con otras organizaciones, por lo que no puede tener además ningún acceso Documentos: la plataforma se niega a guardarla así. Para el catálogo, use una clave aparte.

Plantillas a través de la API pública: dos reglas

Son reglas de la API pública y se aplican a cualquier clave que consulte plantillas:

• El plan que cuenta es el de quien sirve la plantilla, no el de quien llama. Si la organización propietaria del catálogo no tiene Plantillas activas, los cinco endpoints que consumen plantillas responden 423 FEATURE_TEMPLATES_NOT_ENABLED.
• Los borradores no existen para la API. No aparecen en el listado, y pedir el detalle de uno devuelve 404. Publique la plantilla antes de integrarla.

Gestionar claves

La lista muestra Nombre, Clave, Accesos, Validez, Estado, Creada y Último uso; este último indica Nunca para una clave que nunca se ha autenticado. Esa columna es la forma más rápida de detectar una clave que nadie usa.

Acción	Efecto
Editar	Cambiar el nombre, la validez o los accesos
Rotar clave	Generar un secreto nuevo para la misma integración; véase más abajo
Suspender	“Mientras esté suspendida, la clave no autentica hasta que se vuelva a activar.”
Activar	Reactivar una clave suspendida
Eliminar	Definitivo

El Estado de una clave es Activa, Suspendida o Caducada.

Rotar una clave

Cuando pierde una clave, o sospecha que ha quedado expuesta, no necesita eliminarla y volver a configurar la integración desde cero. Rotar clave abre Rotar la clave (“Se genera una clave nueva para esta integración. El nombre, los accesos, la validez y los asistentes de IA conectados se mantienen; solo cambia el secreto.”) y pregunta cuándo La clave actual deja de funcionar:

Opción	Cuándo usarla
Ya: use esta opción si la clave puede haber quedado expuesta	“La integración que usa la clave actual dejará de poder autenticarse en el momento en que la rote.”
Dentro de 1 hora: tiempo para sustituirla en el sistema que la usa	La opción predeterminada: las dos claves funcionan durante una hora.
Dentro de 24 horas	Lo mismo, con un día de margen.

La clave nueva se muestra una sola vez, como al crearla (Clave rotada), con “La clave anterior sigue funcionando hasta el {fecha}. Sustitúyala en el sistema que la usa antes de esa fecha.” o, si eligió «Ya», “La clave anterior ha dejado de funcionar.” En la lista, la clave pasa a mostrar Rotada el {fecha} y, mientras dure la superposición, “La anterior funciona hasta el {fecha}”.

Una clave Caducada no se rota: “Caducada: cree una clave nueva en lugar de rotarla.”

Suspenda antes de eliminar

Suspender es reversible; eliminar no lo es: “es irreversible: la integración que la usa dejará de poder autenticarse de inmediato.” Si sospecha que una clave está comprometida o sin uso, suspéndala y compruebe qué deja de funcionar. Siempre puede reactivarla.

Recibir un aviso cuando ocurre algo

Para que su sistema reciba un aviso cuando le ocurre algo a un documento, en lugar de estar consultando continuamente, consulte Recibir webhooks.

Véase también

• Recibir webhooks
• Roles y permisos: las claves de API y los webhooks son solo del Propietario; Integraciones y Almacenamiento, del Propietario y del Administrador
• Configurar las políticas de la organización