Standard bulk move

Please make sure you read the Conventions before continuing with this guide.

Bulk Move Guide

This guide explains how to move all tickets from one manifest to another using the Betterez API.

Prerequisites

You will need an X-API-KEY and a Basic Access Authentication token generated from your username and password.

Flow overview and about this guide

The process involves selecting an origin manifest, choosing tickets, and assigning them to a new destination manifest.

This guide presents the steps to complete a Standard (restricted) Bulk Move. It is bringing a Postman collection available to complete the flow dinamically (in case you don't have already choosen manifests) and manually (by adding your already choosen manifests and tickets in the environment variables).

1. Authentication & permissions

Ensure you have the necessary credentials and permissions to perform the operations. Follow guides below to get your x-api-key and your token.

2. Choose origin manifest, tickets to be moved and destination manifest

a) Select the origin manifest

You can interact with /operations/manifests endpoint to list all manifests available between specific dates in order to choose the tickets you will be moving from.

From the selected manifest you will take the list of tickets to be moved.

Example request using Curl:
curl --location 'https://sandbox-api.betterez.com/operations/manifests?dateFrom={{date-from}}&dateTo={{date-to}}' \
--header 'x-api-key: {{your-api-key-here}}' \
--header 'Authorization: Bearer {{your-base-token-authentication}}'

See the guide of how to use this endpoint here.

In case you already have a manifest id from where to move the tickets, you can use /operations/manifests/{{destinationManifestId}} endpoint to get its data and tickets.

Example request using Curl:
curl --location 'http://localhost:3070/operations/manifests/{{destinationManifestId}}' \
--header 'x-api-key: {{your-api-key-here}}' \
--header 'Authorization: Bearer {{your-base-token-authentication}}'

See the guide of how to use this endpoint here.

Using the available Postman collection

If you execute the endpoint from the available collection, you can use the environment variables to search manifests between given dates. Using ranges, take into account that dates can't exeed 7 days periods.

getManifestsRequest_dateFrom: 2023-07-16

getManifestsRequest_dateTo: 2023-07-21

The postman collection aims to help you to complete the flow fastly, so it was added a post script to processes the response from the endpoint to identify manifests that contain at least one ticket. It filters out the manifests that meet this condition and saves them as an environment variable named manifests. The script randomly selects a manifest that have at least 1 ticket as environment variable randomManifest, that will later be used dynamically to perform the standard bulk move operation. Finally, the script verifies that the response status code is 200, indicating a successful API call.

b) Choose tickets to move

Each manifest has a tickets property containing a list of tickets. Select the tickets you wish to move from this manifest.

Although each ticket object has many properties, its enaugh to send the following ones in order to build the list you have to send when you do the movement.

"tickets": [

    {
        "_id": "^000000000000000000000000$",
        "section": "string",
        "sectionName": "string",
        "seat": "string",
        "row": "string",
        "seatId": "string"
    }

]

Using the available Postman collection

In case you already manually choose the tickets, you can use the env variable ticketsToMove to save them and use it into the move endpoint.

In case you prefer to use a dinamically flow, the pre request script of the bulk move endpoint retrieves manifests saved for a specific date range and selects tickets from one of these manifests. The script specifically selects the first two tickets from the chosen manifest and maps them to include only the necessary properties (_id, section, sectionName, seat, row, seatId).

c) Choose the destination manifest

To move tickets, you'll need details of the destination manifest such as:

  • routeId
  • scheduleId
  • date

Take into account that destination manifest must to reach some conditions. See below to understand movement conditions.

Using the available Postman collection

In case you already know necessary values of a valid destination manifest, you can set manualFlow env variable to true, and then configure some variables:

  • destinationManifestId
  • newManifestScheduleId
  • newManifestRouteId
  • newManifestDate

If you prefer to try the dynamic flow, you can just leave manualFlow as false.

3. New standard bulk move

Use the /movements endpoint to move the selected tickets to the new manifest.

Movement conditions

To ensure a successful transfer of tickets, some conditions must be met:

  • Same stations: Tickets must have the same stations and in the same order as the original manifest.
  • Product validity: The product associated with the tickets must be valid for the destination manifest.
  • Ticket presence: The tickets must not already be present in the destination manifest.
  • Manifest status: The manifest must not be in a planned or canceled state.
  • Seats availability: Destination trip manifest must have enaught seats.

Example request:

curl --location 'https://sandbox-api.betterez.com/operations/movements' \
--header 'x-api-key: {{your-api-key-here}}' \
--header 'Authorization: Bearer {{your-base-token-authentication}}' \
--header 'Content-Type: application/json' \
--data '{
    "tickets": {{ticketsToMove}},
    "destinationManifest": {
        "routeId": "{{newManifestRouteId}}",
        "scheduleId": "{{newManifestScheduleId}}",
        "date": "{{newManifestDate}}"
    }
}'

Using the available Postman collection

Pre-Request Script

The pre-request script handles the following:

  • Manual Flow: If manualFlow is set to true, it uses the manually configured variables (destinationManifestId, newManifestRouteId, newManifestScheduleId, newManifestDate) to perform the move. This means you must provide these values manually.
  • Dynamic Flow: If manualFlow is set to false, the script dynamically selects a destination manifest and tickets based on the predefined criteria. The script ensures that all conditions are met, including checking that tickets have the same stations as in the original manifest.
Running the Collection

You can run the entire Postman collection without additional configuration if manualFlow is set to false. The collection will automatically handle the selection and movement of tickets, making the process more streamlined.

4. Check destination manifest

To verify the success of the bulk move:

Endpoint Call

Use the GET /manifest/{destinationManifestId} endpoint to fetch the updated destination manifest.

Validation

After the POST request, the test checks if the number of tickets in the destination manifest has increased as expected.

Postman Requests and Environments

The Postman collection provides a set of pre-configured requests to help you perform the bulk move operations. Also it includes some variables to be used into the dynamic or manual flow:

You can download the following Postman collection with the environment.

Postman Collection

Postman Environment

Variables

basePathOperations: The base URL for the operations API endpoint.

basePathAccounts: The base URL for the accounts API endpoint. Similar to basePathOperations, this points to the accounts service.

x-api-key: The API key required for authentication when making requests to the Betterez services. Replace with your actual API key.

jwtToken: The JSON Web Token (JWT) used for authenticated requests. Ensure that this token is valid and corresponds to the appropriate user and roles.

audience: The intended audience for the JWT token, typically set to betterez-app.

channel: Specifies the channel or source of the request, such as backoffice, which can be useful for logging or permission purposes.

user_name & user_pass: Credentials used for login purposes, generally set to the email and password of the account being used. Be sure to replace these with valid credentials for your environment.

getManifestsRequest_dateFrom & getManifestsRequest_dateTo: These variables define the date range for retrieving manifests. Adjust these values based on the time frame of the manifests you want to work with.

manifests: A JSON string representing the list of manifests returned by the system. This variable is populated dynamically during requests.

randomManifest: Stores a random manifest selected from the list of available manifests. This is used primarily in dynamic selection when manualFlow is set to false.

ticketsToMove: A JSON string representing the tickets selected for the bulk move operation. This can either be populated manually or selected dynamically depending on the flow.

newManifestScheduleId: The schedule ID for the destination manifest in the bulk move. This should match the new manifest where the tickets will be moved.

newManifestRouteId: The route ID for the destination manifest. Ensure this matches the new route where the tickets will be moved.

newManifestDate: The date for the new destination manifest, formatted as YYYY-MM-DD. This is used to specify the date on which the move operation should take place.

initialTicketCount: Tracks the number of tickets initially selected for the move. This variable can help in verifying that the correct number of tickets has been processed.

destinationManifest: Contains the JSON object representing the manifest to which the tickets are being moved, used by dynamic flow.

destinationManifestId: The ID of the selected destination manifest.

randomManifestId: The ID of the randomly selected manifest. This is used in the dynamic selection process.

manualFlow: A boolean (true or false) that determines whether the process is in manual mode. When true, the operation will use pre-set variables like destinationManifestId, newManifestScheduleId, etc. When false, the process will select these dynamically.