SkjölunFyrir forritara
API-tilvísun
Grunnreglur Kling greiðslu-API fyrir Ísland, svo sem auðkenning, prófunar- og raunlyklar, upphæðir í heilum krónum, idempotency, villur, takmörk og síðuskipting, og hvar heildarlýsing allra endapunkta er.
Gagnvirk lýsing á öllum endapunktum er á api.kling.is/docs, búin til úr OpenAPI-lýsingunni á api.kling.is/docs/json. Bentu gervigreindartólinu þínu á JSON-lýsinguna; hún er réttasta heimildin um form beiðna og svara. Hér er farið yfir það sem gildir um alla endapunkta.
Slóð og auðkenning
https://api.kling.is
Authorization: Bearer sk_test_...
Content-Type: application/jsonNotaðu leynilykil af síðunni API lyklar og skjölun. sk_test_... lyklar virka í test-umhverfinu, sk_live_... í raunumhverfinu. Umhverfin eru alveg aðskilin: viðskiptavinir, vörur, greiðslur og webhooks blandast aldrei. Geymdu leynilykla á þjóninum. Sendu meginmál beiðna sem JSON með Content-Type: application/json. Án þess hauss hunsar API-ið meginmálið.
Ein undantekning frá aðskilnaðinum í dag: GET /v1/claims tekur við færibreytunni environment og skilar kröfum þess umhverfis til hvaða lykils sem er, merktum með livemode lykilsins sem spyr. Ekki senda hana.
Upphæðir
Allar upphæðir eru heiltölur í minnstu einingu gjaldmiðilsins. Krónan hefur enga aukastafi, svo 5000 er 5.000 kr. Aldrei margfalda með 100. Hægt er að virkja evrur og Bandaríkjadali (tveir aukastafir, svo 4990 er 49,90 €) fyrir aðganginn þinn. Verð með VSK-hlutfalli (0, 11 eða 24) eru með VSK inniföldum.
Idempotency
Sendu Idempotency-Key haus með skrifbeiðni til að mega endurtaka hana örugglega. Kling geymir svarið í 24 klukkustundir: sami lykill með sama meginmáli skilar sama svari án þess að verkið sé unnið tvisvar. Sami lykill með öðru meginmáli fær 422 idempotency_error, og ef beiðni með sama lykli er enn í vinnslu kemur 409 idempotency_conflict. Aðeins svör sem tókust eru geymd, svo misheppnaða beiðni má reyna aftur með sama lykli. Lykill gildir fyrir einn endapunkt í einu umhverfi.
Villur
Villusvör hafa þetta form:
{ "error": { "type": "invalid_request_error", "message": "...", "code": "bank_claim_currency_not_supported" } }type |
Staða | Hvenær |
|---|---|---|
validation_error |
400 | Meginmál eða fyrirspurn passar ekki við lýsinguna |
invalid_request_error |
400, 403, 404, 409 | Beiðninni er hafnað, til dæmis óþekkt auðkenni eða lykill án aðgangs |
card_error |
400 | Ekki er hægt að rukka vistaða kortið, til dæmis payment_method_revoked |
authentication_error |
401 | API-lykil vantar eða hann er óþekktur |
not_found |
404 | Enginn slíkur endapunktur, og óþekkt auðkenni á sumum endapunktum |
idempotency_conflict |
409 | Beiðni með sama Idempotency-Key er enn í vinnslu |
idempotency_error |
422 | Idempotency-Key var notaður með öðru meginmáli |
rate_limit_error |
429 | Of margar beiðnir |
api_error |
500, 502 | Eitthvað fór úrskeiðis hjá Kling eða hjá færsluhirðinum |
service_unavailable |
503 | Þjónusta sem Kling reiðir sig á er ekki tiltæk |
Taktu ákvarðanir út frá HTTP-stöðunni og code, ekki type: flest óþekkt auðkenni skila 404 invalid_request_error. code, þegar það fylgir, er nákvæm ástæða sem þú getur brugðist við. Óvænt villa á þjóninum getur skilað 500 með öðru meginmáli, svo líttu á allar 5xx-villur sem tímabundnar og reyndu aftur með sama Idempotency-Key.
Hafnaðar greiðslur
Hafnað kort er ekki villusvar. POST /v1/payment-intents svarar 200 með greiðslunni, status: "failed" og error: { "code": "card_declined_insufficient_funds", "message": "..." }. Athugaðu alltaf status: captured þýðir að upphæðin hefur verið tekin. pending_settlement með code: "payment_outcome_pending" þýðir að færsluhirðirinn hefur ekki staðfest niðurstöðuna. Ekki rukka aftur; Kling athugar hana.
Takmörk
200 beiðnir á mínútu á hvern API-lykil. Yfir mörkunum færðu 429 rate_limit_error; bíddu og reyndu aftur. Svör innan markanna bera RateLimit-Limit, RateLimit-Remaining og RateLimit-Reset (sekúndur þar til mörkin endurstillast). 429-svarið hefur engan Retry-After haus í dag.
Síðuskipting
Listaendapunktar skila { "object": "list", "data": [...], "has_more": true }, nýjasta fyrst. limit ræður stærð síðunnar, mest 100 (500 fyrir vörur).
Aðeins þrír listaendapunktar taka við bendli: GET /v1/checkout/sessions, GET /v1/customers og GET /v1/subscriptions. Sendu starting_after með síðasta id sem þú fékkst til að sækja næstu síðu.
Hinir listaendapunktarnir (greiðslur, vörur, afsláttarmiðar, afsláttarkóðar, greiðsluhlekkir og tilkynningarásir) hunsa starting_after og skila alltaf nýjustu limit færslunum. Þar segir has_more: true aðeins að fleiri séu til. Ekki lykkja á því: þú færð sömu síðuna í hvert sinn. Til að stemma af pantanir skaltu lista greiðsluferli með status=complete og created_gte og athuga payment_status hvers þeirra, eða nota webhooks.
Kröfur nota limit og offset í staðinn. GET /v1/events skilar engu has_more; sendu after (tímastimpil) til að fá nýrri atburði.
Helstu endapunktar
| Slóð | Hvað hún gerir |
|---|---|
/v1/checkout/sessions |
Greiðsluferli, á greiðslusíðu eða í greiðsluglugga |
/v1/payment-intents |
Greiðslur: rukka vistuð kort, innheimta, endurgreiða |
/v1/payment-links |
Greiðsluhlekkir |
/v1/products, /v1/subscriptions |
Áskriftir |
/v1/billing-portal/sessions |
Innheimtugátt viðskiptavina |
/v1/claims |
Kröfur í heimabanka |
/v1/customers, /v1/payment-methods |
Viðskiptavinir og vistuð kort þeirra |
/v1/coupons, /v1/promotion-codes |
Afslættir |
/v1/notification-channels |
Webhooks |
/v1/kling.js |
Skriftan fyrir greiðslugluggann í vafranum |