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

```json
{
  "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`:

```json
"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ð:

```json
{
  "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

```json
[
  {
    "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:

```json
{
  "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`:

```json
{
  "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

### Skilagreina API

- [ ]  `POST /fund-payments` tekur við og vinnur úr skilum
- [ ]  `DELETE /fund-payments/{transactionId}` styður bakfærslu og fylgir reglum sjóðs um hvenær bakfærsla er leyfð (`200 REVERSED` / `403` / `404` / `409`)
- [ ]  `GET /fund-entities` skilar sjóðunum og tegundum sjóðafærslna sem innheimtuaðili styður
- [ ]  Svör nota `FundPaymentResponse` schema með réttum `response` enum gildum
- [ ]  `issues` fylkið er útfyllt fyrir `ACCEPTED_WITH_COMMENTS` og `REJECTED` svör
- [ ]  `transactionId` úr skilunum er endurtekið í hverju svari
- [ ]  `employeeTransactionRef` er vísað í villum sem tengjast tilteknum launþegai (ekki `nationalId`)
- [ ]  `summaries` eru kross-sannprófaðar á móti heildartölum færslna
- [ ]  Sannprófun tímabila er framfylgt (sama skilatímabil, engin áramótaspönn)
- [ ]  `POST /fund-payments/validation` innleitt (ef `validationEndpoint` er birt)
- [ ]  `entityTypeRules[].additionalAttributes` birtir sjóðasértæka viðbótarreiti með villuprófunarreglum (`name`, `type`, og eftir atvikum `required`, `allowedValues`)
- [ ]  `paymentEntry.additionalAttributes` eru villuprófaðir gegn reglum sjóðsins (gerð, `required`, `allowedValues`)