Documentação da API

Autenticação

Envie sua chave no cabeçalho Authorization como Bearer token. Gere e gerencie chaves no painel, em Configurações → Chaves de API. A chave secreta aparece uma única vez na criação — guarde-a com segurança e nunca a exponha no navegador.

curl https://www.khelp.com.br/api/v1/doacoes \
  -H "Authorization: Bearer khl_live_..."

Endpoints

Os endpoints retornam JSON e já vêm filtrados pela sua organização — você nunca vê dados de outra. A leitura exige os escopos :read; a criação de cadastro exige o escopo cadastros:write, que você marca ao gerar a chave.

• GET /api/v1/doacoesLista as doações da sua organização.
• GET /api/v1/doacoes/{id}Consulta uma doação específica pelo identificador.
• GET /api/v1/cadastrosLista os cadastros (doadores e contatos).
• POST /api/v1/cadastrosCria um cadastro. Campos: nome e email (obrigatórios), telefone, tipo_pessoa, tipos, cidade, estado, pais.
• GET /api/v1/campanhasLista as campanhas.
• GET /api/v1/recorrenciasLista as doações recorrentes. Filtro opcional: ?status=active.

curl -X POST https://www.khelp.com.br/api/v1/cadastros \
  -H "Authorization: Bearer khl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"nome":"Maria Silva","email":"maria@exemplo.com","tipos":["doador"]}'

Paginação

Use os parâmetros limite (máx. 100, padrão 50) e offset. A resposta traz um envelope com os dados e o bloco paginacao (limite, offset, total, tem_mais).

curl "https://www.khelp.com.br/api/v1/cadastros?limite=50&offset=0" \
  -H "Authorization: Bearer khl_live_..."

{
  "dados": [ /* ... */ ],
  "paginacao": { "limite": 50, "offset": 0, "total": 128, "tem_mais": true }
}

Limites de uso

Cada chave tem um teto de requisições por minuto (padrão 120). As respostas trazem os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining. Ao exceder, a API responde 429 com Retry-After. Precisa de um limite maior? Fale com o suporte.

Erros

Erros retornam um JSON { "erro": "<código>" } com o status HTTP adequado: 401 (chave ausente/inválida), 403 (escopo insuficiente), 404 (recurso não encontrado), 429 (limite excedido).

Webhooks

Em vez de consultar a API repetidamente, receba eventos (doação paga, recorrência) no seu endpoint. Cadastre a URL no painel, em Configurações → Webhooks. Cada entrega é assinada — verifique a assinatura antes de confiar no conteúdo.

Khelp-Signature: t=<unix>,v1=<hex>

import { createHmac } from 'crypto'

// req.rawBody = bytes EXATOS recebidos (não o JSON re-serializado)
function verificar(rawBody, header, segredo) {
  const partes = Object.fromEntries(header.split(',').map(p => p.split('=')))
  const t = Number(partes.t)
  if (Math.abs(Date.now() / 1000 - t) > 300) return false // ±5 min
  const esperado = createHmac('sha256', segredo)
    .update(`${t}.${rawBody}`).digest('hex')
  return esperado === partes.v1
}

Eventos disponíveis

Escolha quais eventos cada endpoint recebe. A entrega é reenviada automaticamente em caso de falha, e cada evento carrega um identificador estável — trate o recebimento como idempotente e ignore repetições do mesmo evento.

• doacao.pagaUma doação foi confirmada como paga (avulsa ou parcela de uma recorrência).
• recorrencia.criadaUma doação recorrente foi ativada — a primeira cobrança foi paga.
• recorrencia.canceladaUma doação recorrente foi cancelada, seja pelo doador, pela organização ou pelo meio de pagamento.
• webhook.testeEvento de teste, enviado por você pelo painel para conferir a integração.

Versionamento e depreciação

A API é versionada na URL (/api/v1). Mudanças compatíveis entram na v1 sem aviso; mudanças que quebram entram numa nova versão (v2). Endpoints em depreciação enviam o cabeçalho Sunset com a data de desligamento, com antecedência.

Começar

Crie sua primeira chave no painel, em Configurações → Chaves de API, e faça a primeira chamada com o exemplo acima.

Configurações → Chaves de API →