Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

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-esign se rechaza en la entrada con HTTP 402, antes de que se ejecute ninguna herramienta: un rechazo de capa 1. ADDON_NOT_PURCHASED aparece dentro del texto message de 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. En waafir, en cambio, las herramientas esign_ se ocultan en la lista de herramientas, y una llamada a una de ellas se rechaza en la capa 2 con QUOTA_EXCEEDED y un mensaje que nombra la herramienta, que también incluye ADDON_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 interno ESIGN_QUOTA_EXCEEDED; eso es texto descriptivo, así que decida según error.code, que es QUOTA_EXCEEDED. Una creación con send: true que 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-esign antes aceptaba argumentos en camelCase. fileId, envelopeId, signingMode, fieldLayout y consentAffirmed ya no se aceptan; cada uno tiene ahora una grafía snake_case, indicada en las tablas siguientes. confirm_send no 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 fileId a esign_create_envelope falla en la validación de argumentos, que nombra file_id como 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_id y consent_affirmed), esign_decline, esign_void_envelope, esign_revise_signers (envelope_id y signatories) y esign_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 campo error.code de la capa 2. No decida según INVALID_ARGUMENT ante un fallo de forma de los argumentos: lea el mensaje. INVALID_ARGUMENT sigue siendo lo que recibe ante un rechazo que una herramienta emite después de empezar, como un confirm_token mal formado.

  • Clave opcional → la llamada tiene éxito y hace otra cosa. Recibe un 200 y un resultado bien formado que responde a otra pregunta:

    • Los filtros de esign_list_envelopes son opcionales, así que un fileId suelto 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, un signingMode: "sequential" descartado deja el sobre en su modo predeterminado parallel. Al enviarlo, se manda entonces una solicitud de firma jurídicamente vinculante a todos los firmantes a la vez, que es precisamente lo que pedir sequential debía evitar. fieldLayout se descarta del mismo modo.

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.

CampoTipoObligatorioDescripción
file_idstring (UUID)síEl archivo que se va a firmar. Debe pertenecer a su organización.
signatoriesarraysí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_idstring (UUID)noObsoleto e ignorado. Se acepta para que las integraciones existentes sigan funcionando; deje de enviarlo.
sendbooleannoSi 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_tokenstringnoSolo con send: true: el token de la llamada de vista previa.
confirm_sendbooleannoObsoleto e ignorado: send: true ahora usa confirm_token.
signing_mode"parallel" | "sequential"noOrden 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_layoutarraynoSustitución del diseño de colocación de campos; omítalo para usar el diseño predeterminado.
observersarraynoHasta 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:

  1. Vista previa. Llame sin confirm_token. No se firma nada. El resultado es dry_run: true con el sobre, los documents en orden, un único document_hash que los cubre todos, el signer, los fields que proporcionó, la declaración de consentimiento, un confirm_token y su expires_at.
  2. 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.

CampoTipoObligatorioDescripción
envelope_idstring (UUID)síEl sobre que se va a firmar.
consent_affirmedbooleansí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.
fieldsobjectnoValores de relleno indexados por la etiqueta del campo; el nombre y la fecha se rellenan por defecto si se omiten.
confirm_tokenstringnoOmí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.codecode:Qué hacer
FORBIDDENGRANT_REQUIREDEl token no puede firmar. Cree uno nuevo con Firmar documentos activado.
INVALID_ARGUMENTCONFIRM_TOKEN_MALFORMEDVuelva a llamar sin confirm_token para obtener uno.
CONFLICTCONFIRM_TOKEN_INVALIDEl token venció, ya se usó o pertenece a otro token. Vuelva a obtener la vista previa.
CONFLICTCONFIRM_ARGS_MISMATCHLos argumentos difieren de los de la vista previa. Vuelva a obtener la vista previa.
CONFLICTCONFIRM_STATE_CHANGEDEl sobre cambió desde la vista previa. Vuelva a obtener la vista previa y muéstresela a la persona.
CONFLICTDOCUMENT_NOT_PINNEDEl sobre se envió antes de que existiera la fijación de documentos. Fírmelo en Waafir desde el correo de firma.
UNAVAILABLECONFIRM_UNAVAILABLELa 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, sent o partially_signed. Cualquier otro estado devuelve CONFLICT, 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 recibe NOT_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.

CampoTipoObligatorioDescripción
envelope_idstring (UUID)síEl sobre que se va a revisar.
signatoriesarraysí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"noCambia el orden de firma. Si se omite, se mantiene el modo actual; no vuelve a "parallel".
observersarraynoLa 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 con CONFLICT.
  • 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) es INVALID_ARGUMENT; un firmante u observador nuevo en un sobre enviado cuando usted no puede leer todos los documentos que cubre es FORBIDDEN.

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.