Subscriptions

Þ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á Subscription Contracts 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"

Í 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

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.

Athugasemd um nýja líkanið

Eldri áskriftarslóðir halda áfram að virka fyrir eldri samþættingar. 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ð Subscription Contracts V2.