API documentation

Authentication

Send your key in the Authorization header as a Bearer token. Create and manage keys in the panel, under Settings → API keys. The secret key is shown only once at creation — store it safely and never expose it in the browser.

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

Endpoints

Endpoints return JSON and are already filtered to your organization — you never see another organization's data. Reads require the matching :read scopes; creating a contact requires the cadastros:write scope, which you select when generating the key.

• GET /api/v1/doacoesLists your organization's donations.
• GET /api/v1/doacoes/{id}Retrieves a single donation by its identifier.
• GET /api/v1/cadastrosLists contacts (donors and contacts).
• POST /api/v1/cadastrosCreates a contact. Fields: nome and email (required), telefone, tipo_pessoa, tipos, cidade, estado, pais.
• GET /api/v1/campanhasLists campaigns.
• GET /api/v1/recorrenciasLists recurring donations. Optional filter: ?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"]}'

Pagination

Use the limite (max 100, default 50) and offset parameters. The response is an envelope with dados and a paginacao block (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 }
}

Rate limits

Each key has a per-minute request ceiling (default 120). Responses include the X-RateLimit-Limit and X-RateLimit-Remaining headers. When exceeded, the API returns 429 with Retry-After. Need a higher limit? Contact support.

Errors

Errors return JSON { "erro": "<code>" } with the appropriate HTTP status: 401 (missing/invalid key), 403 (insufficient scope), 404 (resource not found), 429 (rate limit exceeded).

Webhooks

Instead of polling the API, receive events (donation paid, recurring gift) at your endpoint. Register the URL in the panel, under Settings → Webhooks. Every delivery is signed — verify the signature before trusting the payload.

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
}

Available events

Choose which events each endpoint receives. Deliveries are retried automatically on failure, and every event carries a stable identifier — treat delivery as idempotent and ignore repeats of the same event.

• doacao.pagaA donation was confirmed as paid (one-off, or an installment of a recurring gift).
• recorrencia.criadaA recurring donation became active — its first charge was paid.
• recorrencia.canceladaA recurring donation was canceled, whether by the donor, the organization, or the payment provider.
• webhook.testeTest event, sent by you from the panel to check the integration.

Versioning and deprecation

The API is versioned in the URL (/api/v1). Backwards-compatible changes land in v1 without notice; breaking changes go to a new version (v2). Deprecated endpoints send a Sunset header with the shutdown date, in advance.

Get started

Create your first key in the panel, under Settings → API keys, and make your first call with the example above.

Configurações → Chaves de API →