Gränssnitt

Filtransport har ett enkelt textbaserat gränssnitt över HTTP med TLS. Kommandon skickas som HTTP GET eller POST.

Vid testning av HTTP gränssnitt (som Filtransport) används ofta cURL. Exempel på cURL anrop mot Filtransport finns i menyn under Testa filtransport.

Anrop

Nedan följer en komplett beskrivning av möjliga anrop mot Filtransport.

Utdatafil

I följande tabeller beskrivs värden för URL-parametern utdatafil.

ny
Funktion Lista utdatafiler med status NY
Resultat Lista med nya utdatafiler
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?utdatafil=ny
Exempel - Svar (HTTP 200) SPARAvisering_2021_SPAR501.xml.zip
SPARUrval_2021_SPAR501.xml.zip
hamtad
Funktion Lista utdatafiler med status HAMTAD
Resultat Lista med hämtade utdatafiler
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?utdatafil=hamtad
Exempel - Svar (HTTP 200) SPARAvisering_2020_SPAR501.xml.zip
SPARUrval_2020_SPAR501.xml.zip
alla
Funktion Lista utdatafiler oavsett status
Resultat Lista med alla utdatafiler och status per fil
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?utdatafil=alla
Exempel - Svar (HTTP 200) SPARAvisering_2021_SPAR501.xml.zip NY
SPARUrval_2020_SPAR501.xml.zip HÄMTAD

Indatafil

I följande tabeller beskrivs värden för URL-parmetern indatafil.

mottagen
Funktion Lista indatafiler med status mottagen
Resultat Lista med indatafiler med status mottagen
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?indatafil=mottagen
Exempel - Svar (HTTP 200) SPARAvisering_2021_SPAR501.xml
SPARUrval_2021_SPAR501.xml.zip
validerad
Funktion Lista indatafiler med status validerad
Resultat Lista med indatafiler med status validerad
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?indatafil=validerad
Exempel - Svar (HTTP 200) SPARAvisering_2021_SPAR501.xml
SPARUrval_2021_SPAR501.xml.zip
inkorrekt
Funktion Lista indatafiler med status inkorrekt
Resultat Lista med indatafiler med status inkorrekt
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?indatafil=inkorrekt
Exempel - Svar (HTTP 200) SPARAvisering_2021_SPAR501.xml
SPARUrval_2021_SPAR501.xml.zip
alla
Funktion Lista indatafiler oavsett status
Resultat Lista med alla indatafiler och status per fil
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?indatafil=alla
Exempel - Svar (HTTP 200) SPARAvisering_2021_SPAR501.xml MOTTAGEN
SPARUrval_2020_SPAR501.xml.zip INKORREKT

Status

I följande tabeller beskrivs värden för URL-parametern status.

<filnamn>
Funktion Visa status på filen <filnamn>
Resultat Filnamn med status
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?status=SPARAvisering_2021_SPAR501.xml
Exempel - Svar (HTTP 200) SPARAvisering_2021_SPAR501.xml MOTTAGEN

Felrapport

I följande tabeller beskrivs värden för URL-parametern felrapport.

<uppdragsID>
Funktion Hämtar en rapport över funna fel i den uppladdade infilen för det givna uppdraget
Resultat Lista med radnummer och felmeddelanden i CSV-format.
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?felrapport=12345

Saknade

Personnumren i infilen för ett uppdrag kan höra till personer som saknas i SPAR. Med parametrarna ”saknade” returneras en CSV-fil med personnummer för dessa. Om inga sådana personnummer finns, returneras en tom lista. Informationen uppdateras i samband med uppdragskörningar.

I följande tabeller beskrivs värden för URL-parmetern saknade.

<uppdragsID>
Funktion Visar vilka personer i den uppladdade infilen för det givna uppdraget som saknas i SPAR.
Resultat Lista med personnummer i CSV-format.
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?saknade=12345
Exempel - Svar (HTTP 200) PERSONNUMMER
188002210188
188002230178

Avregistrerade

Personnumren i infilen för ett uppdrag kan höra till personer som är avregistrerade. Med parametrarna ”avregistrerade” returneras en CSV-fil med personnummer för dessa. Om inga sådana personnummer finns, returneras en tom lista. Resultatet är de personer som är avregistrerade vid anropstilfället, oavsett när infilen lämnades eller uppdraget kördes.

I följande tabeller beskrivs värden för URL-parametern avregistrerade.

<uppdragsID>
Funktion Visar vilka personer i den uppladdade infilen för det givna uppdraget som är avregistrerade i SPAR.
Resultat Lista med personnummer i CSV-format.
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?avregistrerade=12345
Exempel - Svar (HTTP 200) PERSONNUMMER
188002210188
188002230178

Hämta

I följande tabeller beskrivs värden för URL-parametern hamta.

<filnamn>
Funktion Hämta filen <filnamn>
Resultat Filen <filnamn>
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?hamta=filnamn.xml

Gränssnittet erbjuder möjligheten att administrera XML-schemaversion för ett uppdrag. Det går att se vald schemaversion, se giltiga schemaversioner, samt ändra schemaversion. Se följande tre tabeller för mer information.

Visa version

I följande tabeller beskrivs värden för URL-parmetern version_visa.

<uppdragsID>
Funktion Visar det angivna uppdragets nuvarande schemaversion.
Resultat Uppdragets schema-version i CSV-format.
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?version_visa=12345
Exempel - Svar (HTTP 200) VERSION
20160213

Giltiga versioner

I följande tabeller beskrivs värden för URL-parametern version_giltiga.

<uppdragsID>
Funktion Visa giltiga schemaversioner för det angivna uppdraget.
Resultat Giltiga schemaversioner för uppdraget i CSV-format.
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?version_giltiga=12345
Exempel - Svar (HTTP 200) VERSION
2019.1
20160213

Uppatera version

I följande tabeller beskrivs värden för URL-parametern version_uppdatera (Id till det uppdrag vars version som ska uppdateras) tillsammans med version (den önskade versionen).

<uppdragsID> och <version>
Funktion Sätt schemaversion
Resultat Ursprunglig samt ny schemaversion i CSV-format.
HTTP GET
Exempel - Fråga ext-filer.statenspersonadressregister.se/v2/?version_uppdatera=12345&version=2019.1
Exempel - Svar (HTTP 200) VERSION;TIDIGARE_VERSION
2019.1;20160213

Lämna fil

I följande tabell beskrivs förutsättningar för att lämna en fil via Filtransport.

file
Funktion Lämna fil
HTTP POST
Content-Type multipart/form-data
Form Data (file=) Fil att ladda upp
URL ext-filer.statenspersonadressregister.se/v2/
Exempel - Svar (HTTP 201) Fil uppladdad: SPARInfilPersonNr.xml

Svarsmeddelande

Svaret levereras som text och innehåller en lista på de filer som aktören begärt uppgifter om. Listan sorteras efter datum och tid för när resultatfilen skapades (mest aktuella/senast skapade först).

Om listan innehåller filer med flera olika statusar visas statusvärdet bredvid filnamnet. Exempel:

 SPARAvisering_2021_SPAR501.xml.zip NY
 SPARUrval_2020_SPAR501.xml.zip HÄMTAD

Infiler kan ha följande statusar:

Infil status Innebörd
MOTTAGEN Filen är mottagen, men ännu ej validerad av SPAR-applikationen.
VALIDERAD Filen är mottagen, validerad och inläst.
INKORREKT Filen är mottagen, men har visat sig vara inkorrekt.

Resultatfiler kan ha följande statusar:

Resultatfil status Innebörd
NY Filen har producerats av SPAR och är redo för hämtning.
HÄMTAD Filen har hämtats av aktören.

Felrapport infiler

Om en infil fått status INKORREKT finns möjlighet att få mer information om felet via anropet Felrapport. Rapporten listar då alla funna fel för den senast inkomna infilen till ett givet uppdrag. Svaret returneras i CSV-format (Comma Separated Values) där första raden innehåller kolumnrubrikerna för rapporten och resterande information är varje funnet felmeddelande, radvis, eller en tom lista om inga fel påträffats.

Följande rubriker finns i felrapporten:

Rubrik Innehåll
RADNUMMER Radnummer i infilen där felet påträffas. Innehåller -1 om radnumret är okänt (eller ej applicerbart).  
FELMEDDELANDE Textmeddelande som beskriver felet i detalj. Meddelandet är omslutet av citationstecken och har max 2000 tecken.  

Exempel på en felrapport:

RADNUMMER;FELMEDDELANDE
12;”The content of elements must consist of well-formed character data or markup.”

Felmeddelanden

Vid fel returneras texten ”ERROR”, följd av en beskrivande text. Texterna kan komma att ändras.

I dagsläget finns följande felmeddelande

Felmeddelande Beskrivning
ERROR: Ogiltigt uppdragsid: 12345 Om man som parametervärde anger ett uppdrag man inte har behörighet till, eller som det inte kan lämnas infil till, returneras detta fel.
ERROR: Kundens konto är inte aktiv i SPAR Om den kund som organisationscertifikatet är knuten till inte är aktiv.
ERROR: Angiven kund är ej registrerad som fillämnare eller filhämtare på något uppdrag Om den kund som organisationscertifikatet är knuten till inte är kopplad som leveransmottagare till något uppdrag.