Gift Card PDF Generation

This service allows generating a print-ready PDF of one or more gift cards.
The PDF is intended to be attached to an email and sent to the final customer for future use.
The system returns a downloadable URL of the generated PDF.

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Callback Endpoint (Webhook): The remote URL that receives the asynchronous notification (callback) confirming the creation result of the return order and document.

Preconditions

The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.

Callback Endpoint (External Client): The callback used by Four Way Shop to asynchronously notify the client of success/failure and to return the order ID must be handled (How Testing callback response).

Monitoring / Alerting System: Handling integration errors and retries logs and warnings, as reported in Best Practices for Error Handling in External System.

Main Success Scenario

Client calls the API with gift card details

Service validates payload

PDF is generated including barcodes, value, expiry and recipient details

File is stored in cloud storage

API returns a download URL

Client downloads PDF and sends it to recipient via email

Alternate Flows

Authentication Error: If the client does not provide valid credentials, an error response is returned.

Error Example

Rate Limiting: If the API rate limits are exceeded, the client must respect the retry interval indicated in the response headers Rate Limits.

Sequence Diagram

External System        Giftcard API Service         Cloud Storage
      |                        |                        |
      |---Request PDF--------->|                        |
      |                        |--Validate payload----->|
      |                        |--Generate PDF--------->|
      |                        |--Store file----------->|
      |                        |<---Return file URL-----|
      |<--PDF Download URL-----|                        |
      |---Download PDF-------->|<---Serve file---------|

Best Practices

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Code Example (Node.js)

Request

Query Params

Header Params

Body Params application/json

Example

{
  "giftcards": [
    {
      "emailFrom": "mario.rossi@ciccio.it",
      "nameFrom": "Mario",
      "surnameFrom": "Rossi",
      "emailTo": "Giovanna.sarti@mailmail.com",
      "nameTo": "Giovanna",
      "surnameTo": "Sarti",
      "language": "IT",
      "barcode": "9009978264194",
      "amount": 20,
      "currency": "EUR",
      "endDate": "2023-09-22"
    },
    {
      "emailFrom": "mario.rossi@ciccio.it",
      "nameFrom": "Mario",
      "surnameFrom": "Rossi",
      "emailTo": "Giovanna.sarti@mailmail.com",
      "nameTo": "Giovanna",
      "surnameTo": "Sarti",
      "language": "IT",
      "barcode": "9009978264195",
      "amount": 50,
      "currency": "USD",
      "endDate": "2023-09-22"
    }
  ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Gift Card PDF Generation