API pública

Creado para servidores, no para navegadores

La API pública es para la automatización que se ejecuta en la infraestructura que usted controla: trabajos cron, backends, canalizaciones de CI. Gestiona formularios y campos y lee y procesa envíos. Es independiente de la API de envío de formularios, que recibe datos de formularios de los visitantes de su sitio web; Si eso es lo que necesita, comience con los documentos de la API de envío de formularios.

que puedes hacer

Cada operación está autorizada por los alcances de su clave API y los formularios a los que se otorga esa clave.

• Administrar formularios: enumera, crea, actualiza y elimina formularios, todos regidos por los ámbitos de formularios: leer, formularios: crear, formularios: actualizar y formularios: eliminar.
• Definir campos: lea y actualice la configuración de campos de un formulario en los ámbitos formularios:leer y formularios:actualizar.
• Leer envíos: enumere los envíos por formulario y márquelos como leídos en los ámbitos envíos:leer y envíos:mark_read.
• Acceder a archivos: obtenga acceso de descarga autorizado y de corta duración para los archivos adjuntos a los envíos.
• Opere flujos de trabajo: inspeccione y edite borradores, valide y publique versiones, ejecute pruebas en seco, revise ejecuciones y vuelva a intentar fallas elegibles.

Una petición mínima

Cada llamada se autentica con una clave API de portador en el encabezado de Autorización. Las claves se parecen a smto_live_<key_id>_<secret>: este es solo el formato, no una clave que funcione.

Authorization: Bearer smto_live_<key_id>_<secret>
Accept: application/json

請先呼叫GET /v1/capabilities確認此 Key 的可用能力:

curl https://api.submeto.com/v1/capabilities \
  -H "Authorization: Bearer smto_live_<key_id>_<secret>" \
  -H "Accept: application/json"

Elija un acceso estrecho y planifique la rotación

Una clave es una credencial de servidor independiente. Cambiar su contraseña no la revoca, así que administre su alcance, duración y revocación deliberadamente.

• Comience con formularios seleccionados, lea alcances y un vencimiento de 90 días; agregue un acceso más amplio solo cuando la automatización lo necesite.
• La clave en texto plano se muestra una vez. Si se pierde, cree un reemplazo en lugar de intentar recuperarlo.
• Si es posible que se haya filtrado una clave, revocarla inmediatamente y rotar el secreto de tiempo de ejecución.
• Al deshabilitar la API pública se revocan permanentemente todas las claves activas. Volver a habilitar el acceso nunca restaura una clave antigua.

Reglas de tiempo de ejecución que vale la pena conocer

• Llame primero a GET /v1/capabilities. El acceso de escritura efectivo puede no estar disponible incluso cuando una clave incluye ámbitos de escritura.
• Las ediciones de formularios y flujos de trabajo utilizan ETags para evitar escrituras obsoletas; Las operaciones de creación, publicación, prueba y reintento utilizan claves de idempotencia cuando sea necesario.
• Las operaciones de lista utilizan paginación de cursor delimitada y encabezados de límite de velocidad. Siga Reintentar después después de una respuesta 429.
• Los simulacros del flujo de trabajo nunca entregan mensajes reales, pero los pasos de la IA aún reservan y liquidan puntos de cómputo.

Límites de seguridad

• Las claves API autentican su servidor, nunca un navegador o una aplicación móvil. Solo tiempos de ejecución de servidor a servidor a través de HTTPS.
• Las claves tienen alcances seleccionados y se pueden otorgar únicamente a formularios seleccionados. Los recursos no concedidos no son visibles para la clave.
• Las respuestas omiten secretos, tokens de formulario, configuración de integración y cargas útiles de envío sin procesar.
• Las operaciones destructivas requieren una confirmación a nivel de aplicación además de los alcances.

Empezando

1. Abra la Configuración del panel, habilite la API pública después de revisar los riesgos de seguridad y luego cree una clave API con privilegios mínimos. La clave en texto plano se muestra una vez; guárdela inmediatamente en su administrador secreto del lado del servidor.
2. Llame a GET /v1/capabilities para confirmar la versión de API, los alcances disponibles, el estado de escritura y los límites de velocidad que su clave puede usar.
3. Lea la guía API completa en esta página y la especificación OpenAPI publicada antes de compilar.

Contrato completo y OpenAPI

Esta página es la guía pública. Utilice la referencia de API generada y el artefacto OpenAPI para obtener el contrato completo legible por máquina.