API
API y servidor MCP de Sig.Surf
Sig.Surf tiene una REST API pública y un servidor MCP remoto. Un asistente puede crearle a alguien una firma de correo sin cuenta y darle un enlace para guardarla; con una clave de API, un servidor puede gestionar los empleados de la organización, y un asistente desde el que una persona ha iniciado sesión en Sig.Surf puede trabajar con las firmas guardadas de esa persona.
Empieza aquí
- Descripción OpenAPI 3.1: /api/v1/openapi.json. Se genera a partir de los mismos esquemas con los que valida la API, así que coincide con el comportamiento real.
- URL base de REST:
https://sig.surf/api/v1. JSON de entrada y de salida. - Servidor MCP:
https://sig.surf/mcp(Streamable HTTP). Funciona sin cuenta, con inicio de sesión con OAuth o con una clave de API.
Crea una firma sin cuenta
GET /api/v1/templateslista todas las plantillas de la galería con su id, su categoría, los campos que usa, su SignatureDocument y una vista previa generada con valores de ejemplo. No hacen falta credenciales.POST /api/v1/signaturescon{ "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, o con undocumentcompleto en lugar detemplateId. La respuesta contienehtmlapto para correo,textsin formato,warningsde validación, unclaimUrly unclaimToken.- Dale a la persona el
claimUrl. Al abrirlo e iniciar sesión con Google, la firma se guarda en su cuenta de Sig.Surf. - Hasta que se reclame, léela o modifícala con
GEToPATCH /api/v1/signatures/{id}y la cabeceraX-Claim-Token. Las firmas sin reclamar caducan a los 30 días.
Solo se almacena un hash del token de reclamación. Una vez reclamada la firma, o después de que caduque, el token deja de funcionar.
Endpoints
| Método y ruta | Qué hace | Credenciales |
|---|---|---|
GET /api/v1/templates | Listar plantillas | Ninguna |
POST /api/v1/signatures | Crea una firma | Ninguna, clave de API o sesión |
GET /api/v1/signatures/{id} | Obtener una firma | Token de reclamación, clave de API o sesión |
PATCH /api/v1/signatures/{id} | Actualizar una firma | Token de reclamación, clave de API o sesión |
GET /api/v1/signatures | Listar las firmas de tu organización | Clave de API o sesión |
DELETE /api/v1/signatures/{id} | Eliminar una firma | Clave de API o sesión |
POST /api/v1/signatures/claim | Reclamar una firma anónima | Sesión |
GET, POST /api/v1/employees | Listar o añadir empleados | Clave de API o sesión |
GET, PATCH /api/v1/employees/{id} | Obtener o actualizar un empleado | Clave de API o sesión |
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id} | Listar, crear o revocar claves de API | Sesión (propietario o administrador) |
GET /api/v1/extension/signatures | Las firmas del usuario con sesión iniciada, para la extensión de Chrome | Sesión |
GET /api/v1/openapi.json | El documento OpenAPI | Ninguna |
Autenticación
- Clave de API:
Authorization: Bearer ssk_…. Una clave pertenece a una sola organización y actúa como administrador de ella, así que guárdala en un servidor. Los propietarios y los administradores crean y revocan claves con los endpoints/api/v1/api-keyscon la sesión iniciada; Sig.Surf solo almacena un hash y muestra la clave una única vez. - Sesión: la cookie de inicio de sesión de sig.surf, para las páginas propias de Sig.Surf y la extensión de Chrome. Quienes están en varios espacios de trabajo eligen uno con la cabecera
Sig.Surf-Workspace. Las escrituras autenticadas con la cookie se rechazan desde otros orígenes. - Nada: plantillas, creación de firmas, y lectura o edición de una firma sin reclamar con su token de reclamación.
- Token de acceso de OAuth: solo para el servidor MCP, descrito más abajo. La REST API no acepta estos tokens.
Convenciones
- Los errores son
{ "error": { "code": "snake_case", "message": "…" } }con el estado HTTP correspondiente, por ejemplo422 unknown_template,404 invalid_claim_token,410 claim_expired. - Las listas son
{ "data": [...], "nextCursor": string | null }; pasacursorylimit(de 1 a 100, 25 por defecto) para paginar. - Los ID son UUID y las marcas de tiempo son ISO 8601 en UTC.
- El cuerpo de las solicitudes tiene un máximo de 64 KiB (
413 payload_too_large). - Quienes llaman sin credenciales tienen un límite de 120 solicitudes por minuto y 30 firmas nuevas por hora por dirección de cliente; al superarlo, la respuesta es
429 rate_limitedcon una cabeceraRetry-After. - Los navegadores pueden llamar desde cualquier origen a los endpoints que no necesitan credenciales (plantillas, crear una firma, leer o editar una con su token de reclamación, el documento OpenAPI). Las llamadas entre orígenes nunca llevan cookies, y una clave de API no se puede enviar desde un navegador en otro sitio.
Servidor MCP
Apunta un cliente MCP a https://sig.surf/mcp (Streamable HTTP). Las herramientas validan con los mismos esquemas que la REST API. list_templates devuelve una lista compacta (id, nombre, descripción, categoría, campos), opcionalmente de una sola category; pasa hasta 10 ids para obtener sus documentos y vistas previas.
| Herramienta | Sin cuenta | Con sesión iniciada (permiso de OAuth) | Clave de API |
|---|---|---|---|
list_templates | Sí | Sí | Sí |
create_signature | Sí (devuelve un enlace de reclamación) | signatures:write (se guarda en la cuenta) | Sí |
get_signature | Con el token de reclamación | signatures:read | Sí |
update_signature | Con el token de reclamación | signatures:write | Sí |
list_signatures | No | signatures:read | Sí |
list_employees | No | employees:read, solo propietario o administrador | Sí |
create_employee, update_employee | No | employees:write, solo propietario o administrador | Sí |
Todavía no hay herramientas para campañas.
Iniciar sesión con OAuth
El servidor MCP es un recurso protegido de OAuth 2.1 y Sig.Surf es su servidor de autorización, conforme a la especificación de autorización de MCP del 2026-07-28. Un cliente compatible con la autorización de MCP no necesita configuración: llama a una herramienta que requiere cuenta, recibe un 401 con una cabecera WWW-Authenticate y sigue a partir de ahí. La persona inicia sesión en Sig.Surf con Google y ve una página que nombra la aplicación y lo que pide.
- Metadatos del recurso protegido (RFC 9728):
https://sig.surf/.well-known/oauth-protected-resource/mcp. - Metadatos del servidor de autorización (RFC 8414):
https://sig.surf/.well-known/oauth-authorization-server/api/auth. El emisor eshttps://sig.surf/api/auth. - Registro de clientes: se admiten, y se prefieren, los Client ID Metadata Documents (el
client_ides la dirección HTTPS del documento de metadatos del cliente). Dynamic Client Registration (RFC 7591) también está abierto, para los clientes que no tienen otra cosa. Todos los clientes son clientes públicos: no se emite ningún secreto de cliente, aunque se pida. - Solo flujo de código de autorización con PKCE (
S256). Envíaresource=https://sig.surf/mcp; los tokens quedan vinculados a esa dirección y se rechazan en cualquier otro lugar, incluida la REST API. - Permisos:
signatures:read,signatures:write,employees:read,employees:write, yoffline_accesspara obtener un token de actualización. Una respuesta401o403 insufficient_scopeindica el permiso que necesita la herramienta, de modo que un cliente puede empezar con poco y pedir más. - Los tokens de acceso duran una hora. Los tokens de actualización duran 30 días desde su último uso y se sustituyen en cada uso; volver a usar uno antiguo pone fin a la concesión. Los tokens se pueden revocar en el endpoint de revocación (RFC 7009), y un token revocado deja de funcionar en la siguiente solicitud.
Un token nunca tiene más autoridad que la que tiene en ese momento la persona que lo concedió. Las herramientas de firmas solo llegan a las firmas de esa persona. Los permisos de empleados solo puede concederlos un propietario o un administrador del espacio de trabajo, y Sig.Surf vuelve a comprobar la pertenencia y el rol de la persona en cada llamada, de modo que el acceso termina cuando deja el espacio de trabajo o deja de ser administrador. Una concesión pertenece a un solo espacio de trabajo: el primero de la persona.
El inicio de sesión con OAuth se ha probado de principio a fin con el cliente oficial del SDK de TypeScript de MCP. Todavía no se ha probado con todos los asistentes; si el tuyo no puede conectarse, las herramientas que no necesitan cuenta siguen funcionando.
También legible por máquinas
- Todas las páginas de marketing y de documentación se sirven también en Markdown: añade
.mda la URL, o usa/index.mdpara la página de inicio. - llms.txt lista las páginas con descripciones de una línea, y llms-full.txt contiene su texto completo.
- pricing.json y pricing.md recogen todos los planes, precios y límites.
- sitemap.xml lista todas las páginas.
Esta página también está disponible en Markdown.