Primeiro pedido

Manual de integração · API v1

Ligue o seu site em minutos

A Central de Esportes busca os dados de futebol na fonte uma única vez e entrega para cada site que tem um token. O seu sistema faz pedidos simples, recebe JSON e cuida das apostas do jeito dele.

Endereçohttps://api.3tag.click/api/v1/
AcessoToken Bearer
FormatoJSON
Limite300 pedidos/min

01Visão geral

O caminho dos dados, do campo até o jogador. A central cuida das duas primeiras etapas; o seu sistema, das outras duas.

FontePartidas, odds e placares de futebol
CentralOrganiza, guarda em cache e confere os resultados
Seu siteAplica a sua margem, aceita e paga as apostas
JogadorVê os jogos e aposta

Entre a central e o seu site, todo pedido leva o seu token: Authorization: Bearer cse_…

O que a central entrega

  • Partidas que ainda não começaram, com as odds de 24 mercados (resultado, gols, 1º tempo, escanteios, placar exato e combinados).
  • Ao vivo: relógio, placar, escanteios, cartões e o link da animação 2D.
  • Resultados: placar final, do 1º tempo e escanteios, e as partidas canceladas.

O que fica com o seu sistema

  • Cupom de aposta, carteira do jogador e limites de risco.
  • A sua margem sobre as odds (elas chegam sem margem).
  • A apuração das apostas, com as regras deste manual.

As odds são de pré-jogo: as apostas fecham quando a partida começa. O ao vivo serve para mostrar placar e animação.

02Primeiro pedido em 1 minuto

Com o token que recebeu, peça a situação da central. Se vier o nome do seu site, está tudo certo.

Terminalcurl
curl https://api.3tag.click/api/v1/status \
  -H "Authorization: Bearer cse_SEU_TOKEN" \
  -H "Accept: application/json"
Resposta200
{
    "server_time": "2026-10-01T01:37:43+00:00",
    "fixtures_synced_at": "2026-10-01T01:01:28+00:00",
    "odds_synced_at": "2026-10-01T01:37:13+00:00",
    "results_synced_at": "2026-10-01T01:30:03+00:00",
    "live_synced_at": "2026-10-01T01:37:41+00:00",
    "live_interval": 5,
    "site": {
        "id": 1,
        "name": "seu-site"
    }
}

Endereço base de todas as rotas: https://api.3tag.click/api/v1/

03Token e limites

  • Cada site tem um token próprio, que começa com cse_. Ele vai no cabeçalho Authorization: Bearer de todo pedido.
  • O token aparece uma única vez, quando o site é criado ou o token é trocado. A central guarda só uma impressão dele: se perder, peça um novo.
  • Guarde o token no servidor (variável de ambiente ou banco, criptografado). Nunca no código do navegador.
  • Limite: 300 pedidos por minuto por site. A agenda recomendada usa cerca de 35.
CódigoQuandoO que fazer
200Tudo certoUse a resposta.
401Token não existe ou foi trocadoConfira o token. Não adianta repetir o pedido.
403Site bloqueado na centralFale com quem administra a central.
429Passou de 300 pedidos no minutoEspere o tempo do cabeçalho Retry-After e revise a agenda.
5xx ou sem respostaCentral fora do arMantenha os dados que já tem e tente de novo no próximo ciclo. Veja a validade das odds.
Erro401
{
    "error": "Token inválido."
}

04Partidas e odds

GET /api/v1/fixtures · a cada 1 minuto

Lista completa das partidas que ainda não começaram, nos próximos dias, com todas as odds de cada uma. A resposta já vem pronta da central: pedir a cada minuto é barato.

Resposta (cortada)200
{
    "generated_at": "2026-10-01T01:37:45+00:00",
    "odds_synced_at": "2026-10-01T01:37:13+00:00",
    "fixtures_synced_at": "2026-10-01T01:01:28+00:00",
    "fixtures": [
        {
            "api_id": 5491281,
            "league": {
                "id": 16797,
                "name": "Liga das Nações da UEFA - A",
                "logo": "https://s.q5qo.com/data/6a0b04….png",
                "country": "Europa"
            },
            "season": 2026,
            "home": {
                "name": "Alemanha",
                "logo": "https://s.q5qo.com/data/c66381….png"
            },
            "away": {
                "name": "Sérvia",
                "logo": "https://s.q5qo.com/data/e5cb3b….png"
            },
            "starts_at": "2026-10-01T18:45:00+00:00",
            "status": "NS",
            "odds": [
                ["match_winner", "home", 1.2, 1790818632],
                ["match_winner", "draw", 6.8, 1790818632],
                ["match_winner", "away", 14, 1790818632],
                ["btts", "yes", 1.88, 1790818204],
                ["btts", "no", 1.93, 1790818204],
                ["correct_score", "2-0", 7.1, 1790818204]
            ]
        }
    ]
}
CampoO que é
api_idIdentificador da partida. É o mesmo no ao vivo e nos resultados: use como chave.
leagueLiga: id, name, logo e country (nomes em português).
home, awayMandante e visitante, com nome e escudo.
starts_atInício, em ISO 8601 com fuso (UTC). Converta para o horário do seu site.
statusNS (não começou) ou TBD (horário a confirmar).
oddsLista de [mercado, seleção, odd sem margem, confirmada em]. O último item é a hora (unix, em segundos) em que a fonte confirmou aquela odd pela última vez.

Como gravar

  • A cada pedido, troque todas as odds da partida pelas recebidas. Odd que não veio é mercado suspenso: tire do site.
  • Partida que sumiu da lista começou, foi adiada ou cancelada. Pare de aceitar apostas nela. O desfecho chega em resultados.
  • Feche as apostas no starts_at (ou alguns minutos antes, se preferir), mesmo que a partida ainda esteja na lista.

05Margem e validade das odds

As odds chegam sem margem, para cada site definir a sua. A conta que o prime7 usa:

Fórmulamargem em %
odd do site = arredondar para baixo( odd bruta ÷ (1 + margem ÷ 100), 2 casas )
mínimo 1,01

ex.: odd bruta 2,00 com 6% de margem → 2,00 ÷ 1,06 = 1,886… → 1,88

Regra de segurança

Não aceite aposta numa odd confirmada há mais de 30 minutos (o último item de cada odd). Se a central ou a fonte pararem, as odds envelhecem e o seu site para de aceitar apostas sozinho, em vez de vender odd desatualizada.

Ao aceitar a aposta, confira a odd de novo no seu banco: se ela caiu desde que o jogador montou o cupom, peça confirmação.

06Mercados

Os mercados e as seleções têm nomes fixos, iguais em todas as partidas. Uma partida traz só os mercados que a fonte está oferecendo naquele momento.

MercadoNomeSeleçõesComo apurar
Principais
match_winner Resultado final "home" "draw" "away" Placar final do tempo regulamentar (ft).
double_chance Dupla chance "home_draw" "home_away" "draw_away" Ganha se o resultado for um dos dois da seleção.
draw_no_bet Empate anula "home" "away" Empate devolve a aposta (void). Vitória de quem foi escolhido ganha.
Gols
over_under_25 Total de gols 2,5 "over" "under" Soma de gols (ft) acima ou abaixo de 2,5.
btts Ambas marcam "yes" "no" "yes" ganha se os dois times marcarem pelo menos 1 gol.
over_under_15 Total de gols 1,5 "over" "under" Soma de gols (ft) acima ou abaixo de 1,5.
over_under_35 Total de gols 3,5 "over" "under" Soma de gols (ft) acima ou abaixo de 3,5.
over_under_45 Total de gols 4,5 "over" "under" Soma de gols (ft) acima ou abaixo de 4,5.
exact_goals Total exato de gols "0" "1" "2" "3" "4" "5" "6+" Soma exata de gols (ft); "6+" = 6 gols ou mais.
odd_even Total de gols ímpar/par "odd" "even" Soma de gols ímpar ou par (0 x 0 é par).
which_team_scores Quem marca "none" "only_home" "only_away" "both" Nenhum, só o mandante, só o visitante ou os dois marcam.
home_ou_05 Gols do mandante 0,5 "over" "under" Gols do mandante acima ou abaixo de 0,5.
home_ou_15 Gols do mandante 1,5 "over" "under" Gols do mandante acima ou abaixo de 1,5.
away_ou_05 Gols do visitante 0,5 "over" "under" Gols do visitante acima ou abaixo de 0,5.
away_ou_15 Gols do visitante 1,5 "over" "under" Gols do visitante acima ou abaixo de 1,5.
1º tempo
ht_match_winner Resultado do 1º tempo "home" "draw" "away" Placar do 1º tempo (ht).
ht_over_under_05 Gols no 1º tempo 0,5 "over" "under" Soma de gols do 1º tempo (ht) acima ou abaixo de 0,5.
ht_over_under_15 Gols no 1º tempo 1,5 "over" "under" Soma de gols do 1º tempo (ht) acima ou abaixo de 1,5.
Escanteios
corners_ou_85 Escanteios 8,5 "over" "under" Soma de escanteios do jogo acima ou abaixo de 8,5. Sem o dado, a aposta fica aberta.
corners_ou_95 Escanteios 9,5 "over" "under" Soma de escanteios do jogo acima ou abaixo de 9,5. Sem o dado, a aposta fica aberta.
corners_ou_105 Escanteios 10,5 "over" "under" Soma de escanteios do jogo acima ou abaixo de 10,5. Sem o dado, a aposta fica aberta.
Combinados
winner_btts Resultado + ambas marcam "home_yes" "home_no" "draw_yes" "draw_no" "away_yes" "away_no" As duas coisas precisam acontecer: o resultado e o "ambas marcam".
winner_ou_25 Resultado + total 2,5 "home_over" "home_under" "draw_over" "draw_under" "away_over" "away_under" As duas coisas precisam acontecer: o resultado e o total de 2,5.
Placar exato
correct_score Placar exato "0-0" "1-0" "2-1" … Placar exato do tempo regulamentar, no formato "casa-fora" (ex.: "2-1"). Só vêm os placares com odd.

home = mandante, away = visitante, draw = empate, over = mais de, under = menos de. Nos combinados, as duas partes vêm unidas por _ (ex.: home_yes = mandante vence e ambas marcam).

07Ao vivo

GET /api/v1/live · a cada 2 a 5 segundos

Partidas acontecendo agora, para mostrar placar, relógio e animação. A central atualiza a cada live_interval segundos (veja situação): pedir mais rápido que isso não traz nada novo.

Resposta (cortada)200
{
    "generated_at": "2026-10-01T01:37:41+00:00",
    "live_synced_at": "2026-10-01T01:37:41+00:00",
    "fixtures": [
        {
            "api_id": 5567669,
            "league": {
                "id": 10320,
                "name": "Amigável internacional",
                "logo": "https://s.q5qo.com/data/10d586….png",
                "country": "Internacional"
            },
            "season": 2026,
            "home": {
                "name": "Argentina",
                "logo": "https://…"
            },
            "away": {
                "name": "Bolívia",
                "logo": "https://…"
            },
            "starts_at": "2026-10-01T00:00:00+00:00",
            "status": "LIVE",
            "live": {
                "clock": 4567,
                "running": true,
                "period": 1004,
                "score": [3, 0],
                "ht": [2, 0],
                "corners": [11, 1],
                "yellow": [0, 1],
                "red": [0, 0]
            },
            "goals": [3, 0],
            "animation_url": "https://animation.9u9o.com/animation/index2.html?matchId=6778929&configId=…",
            "live_updated_at": "2026-10-01T01:37:41+00:00"
        }
    ]
}
CampoO que é
live.clockSegundos de jogo. Com running: true, o relógio está andando: conte sozinho no navegador entre um pedido e outro.
live.period1002 1º tempo, 1003 intervalo, 1004 2º tempo. Outros códigos: trate como "em andamento".
live.score, live.htPlacar [mandante, visitante] do jogo e do 1º tempo.
live.corners, yellow, redEscanteios e cartões [mandante, visitante]. Podem vir null.
goalsO mesmo placar, fora do objeto live (atalho).
animation_urlPágina da animação 2D, para abrir num iframe. Para português, acrescente language=pt-br (ou culture=pt-BR se o endereço for da Genius). Pode vir null.

O ao vivo é só para exibir. A apuração usa os resultados, que a central confere depois do apito final.

08Resultados

GET /api/v1/results?since=unix · a cada 1 a 2 minutos

Partidas que terminaram ou foram canceladas, só as que mudaram desde o horário em since (unix, em segundos). Sem since, vêm os últimos 3 dias. O limite de volta é 7 dias, e cada resposta traz até 1.000 partidas.

Resposta (cortada)200
{
    "generated_at": "2026-10-01T01:37:46+00:00",
    "results_synced_at": "2026-10-01T01:30:03+00:00",
    "fixtures": [
        {
            "api_id": 5598917,
            "status": "FT",
            "starts_at": "2026-09-30T13:00:00+00:00",
            "ft": [0, 1],
            "ht": [0, 0],
            "corners": [2, 7],
            "result_updated_at": "2026-09-30T15:32:40+00:00"
        },
        {
            "api_id": 5638031,
            "status": "CANC",
            "starts_at": "2026-09-30T16:00:00+00:00",
            "ft": [null, null],
            "ht": [null, null],
            "corners": [null, null],
            "result_updated_at": "2026-09-30T15:40:02+00:00"
        }
    ]
}

Como ler sem perder nenhum

  1. Guarde o maior result_updated_at recebido (em unix).
  2. No próximo pedido, mande since = esse valor menos 60 segundos (folga para resultados gravados no mesmo segundo).
  3. Por causa da folga, uma partida pode vir de novo: apure cada partida uma vez só.
  4. Se vierem 1.000 partidas, peça de novo na hora com o novo since.
StatusSignificaO que fazer
FT AET PENEncerrada (no tempo normal, na prorrogação ou nos pênaltis)Apure com ft, ht e corners.
CANC ABD AWD WOCancelada, abandonada, decidida fora de campo ou W.O.Devolva as apostas. Na múltipla, a seleção vale odd 1,00.

ft é o placar do tempo regulamentar (90 minutos e acréscimos), mesmo quando o jogo foi para prorrogação ou pênaltis. ht é o placar do 1º tempo e corners os escanteios do jogo.

09Apuração

Cada seleção termina como ganha, perdida ou devolvida, pela regra do mercado na tabela.

  • Devolvida: partida cancelada, ou empate no "empate anula". A aposta simples volta inteira; na múltipla, aquela seleção vale odd 1,00 e as outras seguem.
  • Falta dado (ex.: escanteios null, ou ht vazio num mercado de 1º tempo): deixe a seleção aberta e resolva à mão. Não dê como perdida.
  • Múltipla: perdida se uma seleção perder; ganha quando todas estiverem resolvidas, pagando o produto das odds das que ganharam.

10Ligas

GET /api/v1/leagues · uma vez por dia, ou para montar filtros

selected são as ligas que a central acompanha (vazio = todas). catalog traz o nome em português e quantas partidas cada liga tem agora.

Resposta (cortada)200
{
    "selected": [
        {
            "id": 10580,
            "name": "Brazil Serie A",
            "region": "Brazil"
        },
        {
            "id": 11062,
            "name": "England Premier League",
            "region": "England"
        }
    ],
    "catalog": [
        {
            "id": 10580,
            "name": "Brasil Série A",
            "region": "Brasil",
            "matches": 12
        },
        {
            "id": 11062,
            "name": "Inglaterra Premier League",
            "region": "Inglaterra",
            "matches": 20
        }
    ]
}

11Situação

GET /api/v1/status · a cada 1 a 5 minutos

Horário da última atualização de cada parte, o intervalo do ao vivo e o site dono do token (resposta no primeiro pedido). Use para um alerta no seu painel:

  • odds_synced_at com mais de 10 minutos: odds paradas.
  • live_synced_at com mais de 1 minuto, com jogos acontecendo: ao vivo parado.
  • Pedido sem resposta: a central está fora do ar. As odds vão envelhecendo e a regra dos 30 minutos protege o caixa.

12Agenda recomendada

RotaFrequênciaPedidos por minuto
/fixturesa cada 1 minuto1
/livea cada 2 a 5 segundos (só com jogos ao vivo na tela)12 a 30
/resultsa cada 1 a 2 minutosaté 1
/statusa cada 1 a 5 minutosaté 1
/leaguesuma vez por dia—

Peça à central do seu servidor, não do navegador de cada jogador. Grave no seu banco ou cache e sirva os jogadores a partir dele: 10 ou 10 mil jogadores online fazem o mesmo número de pedidos à central.

13Exemplo em PHP

Um conector mínimo, em PHP puro, para adaptar às tabelas do seu sistema. Em outra linguagem a lógica é a mesma.

conector.phpPHP 8
<?php
// Conector minimo em PHP puro (sem framework). Rode pelo cron: cada funcao no seu intervalo.

const CENTRAL = 'https://central.seudominio.com/api/v1/';
const TOKEN   = 'cse_...'; // guarde fora do codigo (variavel de ambiente)
const MARGEM  = 6;         // % da sua casa

function central(string $rota, array $query = []): array
{
    $ch = curl_init(CENTRAL . $rota . ($query ? '?' . http_build_query($query) : ''));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . TOKEN, 'Accept: application/json'],
    ]);
    $corpo  = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($corpo === false || $status !== 200) {
        throw new RuntimeException("Central respondeu HTTP $status em $rota: $corpo");
    }

    return json_decode($corpo, true);
}

function oddComMargem(float $bruta): float
{
    return max(1.01, floor($bruta / (1 + MARGEM / 100) * 100) / 100);
}

// A cada 1 minuto: partidas e odds (a lista inteira; troque as odds de cada partida pelas recebidas)
function sincronizarPartidas(PDO $db): void
{
    foreach (central('fixtures')['fixtures'] as $p) {
        // grave/atualize a partida: $p['api_id'], $p['home']['name'], $p['starts_at'] (UTC) ...
        $db->prepare('DELETE FROM odds WHERE partida = ?')->execute([$p['api_id']]);
        foreach ($p['odds'] as [$mercado, $escolha, $bruta, $confirmadaEm]) {
            $db->prepare('INSERT INTO odds (partida, mercado, escolha, odd, confirmada_em) VALUES (?, ?, ?, ?, FROM_UNIXTIME(?))')
               ->execute([$p['api_id'], $mercado, $escolha, oddComMargem($bruta), $confirmadaEm]);
        }
    }
}

// A cada 1 a 2 minutos: so o que mudou desde a ultima leitura
function sincronizarResultados(PDO $db, int &$desde): void
{
    $resposta = central('results', $desde ? ['since' => $desde - 60] : []);
    foreach ($resposta['fixtures'] as $r) {
        $desde = max($desde, strtotime($r['result_updated_at']));
        if (in_array($r['status'], ['FT', 'AET', 'PEN'], true) && $r['ft'][0] !== null) {
            // apure as apostas abertas da partida $r['api_id'] com $r['ft'], $r['ht'], $r['corners']
        } elseif (in_array($r['status'], ['CANC', 'ABD', 'AWD', 'WO'], true)) {
            // devolva as apostas da partida (na multipla, a selecao vale odd 1,00)
        }
    }
    // guarde $desde (banco ou arquivo) para a proxima rodada
}

14Antes de lançar

  • O token fica só no servidor, fora do código-fonte.
  • As odds de cada partida são trocadas inteiras a cada pedido; mercado que não veio sai do site.
  • A margem é aplicada no seu lado, com arredondamento para baixo.
  • Aposta só é aceita com odd confirmada há menos de 30 minutos e antes do início da partida.
  • Resultados lidos com since e cada partida apurada uma vez só.
  • Partida cancelada devolve as apostas; dado faltando deixa a aposta aberta.
  • Horários convertidos de UTC para o fuso do seu site.
  • Um alerta no seu painel quando /status mostrar dados parados ou a central não responder.