1. Inledning

1.1. Om dokumentet

Denna beskrivning är ett tillägg av tjänstekontrakten i tjänstedomänen masterdata:citizen:citizen. Dokumentet beskriver hur tjänsten ”Hämta filer” är uppbyggd med hjälp av en SOAP-service för listning samt en REST-service hämtning. Valet att använda en SOAP+REST baseras på dokument ARK_0038 enligt Rivta standarden. Tjänsten för att lista tillgängliga filer är av typen SOAP (enligt Rivta2.1) och tjänsten för att hämta filer är av typen HTTP-REST. En REST-service tillåter olika typer av HTTP anrop GET, PUT, POST och DELETE. I ”hämta filer”-tjänsten är det endast GET som kommer att implementeras, då det bara är hämtning som kan utföras. Anrop mot tjänsterna sker med https(tvåvägs-SSL) och validering av certifikatet från tjänstekonsument utförs för att endast tillåta att tjänsten levererar data till tillåtna mottagare.

1.2. Konnektivitet

SOAP-tjänst för att lista tillgängliga filer är tillgängliga via Nationell Tjänsteplattform (NTjP), och är på så vis nåbar både via SJUNET och INTERNET. Dock saknar NTjP stöd för REST-baserade tjänster vilket medför att REST-tjänst för att hämta filer är enbart tillgänglig via SJUNET och med direktaccess mot tjänsteproducent.

2. Flöde

Flödet för att hämta filer börjar med anrop till SOAP-tjänsten GetFilesForOrderId (via NTjP). Specifikation finns i TKB för masterdata:citizen:citizen (www.rivta.se). En konsument anropar tjänsten med ett OrderId. PU-tjänsten returnerar ett svar innehållande 0..n referenser (unik URL för varje hämtbar fil) som konsumenten kan gå igenom för att hämta varje enskild fil via REST-tjänsten. Referensen som returneras användas i sin helhet för att hämta en fil.

3. GetFilesForOrderId

Se tjänstekontraktsbeskrivning https://bitbucket.org/rivta-domains/riv.masterdata.citizen.citizen

4. PuDownload

Tjänst för att hämta en fil. Tjänsten måste anropas för varje fil som ska hämtas. Således måste anrop föregås av anrop till tjänsten "lista tillgängliga filer" (GetFilersForOrderId) för att veta vilka filer som kan hämtas.

Konsumentens certifikat verifieras för att inga filer som inte tillhör konsumenten returneras. 

4.1. Exempel

4.1.1. Exempel på anrop

Tjänsten anropas genom:

https://<host>:<port>/pudownload/file/<GUID>

GUID kan se ut enligt följande: 7fbbe720-ec37-460b-9edf-780ff570f4fc

4.1.2. Exempel på svar

4.1.2.1. Svar om efterfrågad fil laddas ner:

Statuskod: 200
Content-Type: application/zip
Content-Disposition: attachment; filename="<filnamn>"
Transfer-Encoding: chunked
Content: fil (zippat xmldata enligt SKV's navetavisering-schema)

Schema för innehåll i zippad XML-fil följer Skatteverkets XSD Navetavisering V1

Struktur för filnamn (både ZIP och XML): <orderId>_<datum>_<löpnummer>.zip (samt .xml)
Exempel: 11111-22222-3333-75_20161103_1.zip 

4.1.2.2. Svar vid ogiltig förfrågan:

Statuskod: 400 BAD_REQUEST

 * Ogiltig context path
 * HSA-id för konsument saknas
 * Certifikat för OrderId matchar inte certifikat som används vid hämtning av fil
 * Filen har redan hämtats

Statuskod: 401 UNAUTHORIZED

 * Konsumenten saknar behörighet till tjänsten

Statuskod: 404 NOT FOUND

 * Begärd referens (GUID) existerar inte

Statuskod: 500 INTERNAL SERVER ERROR

 * Internt oförutsätt fel