4WS Suite
Home
API Reference
  • Data mangement API
  • Documents API
Home
API Reference
  • Data mangement API
  • Documents API
Fourwayshop
  1. Sales
  • Document Manager
    • Orders
      • Save Sale Order
      • Save Return Order
    • Orchestrated Orders
      • Orchestrated Order
      • Orchestrated Return order
      • Orchestrated Update order
    • Cart
      • Cart Validation
      • Cart Full Validation
    • Sales
      • Save receipt
        POST
      • Salve only Order
        POST
      • Replace or update sale
        POST
      • Get last digital order
        GET
    • Warehouse
      • Save Entry from supplier
      • Save Transfer document
      • Save Free Entry
    • Purchase
      • Save Purchase
    • Get Document
      GET
    • Update Document external references
      POST
  • Customer
    • Get Customer
      GET
    • Set Customer Opt-in
      POST
  • Loyalty vouchers
    • Get customer loyalty vouchers
      GET
    • Get loyalty vouchers at a time interval
      GET
    • Get last loyalty vouchers
      GET
  • Giftcard
    • Get Giftcard
      GET
    • Update Giftcard
      POST
    • Generate Gift Card Barcode
      POST
    • Gift Card PDF Generation
      POST
  • Stock
    • Get Stock
      POST
    • Get last stock
      GET
    • Insert Stock
      POST
  1. Sales

Save receipt

POST
/api
Last modified:2025-11-10 16:28:28

Save A New Receipt#

This API allows an external system to create a receipt of a sale within the 4ws.sale platform.
Validate Cart
Before invoking the saving of the receipt, the sales cart must be validated by invoking the API Cart Validation.
The receipt process includes:
Capturing product details via barcode
Assigning the receipt to a seller and a customer
Calculating total price, taxes, and any discounts
Storing the transaction with a unique ticket number
The external system can use this API to seamlessly integrate receipt transactions into the 4ws.sale system.

Actors#

API Client: The system or user initiating the request.
4ws.trade: The backend system that processes the request.

Preconditions#

The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.
In the receipt header you have to specify the transactionId, this id must be unique, for example an UUID, a progressive or a unique combination of information.This id will be used to refer to this document in the future requests, for example in the case of a return.
For each row you must specify a unique rowId. As for the header this id must be unique, for example an UUID, a progressive or a unique combination of information and this id will be used to refer to this row in the case of a return.
The callback URL must be functional and ready to receive POST requests.

Main Success Scenario#

1.
The external system sends a request containing receipt details.
2.
The API processes the receipt by:
Validating product details
Assigning seller and customer information
Calculating total cost, taxes, and any applicable discounts
3.
The system stores the receipt transaction and generates a unique ticket.
4.
The response includes confirmation details along with the receipt summary.
external system and transactionId
It is strongly recommended that the external system store the unique doc ID 02931b8a-a6c8-4e47-b3f1-041ffb1e432q.
Request example
Unique rowId
Each items row on request must have a unique rowId

Movement type movementType#

The movementType field allows you to identify the type of movement requested V sales receipt goods and R for a return receipt of goods.
On return movementType=V is usefull set rowIdRef field should be filled in with the corresponding rowId of the receipt, this allows you to link the two documents and verify that the product(s) of the receipt document are displayed as returns in the receipt document.
Remember:
transcationId of returned cart is different from the original cart
specify the originalCart in the json (if you don't have the entire cart available, pass just the transactionId)
specify cart movementType R
items movementType R
Return sample

Payments payments#

Payments collected to pay off the cart must be tracked in the payments array.
Credit card payment

Callback#

The callback url will be called in POST when the request has ended. In case of success the callback reuqest body is the following JSON:
{
    "success": true,
    "barcode": "123456789012",
    "documentNumber": "1",
    "payload": "request payload"
}
otherwise:
{
    "success": false,
    "message": "Error message"
}

Alternate Flows#

Invalid Product Code: If an invalid barcode is provided, the API returns an error.

Sequence Diagram (Mermaid)#

Code Examples in Node.js#

Request

Query Params

Header Params

Body Params application/json

Example
{"seller":"Filippo Giacomelli","zReportNumber":"20220621","clientName":"DANIEL","pointsUsed":"0400","docNumber":11,"endDate":"2022-06-21 13:13:44","goodsVoucher":[],"payments":[{"paymentType":"E","paymentCode":"CC","paymentDescription":"Carta di credito","paymentImg":"carte-ok.png","paymentCash":368,"channel":"IN_STORE","paymentProgr":"70AE705B-147F-4E46-8569-F9441DEA128C","paymentRoundingAmount":0,"paymentAmount":368,"paymentChange":0,"paymentDone":"Y"},{"paymentType":"C","paymentCode":"CONTANTI","paymentDescription":"Contanti","paymentImg":"contanti-euro.png","paymentCash":150,"channel":"IN_STORE","paymentProgr":"9090BAEE-0C8E-4E88-A955-8A9194093DA6","paymentRoundingAmount":0,"paymentAmount":122,"paymentChange":28,"paymentDone":"Y"}],"masterRegister":"N","clientDenomination":"GIACOMELLI DANIEL","clientSurname":"GIACOMELLI","deviceId":"5327E23B-CB96-4BAF-AC01-88E978267021","pointsCode":"OK","printerCode":"LUNGO_501_501_1070_TM-m30II-NT","pointsEarned":980,"sellerId":"777","movementType":"V","pointsPrevious":720,"barcodeInfo":"10701070222062100011","currency":"EUR","discountsManualCumulative":"Y","deliveryDate":"2022-06-28 15:07:12","registerCode":"10702","clientBarcode":"8966","delivery":[],"entityCode":"501","clientId":47109,"ticket":11,"clientEmail":"scazdaniel@gmail.com","pointsBalance":1300,"pointsMessage":"OK","currencySymbol":"€","rounding":2,"totals":{"totalDiscount":10,"totalDiscountType":"N","totalDiscountReasonDescription":"LOYALTY - Sconto con scelta fasce","totalDiscountAmount":10,"total":490,"vat":0,"grandTotal":490,"inStoreGrandTotal":490,"digitalGrandTotal":0,"totalDeposits":0,"totalDepositsVat":0,"allowance":0,"alreadyPayed":0,"taxableIncome":490,"autoTotalDiscountType":"PROMO"},"transactionId":"1fe0a4f9-a1ce-4963-9f18-94eb5fbf16a4","branchCode":"1070","onlineValidation":"Y","filling":"FIRST","appliedPromotions":[{"idPromozione":"50120220505104019","description":"LOYALTY - Sconto con scelta fasce","multipleDiscount":1,"discounts":[{"vantaggio":10,"consumedPoints":400}],"barcode":"13061360122101101","status":"ACCEPTED","discountType":"TOTAL","callbackAction":10609,"vantaggio":"10","consumedPoints":"400"}],"ticketRT":11,"candidatePromos":[{"idPromozione":"50120220505104019","description":"LOYALTY - Sconto con scelta fasce","multipleDiscount":1,"discounts":[{"vantaggio":10,"consumedPoints":400}],"barcode":"13061360122101101","status":"ACCEPTED","discountType":"TOTAL","callbackAction":10609,"vantaggio":"10","consumedPoints":"400"}],"items":[{"rowId":"B59FAFB3-6265-4EAD-B3AD-B4B2B0582425","rowType":"ITEM","barcode":"13061360122101101","barcodeType":"BARCODE_ARTICOLO","unitPrice":500,"qty":1,"qtyType":"N","itemState":"SERVER_OK","seller":"Filippo Giacomelli","sellerId":"777","taxRate":0,"vatCode":"4","rowTaxableIncome":490,"rowVat":0,"rowTotal":490,"itemType":"PRODUCT","movementType":"V","havingTailoring":"N","priceList":"1070","channel":"IN_STORE","addTimestamp":1655816803158,"itemCode":"SA1VX0009 P4517","currencySymbol":"€","currency":"EUR","rounding":2,"shopDescription":"PORTACARTE","description":"PORTACARTE","dimensionDescription1":"TU","dimensionDescription2":"T8013 - BLACK","attributeLevel1":"1","hierarchyLevel1":"30","attributeLevel2":"1","hierarchyLevel2":"3063","attributeLevel3":"360","hierarchyLevel3":"61","dimension1":"TU","dimension2":"T8013#@#BLACK","dimensionType1":"TAGLIA","dimensionType2":"COLORE","dimensionGroup1":"TAUN","dimensionGroup2":"360","discountTotalAmount":10,"discountRowTotalAmount":10,"originalUnitPrice":180,"priceForcingReason":"FORZA","rowOrder":1}],"transactionState":1,"startDate":"2022-06-21 13:06:43","printerSerial":"NOFISCAL","printerTaxation":"NOFISC"}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request POST '/api?applicationId={{APPLICATION_ID}}&appId={{APPLICATION_ID}}&cmd=saveSale_v1' \
--header 'applicationId: {{APPLICATION_ID}}' \
--header 'appId: {{APPLICATION_ID}}' \
--header 'namespace: {{NAMESPACE}}' \
--header 'languageId: {{LANGUAGE}}' \
--header 'username: {{USERNAME}}' \
--header 'password: {{PASSWORD}}' \
--header 'companyId: {{COMPANY_ID}}' \
--header 'siteId: {{SITE_ID}}' \
--header 'loadRoles: Y' \
--header 'Content-Type: application/json' \
--data-raw '{"seller":"Filippo Giacomelli","zReportNumber":"20220621","clientName":"DANIEL","pointsUsed":"0400","docNumber":11,"endDate":"2022-06-21 13:13:44","goodsVoucher":[],"payments":[{"paymentType":"E","paymentCode":"CC","paymentDescription":"Carta di credito","paymentImg":"carte-ok.png","paymentCash":368,"channel":"IN_STORE","paymentProgr":"70AE705B-147F-4E46-8569-F9441DEA128C","paymentRoundingAmount":0,"paymentAmount":368,"paymentChange":0,"paymentDone":"Y"},{"paymentType":"C","paymentCode":"CONTANTI","paymentDescription":"Contanti","paymentImg":"contanti-euro.png","paymentCash":150,"channel":"IN_STORE","paymentProgr":"9090BAEE-0C8E-4E88-A955-8A9194093DA6","paymentRoundingAmount":0,"paymentAmount":122,"paymentChange":28,"paymentDone":"Y"}],"masterRegister":"N","clientDenomination":"GIACOMELLI DANIEL","clientSurname":"GIACOMELLI","deviceId":"5327E23B-CB96-4BAF-AC01-88E978267021","pointsCode":"OK","printerCode":"LUNGO_501_501_1070_TM-m30II-NT","pointsEarned":980,"sellerId":"777","movementType":"V","pointsPrevious":720,"barcodeInfo":"10701070222062100011","currency":"EUR","discountsManualCumulative":"Y","deliveryDate":"2022-06-28 15:07:12","registerCode":"10702","clientBarcode":"8966","delivery":[],"entityCode":"501","clientId":47109,"ticket":11,"clientEmail":"scazdaniel@gmail.com","pointsBalance":1300,"pointsMessage":"OK","currencySymbol":"€","rounding":2,"totals":{"totalDiscount":10,"totalDiscountType":"N","totalDiscountReasonDescription":"LOYALTY - Sconto con scelta fasce","totalDiscountAmount":10,"total":490,"vat":0,"grandTotal":490,"inStoreGrandTotal":490,"digitalGrandTotal":0,"totalDeposits":0,"totalDepositsVat":0,"allowance":0,"alreadyPayed":0,"taxableIncome":490,"autoTotalDiscountType":"PROMO"},"transactionId":"1fe0a4f9-a1ce-4963-9f18-94eb5fbf16a4","branchCode":"1070","onlineValidation":"Y","filling":"FIRST","appliedPromotions":[{"idPromozione":"50120220505104019","description":"LOYALTY - Sconto con scelta fasce","multipleDiscount":1,"discounts":[{"vantaggio":10,"consumedPoints":400}],"barcode":"13061360122101101","status":"ACCEPTED","discountType":"TOTAL","callbackAction":10609,"vantaggio":"10","consumedPoints":"400"}],"ticketRT":11,"candidatePromos":[{"idPromozione":"50120220505104019","description":"LOYALTY - Sconto con scelta fasce","multipleDiscount":1,"discounts":[{"vantaggio":10,"consumedPoints":400}],"barcode":"13061360122101101","status":"ACCEPTED","discountType":"TOTAL","callbackAction":10609,"vantaggio":"10","consumedPoints":"400"}],"items":[{"rowId":"B59FAFB3-6265-4EAD-B3AD-B4B2B0582425","rowType":"ITEM","barcode":"13061360122101101","barcodeType":"BARCODE_ARTICOLO","unitPrice":500,"qty":1,"qtyType":"N","itemState":"SERVER_OK","seller":"Filippo Giacomelli","sellerId":"777","taxRate":0,"vatCode":"4","rowTaxableIncome":490,"rowVat":0,"rowTotal":490,"itemType":"PRODUCT","movementType":"V","havingTailoring":"N","priceList":"1070","channel":"IN_STORE","addTimestamp":1655816803158,"itemCode":"SA1VX0009 P4517","currencySymbol":"€","currency":"EUR","rounding":2,"shopDescription":"PORTACARTE","description":"PORTACARTE","dimensionDescription1":"TU","dimensionDescription2":"T8013 - BLACK","attributeLevel1":"1","hierarchyLevel1":"30","attributeLevel2":"1","hierarchyLevel2":"3063","attributeLevel3":"360","hierarchyLevel3":"61","dimension1":"TU","dimension2":"T8013#@#BLACK","dimensionType1":"TAGLIA","dimensionType2":"COLORE","dimensionGroup1":"TAUN","dimensionGroup2":"360","discountTotalAmount":10,"discountRowTotalAmount":10,"originalUnitPrice":180,"priceForcingReason":"FORZA","rowOrder":1}],"transactionState":1,"startDate":"2022-06-21 13:06:43","printerSerial":"NOFISCAL","printerTaxation":"NOFISC"}'

Responses

🟢200Save cart - success
application/json
Body

Example
{
    "success": true
}
🟠422Unique constraint error
Modified at 2025-11-10 16:28:28
Previous
Cart Full Validation
Next
Salve only Order
Built with