Skip to main content

Update The Package’s Invoice

Actors​

  • Akinon Order Management System (OMS)
  • Akinon Omnitron System
  • Integrated Application (ERP)

Domain Objects​

  • Packaging Orders
  • Invoice Number
  • Invoice Document
  • OMS Command

Process​

  1. The OMS application copies orders from the Akinon Omnitron Application to itself to prepare a delivery/distribution plan and generate packaging orders, which are then transferred to the operation points.

  2. The products in the order are distributed to Packaging Orders by applying the rules in the distribution scenarios by the brand.

  3. Packaging Orders are transferred to the Akinon Instore Application or the brand's integrated software. ( Packing Orders Webhooks )

  4. Packaging orders assigned to a Store/Warehouse begin in the Waiting status.

  5. When the packaging is physically prepared for distribution in one or more steps, it transitions to the Packed status either through screens in the Akinon Instore application or by executing OMS commands from another integrated software.

  6. Packages with the Packed status have a Packaging Document created by OMS, which can later be replaced with an Invoice produced by the brand's own software. The command for this change is defined in the OMS Commands API.

  7. A packaging order in the Packed status, as well as later statuses, can be created by executing the UpdateInvoiceOfThePackageCommand command:

  • Invoice number
  • Invoice document type
  • Invoice document content
  • Date of Invoice

Upon sending the parameters according to the service requirements, the transfer of Package and Invoice information to the financial section of the OMS application is completed.

After executing this command, a copy of the document becomes available in the OMS application, allowing it to be viewed and reported on the Packing Order detail pages (Akinon Instore + Akinon OMS Web).

Command Parameters and Prerequisites​

For each packaging order following parameters uses;

  • Packing Order ID (integer): Unique identifier for each order.
  • Command Transition ID (integer): Fixed value provided during OMS installation.
  • Invoice Number (string): Dynamic invoice number for each package.
  • Invoice Date (string): Date format: %Y-%m-%dT%H:%M:%S%z.
  • Data Type (String): Type of data (url, html, base64, text). The data type determines the format of the invoice data.
  • Invoice Data (String): HTML or PDF data, depending on the specified data type.

If this command is executed before a packaging order reaches the Packed status, it will result in a validation error. The prerequisite for all packaging orders that have reached the Packed status is considered to be completed (e.g., shipped status).

POST Update The Package’s Shipment Status​

Path: https://{customer_api_url}-oms.akinon.net/api/v1/oms/packages/{package_id}/command/

Request Parameters​

ParameterData TypeInDescription
tokenstringheaderThe API key of the customer account
  • Package ID: package_id (integer)
  • Transition ID: transition id (integer) (set after OMS installation)

Request Body​

{
    "transition": <transition-id>,
    "package": <package-id>,
    "invoice_number": "Inv-1234-XYZ-Any",
    "data_type": "url",
    "invoice_data": "http://ecommerce.com/invoices/any_invoice_page/<id>"
    "invoice_date": "2024-11-05T13:58:32.384293Z"
}

Successful Response​

Status Code: 204 No Content

Body: Empty

HTML Data​

If the invoice information will be transferred in HTML format;

{
    "transition": <transition-id>,
    "package": <package-id>,
    "invoice_number": "Inv-1234-XYZ-Any",
    "data_type": "html",
    "invoice_data": "<html><head></head><body>.... any html string will be here ... </body></html>",
    "invoice_date": "2024-11-05T13:58:32.384293Z"
}
Base64 Data​

If the invoice information will be transferred in Base64 image or PDF format;

{
    "transition": <transition-id>,
    "package": <package-id>,
    "invoice_number": "Inv-1234-XYZ-Any",
    "data_type": "base64",
    "invoice_data": "data:image/png;base64,i....",
    "invoice_date": "2024-11-05T13:58:32.384293Z"
}

Transitions and Validations​

The command transition source and destination values must be the same.

valid source states:

* PackageStatus.packed

* PackageStatus.shipped

* PackageStatus.delivered

* PackageStatus.waiting_transfer_operation

Valid destination states:

* PackageStatus.packed

* PackageStatus.shipped

* PackageStatus.delivered

* PackageStatus.waiting_transfer_operation

Valid state transitions:

* PackageStatus.packed → PackageStatus.packed

* PackageStatus.shipped → PackageStatus.shipped

* PackageStatus.delivered → PackageStatus.delivered

* PackageStatus.waiting_transfer_operation → PackageStatus.waiting_transfer_operation