Documentación de la API

Autenticación

Envía tu clave en el encabezado Authorization como Bearer token. Crea y gestiona claves en el panel, en Configuración → Claves de API. La clave secreta se muestra una sola vez al crearla — guárdala de forma segura y nunca la expongas en el navegador.

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

Endpoints

Los endpoints devuelven JSON y ya vienen filtrados por tu organización — nunca ves datos de otra. La lectura exige los ámbitos :read; crear un contacto exige el ámbito cadastros:write, que eliges al generar la clave.

• GET /api/v1/doacoesLista las donaciones de tu organización.
• GET /api/v1/doacoes/{id}Consulta una donación específica por su identificador.
• GET /api/v1/cadastrosLista los contactos (donantes y contactos).
• POST /api/v1/cadastrosCrea un contacto. Campos: nome y email (obligatorios), telefone, tipo_pessoa, tipos, cidade, estado, pais.
• GET /api/v1/campanhasLista las campañas.
• GET /api/v1/recorrenciasLista las donaciones recurrentes. 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"]}'

Paginación

Usa los parámetros limite (máx. 100, predet. 50) y offset. La respuesta es un envoltorio con dados y un bloque 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 }
}

Límites de uso

Cada clave tiene un tope de solicitudes por minuto (predet. 120). Las respuestas incluyen los encabezados X-RateLimit-Limit y X-RateLimit-Remaining. Al excederlo, la API responde 429 con Retry-After. ¿Necesitas un límite mayor? Contacta al soporte.

Errores

Los errores devuelven JSON { "erro": "<código>" } con el estado HTTP adecuado: 401 (clave ausente/inválida), 403 (ámbito insuficiente), 404 (recurso no encontrado), 429 (límite excedido).

Webhooks

En vez de consultar la API repetidamente, recibe eventos (donación pagada, recurrente) en tu endpoint. Registra la URL en el panel, en Configuración → Webhooks. Cada entrega está firmada — verifica la firma antes de confiar en el contenido.

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 disponibles

Elige qué eventos recibe cada endpoint. La entrega se reintenta automáticamente si falla, y cada evento lleva un identificador estable — trata la recepción como idempotente e ignora las repeticiones del mismo evento.

• doacao.pagaUna donación fue confirmada como pagada (puntual o cuota de una recurrente).
• recorrencia.criadaUna donación recurrente fue activada — se pagó su primer cobro.
• recorrencia.canceladaUna donación recurrente fue cancelada, ya sea por el donante, la organización o el medio de pago.
• webhook.testeEvento de prueba, enviado por ti desde el panel para verificar la integración.

Versionado y deprecación

La API está versionada en la URL (/api/v1). Los cambios compatibles entran en v1 sin aviso; los cambios que rompen entran en una nueva versión (v2). Los endpoints en deprecación envían el encabezado Sunset con la fecha de cierre, con antelación.

Empezar

Crea tu primera clave en el panel, en Configuración → Claves de API, y haz tu primera llamada con el ejemplo de arriba.

Configurações → Chaves de API →