Crie na V-ENT

Obter acesso

1. Candidate-se na página de parceiros, indicando o que está a criar e os scopes de que precisa.
2. Um administrador da V-ENT analisa e aprova os scopes concedidos. Pode aprovar menos do que pediu.
3. Gere uma chave na sua página de parceiro. O segredo é mostrado uma única vez, por isso guarde-o antes de fechar o separador.

Uma chave nunca pode ter um scope que a sua organização não recebeu, seja qual for o pedido. Suspender um parceiro para imediatamente todas as suas chaves, sem esperar que expirem.

Autenticação

Envie a chave como bearer token em cada pedido.

curl https://api.v-ent.co/api/v1/whoami/ \
  -H "Authorization: Bearer vent_pk_<key id>.<secret>"

whoami é o primeiro endpoint a chamar: devolve o parceiro a que a chave pertence e os scopes exatos que carrega, a forma mais rápida de distinguir uma chave mal configurada de uma permissão em falta.

Scopes

Cada endpoint exige um scope. Peça apenas o que usa: um pedido que abrange tudo demora mais a ser aprovado.

events:read

Read events, their schedule and their venues

events:tickets:read

Read ticket types and remaining capacity for events

tournaments:read

Read tournaments, formats, prize pools and schedules

tournaments:participants:read

Read who is registered for a tournament

tournaments:brackets:read

Read brackets, matches and results

teams:read

Read team profiles and rosters

players:read

Read public player profiles

players:stats:read

Read player win and loss records

rankings:read

Read platform rankings

Endpoints

Todos apenas de leitura, todos em /api/v1/. As listas são paginadas e devolvem results, count e a página pedida.

curl "https://api.v-ent.co/api/v1/tournaments/?page=1" \
  -H "Authorization: Bearer vent_pk_<key id>.<secret>"

Todas as respostas têm a mesma forma

Sucesso ou falha, são as mesmas chaves no nível de topo e mais nada. Ramifique por code, nunca por message: a mensagem é escrita para uma pessoa e pode ser reescrita, o código é o contrato.

{ "status": "success", "data": { }, "message": "Tournaments" }

{ "status": "error", "code": "SCOPE_REQUIRED", "message": "…", "data": null }

Paginação

Todas as listas paginam da mesma forma. page começa em 1, page_size é 25 por omissão e para nos 100. Pagine com has_more em vez de contar: vem da mesma consulta que as linhas, por isso não as pode contradizer.

GET /api/v1/tournaments/?page=2&page_size=50

{ "results": [ … ], "page": 2, "page_size": 50, "total": 137, "has_more": true }

Indicar que os dados vêm da V-ENT

GET /api/v1/ traz um bloco brand com as marcas e a única indicação a seguir, para não ter de ir buscar um logótipo ao site no tamanho em que o encontrar. Não é precisa chave para o ler, porque quem está a decidir se integra ainda não tem uma.

"brand": {
  "name": "V-ENT",
  "logo": "https://v-ent.co/images/logo_mark_red.png",
  "logo_svg": "https://v-ent.co/images/logo_mark_red.svg",
  "colour": "#ED1C24",
  "attribution": "Data from V-ENT"
}

Use a marca para indicar de onde vieram os dados, nas suas próprias proporções e nunca com menos de 24 px de altura. Não a recolora, não a estique e não a utilize de forma a sugerir que a V-ENT recomenda o seu produto. Prefira o SVG: mantém-se nítido em qualquer tamanho, o que o PNG não faz.

Limite de pedidos

60 pedidos por minuto por chave. Peça se precisar de mais, dizendo para quê. As classificações e os quadros terminados mudam raramente, por isso um minuto de cache não lhe custa nada e mantém-no bem dentro do limite.

Quatro coisas a saber antes de construir

Enderece os registos por slug

Todos os endereços V-ENT que uma pessoa vê usam o slug, e um registo renomeado mantém os endereços antigos a funcionar. É o que quer num link de volta para nós.

O dinheiro é uma cadeia decimal

\"220000.00\", não um número. Analise-o como decimal. Um prémio que passou por um float é um prémio que mais tarde vai mostrar errado.

As horas são UTC, ISO 8601

Com o Z no fim. Converta para os seus leitores; não assuma Lagos.

Apenas registos públicos

Rascunhos, torneios privados e tudo o que pertence a uma conta suspensa nunca são devolvidos, e nenhum âmbito os abre.

Iniciar sessão com V-ENT

Fluxo authorization-code padrão com PKCE. Se já integrou o "Iniciar sessão com Google", conhece o formato. Peça a um administrador da V-ENT para aprovar o SSO na sua conta de parceiro e receberá um client id e um segredo, mostrado uma vez.

Scopes de identidade

• identity
• identity:email
• identity:teams

Crie primeiro um par PKCE

Guarde o verificador na sessão do visitante, no seu servidor; nunca sai dela. Envie apenas o desafio. Se enviar um desafio, é esse que é verificado e o seu segredo de cliente não é consultado, razão pela qual uma aplicação de navegador nunca precisa de um.

const verifier  = base64url(randomBytes(32));   // keep this
const challenge = base64url(sha256(verifier));  // send this

1. Encaminhe-os para a V-ENT

https://v-ent.co/partners/authorize
  ?client_id=vent_sso_<yours>
  &redirect_uri=https://your-site.example/callback
  &scope=identity identity:email
  &state=<random, checked when they come back>
  &code_challenge=<base64url(sha256(verifier))>
  &code_challenge_method=S256

2. Troque o código, a partir do seu servidor

curl -X POST https://api.v-ent.co/partners/sso/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<the code on your callback>",
    "client_id": "vent_sso_<yours>",
    "client_secret": "<yours>",
    "redirect_uri": "https://your-site.example/callback",
    "code_verifier": "<the verifier you hashed>"
  }'

3. Leia quem é

curl https://api.v-ent.co/partners/sso/userinfo/ \
  -H "Authorization: Bearer <access_token>"

O código é de uso único e de curta duração, e um verifier PKCE errado é recusado. Faça a troca a partir do seu servidor, nunca do navegador: o client secret não pode chegar a uma página que qualquer pessoa possa ler.

Identifique a conta por sub

Não pelo nome de utilizador. Uma pessoa pode mudá-lo; sub é estável durante toda a vida da conta e é o único campo aqui seguro como chave primária do seu lado.

Quem entrou com a V-ENT pode remover a ligação a partir da sua conta, e os tokens existentes deixam de funcionar. Trate BAD_TOKEN reiniciando o fluxo, não mantendo uma sessão morta.

Não existe nenhum âmbito que leia uma carteira, um saldo, uma transação, um pagamento ou um documento de identidade, e não passará a existir. Está escrito no código, não numa política.

Quando algo corre mal

Cada falha devolve um código legível por máquina além de uma frase. Use o código: a frase pode ser reescrita.

{ "status": "error", "code": "INVALID_KEY", "message": "That key is not valid.", "data": null }

MISSING_KEY

Cabeçalho Authorization em falta, ou não é um bearer token.

MALFORMED_KEY

Isto não é uma chave V-ENT. Verifique o prefixo vent_pk_ e o ponto antes do segredo. 401.

INVALID_KEY

Key id desconhecido, segredo errado, ou a chave foi revogada.

PARTNER_INACTIVE

A conta de parceiro está suspensa ou ainda não foi aprovada. As chaves deixam de funcionar de imediato, não na emissão seguinte. 401.

SCOPE_REQUIRED

A chave é válida mas não foi aprovada para este endpoint.

RATE_LIMITED

Demasiados pedidos neste minuto. Aguarde e tente novamente.

EVENT_NOT_FOUND

Não existe tal registo, ou não é público. Um registo privado responde 404 em vez de 403, porque dizer que existe já é uma divulgação. Também TOURNAMENT_NOT_FOUND, TEAM_NOT_FOUND, PLAYER_NOT_FOUND. 404.