Você precisa implementar uma integração esportiva esta semana: listar os esportes suportados para um menu de filtro, pesquisar equipes/ligas pelo nome e mostrar bandeiras de países ao lado de clubes e seleções nacionais. Ao final deste artigo, você saberá como fazer isso com a SofaScore - API ao Vivo no Zyla API Hub, incluindo uma chamada curl funcional, um trecho de Python e notas para usar a mesma API a partir de um agente de IA via MCP.
O que esta API faz e quando usá-la
A SofaScore - API ao Vivo expõe endpoints para explorar metadados esportivos e pesquisar entidades no catálogo da SofaScore. Com ela, você pode:
- Buscar o catálogo de esportes disponíveis (por exemplo, Futebol, Tênis, Basquete) para alimentar filtros, fluxos de integração ou descoberta de conjuntos de dados.
- Pesquisar em todas as entidades (equipes, etc.) por uma string de consulta para resolver a entrada do usuário como “real madrid” para uma entidade canônica com IDs e caminhos de imagem.
- Recuperar uma bandeira de país como bytes de imagem bruta quando você precisa renderizar bandeiras ao lado de clubes, seleções nacionais ou perfis de jogadores.
Aplicações típicas: painéis de placar ao vivo, ferramentas de apostas e fantasia, páginas de conteúdo e pré-visualização, escritórios administrativos para etiquetar conteúdo por esporte e agentes de IA que precisam resolver nomes de entidades esportivas de forma confiável.
Começando no Zyla API Hub
Todas as chamadas passam pelo Zyla API Hub com uma chave de API e um modelo de assinatura + cota (não é pago por chamada). A primeira API inclui um teste de 7 dias ou 50 solicitações para que você possa validar rapidamente. Para começar:
- Abra a página da SofaScore - API ao Vivo e inicie o teste: Iniciar teste de 7 dias na SofaScore - API ao Vivo.
- Copie sua chave de API do painel.
- Envie solicitações para as URLs documentadas do Zyla Hub com o cabeçalho Authorization: Bearer YOUR_API_KEY.
Você pode descobrir mais de 10.000 APIs públicas e gerenciá-las a partir de uma única conta em zylalabs.com. Se você planeja adicionar mais recursos esportivos mais tarde, a chave unificada e a assinatura tornam tudo mais simples.
Endpoints disponíveis
Abaixo estão os endpoints documentados para esta API. Apenas os métodos, URLs e parâmetros listados estão disponíveis; implemente exatamente como mostrado.
1) Obter todos os esportes
- Método: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- Parâmetros: nenhum documentado
- Casos de uso: preencher dropdowns e filtros, validar slugs de esportes, pré-seed seu DB com IDs/slugs de esportes.
exemplo curl (pronto para copiar e colar):
curl -s -X GET "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports" \
-H "Authorization: Bearer YOUR_API_KEY"
Resposta JSON de exemplo oficial:
[
{
"id": 1,
"name": "Futebol",
"slug": "futebol"
},
{
"id": 5,
"name": "Tênis",
"slug": "tenis"
},
{
"id": 2,
"name": "Basquete",
"slug": "basquete"
},
{
"id": 64,
"name": "Beisebol",
"slug": "beisebol"
},
{
"id": 23,
"name": "Voleibol",
"slug": "voleibol"
},
{
"id": 63,
"name": "Futebol americano",
"slug": "futebol-americano"
},
{
"id": 6,
"name": "Handebol",
"slug": "handebol"
},
{
"id": 20,
"name": "Tênis de mesa",
"slug": "tenis-de-mesa"
},
{
"id": 4,
"name": "Hóquei no gelo",
"slug": "hoquei-no-gelo"
},
{
"id": 22,
"name": "Dardos",
"slug": "dardos"
},
{
"id": 72,
"name": "E-sports",
"slug": "esports"
},
{
"id": 11,
"name": "Motorsport",
"slug": "motorsport"
},
{
"id": 65,
"name": "Ciclismo",
"slug": "ciclismo"
},
{
"id": 62,
"name": "Críquete",
"slug": "criquete"
},
{
"id": 76,
"name": "Artes Marciais Mistas",
"slug": "mma"
},
{
"id": 12,
"name": "Rugby",
"slug": "rugby"
},
{
"id": 29,
"name": "Futsal",
"slug": "futsal"
},
{
"id": 31,
"name": "Badminton",
"slug": "badminton"
},
{
"id": 26,
"name": "Polo aquático",
"slug": "polo-aquatico"
},
{
"id": 19,
"name": "Snooker",
"slug": "snooker"
},
{
"id": 13,
"name": "Regras australianas",
"slug": "regras-australianas"
},
{
"id": 34,
"name": "Vôlei de praia",
"slug": "volei-de-praia"
},
{
"id": 109,
"name": "Minifutebol",
"slug": "minifutebol"
},
{
"id": 7,
"name": "Floorball",
"slug": "floorball"
},
{
"id": 15,
"name": "Bandy",
"slug": "bandy"
},
{
"id": 110,
"name": "Padel",
"slug": "padel"
}
]
Campos que você realmente usará:
- id: identificador numérico para o esporte. Armazene-o para consultas e junções em seu sistema.
- name: nome de exibição que você pode mostrar na interface do usuário.
- slug: identificador estável adequado para URLs e filtros (por exemplo, “futebol”, “basquete”).
2) Pesquisar todas as entidades
- Método: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- Parâmetros:
- q (string, obrigatório): consulta de pesquisa, por exemplo real madrid
- O que faz: pesquisa todas as entidades da SofaScore pela string de consulta. Útil para autocompletar, resolver a entrada do usuário para IDs canônicos ou auto-vincular conteúdo a equipes.
URL de exemplo de solicitação com parâmetros (cabeçalho de autorização necessário):
https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities?q=real+madrid
3) Obter bandeira do país
- Método: GET
- URL: https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- Parâmetros:
- country_code (string, obrigatório): um código no estilo alpha-2, por exemplo EN
- O que faz: retorna os bytes da imagem da bandeira do país. Incorpore ou persista conforme necessário para emblemas de bandeira.
URL de exemplo de solicitação com parâmetros (cabeçalho de autorização necessário):
https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag?country_code=EN
Exemplo em Python: buscar e usar o catálogo de esportes
Este trecho de Python chama Obter todos os esportes, analisa os poucos campos que você normalmente precisará e demonstra um cache simples para evitar buscar repetidamente durante o dia.
import os
import time
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
URL = "https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# Cache muito simples: atualizar a cada 6 horas
CACHE_FILE = "/tmp/sofascore_sports.json"
CACHE_TTL_SECONDS = 6 * 60 * 60
def should_refresh(path, ttl):
try:
mtime = os.path.getmtime(path)
except FileNotFoundError:
return True
return (time.time() - mtime) > ttl
def load_cached(path):
import json
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
def save_cache(path, data):
import json
with open(path, "w", encoding="utf-8") as f:
json.dump(data, f)
def get_all_sports():
if not should_refresh(CACHE_FILE, CACHE_TTL_SECONDS):
return load_cached(CACHE_FILE)
resp = requests.get(URL, headers=HEADERS, timeout=15)
resp.raise_for_status()
data = resp.json() # Esperando uma lista de {id, name, slug}
save_cache(CACHE_FILE, data)
return data
if __name__ == "__main__":
sports = get_all_sports()
# Construir uma pesquisa: slug -> id
slug_to_id = {s["slug"]: s["id"] for s in sports}
# Manter uma lista ordenada de nomes para um dropdown
sport_names = [s["name"] for s in sports]
print("Slugs de esportes -> ids:", slug_to_id)
print("Opções do dropdown:", sport_names)
Notas práticas de implementação
- Autenticação: todos os endpoints requerem o cabeçalho Authorization: Bearer YOUR_API_KEY.
- Formatos de resposta:
- Obter todos os esportes retorna itens de array JSON com id, name, slug.
- Pesquisar todas as entidades retorna JSON com metadados de entidade correspondentes à consulta. Use isso para mapear a entrada do usuário para IDs e caminhos de imagem.
- Obter bandeira do país retorna bytes de imagem. Trate o corpo como binário ao armazenar ou servir. Defina um tipo de conteúdo de imagem apropriado ao re-servir.
- Cache:
- O catálogo de esportes muda raramente. Armazene a resposta em cache (por exemplo, 6–24h) para economizar cota e reduzir o tempo de inicialização.
- Os resultados da pesquisa são impulsionados pelo usuário e variam; você pode memorizar consultas comuns como nomes de clubes.
- Bandeiras de países são estáticas; armazene uma vez, indexadas pelo código do país.
- Tratamento de erros: trate códigos de status não-2xx e timeouts. Para pesquisa, recorra a mostrar sugestões ou peça ao usuário para refinar a consulta.
- Cotas e teste: a primeira API inclui um teste de 7 dias ou 50 solicitações. Para opções de acesso atuais e preços além do teste, verifique a página da API.
Casos de uso esportivos concretos que você pode implementar esta semana
1) Fluxo de integração: escolha seu esporte
Chame Obter todos os esportes para preencher uma seleção inicial de interesse ou para definir a cobertura da sua aplicação. Persista o id e o slug do esporte para que recursos subsequentes (por exemplo, feeds, competições) possam permanecer dentro desses esportes.
2) Pesquisa e resolução de equipes
Use Pesquisar todas as entidades com q igual à entrada do usuário. Por exemplo, um usuário digita “real madrid”: chame o endpoint de pesquisa e apresente os principais resultados. Armazene o entity.id e o entity.slug retornados para roteamento ou relações de banco de dados. Use entity.imagePath se precisar de um emblema na sua interface.
3) Bandeiras de países em listas e cabeçalhos de partidas
Ao renderizar listas de equipes ou partidas internacionais, busque bandeiras de países pelo código no estilo alpha via Obter bandeira do país. Armazene os bytes da imagem (por exemplo, S3 ou seu CDN) indexados pelo código para que você não busque repetidamente o mesmo ativo.
4) Etiquetagem administrativa e gerenciamento de conteúdo
Equipes editoriais podem usar o catálogo de esportes para etiquetar artigos e vídeos por esporte. Pesquisar todas as entidades pode alimentar um autocompletar para garantir IDs de entidade consistentes em seu CMS, evitando registros duplicados de equipes.
5) Assistentes de IA que conhecem entidades esportivas
Quando um agente de IA recebe uma solicitação de usuário referenciando uma equipe, chame Pesquisar todas as entidades para resolver ambiguidades e obter IDs canônicos e caminhos de imagem antes de compor uma resposta ou buscar mais detalhes em outro lugar em sua pilha.
Detalhes do endpoint e dicas de integração
Obter todos os esportes
Como não há parâmetros de solicitação, sua integração é direta: envie um GET para a URL com o cabeçalho de autorização e analise o array JSON. Normalize os slugs para minúsculas para chaves consistentes. Se seu aplicativo suporta apenas um subconjunto de esportes, filtre o array uma vez e mantenha uma lista local.
Pesquisar todas as entidades
- O parâmetro q é obrigatório e deve ser codificado em URL. Mantenha a entrada do usuário com recortes e normalização (por exemplo, colapse espaços múltiplos).
- A resposta inclui metadados da entidade; armazene os IDs retornados para vincular as seleções do usuário com seus registros internos. Muitos sistemas criam uma tabela de mapeamento local: external_id (SofaScore) -> internal_id.
- Autocompletar: debilite as solicitações na interface do usuário para evitar sobrecarga enquanto os usuários digitam; chame apenas quando a consulta tiver comprimento ≥ 2–3.
Obter bandeira do país
- O parâmetro country_code é obrigatório. O exemplo usa EN. Valide os códigos que você planeja solicitar e trate os ausentes de forma adequada.
- Como a resposta é bytes de uma imagem, persista os bytes brutos ou converta para base64 para armazenamento onde conveniente. Ao servir para navegadores, defina um Content-Type correto (por exemplo, image/png) com base no formato da imagem que você detectar.
- Para desempenho, armazene bandeiras em seus ativos estáticos ou em um CDN após a primeira busca para manter a latência da interface do usuário baixa.
Chame a API a partir de agentes de IA via MCP
Se você usar clientes compatíveis com MCP (Claude Code, Cursor, Windsurf, etc.), pode direcionar chamadas através do endpoint MCP e sua chave de API Zyla. Aponte sua ferramenta para MCP com apikey=YOUR_API_KEY. Seu agente pode então invocar os mesmos URLs documentados do Hub para a SofaScore - API ao Vivo. Isso é útil para assistentes que precisam:
- Listar esportes e propor etapas de configuração a um desenvolvedor.
- Resolver nomes de entidades (via pesquisa) durante uma sessão de chat.
- Buscar bandeiras para incorporar no código de UI gerado ou na documentação.
Mantenha o mesmo cabeçalho de Autorização nas chamadas HTTP da sua ferramenta. Registre chamadas e respostas durante o desenvolvimento para que você possa ajustar a lógica do prompt ou o comportamento de fallback quando as pesquisas forem ambíguas.
Checklist de segurança, implantação e testes
- Variáveis de ambiente: armazene YOUR_API_KEY em seu gerenciador de segredos ou variáveis de CI/CD.
- Timeouts e tentativas: use timeouts conservadores (10–15s) e considere uma única tentativa para GETs idempotentes.
- Validação de entrada: sanitize q para pesquisa e valide country_code antes de chamar.
- Monitoramento: registre códigos de status e latências; alerta sobre taxas elevadas de 4xx/5xx.
- Estratégia de cache:
- Catálogo de esportes: atualize diariamente ou na implantação.
- Pesquisa: memorize consultas comuns ou armazene por sessão para reduzir a rotatividade.
- Bandeiras: armazenamento em cache/CDN persistente; invalide raramente.
Referência rápida
- Obter todos os esportes:
- GET https://zylalabs.com/api/12787/sofascore-live-api/25080/get-all-sports
- Cabeçalhos: Authorization: Bearer YOUR_API_KEY
- Parâmetros: nenhum
- Pesquisar todas as entidades:
- GET https://zylalabs.com/api/12787/sofascore-live-api/25082/search-all-entities
- Cabeçalhos: Authorization: Bearer YOUR_API_KEY
- Parâmetros: q (string, obrigatório), por exemplo, real madrid
- Obter bandeira do país:
- GET https://zylalabs.com/api/12787/sofascore-live-api/31197/get-country-flag
- Cabeçalhos: Authorization: Bearer YOUR_API_KEY
- Parâmetros: country_code (string, obrigatório), por exemplo, EN
FAQ
Como faço para autenticar solicitações?
Envie o cabeçalho Authorization: Bearer YOUR_API_KEY com cada solicitação para as URLs do Zyla Hub.
O que “Obter bandeira do país” retorna?
O corpo da resposta são os bytes da imagem da bandeira. Trate como dados binários. Se você proxy ou armazena, defina um tipo de conteúdo de imagem apropriado ao servir para clientes.
Posso armazenar em cache a lista de esportes?
Sim. A lista não muda com frequência. Armazene em cache em seu aplicativo (por exemplo, diariamente) para acelerar a inicialização e economizar cota.
Que consulta devo passar para Pesquisar todas as entidades?
Passe a string de pesquisa do usuário pelo parâmetro q (codificado em URL), por exemplo q=real+madrid. Use os IDs e slugs de entidade retornados para referências estáveis em seu sistema.
Há um plano gratuito?
A primeira API inclui um teste de 7 dias ou 50 solicitações para que você possa avaliar rapidamente. Para opções de acesso atuais e preços após o teste, verifique a página da API.
Implemente
Agora você tem os endpoints e o código que precisa para alimentar filtros esportivos, pesquisa de entidades e bandeiras de países. Crie sua conta e inicie o teste de 7 dias diretamente na listagem: Iniciar teste de 7 dias na SofaScore - API ao Vivo. Você pode gerenciar tudo em um só lugar em zylalabs.com e chamar os mesmos endpoints a partir de suas ferramentas de IA via MCP.