Você está organizando seu sábado para o jogo do Arsenal fora de casa contra o Newcastle. Um amigo em Nova York precisa saber o horário da partida. Então, alguém no grupo pergunta qual foi o resultado do Arsenal no último jogo fora de casa. A primeira resposta está na tabela de jogos. Para a segunda, você precisa saber de quem é o gol no placar “Liverpool 0, Arsenal 1”.
Você vai criar o Matchday Notebook, um chatbot de futebol que busca os próximos três jogos da Premier League, informa os últimos cinco resultados do Arsenal no campeonato e encontra a posição do time na tabela. O exemplo está fixado em 18 de novembro de 2026. O jogo fora de casa contra o Newcastle estava marcado para sábado, 21 de novembro, às 17:30 UTC, ou 12:30 em Nova York.
A página da partida no provedor e o Agent privado concordam quanto ao horário do jogo. A conversa no Quickchat AI usou uma simulação com registros públicos datados, que você pode reproduzir abaixo.
Confira o jogo contra o Newcastle ou baixe o kit do Matchday Notebook. Descompacte o arquivo e execute python3 replay.py para ver os três jogos, cinco resultados e a linha da tabela sem precisar de uma conta. O mesmo kit inclui as configurações da Action e o Main Prompt para conectar seu próprio feed.
1. Qual clube e competição o chatbot seguirá?
Defina o clube e o campeonato primeiro. O desempenho do Arsenal no campeonato pode mudar dependendo se você conta um jogo de meio de semana na Europa. Neste caderno, Arsenal significa o time 57 e campeonato significa a Premier League 2021, também conhecida por seu código PL.
- Abra o formulário de cadastro do football-data.org. Insira seu nome e endereço de e-mail, aceite os termos e selecione Create account. Verifique sua liga na lista de cobertura. O plano gratuito inclui a Premier League, com tabela de jogos e placares com atraso.
Use um endereço de e-mail que você possa verificar. O football-data.org envia a chave da API para lá após o cadastro. O plano gratuito permite 10 requisições por minuto.
Se você já tem uma conta, faça o login com seu e-mail e token da API. Se precisar de outra cópia do token, solicite-a por e-mail usando o endereço que você cadastrou. Guarde o token para o cabeçalho protegido na Etapa 2.
Verifique seu plano em Subscription e procure sua liga em Available competitions. Este trecho mostra a UEFA Champions League (CL) e a Bundesliga (BL1).
- Para seguir outro clube, procure-o na lista de times da competição, por exemplo
GET /v4/competitions/PL/teams. Use o ID do time e o ID da competição retornados nas requisições de partida abaixo. O guia de início rápido da v4 mostra como fazer as duas buscas. - Crie um Agente Quickchat AI, nomeie-o Matchday Notebook, e mantenha-o privado enquanto você testa. Você precisa de créditos disponíveis para conversas e simulações. Abra Identity → AI Persona → Main Prompt e cole as instruções abaixo. As capturas de tela e as configurações copiáveis usam inglês.
Mantenha o mesmo clube em ambos os lugares. No produto, as instruções do Agente ficam em Identity.
Copie o Main Prompt do Matchday Notebook
You are Matchday Notebook, an Arsenal Premier League companion. Use get_club_fixtures for the schedule, get_recent_results for form and get_league_standings for the league table. For match reads, use an inclusive UTC start date and an exclusive end date. Ask for dates when the window is unclear.
List up to the requested number of TIMED or SCHEDULED fixtures in kickoff order. Give the date, time and timezone; say when the hour is unconfirmed. Flag postponed or cancelled games separately. For form, sort FINISHED matches newest first, take up to five and read full-time scores home first. Judge wins, draws and losses from Arsenal's side. For standings, find Arsenal (team 57) in the TOTAL table. Give the season, position, games played and points.
Keep answers short. Link a match to https://native-stats.org/match/ID using its returned ID, and the Premier League table to https://native-stats.org/competition/PL/. Attribute football-data.org, give the relevant date and identify any snapshot as a snapshot. Quote a retrieval time only if supplied. Keep null scores unknown. Report empty windows, missing scores and failed reads accurately. Stop after a rate limit. Do not predict scores.
2. Como obter o próximo jogo do Arsenal?
Comece com a Action que responde à pergunta do grupo sobre o horário do jogo. Uma única requisição retorna ambos os clubes, o horário agendado e o status da partida. Deixe o filtro de status aberto para que um eventual adiamento ainda possa ser exibido. Um registro TIMED tem um horário de início definido. Para SCHEDULED, informe ao leitor que o horário ainda será confirmado.
- Abra Actions & MCPs → Add Action → API Action → Create manually. Defina API Action Name como
get_club_fixturese When to run como AI decides. Em What to ask the user first, adicione as entradas de Text obrigatóriasdate_fromedate_to, ambas com No default. As descrições são “Primeira data UTC a incluir, YYYY-MM-DD” e “Primeira data UTC a excluir, YYYY-MM-DD”. - Para API Endpoint, escolha GET e insira a URL abaixo. Abra Query Params e defina
competitionscom o literal2021. AdicionedateFromedateTo. Para cada valor, use Add AI Data → Parameters para inserir a data correspondente. Deixe o Body vazio. - Cole a descrição abaixo em API Action Description e salve a Ação. Em Headers, a credencial irá em uma linha
X-Auth-Tokensomente para escrita. Configure isso antes de sua primeira solicitação. Adicione um segundo cabeçalho comum comAcceptcomo chave eapplication/jsoncomo valor. Use os mesmos dois cabeçalhos em todas as três Ações.
https://api.football-data.org/v4/teams/57/matches
Siga a rota de jogos da equipe da referência do provedor para dentro da Ação. O Arsenal está fixo na URL, a liga nos Query Params e as duas datas vêm da conversa.
Copie a descrição da Action de jogos
Use for Arsenal's upcoming Premier League fixtures in the requested date window. Sort by utcDate ascending. Show TIMED or SCHEDULED matches and flag postponements or cancellations separately. State the window if fewer fixtures are returned.
Os exemplos de requisição do provedor colocam a chave da API em X-Auth-Token. Use esse mesmo nome de cabeçalho em Headers na ação get_club_fixtures.
O formulário de login recebe seu e-mail e token da API. No Quickchat AI, apenas o token vai na linha protegida X-Auth-Token.
Insira o token de forma privada. O painel pode substituir um segredo salvo. Para que o cabeçalho seja somente de escrita, use a conexão da conta uma vez para cada Ação. Conecte sua conta usando o guia de configuração do Quickchat AI no ChatGPT ou Claude. Peça ao assistente conectado para preparar o cabeçalho com um marcador inofensivo usando a instrução abaixo. Em seguida, abra você mesmo a guia Headers da Ação, substitua o valor na mesma linha pelo seu token bruto do football-data.org e selecione Save changes. Reabra o editor e verifique se ele exibe [redacted]. Mantenha o token no painel e fora da conversa.
On Matchday Notebook, set the X-Auth-Token header of get_club_fixtures to the literal value REPLACE_IN_DASHBOARD with is_secret=true. Preserve the rest of the settings. Read the Action back and confirm that the header is secret and the value is [redacted]. Stop before testing.
Este é o cabeçalho salvo. O provedor espera o token sozinho, sem um prefixo Bearer.
Faça a primeira leitura. Em Test Response → Test the API, forneça uma data de início e o dia seguinte à última data desejada. Em seguida, habilite a Ação e peça no AI Preview os próximos três jogos do campeonato nesse período. Para uma implementação em tempo real, escolha datas futuras. O exemplo de arquivo usou 2026-11-18 e 2026-12-03, então a noite de 2 de dezembro foi incluída. Verifique a partida mais próxima abrindo o link da fonte. A referência do filtro de data v4 explica a data final exclusiva.
Na simulação, o jogo fora de casa contra o Newcastle foi em 21 de novembro, o jogo em casa contra o Manchester City em 29 de novembro e o jogo fora de casa contra o Brentford em 2 de dezembro. Terminar a requisição em 2 de dezembro teria deixado o Brentford de fora.
3. Como consultar os últimos cinco resultados do Arsenal?
O jogo mais revelador neste exemplo terminou Liverpool 0, Arsenal 1. Se o chatbot tratar o primeiro número sempre como o placar do Arsenal, ele transforma uma vitória fora de casa em uma derrota. Mantenha cada placar na ordem mandante-visitante e use o ID do time para decidir o desempenho do Arsenal.
- Crie uma segunda API Action chamada
get_recent_results. Use o mesmo endpoint GET, entradas de data, chips de data e filtro de competição. Adicione a linha de consultastatuscom o valor literalFINISHED. - Defina a descrição abaixo. Repita a configuração do cabeçalho somente para escrita para
get_recent_results, verifique a máscara e habilite a Action. - Peça os cinco jogos mais recentes do campeonato em um período especificado. Para o exemplo, use de 1º de outubro a 17 de novembro de 2026. Ordene por
utcDateantes de selecionar os cinco. Se o período retornar apenas três, mostre esses três e ofereça para procurar mais para trás.
Copiar a descrição da Ação de resultados
Use for Arsenal's recent Premier League form in the requested date window. Sort FINISHED matches newest first, then take up to five. Use both full-time goals and the home and away team IDs to judge each result from Arsenal's perspective.
Primeiro encontre o Arsenal como visitante e depois leia o gol do visitante. O zero do Liverpool significa que não sofreu gols.
Leia a sequência do mais recente para o mais antigo. O Arsenal venceu o Hull por 1 a 0, venceu o Liverpool fora de casa por 1 a 0, venceu o Everton por 2 a 0, venceu o Nottingham Forest fora de casa por 1 a 0 e venceu o Leeds por 2 a 1. Isso totaliza cinco vitórias, sete gols marcados e um sofrido. A ficha da partida contra o Liverpool é um bom teste porque o time vencedor aparece em segundo lugar.
Nos dados de teste salvos, a lista retornada começa deliberadamente com o jogo contra o Leeds e termina com o jogo contra o Hull. A ordenação pelo horário de início da partida move o Hull para o topo da resposta. Abra a resposta da Ação ao lado do chat e compare o primeiro e o último jogo em ambas as listas.
Cinco vitórias podem esconder um detalhe importante. Duas delas foram fora de casa, então o placar da vitória está à direita.
4. De onde vêm a posição no campeonato e os pontos?
Cinco vitórias mostram como foram as últimas semanas. A posição no campeonato também depende de todas as partidas anteriores e dos resultados dos outros times. Dê ao Agente uma Ação separada para a tabela de classificação.
- Nomeie-o
get_league_standings. Escolha GET, cole o endpoint abaixo e deixe as entradas, parâmetros de consulta e corpo vazios. Use AI decides, adicione a descrição abaixo e repita a configuração do cabeçalho somente para escrita para esta Ação. - Em Test Response, procure em
standingsa entrada cujotypeéTOTAL. Dentro de suatable, encontreteam.idigual a57. Habilite a Ação e pergunte “Qual a posição do Arsenal na tabela da Premier League?” - Compare
position,playedGamesepointscom a fonte para a mesma temporada e data. Em 18 de novembro, a tabela da Premier League no Native Stats mostrava 1º lugar, 10 jogos, 27 pontos. Sua tabela atual mudará à medida que outros clubes jogarem.
https://api.football-data.org/v4/competitions/PL/standings
Copiar a descrição da Ação de classificação
Use for the current Premier League table. Find team ID 57 in standings where type is TOTAL. Report season, position, playedGames and points. If the row is missing, say the position is unavailable.
Leia uma única linha em TOTAL. Os 27 pontos cobrem todas as dez partidas do campeonato no momento da captura.
5. É possível rastrear o resumo da partida até suas fontes?
Inicie uma nova conversa no AI Preview. Peça os próximos três jogos, continue com “Qual foi nosso desempenho nos últimos cinco jogos do campeonato?”, forneça o período dos resultados e, em seguida, pergunte “Em que posição isso nos deixa na tabela?” Em Inbox, abra o marcador da Ação chamada para cada resposta. A opção View logs da Ação permite comparar os parâmetros e a resposta com o que o torcedor viu. O guia para criar uma API Action mostra onde encontrar esses controles.
Para obter o resumo da rodada mostrado no início do artigo, faça a pergunta abaixo usando as datas do exemplo salvo. Para um resumo atualizado, use datas futuras para os próximos jogos e datas recentes para os resultados.
Arsenal briefing for 18 Nov 2026: next away kickoff this week (UTC), last five since 1 Oct, and table position. Three short lines.
Inspecione as datas e o ID da partida na chamada. Na simulação local, 560651 é o jogo contra o Newcastle.
Para uma verificação repetível, abra Conversations → Testing, crie um conjunto de dados e salve as três perguntas. Adicione as duas perguntas de limite mostradas abaixo. Execute o conjunto de dados após alterar a descrição de uma Ação e inspecione as chamadas junto com as respostas. Use uma resposta controlada para exercitar um status raro ou um erro. Uma pergunta hipotética sozinha testa a formulação de uma resposta.
Use as mesmas perguntas após cada edição. O resultado fora de casa detecta um erro de placar que um teste apenas com jogos em casa não pegaria.
| Caso de teste | O que o torcedor deve ouvir |
|---|---|
Uma partida é adiada e ambos os gols são null. Foi um empate? | A partida foi adiada. Não há placar registrado. |
Uma busca bem-sucedida retorna uma lista matches vazia. A temporada inteira está vazia? | Nenhuma partida foi encontrada nesse período. Informe as datas que você pesquisou. |
| O provedor retorna 401 ou 403. | A consulta falhou. Verifique o token salvo e a cobertura da competição. |
| O provedor retorna 429. | O limite de requisições por minuto foi atingido. Tente novamente mais tarde. |
Uma busca sem resultados ainda corresponde a uma requisição bem-sucedida. O assistente pode sugerir o aumento do intervalo de datas.
Para confirmar uma mudança no horário da partida, compare com as alterações na tabela de jogos publicadas pela liga. Guarde a data agendada, o fuso horário e a data da sua consulta. O feed gratuito pode ter um atraso em relação a uma mudança na transmissão, o que é importante para quem está planejando o sábado com base na resposta.
Football data provided by the Football-Data.org API. O exemplo datado usa as páginas públicas Native Stats do provedor. Consulte os planos e limites de requisição para ver a cobertura e a frequência de atualização.
Perguntas frequentes
Qual API de futebol posso usar para um chatbot de jogos?
A API v4 do football-data.org fornece tabela de jogos, resultados e classificação para as competições cobertas. Use o endpoint de partidas do time para ver a programação e o desempenho recente, e o endpoint de classificação da competição para ver a posição na tabela.
Os placares do football-data.org são ao vivo no plano gratuito?
O plano gratuito inclui placares e calendários com atraso, tabelas de classificação para as competições cobertas e 10 requisições por minuto. Inclua a fonte e a data em cada resposta e verifique seu plano se precisar de placares ao vivo.
Como mudo o Arsenal para outro time?
Encontre o ID do time e da competição do clube no football-data.org. Substitua o time 57 em ambas as Actions de partida, altere o filtro numérico da competição e a URL da classificação, depois atualize o nome do clube e o ID do time nas instruções. Teste com um jogo que você reconheça.
Como obtenho os últimos cinco jogos do ponto de vista do time?
Filtre por jogos do campeonato já finalizados em um período específico, ordene pelo horário de início do mais novo para o mais antigo e selecione até cinco. Para cada placar, verifique se seu time jogou em casa ou fora antes de registrar como vitória, empate ou derrota. Se menos de cinco jogos forem encontrados, mostre quantos foram.
O que significa um placar em branco para uma partida adiada?
Um placar em branco significa que o provedor não forneceu o total de gols para aquele time. Mantenha o status da partida visível e deixe o placar como desconhecido. Um empate sem gols precisa de uma partida finalizada com dois zeros registrados.
Como converto o horário de um jogo de futebol para o meu fuso horário?
Comece com o horário de início UTC da partida, use um fuso horário nomeado como America/New_York e mantenha a data na resposta. O horário de verão e uma mudança de dia do calendário podem afetar o horário exibido.