# Partner Aggregator API

Pacote de documentacao da API de integracao B2B do agregador publicado pela SharkGame.

Este diretorio foi montado para uso operacional do time de integracao, com foco em:

- onboarding rapido
- autenticacao
- catalogo de endpoints
- portal HTML navegavel com busca e exemplos
- payload de launch do cassino
- feeds e eventos esportivos
- collection Postman pronta para importacao
- especificacao OpenAPI para Swagger e geracao de clientes

## Conteudo deste diretorio

- `README.md`: guia humano de integracao
- `index.html`: portal visual da documentacao com busca, filtros e exemplos
- `partner-aggregator-api.postman_collection.json`: collection completa da API
- `partner-aggregator-api.postman_environment.json`: environment base para Postman
- `openapi.json`: especificacao OpenAPI 3.0 da API

## Base URL

Exemplo local:

```text
http://api.sharkgame.com.br
```

Todos os endpoints descritos aqui usam o prefixo:

```text
/api/partner/v1
```

## Autenticacao

Envie um dos headers abaixo em todas as chamadas:

```http
Authorization: Bearer <partner-token>
```

ou:

```http
X-Partner-Key: <partner-token>
```

## Requisitos de onboarding

Antes de consumir a API:

1. o parceiro precisa existir no painel admin
2. o token precisa estar ativo
3. a `callback_url` do parceiro deve ser cadastrada no painel quando a operacao precisar de retorno webhook/callback
4. o gateway de cassino e o provider esportivo devem estar configurados na SharkGame

## Envelope de resposta

### Sucesso padrao

```json
{
  "success": true,
  "partner": {
    "id": 1,
    "name": "Partner API",
    "slug": "partner-api",
    "status": "active"
  },
  "data": {}
}
```

### Erro de autenticacao

```json
{
  "success": false,
  "message": "API key do parceiro nao informada."
}
```

ou:

```json
{
  "success": false,
  "message": "Parceiro invalido ou inativo."
}
```

### Erro do provider esportivo

```json
{
  "success": false,
  "partner": {
    "id": 1,
    "name": "Partner API",
    "slug": "partner-api",
    "status": "active"
  },
  "provider": "thesports",
  "message": "Falha ao consultar o gateway esportivo.",
  "provider_response": {}
}
```

## Endpoints

## 1. Core do agregador

### GET /api/partner/v1/status

Retorna o estado da integracao do parceiro, do cassino e do provider esportivo.

Resposta resumida:

```json
{
  "success": true,
  "data": {
    "partner": {
      "id": 1,
      "name": "Partner API",
      "slug": "partner-api",
      "status": "active",
      "commission_percent": 20
    },
    "playfiver_configured": true,
    "sports_gateway": {
      "configured": true,
      "provider": "thesports"
    }
  }
}
```

## 2. Cassino

### GET /api/partner/v1/providers

Lista os providers disponiveis no agregador de cassino.

### GET /api/partner/v1/games

Lista os jogos do agregador.

Query params opcionais:

- `provider` integer: filtra por provider

Exemplo:

```text
GET /api/partner/v1/games?provider=1
```

### POST /api/partner/v1/launch

Cria o contexto do jogador e solicita a URL de launch do jogo no agregador.

Payload:

```json
{
  "external_player_id": "player-1001",
  "player_name": "Joao Silva",
  "player_email": "joao@partner.com",
  "player_balance": 250.75,
  "game_code": "aviator",
  "provider": "spribe",
  "game_original": true,
  "lang": "pt",
  "user_rtp": 96
}
```

Campos:

- `external_player_id` string, obrigatorio
- `player_name` string, opcional
- `player_email` email, opcional
- `player_balance` number >= 0, obrigatorio
- `game_code` string, obrigatorio
- `provider` string, obrigatorio
- `game_original` boolean, obrigatorio
- `lang` string, opcional
- `user_rtp` integer entre 0 e 100, opcional

Resposta resumida:

```json
{
  "success": true,
  "partner": {
    "id": 1,
    "slug": "partner-api"
  },
  "data": {
    "launch": {
      "url": "https://..."
    },
    "partner_player": {
      "id": 10,
      "external_player_id": "player-1001",
      "internal_user_id": 55,
      "balance": 250.75
    }
  }
}
```

Observacoes:

- quando o modo configurado usa `persist_partner_players=false`, o sistema pode operar com shadow user
- quando o parceiro esta persistido em banco, a relacao `partner_player` passa a ser materializada

## 3. Sports status

### GET /api/partner/v1/sports/status

Retorna o provider esportivo ativo, status e capacidades declaradas pelo gateway.

## 4. Sports catalog

### POST /api/partner/v1/sports/catalog/refresh

Dispara refresh operacional do catalogo local.

Payload opcional:

```json
{
  "sport_id": 1,
  "import_leagues": true,
  "import_events": true
}
```

### GET /api/partner/v1/sports/catalog/overview

Resumo geral do catalogo local.

### GET /api/partner/v1/sports/catalog/sports

Query params:

- `search`
- `sport_id`
- `country`
- `active`
- `page`
- `per_page`

### GET /api/partner/v1/sports/catalog/countries

Mesmo contrato de filtros do endpoint de esportes.

### GET /api/partner/v1/sports/catalog/leagues

Mesmo contrato de filtros do endpoint de esportes.

### GET /api/partner/v1/sports/catalog/teams

Mesmo contrato de filtros do endpoint de esportes.

### GET /api/partner/v1/sports/catalog/filters

Query params:

- `source`: `prematch` ou `live`
- `sport_id`
- `league_id`
- `country`
- `team_id`
- `search`
- `has_odds`
- `date`
- `date_from`
- `date_to`

## 5. Sports feed

### GET /api/partner/v1/sports/feed/prematch

Query params:

- `search`
- `sport_id`
- `league_id`
- `country`
- `team_id`
- `has_odds`
- `date`
- `date_from`
- `date_to`
- `page`
- `per_page`
- `sort_by`: `time`, `league_name`, `home_name`, `away_name`, `last_update`
- `sort_direction`: `asc` ou `desc`

### GET /api/partner/v1/sports/feed/live

Mesmo contrato do feed prematch.

## 6. Sports events e odds

### GET /api/partner/v1/sports/leagues?sport_id=1

Lista ligas do provider esportivo.

### GET /api/partner/v1/sports/events/upcoming?sport_id=1&page=1

Lista agenda futura.

### GET /api/partner/v1/sports/events/live?sport_id=1

Lista eventos ao vivo.

### GET /api/partner/v1/sports/events/live/{eventId}?sport_id=1

Detalhe de um evento ao vivo.

### GET /api/partner/v1/sports/events/ended?sport_id=1&day=20260516&page=1

Lista eventos encerrados.

### GET /api/partner/v1/sports/events/{eventId}/odds

Odds pre-match do evento.

### GET /api/partner/v1/sports/events/{eventId}/odds/live

Odds live do evento.

### GET /api/partner/v1/sports/events/{eventId}/lineup

Lineup do evento.

### GET /api/partner/v1/sports/events/{eventId}/stats-trend

Estatisticas e tendencia do evento.

### GET /api/partner/v1/sports/events/{eventId}/result

Resultado consolidado do evento.

## Codigos de status comuns

- `200`: sucesso
- `401`: token ausente, invalido ou parceiro inativo
- `404`: evento ou resultado nao encontrado
- `422`: payload invalido
- `500`: falha interna de aplicacao
- `502`: erro do provider esportivo

## Fluxo recomendado de integracao

1. validar token com `GET /api/partner/v1/status`
2. consultar `GET /api/partner/v1/providers`
3. consultar `GET /api/partner/v1/games`
4. fazer launch com `POST /api/partner/v1/launch`
5. para sports, iniciar por `GET /api/partner/v1/sports/status`
6. usar catalogo e feeds antes de chamar detalhes de evento e odds

## Webhook e callback do parceiro

A URL de callback do parceiro nao e cadastrada por endpoint publico nesta API.

Ela deve ser definida:

- no painel admin da SharkGame
- ou no painel do proprio parceiro no agregador, na area de chave token / webhook

## Postman

Importe os dois arquivos deste diretorio no Postman:

- `partner-aggregator-api.postman_collection.json`
- `partner-aggregator-api.postman_environment.json`

Depois ajuste:

- `baseUrl`
- `partnerToken`
- `providerId`
- `eventId`
- `gameCode`

## HTML e OpenAPI

- `index.html`: versao navegavel da documentacao para consulta rapida no navegador
- `openapi.json`: arquivo compativel com Swagger Editor, Redoc e geradores OpenAPI

## Observacoes finais

- o envelope externo da API e estavel
- o conteudo de `data` pode variar conforme o provider esportivo configurado
- alguns retornos de provider podem vir com estrutura expandida em `provider_response`
- em ambiente de homologacao, use um token de parceiro nao produtivo