openapi: 3.2.0 info: title: Bevz Integrator Service Lotto Scratcher Games API contact: name: API Support email: tech@bevz.com description: '# Introduction Welcome to the Bevz Integrator Service API documentation. The Bevz Integrator Service empowers our partners—including integrators and third-party POS providers—to seamlessly manage stores and related operations through a secure, scalable, and high-performance REST API platform. ## Who is this documentation for? This documentation is designed for integrators and third-party POS systems looking to leverage the Bevz SaaS platform to automate and streamline store management, menu operations, and more. ## Key Features By integrating with the Bevz platform, you gain access to: - **Rapid Store Onboarding:** Effortlessly provision and deprovision stores using our dedicated APIs. - **Menu Management:** Upload, update, and synchronize store menus programmatically. - **User & Access Management:** Manage integrator admin users and developer access for your organization. - **Order Processing:** Receive and process orders in real time via webhooks and API endpoints. - **Reporting & Analytics:** (Coming Soon) Access comprehensive reporting tools to monitor and optimize your operations. Explore the following sections to get started, review API endpoints, and discover best practices for a successful integration with Bevz. ' version: 1.12.0 servers: - url: https://api.bevz.com/integrator-service description: Production server - url: https://sandbox-api.bevz.com/integrator-service description: Sandbox server tags: - name: Lotto Scratcher Games description: '## Lotto Scratcher Games Retrieve lottery scratch-off game data from supported state lotteries. This endpoint provides game catalogs that can be used to display lotto ticket information in POS systems. ### Supported Lotteries - California (CA_LOTTERY) - Massachusetts (MA_LOTTERY) - Ohio (OH_LOTTERY) - Michigan (MI_LOTTERY) - Arizona (AZ_LOTTERY) - Connecticut (CT_LOTTERY) - Illinois (IL_LOTTERY) - Georgia (GA_LOTTERY) - Florida (FL_LOTTERY) ### UPC Barcode Lookup When a customer''s lottery ticket is scanned, pass the 12-digit UPC-A barcode along with the source to look up the specific game. The system extracts the game number from the barcode and returns the matching game details. ' paths: /integrators/{integrator_id}/lotto-scratcher-games: get: tags: - Lotto Scratcher Games operationId: getLottoScratcherGames summary: Get Lotto Scratcher Games description: 'Retrieve lottery scratch-off game data from supported state lotteries. Use this endpoint to list available lotto scratcher games by source (state lottery) or to look up a specific game by its UPC barcode. The response includes game details such as pricing, odds, top prize, and imagery. #### Listing Games by Source - Pass the `source` query parameter to retrieve all games from a specific state lottery. - Use `limit` and `next_page` to paginate through large catalogs. - Filter by `status` to retrieve only `ACTIVE` or `DISCONTINUED` games. #### UPC Barcode Lookup - When a customer''s lottery ticket is scanned at the POS, pass the 12-digit UPC-A barcode along with the `source` to look up the specific game. - The system extracts the game number from the barcode and returns the matching game details. ' parameters: - name: integrator_id in: path required: true schema: type: integer format: int64 description: Unique identifier for the integrator. - name: source in: query required: true schema: type: string enum: - CA_LOTTERY - MA_LOTTERY - OH_LOTTERY - MI_LOTTERY - AZ_LOTTERY - CT_LOTTERY - IL_LOTTERY - GA_LOTTERY - FL_LOTTERY description: The state lottery source to retrieve games from. - name: upc in: query required: false schema: type: string example: '698720254818' description: A 12-digit UPC-A barcode used to look up a specific lotto scratcher game. - name: status in: query required: false schema: type: string enum: - ACTIVE - DISCONTINUED default: ACTIVE description: Filter games by status. Defaults to ACTIVE. - name: limit in: query required: false schema: type: integer example: 100 description: Maximum number of games to return per page. - name: next_page in: query required: false schema: type: string description: Token for fetching the next page of results. - name: Authorization in: header description: JWT token for authenticating API requests. example: Bearer yourJWTtoken required: true schema: type: string responses: '200': description: Successfully retrieved lotto scratcher games content: application/json: schema: type: object properties: api_version: type: string example: 1.12.0 status_code: type: integer example: 200 message: type: string example: Successfully retrieved lotto scratcher games next_page: type: - string - 'null' example: eyJzb3VyY2UiOiJDVF9MT1RURVJZIiwiZ2FtZUlkIjoiY3RfbG90dGVyeV8xODUyIn0= count: type: integer example: 42 errors: type: array items: type: string example: [] data: type: array items: type: object properties: gameId: type: string example: ca_lottery_1555 description: Unique identifier for the lotto scratcher game. gameNumber: type: string example: '1555' description: The game number assigned by the state lottery. gameName: type: string example: $5 Crossword description: Display name of the lotto scratcher game. gamePrice: type: integer description: Price in cents (500 = $5.00) example: 500 source: type: string enum: - CA_LOTTERY - MA_LOTTERY - OH_LOTTERY - MI_LOTTERY - AZ_LOTTERY - CT_LOTTERY - IL_LOTTERY - GA_LOTTERY - FL_LOTTERY example: CA_LOTTERY description: The state lottery source this game belongs to. upc: type: - string - 'null' example: '735975_1555_' description: UPC barcode associated with the game, if available. imageUrl: type: - string - 'null' example: https://example.com/game-image.png description: URL of the original game image from the lottery source. ticketOdds: type: - string - 'null' example: 1 in 4.23 description: Overall odds of winning any prize on this game. topPrize: type: - integer - 'null' description: Top prize amount in cents (30000000 = $300,000.00) example: 30000000 description: type: - string - 'null' description: Description of the lotto scratcher game, if available. status: type: string enum: - ACTIVE - DISCONTINUED example: ACTIVE description: Current availability status of the game. cdnUrl: type: - string - 'null' example: https://cdn.example.com/game-image.png description: CDN-hosted URL for the game image. '400': description: Bad request! Please check your input. content: application/json: schema: type: object properties: message: type: string errors: type: array examples: Missing or invalid source parameter: value: message: Bad request! Please check your input. errors: - 'source is required and must be one of: CA_LOTTERY, MA_LOTTERY, OH_LOTTERY, MI_LOTTERY, AZ_LOTTERY, CT_LOTTERY, IL_LOTTERY, GA_LOTTERY, FL_LOTTERY' '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string errors: type: array examples: Integrator unauthorized to perform this action!: value: message: Unauthorized request! Please check your permission. errors: - Integrator unauthorized to perform this action! x-tagGroups: - name: getting started tags: - Introduction - What is this documentation for? - Getting Started - name: guides tags: - Preparing Your Store - Using Webhooks - Uploading store menu - Receiving and processing order - name: apis tags: - Integrators - integrator_users - Stores - Store Products - Lotto Scratcher Games - Order - name: Delivery Services Onboarding tags: - Pick a Delivery Service for Onboarding API - Uber Eats Onboarding API Workflow - name: webhooks tags: - Webhooks - name: models tags: - models - name: faqs tags: - faq - name: changelog tags: - Changelog