RVO Bridge API – Integration Manual for BetConstruct

Operator: ALEKS CZ s.r.o. (ICO: 26212013)

Version: 2.0

1. Purpose and Scope

This document describes the RVO Bridge API that BetConstruct (BC) will use to integrate with the Czech Ministry of Finance Automated Gambling Information System (AISG). The Bridge exposes a stable REST/JSON interface in English for BC and internally communicates with Czech state systems (ROB and RVO) in the required MF/AISG formats.

The key principle is stability: after the operator obtains the license and the Bridge is fully connected to AISG, BC will not need to change anything in its integration – endpoints, payloads and behaviour remain identical.

2. Base URL and Environment

The RVO Bridge is available over HTTPS only.

All endpoints documented below are relative to this base path.

3. Authentication

All endpoints under /api/v1/ require an API key.

Every request should also include the operator identifier (ICO) in the payload where required. For ALEKS CZ the value is:

• operatorId (ICO): 26212013

4. General Conventions

4.1 HTTP Methods and Status Codes

• GET is used for health check.
• POST is used for all business endpoints.

4.2 Time Format

All timestamps are UTC and use ISO 8601 format:

YYYY-MM-DDTHH:mm:ssZ
e.g. 2025-11-15T10:12:30Z

4.3 Error Object

When a request fails validation or processing, the response body contains an error object:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "player.birthDate is required"
  }
}

The list of all possible error codes is provided in section 8.

4.4 MF Mapping Block (mf)

Some responses contain an additional mf object with fields used for the internal mapping to MF/AISG services. Example:

"mf": {
  "duvod": "Registrace",
  "plnoleta": "ANO",
  "nalezenaROB": "NEPROVEDENA",
  "nalezenaRVO": "NE"
}

BetConstruct can safely ignore this block. It is provided for traceability and for debugging integration with AISG.

5. Verify Player

The verify-player endpoint verifies a player for one of three purposes: registration, entry, or login. It checks:

• age (18+ requirement),
• RVO exclusion status,
• and, in full AISG integration, existence of the person in the population register (ROB).

This call never creates an exclusion. It is purely a check used during registration/login/entry.

5.1 Endpoint

5.2 Request Body

Example request:

{
  "requestId": "d2f79b2b-6d5d-4e52-91e2-7bcb0d963a10",
  "reason": "REGISTRATION",
  "operatorId": "26212013",
  "hid": null,
  "player": {
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1985-04-10",
    "citizenship": "CZ"
  },
  "placeId": "26212013|PRAHA_KASINO_01",
  "locationType": null
}

5.2.1 Top-Level Fields

5.2.2 reason Values

5.2.3 player Object

5.3 Behaviour and Validation

• REGISTRATION: player is required; hid is optional.
• LOGIN: hid is required; player is not required.
• ENTRY: at least one of hid or player must be present.
• At least one of placeId or locationType must be provided.
• If player.birthDate is present, the Bridge calculates isAdult (18+).

5.4 Response Body

Example successful response:

{
  "requestId": "d2f79b2b-6d5d-4e52-91e2-7bcb0d963a10",
  "hid": "0b0a236d-6e6b-4a3e-8e8b-4f5eb095b7fb",
  "isAdult": true,
  "robStatus": "NOT_PERFORMED",
  "rvoStatus": "NOT_EXCLUDED",
  "allowed": true,
  "checkedAt": "2025-11-15T10:12:30Z",
  "source": "MIASCON_BRIDGE_RVO",
  "mf": {
    "duvod": "Registrace",
    "plnoleta": "ANO",
    "nalezenaROB": "NEPROVEDENA",
    "nalezenaRVO": "NE"
  },
  "error": null
}

5.4.1 Response Fields

5.4.2 robStatus Values

5.4.3 rvoStatus Values

6. Panic Button – 48h Exclusion

The panic-button endpoint creates a temporary exclusion for the player for exactly 48 hours. It is meant to implement the legal requirement of a fast self-protection mechanism. Internally it maps to MF AISG method VyloucitNa48hod.

6.1 Endpoint

6.2 Request Body

{
  "requestId": "f1a2b3c4-d5e6-7890-abcd-ef0123456789",
  "operatorId": "26212013",
  "hid": "0b0a236d-6e6b-4a3e-8e8b-4f5eb095b7fb",
  "placeId": "26212013|PRAHA_KASINO_01",
  "locationType": null
}

6.3 Response Body

{
  "requestId": "f1a2b3c4-d5e6-7890-abcd-ef0123456789",
  "hid": "0b0a236d-6e6b-4a3e-8e8b-4f5eb095b7fb",
  "result": "PROCESSED",
  "effectiveFrom": "2025-11-15T10:13:00Z",
  "effectiveTo": "2025-11-17T10:13:00Z",
  "source": "MIASCON_BRIDGE_RVO",
  "mf": {
    "vysledekPozadavku": "ZPRACOVAN"
  },
  "error": null
}

7. Long-Term Self-Exclusion Request

The request-exclusion endpoint sends a long-term self-exclusion request for the player. Internally it maps to AISG method ZaslatZadostVylouceni.

7.1 Endpoint

7.2 Request Body

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-0123456789ef",
  "operatorId": "26212013",
  "hid": "0b0a236d-6e6b-4a3e-8e8b-4f5eb095b7fb",
  "sendByEmail": true,
  "email": "player@example.com",
  "placeId": null,
  "locationType": "INTERNET"
}

7.3 Response Body

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-0123456789ef",
  "hid": "0b0a236d-6e6b-4a3e-8e8b-4f5eb095b7fb",
  "result": "ACCEPTED",
  "source": "MIASCON_BRIDGE_RVO",
  "mf": {
    "vysledekPozadavku": "PRIJAT"
  },
  "error": null
}

8. Error Codes

All error responses use the same structure with error.code and error.message.

9. Health Check Endpoint

Example response:

{
  "status": "ok",
  "environment": "MIASCON RVO Playground",
  "time": "2025-11-15T10:12:30Z"
}

10. Future AISG Integration

Once the operator obtains the official license, the Bridge will be connected to the real MF AISG SOAP services for ROB and RVO. All Czech-language structures, XSD formats and SOAP details are handled internally.

For BetConstruct this means:

• Same base URL and endpoints.
• Same request and response JSON structures.
• Same behaviour and error codes.

No changes on the BC side will be required.

11. Contact

Technical integration: MIASCON
Operator: ALEKS CZ s.r.o. (ICO: 26212013)