API pública

Criado para servidores, não para navegadores

A API pública é para automação executada na infraestrutura que você controla – cron jobs, back-ends, pipelines de CI. Ele gerencia formulários e campos e lê e processa envios. É separado da API de envio de formulário, que recebe dados de formulário dos visitantes do seu site; se é isso que você precisa, comece com os documentos da API de envio de formulários.

O que você pode fazer

Cada operação é autorizada pelos escopos da sua chave de API e pelos formulários aos quais essa chave é concedida.

• Gerenciar formulários — liste, crie, atualize e exclua formulários, todos governados pelos escopos forms:read, form:create, form:update e form:delete.
• Definir Campos — leia e atualize a configuração de campo de um formulário nos escopos forms:read e forms:update.
• Ler envios - liste os envios por formulário e marque-os como lidos nos escopos submits:read e submits:mark_read.
• Acessar arquivos — obtenha acesso de download autorizado e de curta duração para arquivos anexados aos envios.
• Operar fluxos de trabalho — inspecione e edite rascunhos, valide e publique versões, execute testes práticos, revise execuções e tente novamente falhas elegíveis.

Um pedido mínimo

Cada chamada é autenticada com uma chave de API do portador no cabeçalho de autorização. As chaves se parecem com smto_live_<key_id>_<secret> — este é apenas o formato, não uma chave funcional.

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"

Escolha acesso estreito e planeje rotação

Uma chave é uma credencial de servidor independente. Alterar sua senha não a revoga, portanto, gerencie seu escopo, vida útil e revogação deliberadamente.

• Comece com formulários selecionados, escopos de leitura e prazo de validade de 90 dias; adicione acesso mais amplo somente quando a automação precisar.
• A chave de texto simples é mostrada uma vez. Se for perdido, crie um substituto em vez de tentar recuperá-lo.
• Se uma chave tiver vazado, revogue-a imediatamente e gire o segredo do tempo de execução.
• Desativar a API pública revoga permanentemente todas as chaves ativas. A reativação do acesso nunca restaura uma chave antiga.

Regras de tempo de execução que vale a pena conhecer

• Chame GET /v1/capabilities primeiro. O acesso de gravação efetivo pode não estar disponível mesmo quando uma chave inclui escopos de gravação.
• As edições de formulário e fluxo de trabalho usam ETags para evitar gravações obsoletas; criar, publicar, testar e repetir operações usam chaves de idempotência quando necessário.
• As operações de lista usam paginação de cursor limitada e cabeçalhos de limite de taxa. Siga Retry-After após uma resposta 429.
• As simulações do fluxo de trabalho nunca entregam mensagens reais, mas as etapas de IA ainda reservam e liquidam pontos de computação.

Limites de segurança

• As chaves de API autenticam seu servidor, nunca um navegador ou aplicativo móvel. Somente tempos de execução de servidor para servidor em HTTPS.
• As chaves carregam escopos selecionados e podem ser concedidas somente a formulários selecionados. Os recursos não concedidos não são visíveis para a chave.
• As respostas omitem segredos, tokens de formulário, configuração de integração e cargas brutas de envio.
• As operações destrutivas exigem uma confirmação no nível do aplicativo além dos escopos.

Começando

1. Abra as configurações do painel, habilite a API pública após revisar os riscos de segurança e crie uma chave de API com privilégios mínimos. A chave de texto simples é mostrada uma vez – armazene-a imediatamente no gerenciador de segredos do lado do servidor.
2. Chame GET /v1/capabilities para confirmar a versão da API, os escopos disponíveis, o estado de gravação e os limites de taxa que sua chave pode usar.
3. Leia o guia completo da API nesta página e a especificação OpenAPI publicada antes de construir.

Contrato completo e OpenAPI

Esta página é o guia público. Use a referência de API gerada e o artefato OpenAPI para o contrato completo legível por máquina.