Dato | Hva ble endret? |
---|---|
2021.06.17 | Oppdatert dokumentasjon for tilbakemeldinger. |
2021.07.05 | Justerte til riktig datatype for opplastning av vedlegg. |
2021.08.03 | Endret URL til valideringstjenesten til riktig verdi. |
2021.11.04 | Oppdatert URL for valideringstjenesten. |
2021.11.08 | Oppdatert liste over valideringsfeil |
2021.11.11 | Oppdatert feilmeldinger ved utfylling av mva-melding |
2021.12.08 | Oppdatert lovlig content type til binaerVedlegg |
2022.03.08 | Betalingsinformasjon kan lastes ned etter fullføring av innsending |
2022.06.24 | Endringer i forbindelse med utvidelse av dokumentasjon for andre meldingstyper |
2022.08.06 | Lagt til ny valideringsfeil for duplikate filnavn |
API'ene fungerer for følgende kategorier skattemeldinger for merverdiavgift: Ordinær mva-melding (RF-0002/0004), mva-melding for omvendt avgiftsplikt (RF-0005) og Skattemelding for merverdiavgiftskompensasjon (RF-0009). Når disse meldingene skal sendes til Skatteetaten fra et sluttbrukersystem (SBS) burde disse APIene brukes:
I API-beskrivelsen brukes mva-melding som en samlebetegnelse på de ulike meldingstypene. API'ene beskrives under.
Innsending av Mva Melding gjøres mot Skatteetatens Altinn3 Instans API for Innsending. Detaljert beskrivelse av Altinn3's Instans-API finnes her Altinn Studio Instans API. Inngående kjennskap til dette API'et er ikke nødvendig da denne dokumentasjonen dekker behovet for Mva Melding Innsending.
Det anbefales å benytte swagger dokumentasjonen sammen med denne API-beskrivelsen.
I tillegg finnes det et Python script som kan benyttes til manuell testing under Test
Prosessen gjennomføres med en sekvens av kall mot Instans-API´et og beskrives i detalj under sekvensdiagrammet og er som følger:
Autentisering
Utfylling mot Altinn3-App
Instans API'et til Mva Melding Innsending er tilgjengelig på denne URLen:
instansApiUrl = "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances"
I følgende sekvensdiagram vil applikasjonsUrl'en være skjult, så hvis det er skrevet POST: /intances/
så er det implisitt POST: instansApiUrl
For å veksle ID-porten-tokenet må man gjøre følgende kall:
GET `https://platform.tt02.altinn.no/authentication/api/v1/exchange/id-porten`
HEADERS:
"Authorization": "Bearer " + "{IDPortenToken}"
"content-type": "application/json"
og i responsen vil content være et rykende ferskt altinnToken som brukes som Bearer token i de resterende kallene. Tokenet har i dag en varighet på 8 timer. Senere i 2021 vil Altinn3 tilby refresh-tokens slik at en login vil kunne vare i opptil 3 mnd.
Tjenesten validerer innholdet i en skattemelding og returnerer en respons med eventuelle feil, avvik og advarsler. Tjenesten vil foreta følgende:
Skatteetaten forutsetter at valideringstjenesten blir kalt i forkant av innsending av mva-meldingen. Dette sikrer at mva-meldingen har korrekt format og innhold og øker sannsynligheten for at mva-meldingen vil bli godkjent ved innsending.
URL : POST https://<env>/api/mva/grensesnittstoette/mva-melding/valider
Hvor <env>
er Miljøspesifikk adresse f.eks. idporten-api-sbstest.sits.no
Body :
Eksempel : Innsending av XML på ugyldig format
POST https://idporten-api-sbstest.sits.no/api/mva/grensesnittstoette/mva-melding/valider
Header: Content-Type: application/xml
Med innhold (http body)som ikke passerer XML-validering basert på XSD:
<?xml version='1.0' encoding='UTF-8'?>
<mvaMeldingDto xmlns="no:skatteetaten:fastsetting:avgift:mva:skattemeldingformerverdiavgift:v1.0">
</mvaMeldingDto>
status: 200 Innhold (body)
<valideringsresultat>
<status>UGYLDIG_SKATTEMELDING</status>
<valideringsfeil>
<stiTilFeil>//innsending</stiTilFeil>
<valideringsDetaljer>
<feilmelding>Mva meldingen må være på gyldig format og passere XML skjema valideringen</feilmelding>
<alvorlighetsgrad>UGYLDIG_SKATTEMELDING</alvorlighetsgrad>
<avvikKode>MvaMeldingsinnhold_Xml_SkjemaValideringsfeil</avvikKode>
<informasjon>cvc-complex-type.2.4.b: The content of element 'mvaMeldingDto' is not complete. One of
'{"no:skatteetaten:fastsetting:avgift:mva:skattemeldingformerverdiavgift:v1.0":innsending}' is expected.
</informasjon>
</valideringsDetaljer>
</valideringsfeil>
</valideringsresultat>
En instans er et objekt i altinn som følger prosessen og datamodellen definert av en applikasjon. Skatteetaten har en Mva-Melding-Innsendings applikasjon som har en prosess med foreløpig tre steg for innsending. Stegene er utfyllings-, bekreftelses- og tilbakemeldings-steg.
En instans har i tillegg til å være et objekt, et data-objekt definert av en datamodell i appen.
Når en instans er opprettet vil den være mulig å oppdatere data-objektet til instansen og legge til andre data-objekter i appens datamodell. Dette gjøres i neste steg.
For å opprette en instans utfører man en POST mot instansApiUrl med et instanceOwner
-objekt hvor det fylles inn organisasjonsnummeret for organisasjonen det skal sendes mva melding for:
POST {applikasjonsUrl}/instances/
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
"content-type": "application/json"
CONTENT/BODY:
{
"instanceOwner": {
"organisationNumber": "{organisasjonsnummer}"
}
}
Dette kallet vil opprette instansen og returnere
Response HTTPCode: 201 (OK)
Content:
{
"id": "{partyId}/{instanceGuid}",
"instanceOwner": {
"partyId": "{partyId}",
"organisationNumber": "{organisasjonsnummer}"
},
"appId": "skd/{ApplikasjonsNavn}",
"org": "skd",
"selfLinks": {
"apps": "{instansUrl}", // appens instansUrl
"platform": "{platformUrl}" // altinn3 plattformens url for instansen
},
"data": [
{
"id": "{dataGuid}", // {dataGuid} kan benyttes i neste steg
"instanceGuid": "{instanceGuid}",
"dataType": "no.skatteetaten.fastsetting.avgift.mva.mvameldinginnsending.v1.0",
"contentType": "application/xml",
"blobStoragePath": "skd/{ApplikasjonsNavn}/{instanceGuid}/data/{dataGuid}",
"selfLinks": {
"apps": "{instanceDataAppUrl}", // {instanceDataAppUrl} kan benyttes i neste steg
"platform": "{instanceDataPlatformUrl}"
},
"size": 273,
"locked": false,
"refs": [],
"isRead": true,
"created": "2021-03-01T08:15:25.1139057Z",
"createdBy": "86257",
"lastChanged": "2021-03-01T08:15:25.1139057Z",
"lastChangedBy": "86257"
}
]
// resten av objektet er snippet bort
}
Resten av kallene i sekvensen for innsendingen benytter instansUrl
. Denne kan bli funnet fra responsen ved opprettelsen av instansen. Se i eksempel responsen over.
instansUrl
kan enten bruke selflinks.apps
eller ved å utlede fra instansApiUrl/{partyId}/{instanceGuid}
, hvor {partyId}
og {instanceGuid}
kan bli funnet i id
feltet for den returnerte instansen.
Eksempel på instansUrl: https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50/data/28abba46-dea8-4ab7-ba90-433abba906df
Respons 400 - Bad Request:
Respons 403 - Forbidden:
{"type":"https://tools.ietf.org/html/rfc7231#section-6.5.3","title":"Forbidden","status":403,"traceId":"00-44eab35cb9ca2049b24de316f380a774-a724e045b09dfc44-00"}
Denne feilmeldingen kan en få hvis en prøver å lage en instanse hvor innlogget bruker ikke har rettigheter til organisasjonen definert i request header. Dette vil da også gjelde hvis innlogget bruker ikke har tilstrekkelig roller for å opprette en instans.
Respons 404 - Not Found:
"Cannot lookup party: Failed to lookup party by organisationNumber: 123456789. The exception was: 404 - Not Found - "
Denne feilmeldingen kan en få hvis en setter organisasjonsnummeret i request headeren til noe ugyldig.
MvaMeldingInnsending er en datatype for metadata for innsendingen. Objektet man skal fylle ut blir skapt under instansieringen og vil kunne finnes i instans-objektets data
-liste og har "dataType": "no.skatteetaten.fastsetting.avgift.mva.mvameldinginnsending.v0.1"
. Siden dette objektet allerede finnes når man skal laste opp MvaMeldingInnsending, benyttes PUT for å oppdatere data-elementet.
Modellen for MvaMeldingInnsending finnes her: no.skatteetaten.fastsetting.avgift.mva.mvameldinginnsending.v1.0.xsd
Url til MvaMeldingInnsending har denne oppbygningen:
mvaMeldingInnsendingUrl = {instansApiUrl}/{partyId}/{instanceGuid}/data/{dataGuid}
hvor {dataGuid}
er id til data-objektet til instansen.
Det er 2 måter å komme frem til mvaMeldingInnsendingUrl
og begge benytter instansens data-liste-element som har datatypen no.skatteetaten.fastsetting.avgift.mva.mvameldinginnsending.v1.0
. Når instansen blir skapt finnes bare ett element i lista.
Fra data-elementet kan man enten:
flette inn {dataGuid}
som finnes som verdi i "id"
i oppbygningen over,
{instansApiUrl}/data/{dataGuid}
eller bruke selfLinks.apps
verdien {instanceDataAppUrl}
, som vist i instans-responsen i forrige steg.
mvaMeldingInnsendingsUrl = {instanceDataAppUrl}
Man laster opp MvaMeldingInnsending ved å benytte data-apiet til instansen:
PUT {mvaMeldingInnsendingsUrl}
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
"content-type": "application/xml"
Content:
<?xml version="1.0" encoding="UTF-8"?>
<mvaMeldingInnsending>
...
</mvaMeldingInnsending>
Eksempel på xml-fil for mvaMeldingInnsending finnes under https://github.com/Skatteetaten/mva-meldingen/tree/master/docs/informasjonsmodell_filer/example_files/konvolutt.
Respons 403 - Forbidden:
Hvis innlogget bruker prøver å laste opp fil til instansen, men personen har ikke riktig roller vil en få response kode 403 tilbake.
Modellen for no.skatteetaten.fastsetting.avgift.mva.skattemeldingformerverdiavgift.v1.0.xsd
Url for opplasting av Mva Melding har denne oppbygningen:
{instansUrl}/data?datatype=mvamelding
Mva Melding lastes opp på med følgende request mot instansens data-api:
POST {instansUrl}/data?datatype=mvamelding
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
"content-type": "text/xml"
"Content-Disposition": "attachment; filename=mvaMelding.xml"
Content:
<?xml version="1.0" encoding="UTF-8"?>
<mvaMeldingDto xmlns="no:skatteetaten:fastsetting:avgift:mva:skattemeldingformerverdiavgift:v1.0">
...
</mvaMeldingDto>
Dette kallet vil laste opp xml-dokumentet til instansen.
Respons 403 - Forbidden:
Hvis innlogget bruker prøver å laste opp fil til instansen, men personen har ikke riktig roller vil en få response kode 403 tilbake.
Det er mulig å laste opp fra 0 til 57 vedlegg, med en individuell størrelse på 25MB.
Url for opplasting av Vedlegg har denne oppbygningen:
{instansUrl}/data?datatype=binaerVedlegg
Det tillates opplasting av følgende content-typer:
Vedlegg lastes opp på med følgende request mot instansens data-api:
POST {instansUrl}/data?datatype=binaerVedlegg
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
"content-type": "application/pdf"
"Content-Disposition": "attachment; filename=merknaderTilMvaMeldingen.pdf"
Content:
{pdf-vedlegg i binærformat}
Dette kallet vil laste opp pdf-dokumentet til instansen.
Husk at content-type
skal være passende for vedlegget som skal lastes opp og at filnavnet i Content-Disposition
- headeren også bør være passende og unikt. Det er dette filnavnet Skatteetaten vil forholde seg til for vedlegget.
Respons 403 - Forbidden:
Hvis innlogget bruker prøver å laste opp fil til instansen, men personen har ikke riktig roller vil en få response kode 403 tilbake.
Dette steget bruker prosess-apiet til instansen og instansen vil avslutte utfyllingssteget for Mva Melding Innsending og til neste steg i applikasjonens prosess for instansen.
For å fullføre utfyllingen utføres følgende kall mot prosess-apiet til instansen:
PUT {instansUrl}/process/next
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
"content-type": "application/json"
Innsendingen vil nå være i bekreftelses-steget.
Respons 403 - Forbidden:
Hvis innlogget bruker prøver å bytte til neste steg i instansprossessen, men personen har ikke riktig roller vil en få response kode 403 tilbake.
Respons 409 - Conflict:
"Valideringsfeil: Organisasjonsnummeret i instansen er forskjellig fra organisasjonsnummeret i MvaMeldingInnsending (\"konvolutt\")"
Hvis organisasjonsnummeret som ble brukt til å lage instansen er forskjellig fra organisasjonsnummeret definert i MvaMeldingInnsending vil en få denne feilmeldingen.
"Valideringsfeil: Organisasjonsnummeret i MvaMeldingInnsending (\"konvolutt\") er forskjellig fra organisasjonsnummeret i {filnavn}"
Hvis listen over vedlegg som er definert i MvaMeldingInnsending er forskjellig fra de som har blitt lastet opp instansen vil en få denne feilmeldingen.
"Valideringsfeil: Meldingskategorien i MvaMeldingInnsending (\"konvolutt\") er forsjellig fra Meldingskategorien i {filnavn}"
Hvis verdien i meldingskategori feltet for MvaMeldingInnsending er forskjellig fra meldingskategorien i mva-meldigen vil en få denne feilmeldingen.
"Valideringsfeil: skattleggingsperiode er påkrevd i MvaMeldingInnsending. Validation error: skattleggingsperiode is required in MvaMeldingInnsending"
Hvis verdien i skattleggingsperiode feltet i MvaMeldingInnsending er null vil en få denne feilmeldingen.
"Valideringsfeil: skattleggingsperiode må være utfylt. Validation error: skattleggingsperiode must be populated"
Hvis verdien i skattleggingsperiode feltet i MvaMeldingInnsending er tom vil en få denne feilmeldingen.
"Valideringsfeil: instansstatus er påkrevd i MvaMeldingInnsending. Validation error: instansstatus is required in MvaMeldingInnsending"
Hvis verdien i instansstatus feltet i MvaMeldingInnsending er null vil en få denne feilmeldingen.
"Valideringsfeil: filnavnene i innsendingen må være unike. Validation error: file names in the submission must be unique."
Hvis to eller flere filer er lastet opp til instansen med samme filnavn vil en få denne feilmeldingen.
Valideringstjenesten
"Valideringsfeil: Ugyldig mva-melding"
Appen vil også kalle valideringstjenesten under fullføring av utfyllingen. Hvis mva-meldingen er ugyldig, vil det returneres feilmelding 409 og valideringsresultatet i xml som content.
Eksempel verdi:
<valideringsresultat>
<status>UGYLDIG_SKATTEMELDING</status>
<valideringsfeil>
<stiTilFeil>//innsending</stiTilFeil>
<valideringsDetaljer>
<feilmelding>Mva meldingen må være på gyldig format og passere XML skjema valideringen</feilmelding>
<alvorlighetsgrad>UGYLDIG_SKATTEMELDING</alvorlighetsgrad>
<avvikKode>MvaMeldingsinnhold_Xml_SkjemaValideringsfeil</avvikKode>
<informasjon>cvc-complex-type.2.4.b: The content of element 'mvaMeldingDto' is not complete. One of
'{"no:skatteetaten:fastsetting:avgift:mva:skattemeldingformerverdiavgift:v1.0":innsending}' is expected.
</informasjon>
</valideringsDetaljer>
</valideringsfeil>
</valideringsresultat>
Liste over valideringsfeil for henholdsvis mva-meldingen og kompensasjonsmeldingen.
Validering av MvaMeldingInnsending opp mot xsd modellen no.skatteetaten.fastsetting.avgift.mva.skattemeldingformerverdiavgift.v1.0.xsd
Eksempel:
Valideringsfeil / Validation error:
The 'no:skatteetaten:fastsetting:avgift:mva:mvameldinginnsending:v1.0:skattleggingsperiodeToMaaneder' element is invalid - The value 'juli-september' is invalid according to its datatype 'no:skatteetaten:fastsetting:avgift:mva:mvameldinginnsending:v1.0:SkattleggingsperiodeToMaaneder' - The Enumeration constraint failed.
The element 'mvaMeldingInnsending' in namespace 'no:skatteetaten:fastsetting:avgift:mva:mvameldinginnsending:v1.0' has invalid child element 'opprettingstidspunkt' in namespace 'no:skatteetaten:fastsetting:avgift:mva:mvameldinginnsending:v1.0'. List of possible elements expected: 'opprettetAv' in namespace 'no:skatteetaten:fastsetting:avgift:mva:mvameldinginnsending:v1.0'.
Dette steget bruker prosess-apiet til instansen og instansen vil avslutte bekreftelsessteget for Mva Melding Innsending og oppdatere instansen til neste steg i applikasjonens prosess.
For å fullføre innsendingen utføres følgende kall mot prosess-apiet til instansen:
PUT {instansUrl}/process/next
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
"content-type": "application/json"
Innsendingen vil nå være i tilbakemeldings-steget.
Respons 403 - Forbidden:
Hvis innlogget bruker prøver å bytte til neste steg i instansprossessen, men personen har ikke riktig roller vil en få response kode 403 tilbake.
Response 409 - Conflict:
"Valideringsfeil: filnavnene i innsendingen må være unike. Validation error: file names in the submission must be unique."
Hvis to eller flere filer er lastet opp til instansen med samme filnavn vil en få denne feilmeldingen. Kan forekomme i feilsituasjoner for dette steget.
Når Innsendingen er fullført og instansen nå er i tilbakemeldings-steget, vil betalingsinformasjonen være tilgjengelig på instansen. Den kan finnes ved å hente instansen og laste ned fila betalingsinformasjon.xml
, og har datatypen betalingsinformasjon
. Se tilbakemeldingsfiler.
Skatteetaten har laget 2 api-endepunkter for å forenkle utviklingen av dette steget:
Det følgende sekvensdiagrammet viser hvordan man kan identifisere om Skatteetaten har gitt tilbakemelding til en gitt instans, og hvordan instansen kan hentes.
For å hente status for tilbamelding kan man utføre kall mot instansens feedback-api:
GET {instansUrl}/{partyId}/{instanceGuid}/feedback/status
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
"accept": "application/json"
Hvis kallet er vellykket vil en få status kode 200 og et json objekt i retur:
{
"isFeedbackProvided": boolean
}
hvor isFeedbackProvided
returneres som true
dersom tilbakemelding er gitt, som false
ellers.
GET {instansUrl}/{partyId}/{instanceGuid}/feedback
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
"accept": "application/json"
Dette endepunktet vil returnere instansen når Skatteetaten har gitt tilbakemelding, og vil inneholde data-elementer for alle tilbakemeldingsfilene fra Skatteetaten.
Merk: Sistnevnte endepunkt skal kun brukes i følgende situasjoner:
isFeedbackProvided : true
Respons 400 - Bad Request:
Respons 403 - Forbidden:
Hvis innlogget bruker prøver å hente instansen, men personen har ikke riktig roller vil en få response kode 403 tilbake.
Respons 404 - Not Found:
Når Skatteetaten har gitt tilbakemelding, vil filene til tilbakemeldingen kunne lastes ned fra instansen.
Betalingsinformasjonen vil kunne lastes etter innsendingen er fullført, da den blir produsert under fullføringen.
Eksempler på tilbakemeldingsfiler som er gitt for en innsending den 17.06.2021 finnes her. Disse filene ble lastet ned fra instansen for innsendingen.
Filene som kan lastes ned vil ha dataType
:
og URL'er for nedlastning finnes i instans-objektets data
-element returnert fra feedback- eller instans-api'et som vist under (irrelevant json er fjernet).
Gitt ett data
element, kan filen hentes ved å bruke:
GET {selfLinks.apps}
HEADERS:
"Authorization": "Bearer " + "{altinnToken}"
hvor selfLinks.apps
kan hentes fra listen med data-elementer på instansen som vist her:
"data": [
{
"id": "82c96a52-ad0b-428f-8005-7f214daf367e",
"instanceGuid": "55604b08-1690-4a8d-bf6b-95c11dc40c58",
"dataType": "valideringsresultat",
"filename": "valideringsresultat.xml",
"contentType": "text/xml",
"selfLinks": {
"apps": "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-sit/instances/50267437/55604b08-1690-4a8d-bf6b-95c11dc40c58/data/82c96a52-ad0b-428f-8005-7f214daf367e",
"platform": "https://platform.tt02.altinn.no/storage/api/v1/instances/50267437/55604b08-1690-4a8d-bf6b-95c11dc40c58/data/82c96a52-ad0b-428f-8005-7f214daf367e"
}
},
{
"id": "726a315f-7e5e-4514-8ef1-5eda624407d4",
"instanceGuid": "55604b08-1690-4a8d-bf6b-95c11dc40c58",
"dataType": "betalingsinformasjon",
"filename": "betalingsinformasjon.xml",
"contentType": "text/xml",
"selfLinks": {
"apps": "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-sit/instances/50267437/55604b08-1690-4a8d-bf6b-95c11dc40c58/data/726a315f-7e5e-4514-8ef1-5eda624407d4",
"platform": "https://platform.tt02.altinn.no/storage/api/v1/instances/50267437/55604b08-1690-4a8d-bf6b-95c11dc40c58/data/726a315f-7e5e-4514-8ef1-5eda624407d4"
}
},
{
"id": "cbce850a-a887-4598-aea4-710ea9ffdc7d",
"instanceGuid": "55604b08-1690-4a8d-bf6b-95c11dc40c58",
"dataType": "kvittering",
"filename": "kvittering.pdf",
"contentType": "application/pdf",
"selfLinks": {
"apps": "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-sit/instances/50267437/55604b08-1690-4a8d-bf6b-95c11dc40c58/data/cbce850a-a887-4598-aea4-710ea9ffdc7d",
"platform": "https://platform.tt02.altinn.no/storage/api/v1/instances/50267437/55604b08-1690-4a8d-bf6b-95c11dc40c58/data/cbce850a-a887-4598-aea4-710ea9ffdc7d"
}
}
]
Innsending av kompensasjosnmelding følger den samme prosessen som mva-meldingen. Unntaket er revisors atttestasjon som gjøres i portalen Min merverdiavgift. Diagrammet under illustrerer prosessen for å sende inn kompensasjonsmeldingen.