Save receipt

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

The external system sends a request containing receipt details.

The API processes the receipt by:

Validating product details

Assigning seller and customer information

Calculating total cost, taxes, and any applicable discounts

The system stores the receipt transaction and generates a unique ticket.

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

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Save A New Receipt#

Actors#

Preconditions#

Main Success Scenario#

Movement type movementType#

Payments payments#

Callback#

Alternate Flows#

Sequence Diagram (Mermaid)#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Save A New Receipt

Actors

Preconditions

Main Success Scenario

Movement type `movementType`

Payments `payments`

Callback

Alternate Flows

Sequence Diagram (Mermaid)

Code Examples in Node.js