Afgreiðslupantanir V2

Þegar greitt hefur verið fyrir áþreifanlega vöru í áskriftarsamningi V2 verður til afgreiðslupöntun (e. fulfillment order): ein pöntun fyrir hverja innheimtulotu sem tókst. Mánaðarleg áskrift á kaffipoka gefur því eina opna pöntun í hverjum mánuði, sem þarf að tína til, pakka og senda.

Vöruhús eða afgreiðslukerfi fær pantanirnar sendar jafnóðum með fulfillment_order.* atburðum. Lesaðgerðirnar hér eru viðbót við þá atburði og eru ætlaðar til að:

Sækja pantanir aftur í tímann þegar samþætting er tekin í notkun.
Samstilla stöðu reglulega (e. reconciliation) og finna pantanir sem vantar.
Ná í pöntun sem tapaðist vegna misheppnaðrar sendingar á atburði.

Til viðbótar eru tvær skrifaðgerðir sem loka hringnum hinum megin frá: seljandi sem sendir sjálfur skráir rekjanúmerið hjá sér og afgreiðir pöntunina (fulfill), eða afturkallar hana (cancel). Bókun sendingar og prentun sendingarmiða eru áfram hvergi í vefþjónustunni — það er annaðhvort gert í stjórnborðinu eða í kerfi seljandans.

Afgreiðsla í ytra kerfi

Undir Stillingar › Sendingar er valið hvar pantanir eru afgreiddar:

Stilling	Lýsing
Óvirkt	Engar afgreiðslupantanir verða til.
Í Áskel	Áskell bókar sendinguna hjá flutningsaðila, sækir sendingarmiðann og pöntunin er afgreidd í stjórnborðinu.
Í ytra kerfi	Pantanir verða til og eru sendar út eins og áður, en vöruhúskerfi seljanda bókar sendinguna sjálft og tilkynnir Áskeli um hana með `fulfill`.

Í ytra kerfi hverfa bókunarhnapparnir úr stjórnborðinu, enda á Áskell ekkert erindi við flutningsaðilann; pöntunina má eftir sem áður afgreiða eða afturkalla þar.

Skrifaðgerðirnar eru þó ekki bundnar við þá stillingu. Aðgangur sem afgreiðir í Áskel má allt eins nota þær, til dæmis til að afgreiða pantanir sjálfvirkt úr eigin kerfi eftir að sending hefur verið bókuð hér.

Sjá einnig

Atburðirnir sjálfir eru skjalaðir undir Vefkrókar, og samningarnir og innheimtuloturnar sem pantanirnar verða til úr undir Áskriftarsamningar V2.

Forsendur

Til þess að vefþjónusturnar séu aðgengilegar þarf þrennt:

Leynilegan API lykil:

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

Að aðgangurinn noti áskriftarsamninga V2.
Að sendingar (shipping) séu virkjaðar fyrir aðganginn.

Ef eitthvað af þessu vantar skila slóðirnar 403 með skýringu í detail.

Skrifaðgerðirnar (fulfill og cancel) gera þá kröfu til viðbótar að afgreiðsla sé virk á aðganginum, hvort sem hún fer fram í Áskeli eða ytra kerfi. Lesaðgerðirnar halda áfram að skila pöntunum þótt slökkt sé á afgreiðslu — pantanir sem þegar eru til mega ekki hverfa — en þá er engri þeirra breytt hér.

Athugasemd

Seljandi sem selur áþreifanlega vöru en hefur engan flutningsaðila uppsettan fær samt pantanir. Þær bera þá "shipping_selection": null og tóman fulfillments lista; pöntunina þarf eftir sem áður að tína til og afgreiða.

Slóðir

GET  /api/v2/fulfillment-orders/
GET  /api/v2/fulfillment-orders/{id}/
POST /api/v2/fulfillment-orders/{id}/fulfill/
POST /api/v2/fulfillment-orders/{id}/cancel/

{id} er id pöntunarinnar, ekki number. number er hlaupandi númer pöntunarinnar innan aðgangsins og hentar vel til að vísa í hana gagnvart viðskiptavini, en er ekki uppflettilykill í vefþjónustunni.

Pöntun sem tilheyrir öðrum aðgangi skilar 404, ekki 403.

Sjálfgefið eru allar pantanir skilaðar í einum lista, nýjasta fyrst. Ef page_size fylgir með er svarið síðuskipt með count, next, previous og results.

Stöður pöntunar

Staða	Lýsing
`open`	Pöntunin er ný og engin sending hefur verið afgreidd.
`partially_fulfilled`	Hluti pöntunarinnar hefur verið afgreiddur.
`fulfilled`	Pöntunin telst afgreidd.
`cancelled`	Pöntunin var afturkölluð.

Síur

Færibreyta	Lýsing
`status`	Ein af stöðunum að ofan.
`contract`	Auðkenni áskriftarsamnings.
`customer`	Auðkenni viðskiptavinar.
`customer_reference`	Tilvísun viðskiptavinar úr þínu kerfi.
`updated_since`	Pantanir sem breyttust á eða eftir tímasetningunni.
`created_since`	Pantanir sem urðu til á eða eftir tímasetningunni.
`page_size`	Fjöldi pantana á síðu. Ef sleppt er skilast allt í einum lista.

updated_since og created_since taka ISO 8601 tímasetningu, til dæmis 2026-05-20T00:00:00Z. Stök dagsetning (2026-05-20) er túlkuð sem upphaf dagsins.

Aðvörun

Ógild sía skilar tómum lista, ekki villu. Það á við um bæði ótölulegt contract eða customer og tímasetningu sem ekki tekst að lesa. Samstillingarkeyrsla fær því ekki óvart allar pantanir til baka þegar bendillinn hennar er gallaður — en hún ætti að staðfesta að sían sé rétt mynduð þegar hún fær óvænt ekkert.

Samstilling

Einfaldasta samstillingin byggir á updated_since: geymdu hæsta updated_at sem þú hefur unnið úr og notaðu það sem bendil í næstu keyrslu.

python

import requests

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

# Bendillinn úr síðustu keyrslu. Dragðu smá frá honum svo pantanir sem
# vistuðust á sömu sekúndu og keyrslan endaði detti ekki niður á milli.
cursor = "2026-05-20T00:00:00Z"

response = requests.get(
    "https://askell.is/api/v2/fulfillment-orders/",
    params={"updated_since": cursor, "status": "open"},
    headers=headers,
)
response.raise_for_status()
orders = response.json()

for order in orders:
    handle_order(order)

if orders:
    # Pantanirnar eru í röð eftir stofnun, ekki uppfærslu, svo taktu hæsta gildið.
    cursor = max(order["updated_at"] for order in orders)

Svar

Svarið er nákvæmlega sömu gögn og fylgja fulfillment_order.* atburðunum, svo sama úrvinnsla gengur fyrir hvort tveggja.

{
  "id": 12345,
  "number": 42,
  "status": "open",
  "contract_id": 12345,
  "billing_run_id": 54321,
  "customer_id": 33482,
  "customer_reference": "customer-12345",
  "customer_name": "Jón Jónsson",
  "customer_email": "jon@example.com",
  "delivery_address": {
    "id": 9876,
    "delivery_name": "Jón Jónsson",
    "address_1": "Hringbraut 12",
    "address_2": "",
    "address_3": "",
    "zip_code": "101",
    "city": "Reykjavík",
    "state": null,
    "country": "IS"
  },
  "shipping_selection": {
    "id": 555,
    "option_id": 7,
    "handler": "posturinn",
    "delivery_mode": "pickup_point",
    "option_name": "Póstbox",
    "service_code": "DPO",
    "price_amount": "940.0000",
    "currency": "ISK",
    "location_id": "9591",
    "location_name": "Póstbox Hallveigarstíg",
    "location_address": "Hallveigarstíg 1 101 Reykjavík",
    "location": {
      "id": "9591",
      "name": "Póstbox Hallveigarstíg",
      "address": "Hallveigarstíg 1 101 Reykjavík",
      "street": "Hallveigarstíg 1",
      "zip_code": "101",
      "town": "Reykjavík",
      "external_id": null,
      "latitude": 64.1,
      "longitude": -21.9
    }
  },
  "lines": [
    {
      "id": 1111,
      "product_id": 222,
      "product_reference": "SKU-1",
      "product_name": "Kaffipoki",
      "quantity": 2,
      "quantity_fulfilled": 0
    }
  ],
  "fulfillments": [
    {
      "id": 333,
      "order_id": 12345,
      "handler": "posturinn",
      "carrier": "posturinn",
      "status": "booked",
      "provider_order_id": "PP123456789",
      "tracking_number": "PP123456789",
      "tracking_url": "",
      "weight_grams": 1000,
      "error": "",
      "booked_at": "2024-01-01T00:00:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "estimated_weight_grams": 1000,
  "metadata": {},
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Reitir sem vert er að staldra við

Reitur	Lýsing
`delivery_address`	Afrit heimilisfangsins eins og það var þegar pöntunin varð til; síðari breyting á samningnum hreyfir ekki við eldri pöntunum.
`shipping_selection`	Sendingarval viðskiptavinar, eða `null` þegar enginn flutningsaðili er uppsettur.
`shipping_selection.location`	Afhendingarstaður á uppbyggðu formi — auðkenni, heiti, gata, póstnúmer, staður og hnit — eða `null` þegar valið hefur engan stað.
`lines[].product_reference`	Vörunúmer seljanda (SKU), þ.e. það sem tínt er eftir. `null` ef vörunni hefur verið eytt úr vörulista.
`fulfillments`	Bókaðar sendingar, með rekjanúmeri þegar það liggur fyrir. Tómur listi þar til sending er bókuð.
`fulfillments[].handler`	Flutningsleiðin sem sendingin var bókuð með. Tómur strengur þegar ytra kerfi sendi með flutningsaðila sem Áskell hefur enga tengingu við.
`fulfillments[].carrier`	Hver bar pakkann: flutningsaðilinn sem ytra kerfi tilkynnti, annars `handler`.
`fulfillments[].tracking_url`	Slóð til að rekja sendinguna, eins og hún var tilkynnt með `fulfill`. Tómur strengur þegar engin var tilkynnt.
`estimated_weight_grams`	Áætluð heildarþyngd, eða `null` ef einhverja línu vantar þyngd — hálft mat er aldrei skilað sem heild.

Svar sendingar ber aldrei óunnin svör flutningsaðilans (provider_data); þau geyma meðal annars lyklana sem sendingarmiði er sóttur með. Það sem máli skiptir fyrir samþættingu er dregið út í reitina hér að ofan.

Afgreiða pöntun

POST /api/v2/fulfillment-orders/{id}/fulfill/

Tilkynnir að pöntunin hafi verið send úr vöruhúsi þínu. Áskell skráir sendinguna, merkir allar línur afgreiddar, setur pöntunina í fulfilled, sendir viðskiptavininum tilkynningu um að pöntunin sé á leiðinni og sendir fulfillment_order.fulfilled atburðinn — nákvæmlega eins og þegar pöntun er afgreidd í stjórnborðinu.

Beiðnin má vera tóm ({}); seljandi sem afhendir sjálfur hefur ekkert rekjanúmer að skrá. Allir reitir eru valfrjálsir:

Reitur	Lýsing
`tracking_number`	Rekjanúmer sendingarinnar, mest 128 stafir. Fylgir með í tilkynningunni til viðskiptavinar.
`tracking_url`	Slóð þar sem rekja má sendinguna. Geymd með sendingunni.
`provider_order_id`	Auðkenni sendingarinnar í kerfi flutningsaðilans, mest 128 stafir.
`carrier`	Flutningsaðilinn. `dropp` og `posturinn` eru þekktir og skrá sendinguna á þá; annað er geymt sem texti.
`weight_grams`	Þyngd pakkans í grömmum.

{
  "tracking_number": "PP123456789",
  "tracking_url": "https://posturinn.is/track/PP123456789",
  "provider_order_id": "shp_8812",
  "carrier": "posturinn",
  "weight_grams": 1000
}

Svarið er 200 með pöntuninni allri, sömu gögnum og GET skilar. Sendingin er komin í fulfillments listann í stöðunni shipped og quantity_fulfilled á línunum er orðið jafnt quantity.

Aðgerðin er ítrekunarheld (e. idempotent): sé pöntunin þegar afgreidd skilar hún 200 með óbreyttri pöntun, engin ný sending verður til og hvorki tölvupóstur né atburður er sendur aftur. Vöruhúskerfi sem endursendir beiðni eftir tímaútrás má því gera það áhyggjulaust.

Afgreidd pöntun sem hefur þegar bókaða sendingu í Áskeli (aðgangur sem afgreiðir í Áskel) fær rekjanúmerið skráð á þá sendingu í stað þess að ný verði til.

Afturkalla pöntun

POST /api/v2/fulfillment-orders/{id}/cancel/

Afturkallar pöntun sem ekki verður send, til dæmis þegar varan er ekki til. Beiðnin hefur ekkert meginmál og svarið er 200 með pöntuninni í stöðunni cancelled. Bókuð sending sem ekki er komin af stað er um leið afturkölluð Áskels megin og merkt með skýringu — hún er ekki afturkölluð hjá flutningsaðilanum, það þarf að gera þar.

Aðgerðin er líka ítrekunarheld: pöntun sem þegar er afturkölluð skilar 200 og fulfillment_order.cancelled atburðurinn er ekki sendur aftur.

Algengar villur

Villa	HTTP	Lýsing
Óheimilt	`401`	Enginn API lykill fylgdi beiðninni.
Óheimilt	`403`	Lykillinn er ekki leynilegur, aðgangurinn notar ekki áskriftarsamninga, eða sendingar eru ekki virkjaðar.
Ekki fundið	`404`	Pöntun með þetta `id` fannst ekki á aðganginum.
Aðferð ekki leyfð	`405`	`GET` slóðirnar taka ekki við skrifbeiðnum; notaðu `fulfill` eða `cancel`.
Ógild gögn	`400`	Reitur í beiðninni stóðst ekki athugun, til dæmis of langt `tracking_number`.
Staða stangast á	`409`	Aðgerðin á ekki við stöðu pöntunarinnar.

409 svarið ber code sem segir hvað stóð í vegi:

`code`	Lýsing
`order_cancelled`	Reynt var að afgreiða pöntun sem hafði verið afturkölluð.
`order_fulfilled`	Reynt var að afturkalla pöntun sem hafði þegar verið afgreidd.
`booking_in_progress`	Sending fyrir pöntunina er í bókun í Áskeli einmitt núna.

Fyrstu tvær stöðurnar eru endanlegar: pöntunin fer ekki þangað sem beiðnin ætlaði henni og endurtekning breytir engu. booking_in_progress er hins vegar tímabundin — bókun sem Áskell hóf er enn í gangi — og beiðnina má einfaldlega endurtaka andartaki síðar.

{
  "error": "The order has been cancelled.",
  "code": "order_cancelled"
}