Áskriftir

Þessi síða lýsir eldra áskriftarflæði Áskels, þar sem áskrift er stofnuð út frá PlanVariant og vistuð sem eldra Subscription líkan. Fyrir nýja vörulista-, pakka- og áskriftarsamningsnálgunina skal sjá Áskriftarsamningar V2.

Öll köll í áskriftarvefþjónustur má prófa í Swagger skjölun okkar sem finna má hér.

Auðkenning

Eins og aðrar eldri vefþjónustur Áskels krefjast þessar slóðir leynilegs API lykils eða eldri token-auðkenningar.

Authorization: Api-Key your-secret-api-key

Yfirlit yfir helstu slóðir

Slóð	Lýsing
GET /api/subscriptions/	Sækir lista af eldri áskriftum.
POST /api/subscriptions/	Stofnar eldri áskrift með földuðum gögnum.
GET /api/subscriptions/{id}/	Sækir staka eldri áskrift.
PATCH /api/subscriptions/{id}/	Uppfærir takmarkaða reiti á áskrift.
POST /api/subscriptions/{id}/cancel/	Hættir við virkri áskrift.
POST /api/subscriptions/{id}/activate/	Virkjar áskrift sem er ekki virk.
POST /api/subscriptions/{id}/set_expiry/	Yfirskrifar gildistíma síðustu innheimtufærslu.
POST /api/subscriptions/{id}/execute_billing/	Keyrir innheimtu ef áskrift er komin fram yfir active_until.
GET /api/customers/{reference}/subscriptions/	Sækir áskriftir tiltekins viðskiptavinar.
POST /api/customers/{reference}/subscriptions/add/	Stofnar áskrift fyrir tiltekinn viðskiptavin.
POST /api/subscriptions/multi/	Stofnar eða uppfærir viðskiptavin og fleiri en eina áskrift í einu.

Hvernig eldra flæðið virkar

Eldri áskrift byggir á PlanVariant. PlanVariant skilgreinir meðal annars verð, endurtökutíðni, gjaldmiðil og mögulegan færsluhirði. Á sjálfri áskriftinni er síðan hægt að beita yfirskriftum á upphæð með amount eða discount.

Þegar ný eldri áskrift er stofnuð gerist eitt af eftirfarandi:

1. Ef prufutímabil er í boði verður til færsla fyrir prufutímabil og áskriftin virkjuð án skuldfærslu.

2. Ef ekki er um prufutímabil að ræða verður til endurnýjunarfærsla í innheimtu og fyrsta skuldfærsla reynd strax, nema fyrsta innheimtudagsetning hafi verið sett fram í tímann.

3. Ef upphæð er 0 kr. eða gjaldfrjáls vara á við getur áskrift orðið virk án þess að kort sé skuldfært.

Sækja lista af áskriftum

GET /api/subscriptions/ skilar eldri áskriftum sem tilheyra þínum aðgangi.

Styður meðal annars:

• leit á reference

• síu á reference

• type=light til að fá styttra svar

• röðun á active_until og start_date

Dæmi:

curl "https://askell.is/api/subscriptions/?type=light&ordering=-start_date" \
  -H "Authorization: Api-Key your-secret-api-key"

Athugasemd

ordering og active_until eiga aðeins við um þetta eldra flæði. V2 samningar hafa hvorki active_from né active_until, og listi þeirra styður ekki ordering. Sjá Gildistími og uppsögn í Áskriftarsamningar V2.

Í light svörum er meðal annars skilað:

• id

• plan

• customer_reference

• start_date

• active_until

• last_billing_log

• amount

• cancelled

• cancel_date

• has_payment_plan

• payment_plan_info

Sækja staka áskrift

GET /api/subscriptions/{id}/ skilar ítarlegra svari, þar á meðal billing_logs, delivery_address og földuðum customer og plan gögnum.

Bein stofnun á /api/subscriptions/

POST /api/subscriptions/ notar SubscriptionSerializer og gerir ráð fyrir földuðum plan og customer gögnum. Þessi slóð er því yfirleitt minna þægileg fyrir einfaldar samþættingar en viðskiptavinatengda stofnslóðin.

Í reynd velja flestir annaðhvort:

• POST /api/customers/{reference}/subscriptions/add/ fyrir staka áskrift

• POST /api/subscriptions/multi/ fyrir margar áskriftir í einu

Stofna áskrift á viðskiptavin

Algengasta eldra stofnflæðið er:

POST /api/customers/{reference}/subscriptions/add/

Beiðnigögn geta meðal annars innihaldið:

Reitur	Lýsing
plan	Auðkenni á PlanVariant.
reference	Tilvísun á áskriftinni.
description	Frjáls lýsing.
start_date	Valkvæð fyrsta innheimtudagsetning eða lok prufutímabils.
amount	Valkvæð yfirskrift á upphæð.
discount	Valkvæður afsláttur 0-100.
delivery_address	Valkvætt afhendingarheimilisfang.

Ef greiðsla er nauðsynleg þarf viðskiptavinurinn þegar að vera með gildan og staðfestan greiðslumáta. Ef áskriftarverð er hærra en 0 og enginn greiðslumáti er til staðar fæst villa.

Dæmi:

• python

import requests

API_KEY = 'your api key here'
headers = {
    "Authorization": f"Api-Key {API_KEY}",
}

data = {
    "plan": 12,
    "reference": "sub-2026-0001",
    "description": "Mánaðaráskrift",
    "discount": "10",
}

response = requests.post(
    "https://askell.is/api/customers/customer-123/subscriptions/add/",
    data=data,
    headers=headers,
)

Búa til margar áskriftir í einu

POST /api/subscriptions/multi/ uppfærir eða stofnar viðskiptavin og stofnar síðan fleiri en eina áskrift í sama kalli.

Þessi slóð tekur yfirleitt þrjá meginhluta í beiðnigögnunum:

• customer

• payment_method

• subscriptions

customer inniheldur viðskiptavinagögn og getur einnig innihaldið afhendingarheimilisfang. payment_method getur verið:

• {"invoice": true}

• tímabundið token frá greiðslumátaflokki

• hrá kortagögn í eldri samþættingum

• tómt gagnasafn ef allar áskriftir eru 0 kr.

Hver færsla í subscriptions getur innihaldið:

• plan

• reference

• description

• amount

• discount

• start_date

Dæmi:

{
  "customer": {
    "customer_reference": "customer-123",
    "first_name": "Jón",
    "last_name": "Jónsson",
    "email": "jon@example.com"
  },
  "payment_method": {
    "token": "temporary-payment-token"
  },
  "subscriptions": [
    {
      "plan": 12,
      "reference": "sub-magazine",
      "description": "Tímarit"
    },
    {
      "plan": 13,
      "reference": "sub-donation",
      "amount": "500"
    }
  ]
}

Uppfæra áskrift

PATCH /api/subscriptions/{id}/ leyfir ekki frjálsa breytingu á öllum reitum, en styður helst þessar yfirskriftir:

• plan

• amount

• meta og aðrir serializer-reitir sem standast staðfestingu

Ef skipt er um plan á virkri áskrift og nýja planið er komið að áskriftarþaki (subscription limit) fæst villa.

Hætta við, virkja og færa endingardag

Eldri áskriftir styðja eftirfarandi stjórnunarköll:

Slóð	Lýsing
POST /cancel/	Hættir við áskrift sem er í virkri stöðu.
POST /activate/	Virkjar áskrift aftur ef hún er ekki útrunnin.
POST /set_expiry/	Setur nýjan gildistíma á síðustu innheimtufærslu.
POST /execute_billing/	Keyrir innheimtu ef active_until er liðið.

set_expiry tekur inn reitinn expires og styður bæði:

• YYYY-MM-DD

• YYYY-MM-DDTHH:MM:SS

Á áskrift sem hefur verið flutt yfir í V2 samning hafna öll þessi köll beiðninni, sjá Aðgangar á áskriftarsamningum og fluttar áskriftir.

Aðgangar á áskriftarsamningum og fluttar áskriftir

Þegar áskriftarlíkan aðgangsins er contracts (Eingöngu nýjar áskriftir í stjórnborði) stofna eldri slóðirnar ekki lengur nýjar eldri áskriftir. Eftirfarandi köll skila þá villu 400 með code legacy_subscriptions_disabled, áður en viðskiptavinur er stofnaður eða uppfærður og áður en nokkuð er skuldfært:

• POST /api/subscriptions/

• POST /api/subscriptions/multi/

• POST /api/customers/{reference}/subscriptions/add/

• POST /api/checkouts/ þegar plan fylgir beiðninni. Checkout án plan, þ.e. með payment_processor og currency til að skrá kort eða taka staka upphæð, virkar áfram.

Greiðslusíður sem selja eldri áskriftarleiðir hafna kaupum á sama hátt, með code legacy_subscriptions_disabled, áður en kort er staðfest eða skuldfært. Áskriftarhnappurinn (/subscribe-button/{plan_id}/) hafnar líka kaupum áður en viðskiptavinur er stofnaður eða nokkuð er skuldfært, en svarar með villusíðu (400) fyrir kaupandann en ekki JSON svari með code. Sjá Greiðslusíður.

Aðgangar með áskriftarlíkanið legacy eða dual stofna eldri áskriftir eins og áður. Á samningsaðgangi eru nýjar áskriftir stofnaðar með POST /api/v2/subscription-contracts/, sjá Áskriftarsamningar V2.

{
  "error": "This account uses subscription contracts and no longer creates legacy subscriptions. Use POST /api/v2/subscription-contracts/ instead.",
  "code": "legacy_subscriptions_disabled",
  "v2_endpoint": "/api/v2/subscription-contracts/"
}

POST /api/customers/{reference}/subscriptions/add/ skilar auk þess "status": "error" eins og aðrar villur þeirrar slóðar.

Þegar eldri áskrift hefur verið flutt yfir í V2 samning sér samningurinn um innheimtuna. Í svörum áskriftarinnar er billing_managed_by þá subscription_contract og migrated_to_contract_id vísar á samninginn. Á slíkri áskrift skila eftirfarandi köll villu 400 með code subscription_managed_by_contract og breyta engu, hvert sem áskriftarlíkan aðgangsins er:

• POST /api/subscriptions/{id}/cancel/, óháð stöðu eldri áskriftarinnar

• POST /api/subscriptions/{id}/activate/, óháð stöðu eldri áskriftarinnar

• POST /api/subscriptions/{id}/execute_billing/

• PATCH /api/subscriptions/{id}/ og PUT /api/subscriptions/{id}/

• POST /api/subscriptions/{id}/set_expiry/

GET köllin virka áfram. Ef flutningur er afturkallaður verður billing_managed_by aftur legacy_subscription og köllin virka eins og áður.

{
  "error": "This subscription's billing is managed by subscription contract 123. Cancel it with POST /api/v2/subscription-contracts/123/cancel/ instead.",
  "code": "subscription_managed_by_contract",
  "migrated_to_contract_id": 123,
  "v2_endpoint": "/api/v2/subscription-contracts/123/cancel/"
}

Reitur	Lýsing
error	Lýsing á villunni, á ensku.
code	legacy_subscriptions_disabled eða subscription_managed_by_contract. Samþættingar ættu að bregðast við þessum reit frekar en texta villunnar.
migrated_to_contract_id	Auðkenni V2 samningsins sem sér um innheimtuna. Aðeins með subscription_managed_by_contract.
v2_endpoint	V2 slóðin sem á að nota í staðinn: POST /api/v2/subscription-contracts/ til að stofna, POST /api/v2/subscription-contracts/{id}/cancel/ til að segja upp og /api/v2/subscription-contracts/{id}/ fyrir aðrar breytingar.

Greiðsluáætlanir

Svör frá eldra flæði geta innihaldið upplýsingar um greiðsluáætlun ef slík er virk á áskriftinni:

• has_payment_plan

• payment_plan_info

payment_plan_info getur innihaldið meðal annars:

• total_installments

• current_installment

• remaining_installments

• next_installment_date

• progress_percentage

• status

• billing_period_start

• billing_period_end

Algengar villur

Villa	Lýsing
Plan not found	PlanVariant fannst ekki eða tilheyrir ekki aðganginum.
Plan subscription limit reached	Ný áskrift myndi fara yfir skilgreint áskriftarþak.
Customer does not have a valid payment method	Greiðsluskyld áskrift var stofnuð án gilds greiðslumáta.
Discount must be a value in the range 0-100	Afsláttur er utan leyfilegs bils.
Cannot cancel subscription from ... state	Reynt var að hætta við áskrift úr rangri stöðu.
Cannot activate an expired subscription	Reynt var að virkja útrunna áskrift.
code: legacy_subscriptions_disabled	Aðgangurinn er á áskriftarsamningum (contracts) og stofnar ekki lengur eldri áskriftir. Notið POST /api/v2/subscription-contracts/. Sjá Aðgangar á áskriftarsamningum og fluttar áskriftir.
code: subscription_managed_by_contract	Áskriftin hefur verið flutt yfir í V2 samning (migrated_to_contract_id) sem sér um innheimtuna. Segið upp eða breytið samningnum á slóðinni í v2_endpoint.

Athugasemd um nýja líkanið

Eldri áskriftarslóðir halda áfram að virka fyrir eldri samþættingar á aðgöngum með áskriftarlíkanið legacy eða dual. Á aðgangi sem er eingöngu á áskriftarsamningum hafna þær stofnun nýrra eldri áskrifta, sjá Aðgangar á áskriftarsamningum og fluttar áskriftir. Fyrir nýjar samþættingar sem þurfa vörulista, pakka, viðbótarvörur, verðútgáfur, val á færsluhirði og endurtekningu innheimtulota er mælt með Áskriftarsamningar V2.