REST API

A REST API fica disponível em /api/v1 e serve para scripts, serviços internos, CI, exportações e outra automação no servidor.

Para endpoints protegidos, é necessário um token de API pessoal. A requisição é feita em nome do usuário que emitiu o token e passa pelas mesmas verificações de papéis e permissões.

Autorização

Envie o token no cabeçalho HTTP:

Authorization: Bearer <token>

Como emitir, armazenar e revogar tokens está descrito no artigo Tokens de API.

Exemplo de requisição

curl -sS "$PLATFORM_BASE_URL/api/v1/{org}/surveys" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $PLATFORM_API_TOKEN"

Substitua {org} pelo ID da organização. Os parâmetros do endpoint específico, o formato da resposta e os códigos de erro estão na especificação completa.

Limites de requisições

A API está protegida contra sobrecarga com limitação de taxa:

• API do aplicativo autenticado: 300 requisições por minuto por usuário ou IP.
• Webhook do provedor de pagamentos: 600 requisições por minuto.
• Endpoints públicos (/status, cartões da base de conhecimento): 300 requisições por minuto por IP.

Ao exceder o limite, o servidor retorna o HTTP 429 Too Many Requests com o cabeçalho Retry-After (número de segundos até a nova tentativa) e o corpo do erro:

{
  "status": 429,
  "message": "Muitas requisições. Tente novamente em 30 s.",
  "errors": {}
}

Documentação completa

• OpenAPI reference — documentação interativa de endpoints, parâmetros e esquemas das respostas.
• OpenAPI JSON — um esquema legível por máquina para geradores de clientes, Postman, Insomnia e validações de contrato.