Generate Gift Card Barcode

This service allows external systems to generate unique barcodes for gift cards that will later be activated during sale.
The service does not sell or activate gift cards—it only generates barcodes with validity dates and returns them asynchronously via callback webhook.

Typical usage:

Create barcode batches for printing on physical gift cards

Generate digital gift card identifiers before selling them through e-commerce

Store generated barcodes in an external system until activation

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

External system sends request with itemCode, quantity, and callback URL

Four Way Shop accepts the request and queues barcode generation

Gift card barcodes are generated with validity dates

Four Way Shop sends results asynchronously to the provided callback URL

External system stores barcodes for future sale/activation

Alternate Flows

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

Error Example

Invalid gift card item code: ItemCode parameter in the request is not a valid item code financial product

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

JSON Structure for Callback Response

{
  "success": true,
  "giftcards": [
    {
      "barcode": "4443334961511",
      "startValidity": "2022-06-10 00:00:00",
      "endValidity": "2023-06-10 00:00:00"
    }
  ]
}

Field	Description
barcode	Unique gift card identifier
startValidity	Activation window start
endValidity	Expiration date

Sequence Diagram

Best Practices

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

#### Code Example – Node.js

Generate Gift Card Barcode