No momento, esta página não está disponível em português
Point-of-sale icon

Activate scanning multiple barcodes using Terminal API

Create a batch scanning session to scan multiple barcodes.

On Android payment terminals S1E Barcode, S1E2L, S1F2L, and S1U2 you can use Terminal API to start a batch barcode scanning session. You don't need to set up the scanning button in the Customer Area to use this method. In the request, you specify how long the barcode scanner stays active. During this time, the scanner scans every barcode that it faces when the terminal operator holds the scan button pressed.

You can also create a single scanning session to scan only one barcode at a time.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Requirement Description
Integration type A Terminal API integration with payment terminals.
Hardware Android terminal models S1E Barcode, S1E2L, S1F2L, or S1U2 that have a barcode scanner.
Setup steps Before you begin:
  • You need to implement a way to process the scanned content in your POS app.
  • Set up event notifications.

How it works

  1. You send an Admin request to activate the barcode scanner.
  2. The terminal operator presses and holds the barcode scanning button. The scanner scans every barcode that it faces.
  3. You receive an event notification for each scanned barcode.
  4. With the logic that you have created, you pass the content of the event notification to your POS app.
  5. The barcode scanner stops being active:
    • After the specified timeout.
    • When you send an admin request to end the session before the timeout.

Start a batch barcode scanning session

To start a batch barcode scanning session:

  1. Create a JSON object with the following data elements:

    Parameter Required Description
    Session -white_check_mark- An object with:
    • Id: your unique reference of the scanning session.
    • Type: Begin activates the batch barcode scanning session.
    Operation An object with:
    • Type: ScanBarcode.
    • TimeoutMs: how long the barcode scanner stays on, in milliseconds (from 0 to 30000). If not specified, the default is 30000.

  2. Encode the JSON object to Base64.

  3. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Admin
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
    • AdminRequest: the request body. This must include:
      • ServiceIdentification: the Base64-encoded JSON object.

    The terminal operator can now start scanning barcodes.

  4. In the response, note:

    • If successful, the following fields are returned:
      • Response.Result: Success
      • AdditionalResponse: contains "message": "ScanBarcodeSession request was successfully started".
    • If unsuccessful, the following fields are returned:
      • Response.Result: Failure
      • AdditionalResponse: contains the reason for failure, for example "message": "Admin ScanBarcode request canceled due to Timeout".

    The format of the AdditionalResponse can be a Base64-encoded or URL-encoded. To always receive the AdditionalResponse in one of those formats, contact our Support Team.

  5. For each scan that you perform during a batch barcode scanning session, you will receive an event notification that contains the scanned content or a failure message. With the logic that you have created, you pass the content of the event notification of a successful scan to your POS app.

  6. When the barcode batch scanning session reaches it specified timeout, you receive an event notification with the failure reason Timeout.

If you want to turn off the barcode scanner before the timeout, you need to send a request to cancel the scanning session.

Cancel a batch barcode scanning session

If you want to cancel the barcode scanning batch session before the specified timeout, you need to send an AdminRequest with the Session.Type End.

  1. Create a JSON object with the following data elements:

    Parameter Required Description
    ServiceIdentification.Session -white_check_mark- An object with:
    • Id: the unique reference of the session.
    • Type: End cancels the scanning session.

  2. Encode the JSON object to Base64.

  3. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Admin
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
    • AdminRequest: the request body. This must include:
      • ServiceIdentification: the Base64-encoded JSON object.

  4. If the cancel request succeeds, in the AdminResponse note:

    • Response.Result: Success
    • AdditionalResponse: contains the Base64-encoded message. Decoding the string results in a message of the following format: { "message": "Admin ScanBarcode request was successfully canceled" }

    The format of the AdditionalResponse can be a Base64-encoded or URL-encoded. To always receive the AdditionalResponse in one of those formats, contact our Support Team.

See also