Bevz Lotto Scratcher Games API

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