API Function: Send PDF - trifork/dpk-docs GitHub Wiki

Send PDF

The endpoint is reachable at /api/v1/sendPDF

Instructs the service to generate a PDF using the specified template(s) and request details and then send it to either Digital Post (digital letter) or Strålfors (physical letter).

The endpoint expects Content-Type to be application/json and will respond with HTTP code 415 if not set.

The POST request requires a JSON body, that is UTF-8 encoded, containing:

recipient_list: An array of recipients containing details of each recipient, including:
- message_id: UUID of message
- recipient_identifier: Recipient's CPR number
- recipient_identifier_source: Identifier source, currently only "CPR" is supported [Optional]
- recipient_firstname: Recipient's first name
- recipient_lastname: Recipient's last name
- recipient_address: Street name and house numbering of recipient [Optional - if template_physical is unspecified]
- recipient_city: Recipient's city of residence according to postal code, postal district [Optional - if template_physical is unspecified]
- recipient_postal_code: Recipient's postal code [Optional - if template_physical is unspecified]
- recipient_details: Key-value pair with recipient specific details to put on the letter [Optional]
template_digital: The string identifier of the digital template to be used to generate letters
template_physical: The string identifier of the physical template to be used to generate letters [Optional]
send_date_time: The date and time when the letter should be sent in the format "dd-MM-yyyy HH:mm:ss Z" (e.g. "21-02-2024 11:12:54 +0100"). [Optional]
template_substitution_values: Key-value pair with any substitution values to be used in the letters. [Optional]

Optional fields can be omitted or left with a blank value.

If template_physical is omitted, the system will not send out physical letters (Strålfors). If specified, address information (recipient_address, recipient_city, and recipient_postal_code) must be specified.

If send_date_time is not specified, the message will be sent at the time the request was received (i.e., as soon as possible).

It is possible to override a template_substitution_values value on a recipient level by providing the same key in recipient_details. Recipient details will always take precedence over request details.

Dates provided in recipient_details must have format "YYYY-MM-DD".

Example of POST Request

POST https://dpk.test.tcs.trifork.cloud/api/v1/sendPDF

{
   "recipient_list":[
      {
         "message_id":"23cfcc0f-2cb3-41f0-9888-00bcc49bf8ac",
         "recipient_identifier":"1234567890",
         "recipient_identifier_source":"CPR",
         "recipient_firstname":"Niels",
         "recipient_lastname":"Nielsen",
         "recipient_address":"Nielsensvej 19",
         "recipient_city":"Aarhus C",
         "recipient_postal_code":"8000",
         "recipient_details":{
            "detail":"some details...",
            "detail2":"some other detail..."
         }
      }
   ],
   "template_digital":"Paamindelse_digital",
   "template_physical":"Paamindelse_fysisk",
   "send_date_time": "21-02-2024 11:12:54 +0100",
   "template_substitution_values":{
      "date":"2024-02-21"
   }
}

For every POST request, a unique request_id (UUID) is created. This request_id is associated with the message_ids contained within the request.

The request_id serves to link a group of messages identified by message_ids to a specific request. This facilitates the traceability of messages throughout the system and which requests they are related to.

Response Values

If the request was successfully made, the service will respond with status code 201.

The return value will be of Content-Type: application/json and will for example look like:

{
  "status": "OK",
  "request_id": "3d0cd52d-7fbb-4e33-8e35-418ed6b834dc"
}

As stated above, the request_id is a unique identifier assigned by the system to a specific request. The generated request_id of a request is returned to the requester.

Refer to a request_id for investigations on a batch of messages or refer to a messages_id for investigations on a single message.

Error Values

In case of an error, the service responds with a status code 40x or 50x and corresponding JSON value:

{
  "status": "Failed",
  "error_code": "INVALID_JSON_BODY",
}

If an error occurs, the request is wholly denied and nothing will be sent to Digital Post or Strålfors.

The following request error codes may be returned by the system:

Error Code	Description/Reason	Status
INTERNAL_ERROR	An internal error occured while processing the request	500
BAD_CERTIFICATE	The provided TLS certificate contained invalid information	401
BAD_IP	The calling IP address has not been whitelisted	401
RECIPIENT_VALIDATION_ERROR	Request contains one or more recipients where validation failed	400
RECIPIENT_ID_ERROR	Request contains a duplicated message id	400
INVALID_JSON_BODY	The internal json deserialiser was unable to parse the body as valid json	400
INVALID_DATETIME	The provided `send_date_time` was not in the specified format	400
BAD_DIGITAL_TEMPLATE(t)	The specified digital template was not valid, this error code provides the name of the template	400
BAD_PHYSICAL_TEMPLATE(t)	The specified physical template was not valid, this error code provides the name of the template	400
TEMPLATE_DETAIL_MISSING	One or more details were not provided for the specified template, see message error for details	400

If there's an error with one or multiple recipients, the error message might include recipient-specific details:

{
  "status": "Failed",
  "error_code": "RECIPIENT_VALIDATION_FAILED",
  "recipient_errors": [
    {
      "message_id": "83cfcc1f-2cb3-41f0-9888-00bcc49bf8ad",
      "error_code": "MALFORMED_RECIPIENT_CPR",
    }
  ]
}

The following recipient error codes may be returned by the system:

Error Code	Description/Reason
INTERNAL_ERROR	An internal error occured while processing the request
DUPLICATE_MESSAGE_ID	The specified message id already exists in the system (Regenerate message Id)
MALFORMED_RECIPIENT_CPR	The `recipient_identifier` number did not contain 10 digits
MALFORMED_RECIPIENT_CVR	The `recipient_identifier` number did not contain 8 digits
INVALID_RECIPIENT_MESSAGE_ID	The `message_id` field was not a valid UUID
INVALID_RECIPIENT_IDENTIFIER_SOURCE	The `recipient_identifier_source` field was not `CPR` or `CVR`
INVALID_RECIPIENT_NAME	The `recipient_firstname` field was empty for a `CVR` recipient
INVALID_RECIPIENT_FIRST_NAME	The `recipient_firstname` field was empty for a `CPR` recipient
INVALID_RECIPIENT_LAST_NAME	The `recipient_lastname` field was empty for a `CPR` recipient
INVALID_RECIPIENT_ADDRESS	The `recipient_address` field was empty
INVALID_RECIPIENT_CITY	The `recipient_city` field was empty
INVALID_RECIPIENT_POSTAL_CODE	The `recipient_postal_code` field was empty
INVALID_RECIPIENT_CVR_NOT_SUPPORTED	The `recipient_identifier_source` was set to `CVR` but sending to `CVR` is yet not supported
MISSING_TEMPLATE_DETAIL(d)	Names the template detail that was not provided

If a template detail is provided, but the specified template does not require it, a warning may be returned in the success message:

{
  "status": "Success",
  "request_id": "3d0cd52d-7fbb-4e33-8e35-418ed6b834dc"
  "recipient_warnings": [
    {
      "message_id": "83cfcc1f-2cb3-41f0-9888-00bcc49bf8ad",
      "warning_code": "WARNING_BAD_RECIPIENT_TEMPLATE_DETAILS(extra_detail_1)",
    },
    {
      "message_id": "83cfcc1f-2cb3-41f0-9888-00bcc49bf8ad",
      "warning_code": "WARNING_BAD_RECIPIENT_TEMPLATE_DETAILS(extra_detail_2)",
    }
  ]
}

Possible Warning codes:

Error Code	Description/Reason
WARNING_UNEXPECTED_TEMPLATE_DETAIL(d)	The request-scoped template detail was not expected
WARNING_UNEXPECTED_RECIPIENT_TEMPLATE_DETAIL(d)	The recipient-scoped template detail was not expected