A API de marcações para programadores e agências.

O que ler primeiro

A autenticação é um token no cabeçalho Authorization. Cada chave tem permissões explícitas, e uma chave pública de widget só faz o que um visitante tem direito a fazer.

• https://sutempo.com/openapi.json : a descrição OpenAPI completa da API, servida em /v1
• https://sutempo.com/.well-known/platform-capabilities.json : o manifesto de capacidades deste deployment
• https://sutempo.com/llms.txt : o mesmo resumo, para um assistente
• https://sutempo.com/console : a consola de programador, com o seu sandbox, as chaves de teste e um início rápido em três passos

O caminho mais curto até uma marcação

Ler a disponibilidade, reservar o horário enquanto o pagamento decorre, e confirmar depois. O horário nunca é calculado no cliente: o servidor só propõe inícios posteriores ao seu relógio, e uma reserva temporária impede que dois clientes fiquem com o mesmo horário.

curl -H "Authorization: Bearer $SUTEMPO_KEY" \
  "https://sutempo.com/v1/business-tenants/$TENANT/services"

curl -H "Authorization: Bearer $SUTEMPO_KEY" \
  "https://sutempo.com/v1/business-tenants/$TENANT/availability/search?serviceId=$SERVICE&locationId=$LOCATION&from=2026-10-01&to=2026-10-07"

curl -X POST -H "Authorization: Bearer $SUTEMPO_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"locationId":"...","serviceId":"...","resourceId":"...","startsAt":"2026-10-01T09:00:00Z"}' \
  "https://sutempo.com/v1/business-tenants/$TENANT/appointments/hold"

O servidor MCP

O servidor MCP expõe a configuração de um negócio como ferramentas para um agente. Não lê nem altera as marcações, os clientes ou os pagamentos, e instala-se com npx -y @sutempo/mcp. O contrato obriga a pré-visualizar antes de aplicar: um agente lê a configuração, propõe uma alteração, mostra os efeitos, e só depois aplica.

Não é uma formalidade. A pré-visualização devolve a lista de alterações destrutivas, e a aplicação é recusada se a configuração mudou entre as duas chamadas.

• describe_capabilities, list_business_tenants, list_tenant_modules: o que este deployment sabe fazer
• get_current_blueprint, get_blueprint_version: o estado actual e a sua versão
• preview_blueprint_changes e depois apply_blueprint_changes: propor e aplicar
• schedule_group_sessions, cancel_group_session: as sessões de grupo
• get_translation_status, set_translation_override: os idiomas da página pública

Integrar a marcação num site

Dois caminhos, conforme o que estiver a construir. O widget integrável entra num site existente com uma chave pública e herda o idioma da página. O SDK JavaScript e a API por baixo permitem construir todo o percurso à sua maneira, pagamento incluído.

Nos dois casos, os pagamentos vão para a conta Stripe do negócio, nunca para uma conta intermédia.

<script src="https://sutempo.com/widget.js"
  data-key="pk_…" data-mode="modal"></script>
<button data-platform-widget-open>Reservar</button>

SDK JavaScript e processos de reserva à medida

Instale @sutempo/sdk com npm: inclui um método por operação OpenAPI e é regenerado com o contrato. Utilize @sutempo/booking-flow para criar a sua própria interface, sem HTML nem CSS impostos.

npm i @sutempo/sdk

Pague para gerir negócios, não para chamar a API.

A conta de programador conta os negócios ativos em simultâneo. Arquivar um negócio liberta a respetiva vaga. Todos os planos incluem o ambiente de testes, a consola, as chaves e os webhooks.

Num negócio real, o acesso à API exige o respetivo plano Pro e a autorização revogável do responsável. A subscrição Pro (29 € sem IVA por mês e por local) é paga pelo negócio, não pelo programador.

Criar uma conta de programador · Pedir informações sobre o plano Agência · Preços para negócios

Segurança e fiabilidade

• As chaves têm permissões explícitas e negócios atribuídos, são guardadas sob a forma de hash e só são apresentadas uma vez.
• Os webhooks enviados são assinados com HMAC-SHA256 sobre a marca temporal e o corpo; os destinos têm de utilizar HTTPS.
• As quotas aplicam-se por chave, por negócio e globalmente. Ultrapassar um limite devolve 429 com Retry-After.
• A aplicação é executada na Vercel e a base de dados na Neon, na região de Frankfurt.

Segurança e comunicação de vulnerabilidades · Histórico de alterações