Efni

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

text
https://api.kling.is
Authorization: Bearer sk_test_...
Content-Type: application/json

Notað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:

json
{ "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

Skoða sem markdown