{
  "openapi": "3.1.0",
  "info": {
    "title": "Monato's Lottery API",
    "version": "1.0.0",
    "description": "Monato Lottery API provides endpoints for purchasing lottery tickets through Monato's payment platform.\n\nThis API is designed to be Developer/AI-first, providing comprehensive documentation for easy integration\nin any programming language. All endpoints require Bearer token authentication.\n\n**Key Features:**\n- Retrieve current lottery draw information\n- Purchase lottery tickets with various betting options (rematch, second rematch)\n- Complete ticket purchase workflow with payment processing\n\n**Important Notes:**\n- Always call `/api/v1/lottery_tickets/new` first to get current draw information\n- Prices are specified in cents (e.g., 1500 = $15.00 MXN)\n- Combination count must be between minimum_number_of_boards and maximum_number_of_boards from draw info\n- Second rematch requires rematch to be enabled\n- Total amount must match calculated price: (base_price + rematch_price + second_rematch_price) * combination_count\n",
    "contact": {
      "name": "Monato Support",
      "email": "support@monato.com"
    }
  },
  "servers": [
    {
      "url": "https://dev-api.finco.lat"
    }
  ],
  "paths": {
    "/api/v1/lottery_tickets/new": {
      "get": {
        "summary": "Retrieve current lottery draw information",
        "description": "Returns the active/current lottery draw information. \n\n**This is the first step required before purchasing a lottery ticket.**\n\nThe response includes:\n- Current draw number and date\n- Pricing information (base price, rematch, second rematch) in cents\n- Sales period (begin_sales, end_sales) in HH:MM:SS format\n- Board limits (minimum_number_of_boards, maximum_number_of_boards)\n\n**Implementation Notes:**\n- Use the `draw_number` from the response in the purchase request\n- Validate `combination_count` against `minimum_number_of_boards` and `maximum_number_of_boards`\n- Use pricing information to calculate `total_amount` for purchase\n- All prices are in cents (e.g., 1500 = $15.00 MXN)\n",
        "operationId": "getLotteryDraw",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "payee_id",
            "in": "query",
            "required": true,
            "description": "Unique identifier of the lottery service (it will be provided by Monato).\nMust be a valid UUID v4 format.\n",
            "schema": {
              "type": "string",
              "format": "uuid",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current lottery draw successfully retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LotteryDrawResponse"
                },
                "examples": {
                  "example-1": {
                    "value": {
                      "draw_number": "7327",
                      "draw_date": "13/01/2026",
                      "base_price": 1500,
                      "min_price": 1500,
                      "max_price": 3780000,
                      "rematch": 1000,
                      "second_rematch": 500,
                      "begin_sales": "08:00:00",
                      "end_sales": "23:59:59",
                      "minimum_number_of_boards": 1,
                      "maximum_number_of_boards": 6
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "errors": [
                        "Access denied"
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid input or company not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "examples": {
                  "invalid-input": {
                    "value": {
                      "error": "Invalid input"
                    }
                  },
                  "company-not-found": {
                    "value": {
                      "error": "Company not found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/lottery_tickets": {
      "post": {
        "summary": "Purchase a lottery ticket",
        "description": "Creates a lottery ticket purchase for a specific draw. The system processes the bet payment.\n\n**Prerequisites:**\n- Must call `/api/v1/lottery_tickets/new` first to get current draw information\n- Use `draw_number` from the draw info response\n- Validate `combination_count` against draw info limits\n\n**Betting Rules:**\n- A ticket can have minimum 1 bet (board/combination) and maximum 6 bets\n- Each bet costs the `base_price` from draw info (in cents, e.g., 1500 = $15.00 MXN)\n- Rematch option adds `rematch` price per bet (in cents, e.g., 1000 = $10.00 MXN per bet)\n- Second rematch option adds `second_rematch` price per bet (in cents, e.g., 500 = $5.00 MXN per bet)\n- Second rematch **requires** rematch to be enabled\n\n**Price Calculation:**\n```\ntotal = base_price * combination_count\nIF rematch: total += rematch * combination_count\nIF second_rematch AND rematch: total += second_rematch * combination_count\ntotal_amount = STRING(total)  // Must be string representation of integer in cents\n```\n\n**Implementation Notes:**\n- `total_amount` must match the calculated price based on draw info\n- `payer_reference` must be unique per transaction (use UUID or timestamp-based ID)\n- Store `receipt` information for ticket validation and customer records\n- `security_number` is used for anti-fraud validation\n",
        "operationId": "createLotteryTicket",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLotteryTicketRequest"
              },
              "example": {
                "payee_id": "9432e22b-7e41-4c9e-8d59-9a73e9532342",
                "payer_reference": "1234567890",
                "ticket": {
                  "draw_number": "4294",
                  "combination_count": 5,
                  "rematch": true,
                  "second_rematch": true,
                  "total_amount": "15000"
                },
                "branch": {
                  "name": "Test Branch",
                  "city": "Test City",
                  "street": "Test Street",
                  "neighborhood": "Test Neighborhood"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lottery ticket successfully purchased",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LotteryTicketResponse"
                },
                "examples": {
                  "example-1": {
                    "value": {
                      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                      "client_id": 123,
                      "ticket": {
                        "rematch": true,
                        "second_rematch": true,
                        "draw_number": "1234",
                        "total_amount": "10000",
                        "combination_count": 5
                      },
                      "branch": {
                        "city": "Ciudad de Mexico",
                        "name": "Abarrotes Don Pepe",
                        "street": "Av. Insurgentes Sur 1234",
                        "neighborhood": "Del Valle"
                      },
                      "status": "processed",
                      "payment": {
                        "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
                        "payer_account": "1234567890",
                        "payee_id": "9432e22b-7e41-4c9e-8d59-9a73e9532342",
                        "amount": 100,
                        "currency": "MXN",
                        "status": "completed",
                        "pay_type": "gambling"
                      },
                      "receipt": {
                        "combination_numbers": "10,27,36,41,52,56",
                        "transaction_date": "22/12/2025 20:19:57",
                        "store_id": "26226",
                        "pos_id": "1",
                        "foreign_pos_id": "1",
                        "transaction_number": "432930881",
                        "reference_number": "801500019-35600002",
                        "session_id": "80150001900",
                        "security_number": "HQTNM5-HY9YF%-QS5NZ4-Q8&Z4&-HMJ#8",
                        "serial_number": "4815-052713529-200818",
                        "creation_date": 1769621353354,
                        "ticket_image": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "errors": [
                        "Access denied"
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid input or company not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                },
                "examples": {
                  "invalid-input": {
                    "value": {
                      "error": "Invalid input"
                    }
                  },
                  "company-not-found": {
                    "value": {
                      "error": "Company not found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LotteryDrawResponse": {
        "type": "object",
        "properties": {
          "draw_date": {
            "type": "string",
            "description": "Date of the lottery draw in DD/MM/YYYY format",
            "pattern": "^\\d{2}/\\d{2}/\\d{4}$",
            "example": "13/01/2026"
          },
          "draw_number": {
            "type": "string",
            "description": "Draw number identifier",
            "example": "7327"
          },
          "base_price": {
            "type": "integer",
            "description": "Base minimum price for a standard bet in cents (e.g., 1500 = $15.00 MXN)",
            "minimum": 0,
            "example": 1500
          },
          "min_price": {
            "type": "integer",
            "description": "Minimum price allowed by the provider",
            "example": 1500
          },
          "max_price": {
            "type": "integer",
            "description": "Maximum price allowed by the provider",
            "example": 3780000
          },
          "rematch": {
            "type": "integer",
            "description": "Additional base price for rematch option per bet in cents (e.g., 1000 = $10.00 MXN per bet)",
            "minimum": 0,
            "example": 1000
          },
          "second_rematch": {
            "type": "integer",
            "description": "Additional base price for second rematch option per bet in cents (e.g., 500 = $5.00 MXN per bet). Requires rematch to be enabled.",
            "minimum": 0,
            "example": 500
          },
          "begin_sales": {
            "type": "string",
            "description": "Start time of the sales period for the draw in HH:MM:SS format (24-hour format)",
            "pattern": "^\\d{2}:\\d{2}:\\d{2}$",
            "example": "08:00:00"
          },
          "end_sales": {
            "type": "string",
            "description": "End time of the sales period for the draw in HH:MM:SS format (24-hour format)",
            "pattern": "^\\d{2}:\\d{2}:\\d{2}$",
            "example": "23:59:59"
          },
          "minimum_number_of_boards": {
            "type": "integer",
            "description": "Minimum number of boards/combinations allowed by the provider. Used to validate combination_count in purchase request.",
            "minimum": 1,
            "example": 1
          },
          "maximum_number_of_boards": {
            "type": "integer",
            "description": "Maximum number of boards/combinations allowed by the provider. Used to validate combination_count in purchase request.",
            "minimum": 1,
            "maximum": 6,
            "example": 6
          }
        }
      },
      "CreateLotteryTicketRequest": {
        "type": "object",
        "properties": {
          "payee_id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the lottery operator/company",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "payer_reference": {
            "type": "string",
            "description": "Payer reference (unique transaction identifier).\nMust be unique per transaction. Recommended to use UUID or timestamp-based ID.\n",
            "example": "1234567890"
          },
          "ticket": {
            "$ref": "#/components/schemas/TicketRequest"
          },
          "branch": {
            "$ref": "#/components/schemas/BranchInfo"
          }
        },
        "required": [
          "payee_id",
          "payer_reference",
          "ticket",
          "branch"
        ]
      },
      "TicketRequest": {
        "type": "object",
        "properties": {
          "draw_number": {
            "type": "string",
            "description": "Draw number obtained from GET /api/v1/lottery_tickets/new endpoint.\nMust match the current active draw number.\n",
            "example": "7327"
          },
          "combination_count": {
            "type": "integer",
            "description": "Number of combinations/boards to play.\nMust be between minimum_number_of_boards and maximum_number_of_boards from draw info.\nTypically 1-6, but always validate against draw info.\n",
            "minimum": 1,
            "maximum": 6,
            "example": 5
          },
          "rematch": {
            "type": "boolean",
            "description": "Indicates if rematch option is included.\nIf true, adds rematch price per combination from draw info.\n",
            "example": true
          },
          "second_rematch": {
            "type": "boolean",
            "description": "Indicates if second rematch option is included.\n**Requires rematch to be true.** If true, adds second_rematch price per combination from draw info.\n",
            "example": true
          },
          "total_amount": {
            "type": "string",
            "description": "Total amount in cents as a string representation of integer.\nMust match calculated price: (base_price + rematch_price + second_rematch_price) * combination_count\nExample: \"10000\" = $100.00 MXN\n",
            "pattern": "^\\d+$",
            "example": "10000"
          }
        },
        "required": [
          "draw_number",
          "combination_count",
          "rematch",
          "second_rematch",
          "total_amount"
        ]
      },
      "BranchInfo": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the business where the sale is being made",
            "example": "Abarrotes Don Pepe"
          },
          "street": {
            "type": "string",
            "description": "Street address of the business",
            "example": "Av. Insurgentes Sur 1234"
          },
          "city": {
            "type": "string",
            "description": "City of the business",
            "example": "Ciudad de México"
          },
          "neighborhood": {
            "type": "string",
            "description": "Neighborhood of the business",
            "example": "Del Valle"
          }
        },
        "required": [
          "name",
          "street",
          "city",
          "neighborhood"
        ]
      },
      "LotteryTicketResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the lottery ticket",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "client_id": {
            "type": "integer",
            "description": "ID of the client who made the purchase",
            "example": 123
          },
          "ticket": {
            "$ref": "#/components/schemas/TicketResponse"
          },
          "branch": {
            "$ref": "#/components/schemas/BranchInfo"
          },
          "receipt": {
            "$ref": "#/components/schemas/ReceiptResponse"
          },
          "status": {
            "type": "string",
            "description": "Ticket status",
            "enum": [
              "pending",
              "processed",
              "completed",
              "failed"
            ],
            "example": "processed"
          },
          "payment": {
            "$ref": "#/components/schemas/PaymentResponse"
          }
        }
      },
      "TicketResponse": {
        "type": "object",
        "properties": {
          "combination_numbers": {
            "type": "string",
            "description": "Selected combination numbers as comma-separated string",
            "example": "10,27,36,41,52,56"
          },
          "draw_number": {
            "type": "string",
            "description": "Identifier of the draw associated with the ticket.",
            "example": "1234"
          },
          "combination_count": {
            "type": "integer",
            "description": "Number of combinations played",
            "example": 5
          },
          "rematch": {
            "type": "boolean",
            "description": "Indicates if rematch was included",
            "example": true
          },
          "second_rematch": {
            "type": "boolean",
            "description": "Indicates if second rematch was included",
            "example": true
          },
          "total_amount": {
            "type": "string",
            "description": "Total amount paid (in cents)",
            "example": "10000"
          },
          "transaction_date": {
            "type": "string",
            "description": "Payment date and time in DD/MM/YYYY HH:MM:SS format",
            "pattern": "^\\d{2}/\\d{2}/\\d{4} \\d{2}:\\d{2}:\\d{2}$",
            "example": "22/12/2025 20:19:57"
          },
          "store_id": {
            "type": "string",
            "description": "Identifier of the store/branch where the ticket was generated.",
            "example": "26226"
          },
          "pos_id": {
            "type": "string",
            "description": "Point of sale ID of the integrator",
            "example": "1"
          },
          "foreign_pos_id": {
            "type": "string",
            "description": "Foreign point of sale identifier",
            "example": "1"
          },
          "transaction_number": {
            "type": "string",
            "description": "Ticket transaction number in the provider system.",
            "example": "432930881"
          },
          "draw_date": {
            "type": "string",
            "description": "Date of the associated draw",
            "example": "DOM JUN 16 2024"
          },
          "reference_number": {
            "type": "string",
            "description": "Ticket reference number",
            "example": "801500019-35600002"
          },
          "session_id": {
            "type": "string",
            "description": "Purchase session identifier",
            "example": "80150001900"
          },
          "security_number": {
            "type": "string",
            "description": "Security code for anti-fraud validation.\nStore this value for ticket validation purposes.\n",
            "example": "HQTNM5-HY9YF%-QS5NZ4-Q8&Z4&-HMJ#8"
          },
          "client_name": {
            "type": "string",
            "description": "Name of the business where the sale was made",
            "example": "Abarrotes Don Pepe"
          },
          "client_street": {
            "type": "string",
            "description": "Street address of the business",
            "example": "Av. Insurgentes Sur 1234"
          },
          "client_city": {
            "type": "string",
            "description": "City of the business",
            "example": "Ciudad de México"
          },
          "client_neighborhood": {
            "type": "string",
            "description": "Neighborhood of the business",
            "example": "Del Valle"
          }
        }
      },
      "PaymentResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique payment identifier",
            "example": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
          },
          "payer_account": {
            "type": "string",
            "description": "Payer reference",
            "example": "1234567890"
          },
          "payee_id": {
            "type": "string",
            "description": "Service id",
            "example": "9432e22b-7e41-4c9e-8d59-9a73e9532342"
          },
          "amount": {
            "type": "number",
            "format": "decimal",
            "description": "Payment amount (in monetary units, e.g., 100.00)",
            "example": 100
          },
          "currency": {
            "type": "string",
            "description": "Payment currency (ISO 4217 code)",
            "example": "MXN"
          },
          "status": {
            "type": "string",
            "description": "Payment status",
            "enum": [
              "pending",
              "completed",
              "failed"
            ],
            "example": "completed"
          },
          "pay_type": {
            "type": "string",
            "description": "Payment type",
            "example": "gambling"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error response format for authentication errors",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of error messages",
            "example": [
              "Access denied"
            ]
          }
        },
        "required": [
          "errors"
        ]
      },
      "ValidationErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message describing the validation failure",
            "enum": [
              "Invalid input",
              "Company not found"
            ],
            "example": "Invalid input"
          }
        },
        "required": [
          "error"
        ]
      },
      "ReceiptResponse": {
        "type": "object",
        "description": "Receipt information for ticket validation and customer records",
        "properties": {
          "combination_numbers": {
            "type": "string",
            "description": "Selected combination numbers as comma-separated string",
            "example": "10,27,36,41,52,56"
          },
          "transaction_date": {
            "type": "string",
            "description": "Payment date and time in DD/MM/YYYY HH:MM:SS format",
            "example": "22/12/2025 20:19:57"
          },
          "store_id": {
            "type": "string",
            "description": "Identifier of the store/branch where the ticket was generated",
            "example": "26226"
          },
          "pos_id": {
            "type": "string",
            "description": "Point of sale ID of the integrator",
            "example": "1"
          },
          "foreign_pos_id": {
            "type": "string",
            "description": "Foreign point of sale identifier",
            "example": "1"
          },
          "transaction_number": {
            "type": "string",
            "description": "Ticket transaction number in the provider system",
            "example": "432930881"
          },
          "reference_number": {
            "type": "string",
            "description": "Ticket reference number",
            "example": "801500019-35600002"
          },
          "session_id": {
            "type": "string",
            "description": "Purchase session identifier",
            "example": "80150001900"
          },
          "security_number": {
            "type": "string",
            "description": "Security code for anti-fraud validation",
            "example": "HQTNM5-HY9YF%-QS5NZ4-Q8&Z4&-HMJ#8"
          },
          "serial_number": {
            "type": "string",
            "description": "Serial number of the ticket",
            "example": "4815-052713529-200818"
          },
          "creation_date": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in milliseconds when the ticket was created",
            "example": 1769621353354
          },
          "ticket_image": {
            "type": "string",
            "description": "Image in Base64",
            "example": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
          }
        },
        "required": [
          "combination_numbers",
          "transaction_date",
          "store_id",
          "pos_id",
          "foreign_pos_id",
          "transaction_number",
          "reference_number",
          "session_id",
          "security_number",
          "serial_number",
          "creation_date",
          "ticket_image"
        ]
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Access Token",
        "description": "Bearer token authentication. Include the token in the Authorization header:\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n\nObtain your access token from Monato support team.\n"
      }
    }
  }
}