Meddelandespecifikation Meddelandekvittens
Beskrivning av innehållet i meddelandetypen meddelandekvittens.
Anslutning för leverantörer av meddelandesystem
Version: 1.1
Gäller fr o m 2024-11-18
Inledning
Detta dokument beskriver meddelandetypen ’meddelandekvittens’ som används för att kommunicera kvittens för ett mottaget meddelande. Denna kvittens indikerar att ett meddelande tagits emot av deltagares system enligt syntaktiska och semantiska regelverk och returneras till den deltagare som ursprungligen skickat meddelandet.
Den tekniska syntaxen för meddelandekvittensen är xml-formatet IEC/ISO 19845 UBL ApplicationResponse.
Identitet: fdc:digg.se:edelivery:messagetype:response:1
Innehåll
Informationen på denna sida innehåller följande delar:
- Meddelandets funktion
- Informationsmodell
- Regelverk för formatering av meddelande i XML-format
- Appendix med kodlistor
Intressenter
Informationen på denna sida syftar till att stödja följande intressenter i deras arbete, dess informationsbehov samt ge svar på vanligt förekommande frågeställningar.
Intressenter:
- Verksamhetsutvecklare
- Utvärderar, kravställer
- IT-arkitekter
- Utvecklar, analyserar
Referenser
Referens till | Länk | Kommentar |
|---|---|---|
IEC/ISO 19845 UBL ApplicationResponse. | https://docs.oasis-open.org/ubl/UBL-2.1.html | Se sektion ApplicationRepsonse |
För Verksamhetsutvecklare
Meddelandets funktion
Denna typ av meddelande används för att kommunicera till avsändande deltagare att mottagande deltagare har tagit emot ett meddelande och att meddelandet vid mottagningstillfället följer de syntaktiska och semantiska regler som gäller för meddelandet. Meddelandekvittensen har funktionen att informera avsändande deltagare om huruvida ett meddelande kan accepteras eller ej.
Meddelandekvittens ska inte sammanblandas med den synkrona transportkvittens som accesspunktsfunktioner i Plattform för eDelivery använder för att signalera om en försändelse överförts korrekt enligt transportprotokollet.
Situationer som meddelandekvittensen nyttjas för
- Meddelandets nyttolast är inte följsamt gentemot de valideringsartefakter som specifikationen hänvisar till (såsom XML Schema och Schematron)
- Meddelandets nyttolast inte är följsamt gentemot andra deklarerade regler som specificerats för nyttolasten och som gör att det inte går att behandla/processa
- Meddelandets signatur innehåller fel eller saknas (om det var förväntat utifrån transportmodellen)
Situationer som meddelandekvittensen inte ska nyttjas för
- Meddelandets mottagare okänd (hanteras genom synkront svar av accesspunkten)
- Meddelandets nyttolast är krypterat på ett sätt som gör att mottagaren inte kan dekryptera det på förväntat sätt
Informationsmodell
En kvittens innehåller följande information:
Tabellen nedan beskriver de uppgifter som en kvittens innehåller samt deras placering (XPATH) i syntaxen. Mer detaljer kring strukturen på XML-syntaxen beskrivs i kapitlet Syntaxmappning.
Informations-entitet | Beskrivning |
|---|---|
Meddelandekvittens | Meddelande som indikerar mottaget meddelande enligt syntaktiska, semantiska regelverk. |
Kvittensidentitet | Kvittensens unika identitet (/ApplicationResponse/cbc:ID) |
Identifierare för deltagare som kvitterar | Identifierare för den deltagare som kvitterar (/ApplicationResponse/cac:SenderParty/cbc:EndpointID) Den identifierare som deltagaren använder sig av i Plattform för eDelivery. |
Identifierare för deltagare som ska ta emot kvittens | Identifierare för den deltagare som ska ta emot kvittensen (/ApplicationResponse/cac:ReceiverParty/cbc:EndpointID) Den identifierare som deltagaren använder sig av i Plattform för eDelivery. |
Referens till mottaget meddelande | Referens till det meddelande som kvittensen avser (meddelandets identitet som anges i kuvertet, XHE/ID). Denna identitet avser meddelandet identitet och inte någon identifierare i meddelandets nyttolast (t.ex. en journalnr eller fakturanummer) (/ApplicationResponse/cac:DocumentResponse/cac:DocumentReference/cbc:ID) |
Kvittenskod | Indikerar om meddelandet: · Accepteras (det är följsamt enligt aktuell specifikation), meddelandet anses kunna hanteras av verksamhetssystemet · EJ Accepterat (det är ej följsamt gentemot aktuell specifikation), meddelandet kan inte hanteras av verksamhetssystemet. Vid Ej Accepterat ska detaljkod anges om orsaken. Följsamhet avser validering av nyttolastens format, eventuell signaturs riktighet och att kryptering gjort på förväntat sätt. (/ApplicationResponse/cac:DocumentResponse/cac:Response/cbc:ResponseCode) |
Detaljinformation om orsak | Om meddelandet inte accepterats ska kvittensen innehålla orsaken samt detaljer kring den regel/fel som orsakat att meddelandet inte accepterats. |
Orsakskod | Kod som indikerar orsakskategorin till att meddelandet inte accepterats (/ApplicationResponse/cac:DocumentResponse/cac:LineResponse/cac:Response/cbc:ResponseCode) |
Felutpekning (plats) | XPATH som indikerar det element/attribut som orsakat felet/regelbrott. (/ApplicationResponse/cac:DocumentResponse/cac:LineResponse/cac:LineReference/cbc:LineID) |
Detaljkod | Detaljkod/identifierare för det fel/regelbrott som uppstått (exempelvis regel-id för en valideringsregel) (/ApplicationResponse/cac:DocumentResponse/cac:LineResponse/cac:Response/cac:Status/cbc:StatusReasonCode) |
Detaljtext | Text som ger detaljer om det fel/regelbrott som uppstått (beskrivning av regel som brutits emot eller felmeddelande) (/ApplicationResponse/cac:DocumentResponse/cac:LineResponse/cac:Response/cac:Status/cbc:StatusReason) |
För IT-arkitekter
Syntaxmappning– ISO/IEC 19845:2015 UBL 2.1 ApplicationResponse
Följande regelverk gäller för formatering av meddelandekvittens enligt XML-formatet UBL 2.1 ApplicationResponse. Den kardinalitet som anges för respektive element nedan ska följas även om elementet i vissa fall är valfritt eller upprepningsbart i UBL 2.1 ApplicationResponse schema. Se kapitel 4.3 för mer information om validering.
Kard | Elementnamn | Kommentar |
|---|---|---|
| ubl:ApplicationResponse | Rotelement för meddelandekvittensen |
1..1 | • cbc:CustomizationID | Identifiering av profileringen av XML-formatet [a] Fast värde för profileringen av UBL ApplicationResponse ska vara: |
1..1 | • cbc:ProfileID | Identifiering av process [b] Fast värde för samverkansprocess ska vara: bdx:noprocess |
1..1 | • cbc:ID | Identifierare för kvittensen |
1..1 | • cbc:IssueDate |
|
1..1 | • cbc:IssueTime | [c] Tidsangivelse ska inkludera tidzon (där Z anges för UTC och övriga tidzoner indikeras med avvikelse från UTC enligt formatet ”+/- timmar”). Exempel: ”2021-03-24T17:22:10+01:00” |
1..1 | • cac:SenderParty |
|
1..1 | • • cbc:EndpointID | Identifierare för deltagare som kvitterar [d] Fast värde för identifieringssystem för sändande Deltagare ska vara: |
1..1 | • cac:ReceiverParty |
|
1..1 | • • cbc:EndpointID | Identifierare för deltagare som ska ta emot kvittens [e] Fast värde för identifieringssystem för mottagande Deltagare ska vara: |
1..1 | • cac:DocumentResponse |
|
1..1 | • • cac:Response |
|
1..1 | • • • cbc:ResponseCode | Kvittenskod
|
1..1 | • • cac:DocumentReference |
|
1..1 | • • • cbc:ID | Referens till mottaget meddelande |
0..n | • • cac:LineResponse | Detaljinformation om orsak [f] Orsak måste anges om kvittenskoden är ‘REJECTED’ |
1..1 | • • • cac:LineReference |
|
1..1 | • • • • cbc:LineID | Felutpekning (plats) [g] XPATH ska användas för felutpekning. Om XPATH inte går att identifiera eller om meddelandet som kvitteras inte baseras på ett XML-format ska fast värde “NA” anges. |
1..1 | • • • |
|
1..1 | • • • • cbc:ResponseCode | Orsakskod |
1..1 | • • • • cac:Status |
|
0..1 | • • • • • cbc:StatusReasonCode | Detaljkod |
1..1 | • • • • • cbc:StatusReason | Detaljtext |
Namnrymder som används i meddelandekvittensen
Följande XML namnrymder används i meddelandekvittensen. Prefix som används i syntaxbindningen (cac,cbc) visar vilken namnrymd som respektive element hör hemma i.
Namnrymd | Kommentar |
|---|---|
urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2 | Rotelements namnrymd. Default i syntaxbeskrivningen i kapitel 4. |
urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2 | Prefix ”cac” i syntaxbeskrivningen i kapitel 4. |
urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2 | Prefix ”cbc” i syntaxbeskrivningen i kapitel 4. |
Tomma XML-element och attribut
Ett element/attribut anses vara tomt om det inte innehåller något textinnehåll och inte några underliggande XML-element. Element och attribut som uteslutande innehåller ”whitespace” (mellanslag, tab-tecken eller radbrytning) är också att betrakta som tomt.
<cbc:EndpointID schemeID=””>Exempel på tomma element:
<cbc:StatusReason> </cbc:StatusReason><cbc:StatusReason></cbc:StatusReason><cbc:StatusReason />Exempel på tomt attribut:
[a] Tomma element och attribut ska inte anges.
Valideringsregler för syntax
Denna meddelandespecifikation använder XML-standarden OASIS UBL 2.1 ApplicationResponse som inkluderar XSD-scheman.
[a] En meddelandekvittens som inte validerar korrekt gentemot UBL2.1 ApplicationResponse XSD-scheman är inte att betrakta som följsamt gentemot denna specifikation.
En uppsättning valideringsregler finns definierade för att kontrollera att en meddelandespecifikation är följsam gentemot denna specifikation. Reglerna finns även representerade som schematron-regler för maskinell och automatisk validering.
[b] En meddelandekvittens som bryter mot någon av valideringsreglerna är inte att betrakta som följsamt gentemot denna specifikation.
Regel-ID | Regel | Allvarlighet |
|---|---|---|
R1-APP | Endast XML-element och attribut som angivits i denna specifikation får användas | Fatal |
R2-APP | Tomma element eller attribut får inte anges | Fatal |
R3-APP | CustomizationID måste ha korrekt värde enligt kodlista | Fatal |
R4-APP | ProfileID måste ha korrekt värde enligt kodlista | Fatal |
R5-APP | Kvittenskod (cac:DocumentResponse/cbc:ResponseCode) ska använda giltig kod enligt kodlista | Fatal |
R6-APP | Orsakskod (cac:LineResponse/cac:Response/ | Fatal |
R7-APP | En kvittens med status ACCEPTED ska inte ha några orsakskoder | Fatal |
R8-APP | En kvittens med status REJECTED måste ha minst en orsakskod | Fatal |
R9-APP | Element och attribut ska endast anges i enlighet med den tillåtna kardinalitet som framgår i syntaxmappningen[1]. | Fatal |
XML Validering – kontrollera följsamhet
Ett antal valideringsartefakter (XML-scheman och schematron) finns tillgängliga som stöd till implementerare. Artefakterna kan användas för att validera XML-instanser för att se om de är följsamma gentemot denna specifikation.
Tre nivåer av validering kan utföras:
- Välformaterad XML. Kontrollerar att filen är korrekt XML. Utförs normalt sätt automatiskt vid inläsning av XML.
- XML Schema. Kontrollerar att XML-dokumentet är följsamt gentemot OASIS UBL 2.1 ApplicationResponse XML Schema. XML Schemat kontrollerar att element och attribut är angivna i korrekt ordningsföljd och att namn och datatyper används i enlighet med standarden.
- Schematron. Exekverbara regler som kontrollerar följsamhet gentemot affärsregler, kodlistor, sambandskontroll mellan element samt kontroller av att inte element anges som inte är specificerade i denna specifikation, men som trots det finns tillgängliga i UBL-standarden. Dessa kontroller görs för att försäkra att mappning mot syntaxen är gjord på rätt sätt och att inga uppgifter av misstag har positionerats i element som inte används.
Valideringsartefakter och exempelfiler förvaltas och förbättras löpande för att stödja implementerare i verifiering av format.
Reducerade XML Scheman
En uppsättning reducerade scheman publiceras tillsammans med den här specifikationen. Dessa reducerade scheman är sanna delmängder av OASIS UBL och alla XML-instanser som är följsamma gentemot det reducerade schemat är också följsamt gentemot officiella standard-XML scheman.
Reducerade scheman ger en bättre översikt över vilka element och attribut som används för meddelandekvittensen. Observera att dessa reducerade scheman bara kan appliceras i detta sammanhang och ska inte användas vid andra integrationer där grundstandarden UBL ApplicationReponse nyttjas.
Appendix
Kvittenskod
Kvittenskoden används för att specificera statusen på det inkomna meddelandet.
Kod | Beskrivning | Definition |
|---|---|---|
ACCEPTED | Accepteras | Inga fel som gör att meddelandet inte kan accepteras har identifierats. |
REJECTED | Accepteras Ej | Fel som gör att meddelandet inte kan accepteras har identifierats. |
Orsakskoder
Orsakskoderna används för att klassificera typen av fel/avvikelse som orsakat att ett meddelande ej accepterats.
Kod | Beskrivning | Definition |
|---|---|---|
SV | Nyttolast ej följsamt – schemavalideringsfel | Meddelande ger valideringsfel gentemot meddelande-specifikationens XML schema |
BV | Nyttolast ej följsamt – valideringsregel (fatalt fel) | Meddelande ger valideringsfel gentemot meddelandespecifikationens kompletterande valideringsregel (ex schematron) |
SIG | Signaturen inte korrekt | Meddelandet är inte korrekt signerat |
Ditt svar hjälper oss att förbättra sidan
Senast uppdaterad: