# 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](https://api.kling.is/docs), búin til úr OpenAPI-lýsingunni á [api.kling.is/docs/json](https://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_...
```

Notaðu leynilykil af síðunni **API lyklar og skjölun**. `sk_test_...` lyklar virka í prófunarumhverfinu, `sk_live_...` í raunumhverfinu. Umhverfin eru alveg aðskilin: viðskiptavinir, vörur, greiðslur og webhooks blandast aldrei. Geymdu leynilykla á þjóninum.

## 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) 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.

## Villur

Villur hafa alltaf sama form:

```json
{ "error": { "type": "invalid_request_error", "message": "...", "code": "card_declined_insufficient_funds" } }
```

`type` er `authentication_error` (401), `validation_error` (400), `invalid_request_error`, `not_found` (404) eða `rate_limit_error` (429). `code`, þegar það fylgir, er nákvæm ástæða sem þú getur brugðist við.

## Takmörk

200 beiðnir á mínútu á hvern API-lykil. Að stofna greiðsluferli og payment intents er takmarkað við 30 á mínútu. Yfir mörkunum færðu 429 `rate_limit_error`; bíddu og reyndu aftur.

## Síðuskipting

Listaendapunktar skila `{ "object": "list", "data": [...], "has_more": true }`. Sendu `limit`, og `starting_after` með síðasta `id` sem þú fékkst til að sækja næstu síðu. Kröfur nota `limit` og `offset` í staðinn.

## Helstu endapunktar

| Slóð | Hvað hún gerir |
|---|---|
| `/v1/checkout/sessions` | [Greiðsluferli](https://kling.is/docs/checkout), á greiðslusíðu eða í [greiðsluglugga](https://kling.is/docs/embedded-checkout) |
| `/v1/payment-intents` | [Greiðslur](https://kling.is/docs/payments): rukka vistuð kort, innheimta, endurgreiða |
| `/v1/payment-links` | [Greiðsluhlekkir](https://kling.is/docs/payment-links) |
| `/v1/products`, `/v1/subscriptions` | [Áskriftir](https://kling.is/docs/subscriptions) |
| `/v1/billing-portal/sessions` | [Innheimtugátt](https://kling.is/docs/subscriptions#innheimtugatt) viðskiptavina |
| `/v1/claims` | [Kröfur í heimabanka](https://kling.is/docs/bank-claims) |
| `/v1/customers`, `/v1/payment-methods` | Viðskiptavinir og vistuð kort þeirra |
| `/v1/coupons`, `/v1/promotion-codes` | Afslættir |
| `/v1/notification-channels` | [Webhooks](https://kling.is/docs/webhooks) |
| `/v1/kling.js` | Skriftan fyrir greiðslugluggann í vafranum |