📖 Documentação API Dev

Autenticação

Todas as chamadas exigem sua API key no header X-API-Key (recomendado) ou query ?api_key=.

# Header (recomendado)
curl -H "X-API-Key: nc26_xxxxx" https://nacopa26.com.br/api/v1/info

# Query string
curl "https://nacopa26.com.br/api/v1/info?api_key=nc26_xxxxx"

Cota: 10.000 requests/mês por chave. Resposta 429 ao exceder.

Endpoints

Método	URL	Descrição
GET	/info	Versão, contagens, lista de endpoints
GET	/matches	Lista todos os jogos. Filtros: ?stage=Grupo+C, ?status=finished, ?team=Brasil
GET	/matches/{id}	1 jogo + contagem de palpites
GET	/teams	48 seleções
GET	/teams/{slug}	1 seleção + elenco completo
GET	/players	Lista jogadores. ?limit=100&offset=0
GET	/players/{slug}	Ficha de 1 jogador
GET	/stadiums	16 estádios
GET	/stadiums/{slug}	Ficha de 1 estádio
GET	/phases	Status das 7 fases (open/closed/done)
GET	/ranking	Top palpiteiros globais

Exemplos

PHP

$ch = curl_init('https://nacopa26.com.br/api/v1/matches?stage=Grupo+C');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-API-Key: nc26_xxxxx'],
]);
$data = json_decode(curl_exec($ch), true);
foreach ($data['data'] as $m) {
  echo "{$m['team_a']} x {$m['team_b']}: {$m['score_a']}-{$m['score_b']}\n";
}

Node.js

const r = await fetch('https://nacopa26.com.br/api/v1/teams/brasil', {
  headers: { 'X-API-Key': 'nc26_xxxxx' }
});
const { data } = await r.json();
console.log(data.name, data.coach, data.players.length, 'jogadores');

Python

import requests
r = requests.get('https://nacopa26.com.br/api/v1/ranking',
                 headers={'X-API-Key': 'nc26_xxxxx'})
for p in r.json()['data'][:10]:
    print(f"#{p['position']} {p['user']['nickname']}: {p['points']} pts")

🔔 Webhooks

Cadastre uma URL no painel e receba HTTP POST quando jogos mudarem de status.

Eventos

• match.started — quando jogo passa para "ongoing"
• match.finished — quando jogo passa para "finished" com placar

Payload

POST https://seu-app.com/webhook/nacopa26
Content-Type: application/json
X-NaCopa26-Event: match.finished
X-NaCopa26-Signature: sha256=<hmac_sha256_do_body_com_seu_secret>
User-Agent: NaCopa26-Webhook/1.0

{
  "event": "match.finished",
  "data": {
    "id": 7, "stage": "Grupo C",
    "team_a": "Brasil", "team_b": "Marrocos",
    "score_a": 2, "score_b": 1,
    "status": "finished",
    "stadium": "MetLife Stadium",
    "date": "2026-06-13T19:00:00"
  },
  "sent_at": "2026-06-13T21:08:42-03:00"
}

Validar assinatura (PHP)

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $WEBHOOK_SECRET);
$received = $_SERVER['HTTP_X_NACOPA26_SIGNATURE'] ?? '';
if (!hash_equals($expected, $received)) { http_response_code(401); exit; }
$event = json_decode($body, true);
// processa...

Webhook é desativado após 5 falhas seguidas (HTTP ≠ 2xx). Reative criando novo no painel.

Códigos de resposta

Código	Significado
200	OK
401	Key ausente / inválida / revogada
404	Recurso não encontrado
429	Cota mensal excedida
500	Erro interno (raro, fale com a gente)