python-serviceplatformen 3.2.0

Python modules for easier use of Kombit's serviceplatformen.

python_serviceplatformen

This project is made to make it easier to use Kombit's Serviceplatformen API.

Certificates and authentication

To use Kombit's Serviceplatformen you need a valid OCES3 certificate registered for your project. Ask your local Kombit systems architect for help with this.

You need specific access to each service on Serviceplatformen you want to use. One certificate can have access to multiple services.

This project needs your certificate to be in a unified PEM format. That is with the public and private key in a single file.

If your certificate is in P12-format you can convert it using openssl:

openssl pkcs12 -in Certificate.p12 -out Certificate.pem -nodes

Due to limitations in Python's implementation of SSL your certificate needs to exist as a file on the system while using this library.

When your certificate is registered and in PEM-format, you simply hand it to the KombitAccess class and it will handle the rest for you.

from python_serviceplatformen.authentication import KombitAccess
kombit_access = KombitAccess(cvr="12345678", cert_path="C:\something\Certificate.pem", test=False)

If you want to use the test system instead pass test=True to KombitAccess.

Digital Post

This library supports the full functionality of Digital Post including NemSMS.

Check registration

You can easily check if someone is registered for Digital Post or NemSMS:

digital_post.is_registered(cpr="1234567890", service="digitalpost", kombit_access=kombit_access)
digital_post.is_registered(cpr="1234567890", service="nemsms", kombit_access=kombit_access)

MeMo model

A detailed data class model has been defined to help define MeMo objects which are used in the api.

The entire model is located in the message module:

from python_serviceplatformen.models.message import Message

A detailed description of the model and all attributes can be found in the official documentation: MeMo - Digitaliser.dk

Note: The model doesn't follow the normal python naming conventions to follow the source names as close as possible.

Send Digital Post

To send a message construct a message object and then send it off to the send_message function:

import uuid
from datetime import datetime
import base64

from python_serviceplatformen.authentication import KombitAccess
from python_serviceplatformen import digital_post
from python_serviceplatformen.models.message import (
    Message, MessageHeader, Sender, Recipient, MessageBody, MainDocument, File
)

kombit_access = KombitAccess(cvr="55133018", cert_path=r"C:\somewhere\Certificate.pem")

m = Message(
    messageHeader=MessageHeader(
        messageType="DIGITALPOST",
        messageUUID=str(uuid.uuid4()),
        label="Digital Post test message",
        sender=Sender(
            senderID="12345678",
            idType="CVR",
            label="Python Serviceplatformen"
        ),
        recipient=Recipient(
            recipientID="1234567890",
            idType="CPR"
        )
    ),
    messageBody=MessageBody(
        createdDateTime=datetime.now(),
        mainDocument=MainDocument(
            files=[
                File(
                    encodingFormat="text/plain",
                    filename="Besked.txt",
                    language="da",
                    content=base64.b64encode(b"Hello World").decode()
                )
            ]
        )
    )
)

digital_post.send_message("Digital Post", m, kombit_access)

Note: If you want to trace the message later in Beskedfordeleren you should save the value of Message.MessageHeader.messageUUID.

Recipes

The message module also contains a few static helper functions to construct simple messages. These are not meant to be all encompassing but to help as a starting point.

Physical mail

This library supports sending physical letters through the SF1601 Kombi API (Fjernprint). The letter content is sent as a base64-encoded file (typically a PDF) along with recipient address information.

Fjernprint model

A data class model based on the official XSDs has been defined to help build the request payload. The model is located in the physical_mail module:

from python_serviceplatformen.models.physical_mail import ForsendelseI

Note: Like the MeMo model, the physical mail model doesn't follow the normal Python naming conventions in order to stay close to the source XSD names.

Send physical mail

To send a letter, construct a ForsendelseI object and pass it to send_physical_mail:

import base64
import uuid

from python_serviceplatformen.authentication import KombitAccess
from python_serviceplatformen import digital_post
from python_serviceplatformen.models.physical_mail import (
    AfsendelseIdentifikator, AfsendelseModtager, CountryIdentificationCode,
    CountryIdentificationSchemeType, CPRnummerIdentifikator, DokumentParametre,
    FilformatNavn, ForsendelseI, ForsendelseModtager, ForsendelseTypeIdentifikator,
    MeddelelseIndholdData, ModtagerAdresse, PersonName, PostCodeIdentifier,
    StreetBuildingIdentifier, StreetName, TransaktionsParametreI,
)

kombit_access = KombitAccess(cvr="55133018", cert_path=r"C:\somewhere\Certificate.pem")

with open("letter.pdf", "rb") as f:
    pdf_bytes = f.read()

forsendelse = ForsendelseI(
    afsendelse_identifikator=AfsendelseIdentifikator(value=str(uuid.uuid4())),
    forsendelse_type_identifikator=ForsendelseTypeIdentifikator(value=265),
    forsendelse_modtager=ForsendelseModtager(
        afsendelse_modtager=AfsendelseModtager(
            # Note that this should always be '0000000000' according to the documentation.
            cpr_nummer_identifikator=CPRnummerIdentifikator(value="0000000000")
        ),
        modtager_adresse=ModtagerAdresse(
            person_name=PersonName(value="Test Testesen"),
            street_name=StreetName(value="Testvej"),
            street_building_identifier=StreetBuildingIdentifier(value="3"),
            post_code_identifier=PostCodeIdentifier(value="2300"),
            country_identification_code=CountryIdentificationCode(
                value="DK",
                scheme=CountryIdentificationSchemeType.ISO3166_ALPHA2,
            ),
        ),
    ),
    filformat_navn=FilformatNavn(value="pdf"),
    meddelelse_indhold_data=MeddelelseIndholdData(
        value=base64.b64encode(pdf_bytes).decode()
    ),
    transaktions_parametre_i=TransaktionsParametreI(),
    dokument_parametre=DokumentParametre(),
)

transaction_id = digital_post.send_physical_mail(forsendelse, kombit_access)

Beskedfordeler

This library supports retrieving messages from the Beskedfordeler using the AMQP BeskedHent service.

Note: Remember to explicitly set the Beskedfordeler to use BeskedHent instead of BeskedFåTilsendt in the admin module.

from python_serviceplatformen.authentication import KombitAccess
from python_serviceplatformen import message_broker

kombit_access = KombitAccess(cvr="55133018", cert_path=r"C:\somewhere\Certificate.pem")
queue_id="fc42c3fd-a8d6-4a12-afc2-3ccb82d69994"

for message in message_broker.iterate_queue_messages(queue_id, kombit_access):
    print(message.decode())

Messages can by default only be read once and will be removed from the server after retrieving, so remember to store the information you need.

Alternatively you can set auto_acknowledge=False on the message_broker.iterate_queue_messages function to keep messages in the queue. Keep in mind that Kombit wants the queue to be as empty as possible at all times.

Tests

This project contains automated tests in the "tests" folder. To run these test you need to install the developer dependecies:

pip install python_serviceplatformen[dev]

Environment variables

Create a .env file in the project folder and fill out these variables:

KOMBIT_TEST_CVR = "XXXXXXXX"  # The cvr of the organization who owns the certificate
KOMBIT_TEST_CERT_PATH = "C:\something\Certificate.pem"  # The path to the certificate file
DIGITAL_POST_TEST_CPR = "xxxxxxxxxx"  # The receiver of the test messages

Running the tests

To run all tests open a command line in the project folder and run:

python -m unittest