-
Notifications
You must be signed in to change notification settings - Fork 0
API Function: 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".
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.
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.
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 |