Referencia de waafir-esign
El servidor waafir-esign expone el servicio propio de firma electrónica
de Waafir a un cliente de IA conectado: crear un sobre sobre un archivo de su
organización, hacer que sus firmantes firmen (o rechacen), seguir el estado y
descargar el PDF firmado. Las firmas son AES (PAdES) según eIDAS,
generadas por el motor de firma propio de Waafir; cada firma registra el
consentimiento del firmante (dirección IP, agente de usuario, marca de tiempo)
en un registro de auditoría a prueba de manipulaciones, y el PDF firmado se
almacena como la versión más reciente del archivo de origen.
Conexión: https://app.waafir.io/api/mcp/waafir, o el servidor de área
https://app.waafir.io/api/mcp/waafir-esign — consulte
Configuración. Los nombres de las
herramientas son los mismos en ambos. Las herramientas de lectura requieren el
alcance read, en una conexión creada al iniciar sesión o en un
PAT; crear, enviar,
rechazar, revisar firmantes y anular requieren el alcance write.
Firmar requiere write y el permiso para firmar documentos: aprobado en
la pantalla de consentimiento para una conexión, o activado al crear un token
(consulte
Permitir que un token firme documentos);
sin él, esign_sign se oculta en la lista de herramientas y se rechaza si se
llama. Una conexión o un token restringido a salas de datos concretas solo
puede trabajar con sobres sobre archivos de esas salas de datos — el mismo
límite que aplican las herramientas de sala de datos.
Una cuota mensual de sobres
La firma electrónica se mide por sobre: un documento o trabajo de firma cuenta una vez, tenga los firmantes que tenga. Este servidor MCP y la superficie de firma de la aplicación consumen un único fondo mensual compartido:
- El acceso requiere el complemento E-Signatures o una suscripción activa
a Waafir. Sin ninguno de los dos, toda solicitud a
waafir-esignse rechaza en la entrada con HTTP 402, antes de que se ejecute ninguna herramienta: un rechazo de capa 1.ADDON_NOT_PURCHASEDaparece dentro del textomessagede esa respuesta; no es un campo legible por máquina independiente, así que decida según el estado 402, no según un código. Enwaafir, en cambio, las herramientasesign_se ocultan en la lista de herramientas, y una llamada a una de ellas se rechaza en la capa 2 conQUOTA_EXCEEDEDy un mensaje que nombra la herramienta, que también incluyeADDON_NOT_PURCHASED. - Su plan incluye un paquete mensual de sobres: Starter 10, Premium 50, Enterprise 50 por puesto activo (mes natural).
- Cada unidad adquirida del complemento E-Signatures añade 100 sobres al mes además del paquete de su plan; las unidades se acumulan en cualquier plan.
- La cuota es un límite estricto: cuando envía un sobre al llegar al
límite, el envío se rechaza con el código
QUOTA_EXCEEDED, invitándole a comprar más unidades o a mejorar su plan; nunca se cobra nada por sobre de forma automática. El texto del mensaje también nombra un token internoESIGN_QUOTA_EXCEEDED; eso es texto descriptivo, así que decida segúnerror.code, que esQUOTA_EXCEEDED. Una creación consend: trueque alcanza el límite deja igualmente el borrador creado: envíelo cuando tenga margen en lugar de volver a crearlo.
La cuota se consume cuando se envía un sobre (se abre para firma), no por
firma, de modo que firmar y rechazar nunca consumen cuota. Las lecturas y las
descargas tampoco. Compruebe el margen en cualquier momento con
esign_quota_status.
Su propio NDA, firmado electrónicamente
Cuando su organización carga su propio NDA (Inversores → NDA → Carga tu propio NDA, consulte Personalización), cada inversor lo firma en el firmador de Waafir: un inversor con sesión iniciada elige Firmar el NDA y el documento se abre en una pestaña nueva; un visitante de un enlace para compartir recibe el enlace de firma por correo electrónico en la dirección que introdujo. Estos sobres de NDA no cuentan para la cuota mensual, y la plantilla del NDA en sí no puede enviarse como un sobre normal.
Herramientas
Las claves de argumentos y resultados de este servidor son
snake_case— la misma convención que usan todos los demás servidores MCP de Waafir.file_id,envelope_id,signing_mode,field_layout,consent_affirmed,confirm_send,download_url,has_more.
Cambio incompatible —
waafir-esignantes aceptaba argumentos encamelCase.fileId,envelopeId,signingMode,fieldLayoutyconsentAffirmedya no se aceptan; cada uno tiene ahora una grafíasnake_case, indicada en las tablas siguientes.confirm_sendno cambia: ya era snake_case.Cuando la grafía retirada era un argumento obligatorio, se rechaza, no se acepta en silencio: una llamada que sigue enviando
fileIdaesign_create_envelopefalla en la validación de argumentos, que nombrafile_idcomo la clave que falta. Cuando era opcional, se descarta en silencio, exactamente como cualquier otra clave no reconocida — consulte los dos modos de fallo siguientes. Actualice sus llamadas con las grafías de esta página.
Una clave mal escrita falla de una de dos maneras, y una de ellas es silenciosa. Un argumento no reconocido se descarta, nunca se rechaza, por lo que lo que ocurre a continuación depende únicamente de si la clave que quería usar era obligatoria:
-
Clave obligatoria → la llamada se rechaza. Simplemente falta el argumento. Este es el caso visible y seguro, y cubre
esign_create_envelope(file_id),esign_get_envelope,esign_sign(envelope_idyconsent_affirmed),esign_decline,esign_void_envelope,esign_revise_signers(envelope_idysignatories) yesign_download_signed— incluidas todas las grafías camelCase retiradas de esas claves.No lleva ningún
error.code. Los argumentos se validan contra el esquema publicado de la herramienta antes de que esta se ejecute, por lo que una clave obligatoria que falta — o una de tipo incorrecto — vuelve como un resultado de error que genera el propio servidor: la respuesta se marca como error y su texto nombra el argumento problemático, pero no se ejecutó ninguna herramienta, así que nada rellena el campoerror.codede la capa 2. No decida segúnINVALID_ARGUMENTante un fallo de forma de los argumentos: lea el mensaje.INVALID_ARGUMENTsigue siendo lo que recibe ante un rechazo que una herramienta emite después de empezar, como unconfirm_tokenmal formado. -
Clave opcional → la llamada tiene éxito y hace otra cosa. Recibe un
200y un resultado bien formado que responde a otra pregunta:- Los filtros de
esign_list_envelopesson opcionales, así que unfileIdsuelto se descarta y recibe la lista sin filtrar de todos los sobres que el token puede ver: un superconjunto devuelto como si fuera la respuesta filtrada. - En
esign_create_envelope, unsigningMode: "sequential"descartado deja el sobre en su modo predeterminadoparallel. Al enviarlo, se manda entonces una solicitud de firma jurídicamente vinculante a todos los firmantes a la vez, que es precisamente lo que pedirsequentialdebía evitar.fieldLayoutse descarta del mismo modo.
- Los filtros de
Como una clave opcional descartada no puede avisar de sí misma, compruebe que el resultado refleja lo que pidió: el sobre creado indica su propio
signing_mode, y esign_list_envelopes solo se filtra si escribió el filtro
correctamente.
esign_create_envelope (escritura)
Crea un sobre sobre un archivo de su organización, indicando sus firmantes. Se acepta cualquier dirección de correo electrónico: un firmante no necesita una cuenta de Waafir. Cómo se contacta a cada uno se decide cuando se envía el sobre, según si esa dirección ya tiene una cuenta de Waafir: el titular de una cuenta firma en sesión (una notificación en la aplicación más un correo electrónico con un enlace a la pantalla de firma), y a todos los demás se les envía por correo electrónico un enlace de firma de invitado. La prueba es la existencia de la cuenta, no la pertenencia a su organización, por lo que un firmante que pertenece a otra organización también firma en sesión. Cada firmante pendiente recibe exactamente una de las dos opciones: nunca ambas, nunca ninguna.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
file_id | string (UUID) | sí | El archivo que se va a firmar. Debe pertenecer a su organización. |
signatories | array | sí | De 1 a 50 elementos { "email": string, "name"?: string }. Se acepta cualquier correo electrónico: los firmantes no necesitan ser usuarios de Waafir; las direcciones externas reciben un enlace de firma de invitado. |
transaction_id | string (UUID) | no | Obsoleto e ignorado. Se acepta para que las integraciones existentes sigan funcionando; deje de enviarlo. |
send | boolean | no | Si es true, abre el sobre para firma inmediatamente, en dos pasos (ver más abajo). Requiere un token con Enviar a personas fuera de tu organización. |
confirm_token | string | no | Solo con send: true: el token de la llamada de vista previa. |
confirm_send | boolean | no | Obsoleto e ignorado: send: true ahora usa confirm_token. |
signing_mode | "parallel" | "sequential" | no | Orden de firma. "parallel" es el valor predeterminado: los firmantes pueden firmar en cualquier orden, y el envío manda el correo a todos a la vez. "sequential" envía el correo solo al primero, y habilita a cada firmante una vez que todos los anteriores han firmado; firmar fuera de turno se rechaza con CONFLICT. Omitirlo — o escribirlo mal como signingMode — equivale a "parallel". |
field_layout | array | no | Sustitución del diseño de colocación de campos; omítalo para usar el diseño predeterminado. |
observers | array | no | Hasta 20 observadores (cc) con la forma { "email": string, "name"?: string }. Un observador recibe por correo electrónico una copia de la solicitud de firma y de cada recordatorio, con un enlace de solo lectura para seguir su estado. Los observadores nunca firman y no reciben la copia firmada. |
send: true funciona en dos pasos, porque el envío despacha correos de
solicitud de firma reales y jurídicamente vinculantes a todas las direcciones
indicadas en el momento en que tiene éxito. La primera llamada no crea ni
envía nada: devuelve una vista previa (los firmantes, el número de
observadores y su cuota) más un confirm_token. Vuelva a llamar con
argumentos idénticos y el token para crear y enviar. Un token sirve una vez y
vence a los pocos minutos. Sin el permiso, send: true se rechaza con
FORBIDDEN (GRANT_REQUIRED); cree el sobre sin send y envíelo desde
Waafir.
esign_revise_signers sigue los mismos dos pasos, y requiere el mismo
permiso, cuando enviaría un correo a alguien: un firmante u observador nuevo
en un sobre ya enviado.
Devuelve el sobre. Sus campos son exactamente id, file_id, status,
signing_mode, created_by, signed_output_name,
signed_output_version_count, field_layout, packet_page_count y
expires_at: el resultado es una lista permitida asignada a mano, por lo que
no se transmite nada más. Las marcas de tiempo son cadenas ISO-8601.
Un sobre en borrador debe enviarse antes de que nadie pueda firmar. El envío consume un sobre de su cuota mensual: en el límite, un send devuelve
QUOTA_EXCEEDED y el sobre queda como borrador que puede enviar más tarde. Un
sobre enviado por error puede retirarse con
esign_void_envelope.
Un archivo que aún se está comprobando. Si el archivo es una subida o
versión nueva que Waafir aún no ha terminado de comprobar, la llamada responde
UNAVAILABLE con error.reason: "ACTIVATION_PENDING" y el mensaje
This file is still being checked. Try again shortly. No se crea nada; vuelva a
llamar tras una breve espera.
esign_list_envelopes (lectura)
Lista los sobres de su organización, de más reciente a más antiguo, con los
firmantes y los estados de cada sobre. Filtro opcional: file_id.
(transaction_id está obsoleto y se ignora.) Como son opcionales, una grafía
camelCase retirada se descarta en silencio y la llamada devuelve la lista
sin filtrar en lugar de un error; consulte la nota sobre las claves más
arriba.
Paginado — limit (opcional, 1–100, por defecto 25) y offset (opcional,
por defecto 0) deben ser números; un valor de otro tipo falla la
validación de argumentos como cualquier otro tipo incorrecto. Un número fuera
de rango se ajusta, no se rechaza: limit: 10000 pasa a ser 100,
offset: -2 pasa a ser 0. Devuelve:
{ envelopes: [...],
pagination: { limit, offset, count, has_more, next_offset, total },
filtered_by_pat_scope: boolean }Use has_more para distinguir un resultado recortado de uno completo, y siga
next_offset hasta que sea null; nunca deduzca que hay más páginas a partir
de count === limit. total es el número de sobres que este token puede ver.
filtered_by_pat_scope es true cuando el token está restringido a salas de
datos concretas y esa lista permitida limitó el resultado: la ventana se
aplica después del filtro, por lo que las páginas siempre son exactas. Es
deliberadamente un booleano y no un recuento de sobres ocultos: indicar
cuántos se han retenido revelaría la existencia y el volumen de sobres que el
token no puede ver.
esign_get_envelope (lectura)
Obtiene un sobre con sus firmantes y sus estados
(pending / signed / declined). Entrada: envelope_id. Además de los
campos de la herramienta de creación indicados arriba, el sobre incluye
created_at, updated_at y signatories (cada uno
{ id, email, name, status, signed_at }).
esign_sign (escritura)
Firma su propio puesto de firmante pendiente: el puesto cuyo correo electrónico coincide con el del usuario propietario del token. Firmar no consume cuota (el sobre ya se midió al enviarse). Requiere un token con Firmar documentos activado.
La firma requiere dos llamadas, para que su asistente le muestre lo que va a firmar antes de firmar nada:
- Vista previa. Llame sin
confirm_token. No se firma nada. El resultado esdry_run: truecon el sobre, losdocumentsen orden, un únicodocument_hashque los cubre todos, elsigner, losfieldsque proporcionó, la declaración de consentimiento, unconfirm_tokeny suexpires_at. - Confirmación. Una vez que la persona está de acuerdo, vuelva a llamar
con argumentos idénticos más ese
confirm_token. Esta llamada firma.
Un confirm_token sirve una vez, solo para este token y estos argumentos, y
vence a los cinco minutos. Si entretanto cambian el sobre, sus documentos, su
lugar en el orden de firma o sus campos, la confirmación se rechaza y debe
volver a obtener la vista previa.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
envelope_id | string (UUID) | sí | El sobre que se va a firmar. |
consent_affirmed | boolean | sí | Debe ser literalmente true: una afirmación explícita de la declaración de consentimiento. No hay valor predeterminado; omitirlo, o pasar false, hace fallar la llamada en el límite del protocolo. |
fields | object | no | Valores de relleno indexados por la etiqueta del campo; el nombre y la fecha se rellenan por defecto si se omiten. |
confirm_token | string | no | Omítalo para obtener la vista previa. Pase el token que devolvió la vista previa para firmar. |
La confirmación devuelve { envelope }, el sobre con la misma forma de lista
permitida que devuelve esign_create_envelope.
Errores que puede ver: FORBIDDEN si usted no es un firmante pendiente
del sobre, CONFLICT si el sobre no está abierto para firma — o, en un
sobre sequential, si un firmante anterior aún no ha firmado. Son valores de
error.code dentro del contenido, no estados HTTP — consulte
Configuración.
La confirmación en dos pasos añade estos rechazos, cada uno con su
(code: …) en el mensaje:
error.code | code: | Qué hacer |
|---|---|---|
FORBIDDEN | GRANT_REQUIRED | El token no puede firmar. Cree uno nuevo con Firmar documentos activado. |
INVALID_ARGUMENT | CONFIRM_TOKEN_MALFORMED | Vuelva a llamar sin confirm_token para obtener uno. |
CONFLICT | CONFIRM_TOKEN_INVALID | El token venció, ya se usó o pertenece a otro token. Vuelva a obtener la vista previa. |
CONFLICT | CONFIRM_ARGS_MISMATCH | Los argumentos difieren de los de la vista previa. Vuelva a obtener la vista previa. |
CONFLICT | CONFIRM_STATE_CHANGED | El sobre cambió desde la vista previa. Vuelva a obtener la vista previa y muéstresela a la persona. |
CONFLICT | DOCUMENT_NOT_PINNED | El sobre se envió antes de que existiera la fijación de documentos. Fírmelo en Waafir desde el correo de firma. |
UNAVAILABLE | CONFIRM_UNAVAILABLE | La confirmación no está disponible momentáneamente. Inténtelo de nuevo en breve. |
Si el diseño del sobre tiene campos obligatorios y fields no los
proporciona, la llamada se rechaza con INVALID_ARGUMENT y un mensaje que
contiene (code: MISSING_REQUIRED_FIELDS). El mensaje no nombra las etiquetas
que faltan; la pantalla de firma de la aplicación sí. Rellénelos y vuelva a
llamar.
esign_decline (escritura)
Rechaza su propio puesto pendiente (definitivo: el sobre pasa a declined).
Entrada: envelope_id. Devuelve { id, status: "declined" }. No consume
cuota.
esign_void_envelope (escritura)
Retira un sobre enviado por error. Es la solución cuando salió una solicitud de firma que no debía salir: el sobre deja de aceptar firmas, todos los enlaces de firma de invitado pendientes se invalidan de inmediato, y los firmantes pendientes ya no pueden actuar.
Entrada: envelope_id. Devuelve el sobre anulado, con la misma forma de lista
permitida que devuelve esign_create_envelope.
- Definitivo. Un sobre anulado no puede volver a enviarse: cree uno nuevo en su lugar.
- Las firmas ya registradas y el registro de auditoría completo se conservan; anular no borra lo que ya se firmó.
- Solo es válido mientras el sobre está en
draft,sentopartially_signed. Cualquier otro estado devuelveCONFLICT, y un sobre que ha vencido lo indica en lugar de un estado obsoleto. - Quién puede anular: solo la persona que creó la solicitud de firma, o un
propietario o administrador de la organización. Cualquier otra persona
recibe
FORBIDDEN; quien llama sin ser parte del sobre en absoluto recibeNOT_FOUND, de modo que la herramienta nunca confirma que un sobre existe a alguien que no debería saberlo. - Anular no consume cuota, ni la reembolsa. La cuota se cobra cuando se envía un sobre.
esign_revise_signers (escritura, destructiva)
Corrige a quién se pide la firma, sin anular el sobre ni gastar un segundo sobre de su cuota: un correo electrónico mal escrito, una contraparte olvidada, un orden de firma incorrecto. El sobre conserva su id, su registro de auditoría y su unidad de cuota. No consume cuota.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
envelope_id | string (UUID) | sí | El sobre que se va a revisar. |
signatories | array | sí | La lista completa de firmantes que debe tener el sobre al final, en orden de firma: de 1 a 50 elementos { "email": string, "name"?: string }. Sustituye a la lista actual. |
signing_mode | "parallel" | "sequential" | no | Cambia el orden de firma. Si se omite, se mantiene el modo actual; no vuelve a "parallel". |
observers | array | no | La lista completa de observadores (cc), hasta 20. Si se omite, se mantienen los observadores actuales; un observador que usted deje fuera se elimina y su enlace de solo lectura deja de funcionar. |
Es destructiva. Un firmante que deje fuera de signatories se elimina: su
invitación se retira y su enlace de firma deja de funcionar de inmediato, sin
que se le avise. Se eliminan todos los campos colocados para él. Un firmante
que ya está en el sobre conserva su enlace y no recibe otro correo. Un
firmante nuevo se invita de inmediato si el sobre ya se envió. La herramienta
está marcada con destructiveHint: true, por lo que un cliente que confirma
las llamadas destructivas preguntará antes de ejecutarla.
- Solo hasta la primera firma. Una vez que alguien ha firmado, la lista de
firmantes y el modo de firma quedan bloqueados: la llamada se rechaza con
CONFLICT(code: ESIGN_SIGNERS_FROZEN), y la solución es anular y crear un sobre nuevo. Un sobre vencido también se rechaza conCONFLICT. - Cambiar solo los observadores. Pase la lista de firmantes sin cambios (y
el modo) con una nueva lista
observers. Eliminar un observador está permitido en cualquier momento, incluso después de la firma o de la finalización. Añadir uno solo está permitido mientras el sobre es un borrador o está pendiente de firma. - Quién puede revisar un sobre enviado: solo la persona que creó la
solicitud de firma, o un propietario o administrador de la organización;
cualquier otra persona recibe
FORBIDDEN. Un borrador puede revisarlo cualquiera que pueda verlo. - Los demás rechazos indican su motivo en el mensaje: una dirección duplicada
(
ESIGN_DUPLICATE_SIGNATORY) o una lista vacía (ESIGN_EMPTY_ROSTER) esINVALID_ARGUMENT; un firmante u observador nuevo en un sobre enviado cuando usted no puede leer todos los documentos que cubre esFORBIDDEN.
Devuelve el sobre con la misma forma que
esign_get_envelope, más un resumen revision de
lo que cambió (y observer_revision cuando se pasaron observadores).
esign_list_my_pending_signatures (lectura)
Lista los sobres pendientes de su propia firma en esta organización: todos
los sobres abiertos con un puesto de firmante pendiente que coincide con el
correo electrónico del propietario del token. Es la lectura más útil antes de
esign_sign.
Sin entradas. Devuelve
{ envelopes: [{ id, file_id, document_name, status, created_at }] }.
Se limita a la organización de este token y, si el token está restringido, a su lista permitida de salas de datos: las firmas pendientes en otras organizaciones nunca se muestran, aunque usted pueda ser firmante en ellas.
esign_download_signed (lectura)
Obtiene una URL de descarga prefirmada de corta duración para el PDF firmado.
Entrada: envelope_id. Devuelve { download_url, expires_in_seconds }. El
sobre debe tener al menos una firma registrada; el PDF firmado también está
disponible en el producto como la versión más reciente del archivo de origen.
Requiere un token con Leer contenido de documentos activado; sin él, la
llamada se rechaza con GRANT_REQUIRED.
esign_quota_status (lectura)
Sin entradas. Devuelve { quota, used, remaining } para el mes natural en
curso: la cuota total de sobres (paquete del plan + unidades adquiridas), los
sobres enviados y el margen restante antes del límite.
esign_remind (escritura)
Entrada envelope_id. Vuelve a enviar un correo electrónico a todos los
firmantes pendientes de un sobre pendiente de firma, y una copia a cada
observador, como máximo una vez por hora y por sobre. Requiere Enviar a personas fuera de tu organización, y sigue dos pasos: la primera llamada no
envía nada y devuelve a quién se enviaría el correo, los observadores por su
nombre, más un confirm_token; vuelva a llamar con él. Un observador añadido
entretanto hace fallar la confirmación. Solo para miembros del equipo de la
operación.
esign_resend_signatory (escritura)
Entradas envelope_id, signatory_id. Desbloquea una dirección rebotada o
bloqueada y vuelve a enviar el correo a ese firmante. Mismo permiso y mismos
dos pasos que esign_remind.
esign_send_draft (escritura)
Entrada envelope_id. Envía un borrador guardado: cada firmante recibe por
correo electrónico una solicitud de firma jurídicamente vinculante, cada
observador una copia, y se usa un sobre de la cuota. Mismo permiso y mismos
dos pasos; la vista previa nombra a los firmantes, los observadores y su
cuota, y la lista de firmantes y los observadores que vio en la vista previa
son los que se envían. El resultado lista cualquier dirección suppressed a
la que no se envió el correo.
esign_preview (lectura)
Entrada envelope_id. Devuelve el sobre tal como lo muestra su panel de
firma: { envelope_id, status, file_id, document_name, is_creator, signers, placed, fields, shows_signed_output, shows_live_source }. document_name es null
cuando usted no puede leer el documento. No se devuelve ningún contenido del
documento. Solo para miembros del equipo de la operación.
esign_verify (lectura)
Entrada envelope_id. Devuelve el resumen del certificado y de la integridad
que muestra la página de verificación de Waafir. Solo para miembros del equipo
de la operación.
Validez jurídica
Las firmas son firmas electrónicas avanzadas (PAdES) según eIDAS, válidas para NDA y contratos conforme a ESIGN/UETA de EE. UU. y eIDAS de la UE. El consentimiento del firmante (IP, agente de usuario, marca de tiempo) se registra en el registro de auditoría de Waafir, de solo anexado y encadenado por hash, en el momento de la firma. Los sobres creados o enviados a través de este servidor MCP se registran en ese registro como acciones iniciadas por token, de modo que un envío iniciado por un agente siempre se distingue de uno que una persona realizó en la aplicación. Las firmas cualificadas (QES) no forman parte de esta versión.