Þróunarleiðbeiningar

Skilagrein — Innleiðingarleiðbeiningar fyrir innheimtuaðila og þróunaraðila launakerfa

Þessar þróunarleiðbeiningar eru fyrir:

innheimtuaðila sem taka við skilagreinum frá launakerfum og uppfæra í þeim tilgangi vefþjónustur fyrir samskipti við launakerfi.
þróunaraðila launakerfa sem senda innheimtuaðilum skilagreinar og uppfæra í þeim tilgangi samskipti við skilagrein.is og vefþjónustur innheimtuaðila.

1. Yfirlit

Þessar leiðbeiningar gilda fyrir útgáfu 2.0 sem byggir á JSON REST API og kemur í staðinn fyrir eldra XML-snið (útgáfu 1.0) sem verður útleitt hjá innheimtuaðilum í kjölfar uppfærslu.

Innheimtuaðili ber ábyrgð á:

Að útfæra well-known uppgötvunarslóð svo launakerfi finni vefþjónustur sjálfvirkt.
Að útfæra vefþjónustu (e. API) til að taka á móti og vinna úr skilagreinum.
Að gefa út OAuth 2.0 client credentials til launagreiðenda sem eru samþykktir notendur hjá viðkomandi innheimtuaðila.
Að skila stöðluðum svörum svo launakerfi geti meðhöndlað niðurstöður á samræmdan hátt.

OpenAPI skilgreiningarnar eru tvær:

Skilgreining	Tilgangur
`service-discovery.yaml`	Uppgötvun — segir launakerfum hvar API-ið er og hvernig á að auðkenna sig
`fund-submissions.yaml`	Kjarnavirkni — móttaka, sannprófun og staðfesting skilagreina

2. Arkitektúr

Launakerfi                                Innheimtuaðili
     │                                        │
     │  GET /.well-known/skilagrein-config    │
     │ ─────────────────────────────────────► │  (engin auðkenning)
     │ ◄───────────────────────────────────── │
     │  { endpoint, tokenUrl, scope, ... }    │
     │                                        │
     │  POST {tokenUrl}                       │
     │  client_credentials grant              │
     │ ─────────────────────────────────────► │  Auðkenningarþjónn
     │ ◄───────────────────────────────────── │
     │  { access_token, expires_in, ... }     │
     │                                        │
     │  POST {endpoint}/fund-payments         │
     │  Authorization: Bearer <token>         │
     │ ─────────────────────────────────────► │
     │ ◄───────────────────────────────────── │
     │  201 / 400 / 422 + FundPaymentResponse │

3. Uppgötvunarslóð — Well-Known Configuration

Launakerfi finna vefþjónustuna með því að sækja well-known uppgötvunarskjal, sem er aðgengilegt á þessari slóð:

GET /.well-known/skilagrein-configuration

Þessi slóð verður að vera opin — engar auðkenningar krafist.

3.1 Nauðsynlegir svarreitir

Reitur	Tegund	Skylda	Lýsing
`schemaVersion`	string	✅	Útgáfa skilgreiningarinnar (núna `"1.0"`)
`collectorId`	string	✅	SAL númer innheimtuaðila
`apiVersions`	array	✅	Að minnsta kosti ein API útgáfa (sjá að neðan)

Hver færsla í apiVersions verður að innihalda:

Reitur	Tegund	Skylda	Lýsing
`apiVersion`	string	✅	Útgáfustrengur, t.d. `"1.0"`
`validFrom`	date	✅	Dagsetning þegar þessi útgáfa tók gildi
`validTo`	date/null	—	Lokadagsetning, `null` ef enn virk
`endpoint`	URI	✅	Grunnslóð Skilagreina API
`validationEndpoint`	URI	—	Slóð á valfrjálsa villuprófunarslóð fyrir þessa útgáfu. Sleppt ef ekki stutt
`openApiUrl`	URI	✅	Slóð á útgefna OpenAPI skilgreiningu innheimtuaðila
`authentication`	object	✅	OAuth stillingar (sjá kafla 4)

3.2 Dæmi um svar

{
  "schemaVersion": "1.0",
  "collectorId": "1234",
  "apiVersions": [
    {
      "apiVersion": "1.0",
      "validFrom": "2026-01-01",
      "validTo": null,
      "endpoint": "https://api.example.is/v1/fund-payments",
      "validationEndpoint": "https://api.example.is/v1/fund-payments/validation",
      "openApiUrl": "https://api.example.is/v1/openapi.json",
      "authentication": {
        "type": "oauth2_client_credentials",
        "tokenUrl": "https://auth.example.is/connect/token",
        "scope": "skilagrein",
        "credentialContact": {
          "description": "Hafðu samband við okkur til að fá OAuth aðgangsupplýsingar (client ID og secret)",
          "email": "api@example.is",
          "url": "https://developer.example.is/access"
        }
      }
    }
  ]
}

Ath.: Ef villuprófunarslóðin er ekki innleidd skal sleppa validationEndpoint reitnum úr viðkomandi apiVersions færslu.

4. Auðkenning

Tækniforskriftin miðar við þrjár auðkenningarleiðir : [oauth, basic, none]. Miðað er við að innheimtuaðilar noti OAuth en það er ákvörðun hvers og eins innheimtuaðila.

Stranglega er mælt gegn því að nota basic og none. Ef basic (user+pass) er notað þá er það sett í header.

Þessi kafli lýsir hvað innheimtuaðili þarf að útfæra og hvernig flæðið lítur út frá sjónarhorni launakerfis, séu vefþjónustur fyrir skilagreinar auðkenndar með OAuth 2.0 Client Credentials (client_credentials grant)

4.1 Það sem innheimtuaðili þarf að útfæra

Innheimtuaðili er bæði resource server (þar sem API er hýst) og sá aðili sem gefur út client credentials til launagreiðenda (launakerfa). Innheimtuaðili getur rekið eigin authorization server eða nýtt þriðja aðila (en. identity provider), en ytra viðmótið verður að fylgja stöðluðu client_credentials grant.

Authorization server þarf að:

Taka við POST beiðni á tokenUrl sem birt er í well-known stillingunum.
Styðja client_credentials grant type.
Krefjast scope gildisins skilagrein (eða annað scope sem innheimtuaðili skilgreinir og birtir).
Skila stöðluðu OAuth 2.0 token svari með access_token og expires_in.
Gefa út tokens sem Bearer tokens (venjulega á JWT sniði, en sniðið er ákvörðun innheimtuaðila) sem API fyrir skilagreinar getur staðfest við hverja beiðni.

Skilagreina API þarf að:

Hafna beiðnum sem vantar Authorization haus með 401 Unauthorized svari.
Hafna útrunnum eða ógildum tokens með 401 Unauthorized svari.
Hafna gildum tokens sem vantar nauðsynlegt scope með 403 Forbidden svari.
Samþykkja beiðnir með gildum Bearer token.

4.2 Útgáfa auðkennisupplýsinga (client credentials)

Launakerfi lesa credentialContact í well-known skjalinu og hafa samband við innheimtuaðila til að fá API aðgang. Ferlið ætti að ná yfir:

Staðfestingu á auðkenni rekstraraðilans sem óskar aðgangs.
Útgáfu á client_id og client_secret pari.
Upplýsingagjöf um tokenUrl og scope sem á að nota.

credentialContact hluturinn í well-known stillingunum ætti alltaf að innihalda að minnsta kosti description reitinn. Einnig er mælt með því að hafa með email og/eða url:

"credentialContact": {
  "description": "Hafðu samband við okkur til að fá OAuth auðkennisupplýsingar (client ID og secret)",
  "email": "api@example.is",
  "url": "https://developer.example.is/access"
}

4.3 Token beiðni (sjónarhorn launakerfis)

Launakerfi sækir token með því að senda staðlaða client credentials beiðni á tokenUrl:

POST https://auth.example.is/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<client_id>
&client_secret=<client_secret>
&scope=skilagrein

Þjónninn ætti að svara með:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "skilagrein"
}

4.4 Auðkennd API köll

Launakerfi setja access token sem Bearer token á hvert API kall:

POST https://api.example.is/v1/fund-payments
Authorization: Bearer eyJhbGci...
Content-Type: application/json

{ ... }

4.5 Gildistími og endurnýjun tokens

Tokens renna út eftir expires_in sekúndur. Launakerfi eiga að sækja nýjan token áður en núverandi rennur út.
API á að skila 401 Unauthorized fyrir útrunna tokens. Launakerfi endurauðkenna sig sjálfvirkt við 401 svar.
Ekki skila 200 OK með villuskilaboðum fyrir auðkenningarvillur — mælt er með að nota frekar réttan HTTP stöðukóða.

4.6 Öryggisráðleggingar

Nota ætti eingöngu HTTPS — hafna skal ódulkóðuðum HTTP tengingum.
Nota ætti skammlífa access tokens (5 mínútur er algengt viðmið).
Takmarka ætti scope vandlega — skilagrein scope ætti aðeins að veita þau réttindi sem þarf til skila.
Innheimtuaðili ætti að hafa ferli til að endurnýja client secrets hratt ef grunur er um að leyndarmál hafi lekið, og bjóða rekstraraðilum sjálfsafgreiðslu eða tengilið til að endurnýja aðgangsupplýsingar.

5. Skilagreina API

5.1 `POST /fund-payments` — Skil

Senda inn skilagrein til vinnslu.

POST {endpoint}/fund-payments
Authorization: Bearer <token>
Content-Type: application/json

HTTP stöðukóðar

Staða	Merking
`201 Created`	Skil móttekin. Sjá `response` reit í body fyrir niðurstöðu (`ACCEPTED` eða `ACCEPTED_WITH_COMMENTS`).
`400 Bad Request`	Gölluð beiðni — uppbyggingar- eða sniðvilla áður en viðskiptasannprófun fer fram.
`422 Unprocessable Entity`	Skilunum var hafnað vegna villuprófunarvillna. Sjá `issues` fylkið í svari.

Ath.: 201 þýðir ekki sjálfkrafa að skilagrein hafi verið samþykkt að fullu — alltaf skal athuga response reitinn í body.

5.2 `POST /fund-payments/validation` — Villuprófun (valfrjálst)

Endapunktur fyrir villuprófun (dry-run): villuprófar skilin án þess að vinna úr þeim eða bóka réttindi. Nýtist launakerfum til að athuga hvort villur séu til staðar áður en raunveruleg skil eru framkvæmd.

Þessi slóð er valfrjáls. Ef hún er innleidd fylgir validationEndpoint með í well-known stillingunum.

Uppbygging beiðna og svara er eins og fyrir POST /fund-payments.

5.3 `DELETE /fund-payments/{transactionId}` — Bakfærsla

Bakfæra (afturkalla) áður innsenda skilagrein í heild sinni út frá transactionId. Kemur í stað þess að senda mínus-skilagrein til að afturkalla heila skilagrein.

DELETE {endpoint}/fund-payments/{transactionId}
Authorization: Bearer <token>

Sjóðir geta sett eigin viðskiptareglur um hvenær bakfærsla er leyfð (t.d. ekki hægt að bakfæra skilagrein sem þegar hefur verið bókuð). Ef aðeins þarf að leiðrétta hluta af skilagrein (stakar færslur) skal senda leiðrétta (mínus) skilagrein í gegnum POST /fund-payments.

HTTP stöðukóðar

Staða	Merking
`200 OK`	Skilagrein bakfærð. `response` reitur í body er `REVERSED`.
`403 Forbidden`	Aðili hefur ekki heimild til að bakfæra þessa skilagrein.
`404 Not Found`	Engin skilagrein fannst með uppgefnu `transactionId`.
`409 Conflict`	Ekki hægt að bakfæra skilagrein (þegar bókuð eða þegar bakfærð). Sjá `issues` í body fyrir nánari skýringu.

5.4 `GET /fund-entities` — Studdir sjóðir

Skilar lista yfir sjóði sem innheimtuaðili innheimtir fyrir, ásamt tegund sjóðafærslna (e. entity types), sjálfgefnum hlutföllum (prósentum) og dýnamískum viðbótarreitum (additionalAttributes) fyrir hvern sjóð.

GET {endpoint}/fund-entities
Authorization: Bearer <token>

Launakerfi geta notað þessar upplýsingar til að uppfæra stillingar niður á sjóði.

Sjóðasértækir viðbótarreitir (`additionalAttributes`)

Í stað þess að skilgreina fasta sértæka reiti fyrir B-deildir (eða aðra sérsjóði) er notast við almennt, dýnamískt fyrirkomulag: hver sjóður lýsir í entityTypeRules[].additionalAttributes hvaða viðbótarreitum hann tekur við og hvernig þeir eru villuprófaðir. Launakerfi senda gildi þessara reita inn í paymentEntry.additionalAttributes sem { name, value } pör.

Lausnin er almenn og ekki bundin sérstaklega við B-deildir — önnur félög/sjóðir geta einnig skilgreint eigin viðbótarreiti (t.d. vegna nýrra kjarasamninga) án breytinga á tækniforskriftinni.

Hver færsla í additionalAttributes hefur eftirfarandi reiti:

Reitur	Tegund	Skylda	Lýsing
`name`	string	✅	Heiti reits. Verður að passa við `name` í `paymentEntry.additionalAttributes`.
`type`	enum	✅	Týpa gildisins: `string`, `number`, `boolean` eða `date`. Innheimtuaðili túlkar strenginn skv. þessari týpu.
`description`	string	—	Læsileg lýsing (t.d. "Bundin séreign" eða "Starfshlutfall").
`required`	boolean	—	Hvort reiturinn sé skyldubundinn á öllum samsvarandi `paymentEntry`. Sjálfgefið `false`.
`allowedValues`	array	—	Valkvæður lokaður listi yfir leyfileg gildi. Ef tilgreindur verður `value` að vera eitt af þessum.

Dæmi um svar

[
  {
    "entityNo": "1005",
    "entityTypeRules": [
      {
        "entityType": "L",
        "defaultPercentage": 0.12,
        "additionalAttributes": [
          { "name": "salarySymbol", "type": "string", "description":"Launatákn", "allowedValues": ["001", "B", "V", "032"] }
        ]
      },
      {
        "entityType": "F",
        "defaultPercentage": 0.01,
        "additionalAttributes": [
          { "name": "daysAtSea", "type": "number", "description": "Dagar á sjó" }
        ]
      }
    ]
  }
]

Dæmi: B-deildarsjóður

B-deildarsjóður getur skilgreint eftirfarandi viðbótarreiti á sinni sjóðafærslutegund — þ.m.t. reitir sem áður voru fastir í tækniforskriftinni:

{
  "entityNo": "1234",
  "entityTypeRules": [
    {
      "entityType": "L",
      "defaultPercentage": 0.155,
      "additionalAttributes": [
        { "name": "salarySymbol",      "type": "string", "required": true,  "allowedValues": ["001", "B", "V", "032"], "description": "Launatákn" },
        { "name": "employmentRatio",   "type": "number", "required": true,  "description": "Starfshlutfall" },
        { "name": "salaryTable",       "type": "string", "description": "Launatafla" },
        { "name": "salaryCategory",    "type": "string", "description": "Launaflokkur" },
        { "name": "salarySubCategory", "type": "string", "description": "Launaþrep" },
        { "name": "additionalAmount",  "type": "number", "description": "Bundin séreign" }
      ]
    }
  ]
}

Launakerfi sendir samsvarandi gildi inn í paymentEntry.additionalAttributes:

{
  "entityType": "L",
  "entityNo": "1234",
  "amount": 50000,
  "amountPayrollPercentage": 0.155,
  "additionalAttributes": [
    { "name": "salarySymbol",      "value": "001" },
    { "name": "employmentRatio",   "value": "1.0" },
    { "name": "salaryTable",       "value": "A" },
    { "name": "salaryCategory",    "value": "CAT1" },
    { "name": "salarySubCategory", "value": "SUB1" },
    { "name": "additionalAmount",  "value": "0" }
  ]
}

Villuprófunarreglur fyrir viðbótarreiti (sjá einnig kafla 8):

Reitur sem er merktur required: true verður að vera til staðar á öllum samsvarandi paymentEntry.
value verður að vera túlkanlegt sem type (t.d. number reitur fær gilt tölugildi).
Ef allowedValues er tilgreint verður value að vera eitt af þeim gildum.
Reitir sem ekki eru tilgreindir í additionalAttributes reglum sjóðsins ættu að vera hunsaðir eða valda viðvörun (warning).

6. Uppbygging beiðna

6.1 Efsta lag: `FundPaymentSubmission`

Reitur	Tegund	Skylda	Lýsing
`transactionId`	string	✅	Einkvæmt auðkenni úthlutað af launakerfi fyrir þessi skil. Notað til að para saman skil og svör.
`employerNationalId`	string	✅	Kennitala launagreiðanda — nákvæmlega 10 tölustafir, engin bandstrik.
`currency`	string	✅	ISO 4217 gjaldmiðilskóði (3 hástafir). Sjálfgefið er `ISK`. Fyrir ISK eru upphæðir heiltölur (engin aukastafir).
`paymentEntryGroups`	array	✅	Einn hópur á hvern launþega. Að minnsta kosti 1 færsla.
`summaries`	array	✅	Heildartölur eftir sjóði og tegund sjóðafærslna.

6.2 `PaymentEntryGroup`

Reitur	Tegund	Skylda	Lýsing
`nationalId`	string	✅	Kennitala launþega — nákvæmlega 10 tölustafir, engin bandstrik.
`employeeTransactionRef`	string	✅	Einkvæm tilvísun fyrir launþega innan skila. Skilað til baka í villuboðum til að auðkenna villur án þess að birta kennitölu launþega í svarskeytum.
`periodFrom`	date	✅	Upphafsdagur launatímabils (`YYYY-MM-DD`), tilheyrir því tímabili sem er skilað vegna.
`periodTo`	date	✅	Lokadagur launatímabils (`YYYY-MM-DD`), tilheyrir því tímabili sem er skilað vegna.
`paymentEntries`	array	✅	Greiðslufærslur.

6.3 `PaymentEntry`

Táknar greiðslufærslur fyrir hvern launþega niður á hverja tegund sjóðafærslu. Athugið að tegund sjóðafærslu hefur verið skipt upp þannig að framlag launþega og launagreiðanda er aðskilið í tvær færslur, hvora með sinni entityType, en eldra fyrirkomulag hafði þessar færslur saman í einni línu.

Reitur	Tegund	Skylda	Lýsing
`entityType`	string	✅	Stutt auðkenni fyrir tegund sjóðafærslu (t.d. `L1` fyrir iðgjald launþega, `F1` fyrir félagsgjald launþega, o.s.frv.). Nota skal `GET /fund-entities` til að sækja gildar tegundir sjóðafærslna.
`entityNo`	string	✅	Einkvæmt númer sjóðs (SAL).
`amount`	number	✅	Fjárhæð í tilgreindum gjaldmiðli.
`amountPayrollPercentage`	number	✅	Fjárhæð sem hlutfall af launastofni (decimal, t.d. `0.12` = 12%).
`date`	date	—	Greiðsludagsetning. Valfrjálst.
`additionalAttributes`	array	—	Dýnamískir sjóðasértækir reitir sem `{ name, value }` pör (t.d. `salarySymbol`, `employmentRatio`, `daysAtSea` og B-deildarreitir). Sjóðurinn skilgreinir hvaða reitir eru studdir og villuprófunarreglur þeirra í `entityTypeRules[].additionalAttributes` sem birtist í `GET /fund-entities`. Sjá kafla 5.4 fyrir B-deildardæmi.

6.4 `Summary`

Summa framlags er tekin saman í þessum reitum eftir tegund sjóðafærslu og sjóðsnúmeri, fyrir kross-samanburð á heildartölum.

Reitur	Tegund	Skylda	Lýsing
`entityNo`	string	✅	Sjóðsnúmer (SAL).
`entityType`	string	✅	Auðkenni tegundar sjóðafærslu.
`amountSum`	number	✅	Summa allra `amount` gilda fyrir þessa `entityNo` + `entityType` samsetningu.
`entityName`	string	—	Læsilegt heiti sjóðs. Valfrjálst.

7. Uppbygging svara

7.1 `FundPaymentResponse`

Svartýpa fyrir POST /fund-payments, POST /fund-payments/validation og DELETE /fund-payments/{transactionId} köll.

Reitur	Tegund	Skylda	Lýsing
`transactionId`	string	✅	Endurtekur `transactionId` úr skilunum.
`responseId`	string	✅	Einkvæm tilvísun innheimtuaðila fyrir þetta svar.
`response`	enum	✅	Niðurstaða — sjá gildi að neðan.
`postedAmount`	number	✅	Heildarupphæð sem var bókfærð.
`issues`	array	✅	Tóm þegar `ACCEPTED`. Inniheldur viðvaranir eða villur annars.

7.2 Niðurstöður svara

`response` gildi	HTTP staða	Merking
`ACCEPTED`	`201`	Skil samþykkt að fullu. `issues` fylkið er tómt.
`ACCEPTED_WITH_COMMENTS`	`201`	Samþykkt en með viðvörunum eða upplýsandi athugasemdum. Athuga skal `issues`.
`REJECTED`	`422`	Skilunum var hafnað. `issues` inniheldur villur.
`REVERSED`	`200`	Skilagrein bakfærð að fullu í gegnum `DELETE /fund-payments/{transactionId}`.

7.3 `Issue`

Reitur	Tegund	Skylda	Lýsing
`severity`	enum	✅	`"warning"` eða `"error"`
`message`	string	✅	Læsileg lýsing á vandamálinu.
`employeeTransactionRef`	string	—	Tilvísun á launþegafærsluna sem um ræðir. Til staðar þegar villan tengist tiltekinni launþegalínu. Ætti ekki að innihalda kennitölu launþega.
`entityType`	string	—	Tegund sjóðafærslu sem tengist villunni, ef við á.
`entityNo`	string	—	Sjóðsnúmer sem tengist villunni, ef við á.

Athugasemd um hönnun: employeeTransactionRef er notað viljandi í stað nationalId til að forðast flutning persónuupplýsinga í villuboðum. Gæði villuboða fara eftir því hvort launakerfið sendi employeeTransactionRef með skilunum.

8. Villuprófunarreglur

Þessar leiðbeiningar gilda sem lágmarks viðmið fyrir villuprófun skilagreina. Hver innheimtuaðili og sjóður getur bætt við sínum viðbótarreglum sem er gilda við villuprófun og/eða móttöku og bókun skilagreina.

Uppbygging

employerNationalId verður að vera nákvæmlega 10 tölustafir, engin bandstrik.
nationalId (launþegi) verður að vera nákvæmlega 10 tölustafir, engin bandstrik.
currency verður að vera gildur ISO 4217 3-stafa kóði.
periodFrom verður að vera fyrir eða jafn periodTo.
paymentEntries verður að innihalda að minnsta kosti 1 færslu.
paymentEntryGroups verður að innihalda að minnsta kosti 1 færslu.

Viðskiptareglur

Bæði periodFrom og periodTo verða að falla innan sama skilatímabils.
Launatímabil sem spanna áramót eru almennt ekki leyfð — villuprófun skal fara fram samkvæmt reglum innheimtuaðila.
amountPayrollPercentage ætti að samsvara væntri prósentu fyrir entityType eins og skilgreint er í GET /fund-entities svari innheimtuaðila.
summaries heildartölur verða að passa við summu samsvarandi færslna yfir alla hópa.
Samsetningar entityType og entityNo sem sendar eru inn verða að vera í því setti sem innheimtuaðilinn birtir með GET /fund-entities.
Prósentugildi eru gefin á bilinu 0 til 1 (0.5 = 50%)

Viðbótarreitir (`additionalAttributes`)

Sjóðasértækir viðbótarreitir (t.d. salarySymbol, employmentRatio, B-deildarreitir, daysAtSea) eru villuprófaðir gegn reglunum sem sjóðurinn birtir í entityTypeRules[].additionalAttributes í GET /fund-entities — sjá kafla 5.4 fyrir nánari lýsingu og dæmi.

paymentEntry.additionalAttributes[].name verður að passa við name sem sjóður birtir fyrir samsvarandi entityNo + entityType.
Reitir merktir required: true verða að vera til staðar á öllum samsvarandi paymentEntry.
value verður að vera túlkanlegt sem type reglunnar (string, number, boolean eða date).
Þegar allowedValues er tilgreint verður value að vera eitt af þeim gildum.
Reitir sem ekki eru tilgreindir í reglum sjóðsins ættu að vera hunsaðir eða valda viðvörun (warning).

9. Villumeðhöndlun

Nota skal staðlaða HTTP stöðukóða. Ekki ætti að skila 200 OK með villuupplýsingum.

Tilfelli	HTTP staða	`response` reitur
Samþykkt að fullu	`201`	`ACCEPTED`
Samþykkt með viðvörunum	`201`	`ACCEPTED_WITH_COMMENTS`
Sannprófunarvillur (viðskiptareglur)	`422`	`REJECTED`
Gölluð JSON eða nauðsynlega reiti vantar	`400`	`REJECTED`
Bakfærsla samþykkt	`200`	`REVERSED`
Bakfærsla — skilagrein fannst ekki	`404`	— (body valkvætt)
Bakfærsla — skilagrein þegar bókuð eða þegar bakfærð	`409`	`REJECTED` (skýring í `issues`)
Vantar Bearer token eða ógildur	`401`	— (body ekki krafist)
Gildur token en ónóg scope	`403`	— (body ekki krafist)
Innri villa þjóns	`500`	—

Fyrir 400 og 422 svör skal alltaf skila FundPaymentResponse body með issues fylkið útfyllt. Fyrir 401 og 403 er body valkvætt; ef það er tekið með ætti það að vera í lágmarki til að forðast að leka upplýsingum um af hverju auðkenning mistókst. Fyrir 5xx er body ekki krafist.

10. Innleiðingargátlisti

Nota má þennan gátlista til stuðnings við uppfærslu. Athugið að gátlistinn er ekki tæmandi og er einungis settur fram til stuðnings.

Uppgötvun

GET /.well-known/skilagrein-configuration skilar gildum CollectorConfiguration
Slóðin er opinber (engar auðkenningar krafist)
collectorId er kenni innheimtuaðila (SAL)
apiVersions inniheldur að minnsta kosti eina færslu með validFrom
endpoint vísar á virkt Skilagreina API
openApiUrl vísar á útgefna OpenAPI skilgreiningu innheimtuaðila
authentication blokkin er heil og rétt (sjá að neðan)
validationEndpoint er tekinn með ef sannprófunarslóðin er innleidd, annars sleppt

Auðkenning

OAuth 2.0 authorization server er í gangi og aðgengilegur á birtum tokenUrl
client_credentials grant type er stutt
skilagrein scope (eða samsvarandi) er krafist og framfylgt
Token svar inniheldur access_token, token_type: "Bearer" og expires_in
Skilagreina API staðfestir Bearer tokens við hverja beiðni
401 er skilað fyrir tokens sem vantar, eru útrunnir eða ógildir
403 er skilað fyrir gilda tokens sem vantar nauðsynlegt scope
Ferli fyrir útgáfu aðgangsupplýsinga er skjalfest í credentialContact
HTTPS er framfylgt á öllum slóðum

Þróunarleiðbeiningar

Skilagrein — Innleiðingarleiðbeiningar fyrir innheimtuaðila og þróunaraðila launakerfa

1. Yfirlit

2. Arkitektúr

3. Uppgötvunarslóð — Well-Known Configuration

3.1 Nauðsynlegir svarreitir

3.2 Dæmi um svar

4. Auðkenning

4.1 Það sem innheimtuaðili þarf að útfæra

4.2 Útgáfa auðkennisupplýsinga (client credentials)

4.3 Token beiðni (sjónarhorn launakerfis)

4.4 Auðkennd API köll

4.5 Gildistími og endurnýjun tokens

4.6 Öryggisráðleggingar

5. Skilagreina API

5.1 POST /fund-payments — Skil

HTTP stöðukóðar

5.2 POST /fund-payments/validation — Villuprófun (valfrjálst)

5.3 DELETE /fund-payments/{transactionId} — Bakfærsla

HTTP stöðukóðar

5.4 GET /fund-entities — Studdir sjóðir

Sjóðasértækir viðbótarreitir (additionalAttributes)

Dæmi um svar

Dæmi: B-deildarsjóður

6. Uppbygging beiðna

6.1 Efsta lag: FundPaymentSubmission

6.2 PaymentEntryGroup

6.3 PaymentEntry

6.4 Summary

7. Uppbygging svara

7.1 FundPaymentResponse

7.2 Niðurstöður svara

7.3 Issue

8. Villuprófunarreglur

Uppbygging

Viðskiptareglur

Viðbótarreitir (additionalAttributes)

9. Villumeðhöndlun

10. Innleiðingargátlisti

Uppgötvun

Auðkenning

Skilagreina API

5.1 `POST /fund-payments` — Skil

5.2 `POST /fund-payments/validation` — Villuprófun (valfrjálst)

5.3 `DELETE /fund-payments/{transactionId}` — Bakfærsla

5.4 `GET /fund-entities` — Studdir sjóðir

Sjóðasértækir viðbótarreitir (`additionalAttributes`)

6.1 Efsta lag: `FundPaymentSubmission`

6.2 `PaymentEntryGroup`

6.3 `PaymentEntry`

6.4 `Summary`

7.1 `FundPaymentResponse`

7.3 `Issue`

Viðbótarreitir (`additionalAttributes`)