ePalkat API: entries - palkkarivit

1) Yleiskuvaus & autentikointi

• Palvelu: reports → Metodi: entries
• Autentikointi: Basic Authentication (käytä Authorization: Basic <base64(user:pass)>)
• Vaste: JSON
• Palauttaa palkkarivit annetuilla rajauksilla.

2) Päätepisteet (endpoints)

• POST /entries — suodatusparametrit JSON-rungossa
• GET /entries?… — suodatusparametrit kyselynä
• GET /reports/entries?… — kokoelmahaku
• GET /reports/entries/{id} — yksittäinen rivi (path-parametrina id)

3) Kyselyparametrit (suodatus & sivutus)

Alla olevat parametrit ovat valinnaisia, ellei toisin mainita. Ne voidaan antaa joko POST-rungossa (JSON) tai GET-kyselyn parametreina.

4) Vastausrakenne

{
  "entries_response": {
    "entries": [ /* rivitaulukko, katso alla */ ],
    "skippedrecords": <int>,
    "resultcomplete": <int>
  }
}

• entries: taulukko rivikohteista (kentät alla).
• skippedrecords: palauttaa ohitettujen rivien määrän.
• resultcomplete: 1 = kaikki tulokset palautettu; 0 = hae lisää kasvattamalla skiprecords-arvoa.

5) Rivilistan kentät (entries[])

Nämä ovat palautusdatan kentät. Huom. merkintä “Not used when doing a GET” alkuperäisessä ohjeistuksessa tarkoittaa, ettei kenttää käytetä GET-kyselyn kyselyparametrina, mutta se voi esiintyä vastauksessa.

6) Sivutus & tuloksen täydellisyys

• Sisääntulo: maxrecords (sivukoko) + skiprecords (offset).
• Vaste: skippedrecords kertoo ohitettujen määrän; resultcomplete = 1, kun kaikki rivit on palautettu.

7) Esimerkit

POST /entries

POST /entries
Authorization: Basic <base64(user:pass)>
Content-Type: application/json
Accept: application/json

{
  "personnumber": "12345",
  "period": "2025-08",
  "startdate": "2025-08-01",
  "enddate": "2025-08-31",
  "maxrecords": 100,
  "skiprecords": 0
}

GET /entries

GET /entries?personnumber=12345&period=2025-08&maxrecords=100&skiprecords=0
Authorization: Basic <base64(user:pass)>
Accept: application/json

GET /reports/entries/{id}

GET /reports/entries/5
Authorization: Basic <base64(user:pass)>
Accept: application/json

cURL

# POST
curl -u "user:pass" -H "Content-Type: application/json" -H "Accept: application/json"   -d '{"personnumber":"12345","period":"2025-08","maxrecords":100,"skiprecords":0}'   https://<host>/entries

# GET
curl -u "user:pass" -H "Accept: application/json"   "https://<host>/entries?personnumber=12345&period=2025-08&maxrecords=100&skiprecords=0"

JavaScript (fetch)

const creds = btoa("user:pass");
const url = "/entries?personnumber=12345&period=2025-08&maxrecords=100&skiprecords=0";

fetch(url, {
  method: "GET",
  headers: {
    "Authorization": "Basic " + creds,
    "Accept": "application/json"
  }
})
.then(r => r.json())
.then(data => console.log(data.entries_response));

8) Virhevastaus

Virheet palautuvat listassa ServiceErrors (kentät: ErrorNumber, ErrorPosition, ErrorRecordID, ErrorDescription, ErrorRecomendation).

9) Huomioita

• Yksittäisen rivin haku vaatii id-arvon /reports/entries/{id}-polussa.
• Esimerkeissä käytetty päivämääräformaatti on ohjeellinen; käytä ympäristösi vaatimusten mukaista formaattia.