{"openapi":"3.0.3","info":{"title":"zt-partners · Integração de marcas","version":"1.0.0","description":"\nToda chamada é autenticada pela marca com três headers:\n\n| Header | Valor |\n| --- | --- |\n| `x-brand-key` | API key da marca (exibida na criação / rotação) |\n| `x-timestamp` | epoch em **segundos**; janela de ±300s |\n| `x-signature` | `hex( HMAC-SHA256( hmac_secret, `${timestamp}.${rawBody}` ) )` |\n\nO `rawBody` é exatamente o JSON enviado (bytes), sem re-serializar.\n\n**Idempotência:** `event_id` é único por marca. Reenviar o mesmo `event_id` responde `duplicate` e não reprocessa.\nEventos de jogador **não atribuído** (sem `player.registered` prévio com `btag` válido) respondem `rejected` / `player_not_attributed`.\n\n**Fluxo de atribuição:** o redirector grava o click em `tags` e envia o jogador para a marca com `?btag=<tagId>`.\nA marca guarda o `btag` no cadastro e envia `player.registered` com ele.\n"},"servers":[{"url":"https://api.servportal.com"}],"tags":[{"name":"Eventos","description":"Eventos do ciclo de vida do jogador enviados pela marca"},{"name":"Consulta","description":"Leituras auxiliares"}],"components":{"securitySchemes":{"BrandKey":{"type":"apiKey","in":"header","name":"x-brand-key"},"Timestamp":{"type":"apiKey","in":"header","name":"x-timestamp"},"Signature":{"type":"apiKey","in":"header","name":"x-signature"}},"schemas":{"PlayerRegistered":{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["player.registered"]},"btag":{"type":"string","minLength":1},"meta":{"type":"object","additionalProperties":{"nullable":true}},"profile":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1,"maxLength":32},"name":{"type":"string","minLength":1,"maxLength":160},"locale":{"type":"string","minLength":1,"maxLength":16},"birth_date":{"type":"string","minLength":1,"maxLength":32},"consents":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}}},"attributes":{"type":"object","additionalProperties":{"nullable":true}}}}},"required":["event_id","occurred_at","external_player_id","type"]},"DepositConfirmed":{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["deposit.confirmed"]},"external_tx_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"is_ftd":{"type":"boolean"}},"required":["event_id","occurred_at","external_player_id","type","external_tx_id","amount"]},"WithdrawalConfirmed":{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["withdrawal.confirmed"]},"external_tx_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0}},"required":["event_id","occurred_at","external_player_id","type","external_tx_id","amount"]},"BetPlaced":{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.placed"]},"external_bet_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"product":{"type":"string","minLength":1,"maxLength":64,"default":"default"}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id","amount"]},"BetSettled":{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.settled"]},"external_bet_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"payout":{"type":"number","minimum":0},"product":{"type":"string","minLength":1,"maxLength":64,"default":"default"}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id","amount","payout"]},"BetCancelled":{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.cancelled"]},"external_bet_id":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":256}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id"]},"PlayerStatusChanged":{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["player.status_changed"]},"status":{"type":"string","enum":["ACTIVE","BLOCKED"]}},"required":["event_id","occurred_at","external_player_id","type","status"]},"IntegrationEvent":{"oneOf":[{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["player.registered"]},"btag":{"type":"string","minLength":1},"meta":{"type":"object","additionalProperties":{"nullable":true}},"profile":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1,"maxLength":32},"name":{"type":"string","minLength":1,"maxLength":160},"locale":{"type":"string","minLength":1,"maxLength":16},"birth_date":{"type":"string","minLength":1,"maxLength":32},"consents":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}}},"attributes":{"type":"object","additionalProperties":{"nullable":true}}}}},"required":["event_id","occurred_at","external_player_id","type"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["player.profile_updated"]},"profile":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1,"maxLength":32},"name":{"type":"string","minLength":1,"maxLength":160},"locale":{"type":"string","minLength":1,"maxLength":16},"birth_date":{"type":"string","minLength":1,"maxLength":32},"consents":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}}},"attributes":{"type":"object","additionalProperties":{"nullable":true}}}}},"required":["event_id","occurred_at","external_player_id","type","profile"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["deposit.confirmed"]},"external_tx_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"is_ftd":{"type":"boolean"}},"required":["event_id","occurred_at","external_player_id","type","external_tx_id","amount"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["withdrawal.confirmed"]},"external_tx_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0}},"required":["event_id","occurred_at","external_player_id","type","external_tx_id","amount"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.placed"]},"external_bet_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"product":{"type":"string","minLength":1,"maxLength":64,"default":"default"}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id","amount"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.settled"]},"external_bet_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"payout":{"type":"number","minimum":0},"product":{"type":"string","minLength":1,"maxLength":64,"default":"default"}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id","amount","payout"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.cancelled"]},"external_bet_id":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":256}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["player.status_changed"]},"status":{"type":"string","enum":["ACTIVE","BLOCKED"]}},"required":["event_id","occurred_at","external_player_id","type","status"]}]}},"parameters":{}},"paths":{"/v1/integration/events":{"post":{"tags":["Eventos"],"summary":"Envia um evento","description":"Persiste o evento (idempotente por `event_id`) e enfileira o processamento de comissões.","security":[{"BrandKey":[],"Timestamp":[],"Signature":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationEvent"},"examples":{"PlayerRegistered":{"value":{"type":"player.registered","event_id":"reg-6650a1","occurred_at":"2026-09-29T15:00:00Z","external_player_id":"6650a1b2c3d4e5f6a7b8c9d0","btag":"66509f0e2b1c4d5e6f708192","meta":{"source":"web"}}},"DepositConfirmed":{"value":{"type":"deposit.confirmed","event_id":"dep-7781","occurred_at":"2026-09-29T15:05:00Z","external_player_id":"6650a1b2c3d4e5f6a7b8c9d0","external_tx_id":"7781","amount":50,"is_ftd":true}},"WithdrawalConfirmed":{"value":{"type":"withdrawal.confirmed","event_id":"wd-9921","occurred_at":"2026-09-30T10:00:00Z","external_player_id":"6650a1b2c3d4e5f6a7b8c9d0","external_tx_id":"9921","amount":30}},"BetPlaced":{"value":{"type":"bet.placed","event_id":"bet-5510","occurred_at":"2026-09-29T15:10:00Z","external_player_id":"6650a1b2c3d4e5f6a7b8c9d0","external_bet_id":"5510","amount":10,"product":"lottery"}},"BetSettled":{"value":{"type":"bet.settled","event_id":"settle-5510","occurred_at":"2026-09-29T18:00:00Z","external_player_id":"6650a1b2c3d4e5f6a7b8c9d0","external_bet_id":"5510","amount":10,"payout":0,"product":"lottery"}},"BetCancelled":{"value":{"type":"bet.cancelled","event_id":"cancel-5510","occurred_at":"2026-09-29T15:20:00Z","external_player_id":"6650a1b2c3d4e5f6a7b8c9d0","external_bet_id":"5510","reason":"draw_cancelled"}},"PlayerStatusChanged":{"value":{"type":"player.status_changed","event_id":"status-1","occurred_at":"2026-09-29T20:00:00Z","external_player_id":"6650a1b2c3d4e5f6a7b8c9d0","status":"BLOCKED"}}}}}},"responses":{"200":{"description":"Evento recebido","content":{"application/json":{"schema":{"type":"object","properties":{"r":{"type":"boolean","enum":[true]},"content":{"type":"object","properties":{"event_id":{"type":"string"},"status":{"type":"string","enum":["accepted","duplicate","rejected"]},"reason":{"type":"string"}},"required":["event_id","status"]}},"required":["r","content"]}}}},"400":{"description":"Payload inválido","content":{"application/json":{"schema":{"type":"object","properties":{"r":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"string"}}},"required":["r","errors"]}}}},"401":{"description":"Credenciais / assinatura inválidas","content":{"application/json":{"schema":{"type":"object","properties":{"r":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"string"}}},"required":["r","errors"]}}}}}}},"/v1/integration/events/batch":{"post":{"tags":["Eventos"],"summary":"Envia até 500 eventos (backfill / reenvio)","security":[{"BrandKey":[],"Timestamp":[],"Signature":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["player.registered"]},"btag":{"type":"string","minLength":1},"meta":{"type":"object","additionalProperties":{"nullable":true}},"profile":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1,"maxLength":32},"name":{"type":"string","minLength":1,"maxLength":160},"locale":{"type":"string","minLength":1,"maxLength":16},"birth_date":{"type":"string","minLength":1,"maxLength":32},"consents":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}}},"attributes":{"type":"object","additionalProperties":{"nullable":true}}}}},"required":["event_id","occurred_at","external_player_id","type"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["player.profile_updated"]},"profile":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1,"maxLength":32},"name":{"type":"string","minLength":1,"maxLength":160},"locale":{"type":"string","minLength":1,"maxLength":16},"birth_date":{"type":"string","minLength":1,"maxLength":32},"consents":{"type":"object","properties":{"email":{"type":"boolean"},"sms":{"type":"boolean"},"push":{"type":"boolean"}}},"attributes":{"type":"object","additionalProperties":{"nullable":true}}}}},"required":["event_id","occurred_at","external_player_id","type","profile"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["deposit.confirmed"]},"external_tx_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"is_ftd":{"type":"boolean"}},"required":["event_id","occurred_at","external_player_id","type","external_tx_id","amount"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["withdrawal.confirmed"]},"external_tx_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0}},"required":["event_id","occurred_at","external_player_id","type","external_tx_id","amount"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.placed"]},"external_bet_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"product":{"type":"string","minLength":1,"maxLength":64,"default":"default"}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id","amount"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.settled"]},"external_bet_id":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0},"payout":{"type":"number","minimum":0},"product":{"type":"string","minLength":1,"maxLength":64,"default":"default"}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id","amount","payout"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["bet.cancelled"]},"external_bet_id":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":256}},"required":["event_id","occurred_at","external_player_id","type","external_bet_id"]},{"type":"object","properties":{"event_id":{"type":"string","minLength":1,"maxLength":128},"occurred_at":{"type":"string","nullable":true},"external_player_id":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["player.status_changed"]},"status":{"type":"string","enum":["ACTIVE","BLOCKED"]}},"required":["event_id","occurred_at","external_player_id","type","status"]}]},"minItems":1,"maxItems":500}},"required":["events"]}}}},"responses":{"200":{"description":"Resultado por evento","content":{"application/json":{"schema":{"type":"object","properties":{"r":{"type":"boolean","enum":[true]},"content":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"event_id":{"type":"string"},"status":{"type":"string","enum":["accepted","duplicate","rejected"]},"reason":{"type":"string"}},"required":["event_id","status"]}},"accepted":{"type":"integer"}},"required":["results","accepted"]}},"required":["r","content"]}}}},"400":{"description":"Payload inválido","content":{"application/json":{"schema":{"type":"object","properties":{"r":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"string"}}},"required":["r","errors"]}}}},"401":{"description":"Credenciais / assinatura inválidas","content":{"application/json":{"schema":{"type":"object","properties":{"r":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"string"}}},"required":["r","errors"]}}}}}}},"/v1/integration/players/{externalId}/attribution":{"get":{"tags":["Consulta"],"summary":"Atribuição de um jogador","description":"Informa se o jogador está atribuído a um afiliado e a qual deal. Body vazio: assine `${timestamp}.` (string vazia após o ponto).","security":[{"BrandKey":[],"Timestamp":[],"Signature":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"externalId","in":"path"}],"responses":{"200":{"description":"Atribuição","content":{"application/json":{"schema":{"type":"object","properties":{"r":{"type":"boolean","enum":[true]},"content":{"type":"object","properties":{"attributed":{"type":"boolean"},"attribution":{"type":"object","nullable":true,"properties":{"external_player_id":{"type":"string"},"deal_public_id":{"type":"string"},"registered_at":{"type":"string"},"ftd_at":{"type":"string","nullable":true},"status":{"type":"string","enum":["ACTIVE","BLOCKED"]},"tag_id":{"type":"string"},"affiliate":{"type":"object","properties":{"public_id":{"type":"string"},"name":{"type":"string"}},"required":["public_id","name"]}},"required":["external_player_id","deal_public_id","registered_at","ftd_at","status","tag_id","affiliate"]}},"required":["attributed","attribution"]}},"required":["r","content"]}}}}}}}}}