Retrieving a Document by Identifier

Use Case: Retrieving a Document by Identifier from an External System

Use Case Description

This use case describes how an external system can retrieve a document managed by 4ws.suite by invoking the Get Document API. The document can be searched using one of three methods: by document identifier, by document number, or by document external code.

Actors

External System: The system initiating the request to retrieve a document.

4ws.suite: The system providing the document data.

Preconditions

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

The external system must know the appropriate identifiers or codes to search for the document.

APIs Used

Get Document API: This API is used to retrieve a document based on the provided search parameters.

Main Success Scenario

The external system invokes the Get Document API with the appropriate search parameters.

The 4ws.suite system processes the request.

If the document is found, 4ws.suite returns the document header and rows in the response.

The external system receives and processes the document data.

Alternate Flows

If the document is not found, 4ws.suite returns a response indicating the document is not found with an error message.

JSON Structure for Sale Order Document

By Document Identifier

Field	Description	Type	Mandatory
id	Unique internal identifier of the document within the suite	Varchar(250)	✓

Example invocation:

curl --location -g --request GET 'https://.../api?cmd=getDocument_v1&applicationId=MOBILE_SHOP&appId=MOBILE_SHOP&id=35d3be3d-8953-44e0-8af5-e2b34155feb7' \
--header 'applicationId: MOBILE_SHOP' \
--header 'appId: MOBILE_SHOP' \
--header 'namespace: {{ENV}}' \
--header 'languageId: {{LANGUAGE}}' \
--header 'username: {{USER_NAME}}' \
--header 'password: {{PASSWORD}}' \
--header 'companyId: {{COMPANY}}' \
--header 'siteId: {{SITE}}' \
--header 'User-Agent: Apidog/1.0.0 (https://apidog.com)' \
--header 'Content-Type: application/json'

By Document Number

Field	Description	Type	Mandatory
documentNumber	Document number, e.g., SDN/0000001449	Varchar(250)	✓
documentType	Document type code	Varchar(250)	✓
cause	Document cause code	Varchar(250)	✓
documentStatus	Document status code	Varchar(250)
branchCode	Branch code of the document	Varchar(250)

Example invocation:

curl --location -g --request GET 'https://.../api?cmd=getDocument_v1&applicationId=MOBILE_SHOP&appId=MOBILE_SHOP&documentNumber=SDN/0000001449&documentType=TAX_DOCUMENT&cause=RECEIPT' \
--header 'applicationId: MOBILE_SHOP' \
--header 'appId: MOBILE_SHOP' \
--header 'namespace: {{ENV}}' \
--header 'languageId: {{LANGUAGE}}' \
--header 'username: {{USER_NAME}}' \
--header 'password: {{PASSWORD}}' \
--header 'companyId: {{COMPANY}}' \
--header 'siteId: {{SITE}}' \
--header 'User-Agent: Apidog/1.0.0 (https://apidog.com)' \
--header 'Content-Type: application/json'

By Document External Code

Field	Description	Type	Mandatory
documentExternal	External code of the document	Varchar(250)	✓
documentType	Document type code	Varchar(250)	✓
cause	Document cause code	Varchar(250)	✓
documentStatus	Document status code	Varchar(250)
branchCode	Branch code of the document	Varchar(250)

Example invocation:

curl --location -g --request GET 'https://.../api?cmd=getDocument_v1&applicationId=MOBILE_SHOP&appId=MOBILE_SHOP&documentExternal=EXT12345&documentType=TAX_DOCUMENT&cause=RECEIPT' \
--header 'applicationId: MOBILE_SHOP' \
--header 'appId: MOBILE_SHOP' \
--header 'namespace: {{ENV}}' \
--header 'languageId: {{LANGUAGE}}' \
--header 'username: {{USER_NAME}}' \
--header 'password: {{PASSWORD}}' \
--header 'companyId: {{COMPANY}}' \
--header 'siteId: {{SITE}}' \
--header 'User-Agent: Apidog/1.0.0 (https://apidog.com)' \
--header 'Content-Type: application/json'

Callback Response

If the document exists, the response will include the document header and its rows:

{
  "success": true,
  "documentHeader": {
    "taxableIncome": 106.56,
    "year": 2024,
    "documentNumber": "1",
    "discountAmount": 0,
    "isReservation": "N",
    "isDeposit": "N",
    "currencySite": "EUR",
    "totalQuantity": 1,
    "sellerDescription": "Michele Bozzo",
    "currencyCompany": "EUR",
    "pointsPrevious": 0,
    "branchDescription": "Negozio NAPOLI",
    "id": "ca9e24c4-c112-41f4-a905-bfd13e49c0c8",
    "barcode": "99991024050200001",
    "registerCode": 10,
    "rowVersion": 2,
    "pointsMessage": "OK",
    "causeDescription": "Scontrino vendita",
    "branchSubtype": "NEGOZI",
    "printerReceiptNumber": "1846",
    "branchCode": 9999,
    "totalAmount": 130,
    "companyId": "SVIL3",
    "lastUpdate": "2024-05-02 15:31:11",
    "deposit": 0,
    "subjectDenomination": "Paggiaro Angelina ",
    "printerSerial": "99ICE090909",
    "printerTaxation": "XML7",
    "status": "E",
    "documentDate": "2024-05-02 15:18:46",
    "rebates": 0,
    "documentTypeDescription": "Documento fiscale",
    "documentType": "TAX_DOCUMENT",
    "cause": "RECEIPT",
    "sellerCode": "9999",
    "userCreate": "501_9999",
    "addresseeType": "CUSTOMER",
    "cardBarcode": "9990000000517",
    "currency": "EUR",
    "discountType": "",
    "documentStatus": "CLOSE",
    "branchType": "SHOP",
    "promoDiscount": 0,
    "statusMachineLog": 1,
    "createDate": "2024-05-02 15:30:51",
    "entityCode": 501,
    "cashbackTotalAmount": 0,
    "isDigital": "N",
    "printerZReport": "4123",
    "confirmationDateOrder": "2024-05-02 15:18:46",
    "discountWithVat": 0,
    "visibleMobile": "N",
    "currencySymbol": "€",
    "isInStore": "Y",
    "addresseeDescription": "Paggiaro Angelina ",
    "clientCode": "177735",
    "discountPerc": 0,
    "siteId": 501,
    "totalDiscount": 0
  },
  "documentRows": [
    {
      "id": "67126657-fb9a-47bf-b827-3708b1fd8e22",
      "barcode": "2000021033054",
      "companyId": "SVIL3",
      "composition": "Default 100%",
      "createDate": "2024-05-02 15:30:51",
      "currencySymbol": "€",
      "description": "CAMICIA",
      "dimension1": "1",
      "dimension2": "99",
      "dimension3": ".",
      "dimension4": ".",
      "dimensionDescription1": "UNI",
      "dimensionDescription2": "99",
      "dimensionDescription3": "Non assegnato",
      "dimensionDescription4": "Non assegnato",
      "dimensionGroup1": "6",
      "dimensionGroup2": "1",
      "dimensionGroup3": "DROP",
      "dimensionGroup4": "STATURA",
      "dimensionType1": "TAGLIA",
      "dimensionType2": "COLORE",
      "dimensionType3": "DROP",
      "dimensionType4": "STATURA",
      "discountAmount":

 0,
      "discountPerc": 0,
      "discountRowTotalAmount": 0,
      "discountTotalAmount": 0,
      "discountWithVat": 0,
      "documentDate": "2024-05-02 15:18:46",
      "entityCode": "501",
      "hierarchyDescriptionLevel1": "CAMICIA",
      "hierarchyDescriptionLevel10": null,
      "hierarchyDescriptionLevel2": "Abbligliamento",
      "hierarchyDescriptionLevel3": "Uomo",
      "hierarchyLevel1": "MCAM",
      "hierarchyLevel10": null,
      "hierarchyLevel2": "ABB",
      "hierarchyLevel3": "MAN",
      "internalDocumentRow": null,
      "itemCode": "037--------09999",
      "itemSubType": "ITEM",
      "itemType": "PRODUCT",
      "lastUpdate": "2024-05-02 15:31:11",
      "madeIn": "XIT",
      "note": null,
      "originalPrice": 130,
      "priceCmp": 109.29,
      "priceInvoiceTaxable": 79.94,
      "priceInvoiceTaxableCompany": 79.94,
      "priceInvoiceTaxableSite": 79.94,
      "priceList": "9999",
      "pricePurchaseTaxable": 110,
      "pricePurchaseTaxableCompany": 110,
      "pricePurchaseTaxableSite": 110,
      "priceSale": 130,
      "priceSaleCompany": 130,
      "priceSaleSite": 130,
      "quantity": 1,
      "refDocumentRow": "55fd2650-2584-44e3-b25b-5b908810f449",
      "refOrder": "41839aa7-ff97-42ee-abfa-e11d272a3e3f",
      "refOrderRow": "55411423-6870-402e-acaa-995a2831d864",
      "returnReasonId": "",
      "returnReasonNote": "",
      "rowNumber": 1,
      "rowStatus": "CONFIRM",
      "rowTaxableIncome": 106.56,
      "rowTotal": 130,
      "rowVat": 23.44,
      "rowVersion": 2,
      "seasonCode": "3",
      "seasonDescription": "CONT2000",
      "sellerCode": "9999",
      "sellerDescription": "Michele Bozzo",
      "siteId": 501,
      "status": "E",
      "taxRate": 22,
      "unitPrice": 130,
      "userCreate": "501_9999",
      "userUpdate": "501_9999",
      "vatCode": "4"
    }
  ],
  "moreRows": false
}

External System and transactionId

It is strongly recommended that the External System stores the unique receipt ID 02931b8a-a6c8-4e47-b3f1-041ffb1e432q and links it uniquely to the collected order.

If no document is found, the response will be:

{
    "success": false,
    "message": "Document not found"
}

WARNING

This API is paginated. Please refer to the Pagination section to understand how to navigate through the result pages.

Sequence Diagram

INFO

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

Retrieving a Document by Identifier

Use Case: Retrieving a Document by Identifier from an External System#

Use Case Description#

Actors#

Preconditions#

APIs Used#

Main Success Scenario#

Alternate Flows#

JSON Structure for Sale Order Document#

By Document Identifier#

By Document Number#

By Document External Code#

Callback Response#

Sequence Diagram#

Code Examples in Node.js#

Use Case: Retrieving a Document by Identifier from an External System

Use Case Description

Actors

Preconditions

APIs Used

Main Success Scenario

Alternate Flows

JSON Structure for Sale Order Document

By Document Identifier

By Document Number

By Document External Code

Callback Response

Sequence Diagram

Code Examples in Node.js