የAPI ሰነድ

ማረጋገጫ

ቁልፍዎን በAuthorization ራስጌ ውስጥ እንደ Bearer token ይላኩ። ቁልፎችን በፓነሉ ውስጥ በ ቅንብሮች → የAPI ቁልፎች ያመንጩና ያስተዳድሩ። ሚስጥራዊው ቁልፍ በሚፈጠርበት ጊዜ አንድ ጊዜ ብቻ ነው የሚታየው — በደህና ያስቀምጡት እና በአሳሽ ውስጥ በጭራሽ አያጋልጡት።

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

Endpoints

Endpoint-ዎቹ JSON ይመልሳሉ እና አስቀድሞ በድርጅትዎ ተጣርተው ይመጣሉ — የሌላውን መረጃ በጭራሽ አያዩም። ንባብ :read ስኮፖችን ይፈልጋል፤ የምዝገባ መፍጠር cadastros:write ስኮፕ ይፈልጋል፣ ይህም ቁልፉን ሲያመነጩ የሚያመለክቱት ነው።

• GET /api/v1/doacoesየድርጅትዎን ልገሳዎች ይዘረዝራል።
• GET /api/v1/doacoes/{id}አንድ የተወሰነ ልገሳን በመለያው ያማክራል።
• GET /api/v1/cadastrosምዝገባዎችን (ለጋሾችና ተጠሪዎች) ይዘረዝራል።
• POST /api/v1/cadastrosምዝገባ ይፈጥራል። መስኮች፦ nome እና email (የግድ)፣ telefone፣ tipo_pessoa፣ tipos፣ cidade፣ estado፣ pais።
• GET /api/v1/campanhasዘመቻዎችን ይዘረዝራል።
• GET /api/v1/recorrenciasተደጋጋሚ ልገሳዎችን ይዘረዝራል። አማራጭ ማጣሪያ፦ ?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"]}'

ገጽ ማከፋፈል

የ limite (ከፍተኛ 100፣ ነባሪ 50) እና offset መለኪያዎችን ይጠቀሙ። ምላሹ መረጃውን የያዘ envelope እና 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 }
}

የአጠቃቀም ገደቦች

እያንዳንዱ ቁልፍ በደቂቃ የጥያቄ ጣሪያ አለው (ነባሪ 120)። ምላሾቹ X-RateLimit-Limit እና X-RateLimit-Remaining ራስጌዎችን ይዘው ይመጣሉ። ሲያልፍ API 429 ከ Retry-After ጋር ይመልሳል። ከዚህ የሚበልጥ ገደብ ይፈልጋሉ? ድጋፍን ያነጋግሩ።

ስህተቶች

ስህተቶች ተገቢ በሆነ የHTTP ሁኔታ የ JSON { "erro": "<código>" } ይመልሳሉ፦ 401 (ቁልፍ የለም/ልክ ያልሆነ)፣ 403 (በቂ ያልሆነ ስኮፕ)፣ 404 (ግብዓት አልተገኘም)፣ 429 (ገደብ አልፏል)።

Webhooks

API-ን ደጋግሞ ከመጠየቅ ይልቅ ክስተቶችን (የተከፈለ ልገሳ፣ ተደጋጋሚ) በendpoint-ዎ ላይ ይቀበሉ። URL-ን በፓነሉ ውስጥ በ ቅንብሮች → Webhooks ያስመዝግቡ። እያንዳንዱ ማድረሻ ተፈርሟል — ይዘቱን ከማመንዎ በፊት ፊርማውን ያረጋግጡ።

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
}

ያሉ ክስተቶች

እያንዳንዱ endpoint የትኞቹን ክስተቶች እንደሚቀበል ይምረጡ። ማድረሻው ሲያቅት በራስ-ሰር እንደገና ይላካል፣ እና እያንዳንዱ ክስተት የተረጋጋ መለያ ይዞ ይመጣል — መቀበሉን እንደ idempotent ይያዙት እና የአንድ ክስተትን ድግግሞሽ ችላ ይበሉ።

• doacao.pagaልገሳ እንደተከፈለ ተረጋግጧል (ነጠላ ወይም የተደጋጋሚ ክፍያ ግብር)።
• recorrencia.criadaተደጋጋሚ ልገሳ ገቢር ሆኗል — የመጀመሪያው ክፍያ ተከፍሏል።
• recorrencia.canceladaተደጋጋሚ ልገሳ ተሰርዟል፣ በለጋሹ፣ በድርጅቱ ወይም በክፍያ ዘዴው።
• webhook.testeውህደቱን ለማረጋገጥ በእርስዎ ከፓነሉ የተላከ የሙከራ ክስተት።

ቨርዥን አሰጣጥና ማስወገድ

API በURL ውስጥ ቨርዥን ተሰጥቶታል (/api/v1)። ተኳሃኝ ለውጦች ያለ ማስጠንቀቂያ ወደ v1 ይገባሉ፤ የሚሰብሩ ለውጦች ወደ አዲስ ቨርዥን (v2) ይገባሉ። በማስወገድ ላይ ያሉ endpoint-ዎች የመዘጋቱን ቀን የያዘ Sunset ራስጌ አስቀድመው ይልካሉ።

መጀመር

የመጀመሪያ ቁልፍዎን በፓነሉ ውስጥ በ ቅንብሮች → የAPI ቁልፎች ይፍጠሩ፣ እና የመጀመሪያውን ጥሪ ከላይ ባለው ምሳሌ ያድርጉ።

Configurações → Chaves de API →