API REST · Versão v1 (Beta)

API Pública do ScaleChurch

Integre sua igreja, sistemas e processos ao ScaleChurch de forma segura e escalável. Acesse membros, escalas, ministérios e eventos através de nossa API REST moderna.

Base URL:

https://api.scalechurch.com.br

1. Visão Geral

A API Pública do ScaleChurch segue os princípios REST e utiliza JSON como formato padrão de troca de dados. Todas as requisições devem ser feitas via HTTPS. Requisições em HTTP serão automaticamente rejeitadas.

A API está atualmente em fase Beta. Endpoints e contratos podem sofrer alterações — acompanhe o Roadmap para novidades.

Protocolo

REST / HTTPS

Formato

JSON (UTF-8)

Versão atual

v1 (Beta)

2. Autenticação

A API utiliza tokens Bearer via cabeçalho Authorization. Todas as requisições autenticadas devem incluir o header abaixo:

http

Authorization: Bearer sc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Exemplo de requisição autenticada com cURL:

bash

curl -X GET https://api.scalechurch.com.br/v1/members \
  -H "Authorization: Bearer sc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Atenção: Nunca exponha sua API Key em código client-side, repositórios públicos ou logs de sistema.

3. API Keys

Você pode gerar e gerenciar suas API Keys diretamente no painel do ScaleChurch em Configurações → Integrações → API Keys.

Existem dois tipos de chave:

sc_live_…Produção

Chave de Produção

Acessa dados reais da sua igreja. Use com cuidado.

sc_test_…Sandbox

Chave de Teste

Ambiente isolado para desenvolvimento e testes.

4. Segurança

A segurança da API é garantida por múltiplas camadas de proteção:

Todas as comunicações utilizam TLS 1.3 com certificados renovados automaticamente.
API Keys são armazenadas em hash — nunca em texto plano. Não é possível recuperar uma chave após criação.
Tokens possuem validade configurável (padrão: 90 dias) e podem ser revogados a qualquer momento.
Todas as requisições são registradas em log de auditoria com IP, timestamp e payload.

5. Rate Limits

Os limites de requisições são aplicados por chave de API e variam conforme o plano contratado. Quando o limite é atingido, a API retorna HTTP 429.

Plano	Req / minuto	Req / dia
Essencial	60	5.000
Crescimento	200	20.000
Expansão	500	100.000
Enterprise	Ilimitado*	Ilimitado*

* Sujeito a fair-use policy.

Os headers de resposta informam o estado atual do seu rate limit:

http

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 147
X-RateLimit-Reset: 1735689600

6. Versionamento

A versão da API é especificada diretamente na URL. A versão atual é v1. Versões antigas são mantidas por no mínimo 12 meses após o lançamento de uma nova versão.

bash

# Versão atual
https://api.scalechurch.com.br/v1/members

# Versão futura (exemplo)
https://api.scalechurch.com.br/v2/members

Mudanças que quebram compatibilidade (breaking changes) sempre resultarão em um novo número de versão. Adições de campos e novos endpoints são retrocompatíveis e não exigem migração.

7. Endpoints Disponíveis

Os endpoints estão organizados por recurso. Todos retornam JSON e aceitam parâmetros de paginação via ?page=1&per_page=20.

GET/v1/membersLista todos os membros da igreja

GET/v1/members/{id}Retorna um membro específico

POST/v1/membersCria um novo membro

PUT/v1/members/{id}Atualiza dados de um membro

DELETE/v1/members/{id}Remove um membro

Exemplo — Criar membro via POST:

bash

curl -X POST https://api.scalechurch.com.br/v1/members \
  -H "Authorization: Bearer sc_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria da Silva",
    "email": "maria@email.com",
    "phone": "11999998888",
    "ministry_id": "min_abc123",
    "baptized": true
  }'

Resposta (201 Created):

json

{
  "id": "mbr_7f3k9q2m",
  "name": "Maria da Silva",
  "email": "maria@email.com",
  "phone": "11999998888",
  "ministry_id": "min_abc123",
  "baptized": true,
  "created_at": "2026-06-01T14:00:00Z"
}

8. Códigos de Resposta

Código	Status	Descrição
200	OK	Requisição bem-sucedida.
201	Created	Recurso criado com sucesso.
204	No Content	Ação realizada sem conteúdo de retorno.
400	Bad Request	Parâmetros inválidos ou ausentes.
401	Unauthorized	Token ausente ou inválido.
403	Forbidden	Permissão insuficiente para o recurso.
404	Not Found	Recurso não encontrado.
429	Too Many Requests	Limite de requisições atingido.
500	Internal Server Error	Erro interno na plataforma.

9. Tratamento de Erros

Todos os erros seguem um formato padronizado. O campo error.code pode ser usado programaticamente para identificar o tipo de erro.

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo 'email' é obrigatório.",
    "field": "email",
    "docs": "https://api.scalechurch.com.br/docs/errors#VALIDATION_ERROR"
  },
  "request_id": "req_9f2j3k1p",
  "timestamp": "2026-06-01T14:00:00Z"
}

Principais códigos de erro internos:

VALIDATION_ERROR

RESOURCE_NOT_FOUND

UNAUTHORIZED

FORBIDDEN

RATE_LIMIT_EXCEEDED

INTERNAL_ERROR

10. Webhooks

Configure webhooks no painel para receber notificações em tempo real quando eventos ocorrem na plataforma. Cada evento dispara um POST para a URL configurada com um payload JSON assinado.

Evento	Descrição
member.created	Novo membro cadastrado
member.updated	Dados de membro atualizados
schedule.published	Escala publicada para os membros
event.checkin	Check-in realizado em evento
ministry.updated	Ministério atualizado

Payload padrão de webhook:

json

{
  "event": "member.created",
  "data": {
    "id": "mbr_7f3k9q2m",
    "name": "Maria da Silva",
    "created_at": "2026-06-01T14:00:00Z"
  },
  "webhook_id": "wh_abc123",
  "signature": "sha256=xxxxxxxxxxxxxxxxxxxxxxxx"
}

Validação de assinatura (Node.js)

javascript

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')
  return `sha256=${expected}` === signature
}

11. Boas Práticas

Use paginação sempre

Nunca assuma que todos os dados caberão em uma única resposta. Use ?page e ?per_page para controlar o volume.

Implemente retry com backoff exponencial

Em erros 5xx ou 429, aguarde antes de retentar. Sugerimos: 1s → 2s → 4s → 8s, com no máximo 4 tentativas.

Armazene o request_id

Guarde o campo request_id de cada resposta. Ele é essencial para diagnósticos com o suporte.

Valide os payloads de webhook

Sempre verifique a assinatura HMAC antes de processar eventos recebidos.

Não exponha sua API Key

Use variáveis de ambiente. Nunca comite chaves no repositório. Gire as chaves periodicamente.

12. Roadmap de Integrações

Confira o que está sendo desenvolvido para a API. Funcionalidades podem ser antecipadas ou adiadas conforme prioridade e feedback da comunidade.

Q3 2026

Autenticação OAuth 2.0
SDK JavaScript oficial
Webhooks em tempo real

Q4 2026

GraphQL beta
SDK Python
Integração Zapier

Q1 2027

Rate limits personalizados por plano
Sandbox completo
SDK Mobile (iOS/Android)

Dúvidas sobre a API?

Nossa equipe técnica pode ajudar com integrações, dúvidas sobre endpoints e casos de uso específicos.

Documentação Falar com Dev