Você precisa permitir que os usuários pesquisem um catálogo de cartões de comércio e gráficos de histórico de preços para um cartão graduado específico, sem construir scrapers ou manter conjuntos de dados. Ao final deste artigo, você será capaz de pesquisar um cartão de comércio esportivo e buscar seus preços em série temporal por grau usando a API de Cartões Esportivos e Cartões de Comércio no Zyla API Hub, e então conectar essas chamadas ao seu aplicativo ou a um agente de codificação de IA via MCP.
O que esta API oferece
A API de Cartões Esportivos e Cartões de Comércio fornece duas capacidades:
- Pesquisa de Cartões: pesquisa difusa de cartões de comércio por uma única string de pesquisa (por exemplo, jogador, conjunto, ano). A API retorna uma lista de cartões correspondentes com metadados e um card_id que você usará em chamadas subsequentes.
- Obter Preços de Cartões: recuperar séries temporais de preços recentes para um card_id e grau específicos (por exemplo, PSA 10) ao longo de um determinado número de dias.
Os desenvolvedores usam isso para alimentar ferramentas de inventário, calculadoras de comp, painéis de portfólio, bots de compra/venda e assistentes de listagem de mercado. Tudo é retornado como JSON, para que você possa colocá-lo diretamente em seu backend ou em um aplicativo cliente.
Você trabalhará inteiramente no Zyla API Hub, que centraliza autenticação e faturamento em mais de 10.000 APIs públicas. Uma conta, uma chave de API, assinatura + cota (não pago por chamada), e a primeira API em sua conta pode começar com um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.
Começando no Zyla API Hub
Abra a página da API, assine e pegue sua chave:
- Vá para a listagem da API de Cartões Esportivos e Cartões de Comércio e clique em Assinar ou Começar Teste Gratuito quando disponível: Começar teste de 7 dias na API de Cartões Esportivos e Cartões de Comércio.
- Copie sua chave de API do painel.
- Use Authorization: Bearer YOUR_API_KEY em cada solicitação.
Todas as solicitações vão para os URLs do hub zylalabs.com; não chame hosts de origem diretamente. Os exemplos abaixo são copiáveis e coláveis como estão (substitua YOUR_API_KEY pela sua chave).
Endpoints que você usará
1) Pesquisa de Cartões
Pesquise cartões de comércio esportivo correspondentes por uma única string de consulta difusa. Você pode combinar detalhes como jogador, ano, conjunto e variante em uma única string.
- Método: GET
- URL: https://zylalabs.com/api/2511/sports-card-and-trading-card-api/2494/card-search
- Parâmetro de consulta obrigatório:
- search (string): Texto de pesquisa livre, por exemplo, “Lebron James”.
Exemplo oficial de cURL:
curl -s -X GET "https://zylalabs.com/api/2511/sports-card-and-trading-card-api/2494/card-search?search=Lebron+James" \
-H "Authorization: Bearer YOUR_API_KEY"Exemplo oficial de resposta JSON:
[
{
"description": "LeBron James 2003 Topps Basketball",
"player": "Lebron James",
"set": "2003 Topps Basketball",
"number": "221",
"variant": "Base",
"card_id": "1588290260620x609083468203688000",
"image": "//s3.amazonaws.com/appforest_uf/f1588290324330x374737296708651100/2003-Topps-Basketball-LeBron-James-graded.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Basketball"
},
{
"description": "LeBron James 2003 Upper Deck Rookie Exclusives Basketball",
"player": "Lebron James",
"set": "2003 Upper Deck Rookie Exclusives Basketball",
"number": "1",
"variant": "Base",
"card_id": "1593982609906x272877681796710400",
"image": "//s3.amazonaws.com/appforest_uf/f1593982606419x316822824595257800/2003-Upper-Deck-Rookie-Exclusives-Lebron-James-1.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Upper Deck Rookie Exclusives Basketball"
},
{
"description": "LeBron James 2025 Topps Chrome Cactus Jack Basketball",
"player": "LeBron James",
"set": "2025 Topps Chrome Cactus Jack Basketball",
"number": "46",
"variant": "Base",
"card_id": "1782184797693x851477815192830800",
"image": "//s3.amazonaws.com/appforest_uf/f1598843985116x489100344198574160/05-Basketball.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Chrome Cactus Jack Basketball"
},
{
"description": "LeBron James 2003 Topps Chrome Basketball",
"player": "Lebron James",
"set": "2003 Topps Chrome Basketball",
"number": "111",
"variant": "Base",
"card_id": "1586412050491x786559417729941500",
"image": "//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1766768512710x492230808547762700/resize",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Chrome Basketball"
},
{
"description": "LeBron James 2024 Panini Prizm Basketball",
"player": "LeBron James",
"set": "2024 Panini Prizm Basketball",
"number": "130",
"variant": "Base",
"card_id": "1740403688997x505339465151470000",
"image": "//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1757384268822x692013733346557700/resize",…Campos que você realmente usará:
- description: Rótulo legível por humanos que você pode mostrar nos resultados da pesquisa.
- player, set, number, variant: Metadados para filtragem e exibição.
- card_id: Identificador primário; passe isso para Obter Preços de Cartões.
- image: Caminho para uma imagem que você pode renderizar (prefixe com https: se necessário em seu cliente).
- category, category_group, set_type: Útil para categorização.
2) Obter Preços de Cartões
Retorne preços recentes (série temporal) para um cartão e grau ao longo de uma janela de dias. Use o card_id da Pesquisa de Cartões.
- Método: GET
- URL: https://zylalabs.com/api/2511/sports-card-and-trading-card-api/2495/get-card-prices
- Parâmetros de consulta obrigatórios:
- card_id (string): Um identificador de cartão da Pesquisa de Cartões.
- days (string): Número de dias anteriores a incluir (por exemplo, “90”).
- grade (string): Rótulo de graduação (por exemplo, “PSA 10”).
Exemplo oficial de cURL:
Exemplo oficial de resposta JSON:
[
{
"closing_date": "2026-08-03T23:59:00.000Z",
"Grade": "PSA 10",
"card_id": "1586412050491x786559417729941500",
"price": "16150.00"
},
{
"closing_date": "2026-08-01T23:59:00.000Z",
"Grade": "PSA 10",
"card_id": "1586412050491x786559417729941500",
"price": "18250.00"
},
{
"closing_date": "2026-07-31T23:59:00.000Z",
"Grade": "PSA 10",
"card_id": "1586412050491x786559417729941500",
"price": "17900.00"
},
{
"closing_date": "2026-07-27T23:59:00.000Z",
"Grade": "PSA 10",
"card_id": "1586412050491x786559417729941500",
"price": "17303.00"
},
{
"closing_date": "2026-07-21T23:59:00.000Z",
"Grade": "PSA 10",
"card_id": "1586412050491x786559417729941500",
"price": "17373.00"
},
{
"closing_date": "2026-07-17T23:59:00.000Z",
"Grade": "PSA 10",
"card_id": "1586412050491x786559417729941500",
"price": "15337.20"
},
{
"closing_date": "2026-07-15T23:59:00.000Z",
"Grade": "PSA 10",
"card_id": "1586412050491x786559417729941500",…Campos que você realmente usará:
- closing_date: Timestamp ISO 8601 em UTC (o sufixo “Z”). Use-o como seu eixo x para gráficos.
- Grade: String de grau que ecoa sua consulta (por exemplo, “PSA 10”).
- card_id: Identifica a qual cartão a série pertence.
- price: Preço como uma string. Converta para decimal/número em sua linguagem para evitar desvios de ponto flutuante ao somar ou calcular médias.
Fluxo de trabalho de ponta a ponta
- Chame a Pesquisa de Cartões com uma única string de consulta como “Lebron James 2003 Topps Chrome 111”.
- Inspecione os resultados e escolha a linha certa por jogador, conjunto, número e variante.
- Pegue seu card_id.
- Chame Obter Preços de Cartões com esse card_id, sua janela de dias e um grau como “PSA 10”.
- Renderize um gráfico usando closing_date no eixo x e price no eixo y; ou calcule médias móveis, min/max ou volatilidade para classificação.
Exemplos para copiar e colar
cURL: Pesquisa de Cartões (oficial)
Isso está pronto para colar em um terminal. Substitua YOUR_API_KEY pela sua chave.
Python: Pesquisa de Cartões e escolha um card_id
O trecho abaixo consulta a Pesquisa de Cartões, filtra por Topps Chrome Basketball e imprime o card_id que você passará para Obter Preços de Cartões. Ele também mostra como prefixar com segurança a URL da imagem.
import os
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://zylalabs.com/api/2511/sports-card-and-trading-card-api/2494/card-search"
params = {"search": "Lebron James"}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(BASE_URL, params=params, headers=headers, timeout=30)
resp.raise_for_status()
results = resp.json()
# Escolha o cartão base 2003 Topps Chrome Basketball, se presente:
target = None
for item in results:
if item.get("set") == "2003 Topps Chrome Basketball" and item.get("variant") == "Base":
target = item
break
if not target and results:
target = results[0] # fallback: primeiro resultado
if not target:
raise SystemExit("Sem resultados da Pesquisa de Cartões")
card_id = target["card_id"]
image_url = target.get("image")
if image_url and image_url.startswith("//"):
image_url = "https:" + image_url
print("Descrição:", target.get("description"))
print("Jogador:", target.get("player"))
print("Conjunto:", target.get("set"))
print("Número:", target.get("number"))
print("Variante:", target.get("variant"))
print("card_id:", card_id)
print("URL da Imagem:", image_url)Em seguida, pegue o card_id da saída e chame o endpoint Obter Preços de Cartões (via cURL ou seu próprio código) para recuperar a série temporal para seu grau escolhido.
Notas de implementação que economizam tempo
- Autorização: Sempre envie Authorization: Bearer YOUR_API_KEY.
- Timestamps: closing_date usa UTC (sufixo Z). Converta uma vez na borda e mantenha tudo em UTC para agregações consistentes.
- Preços: price é uma string. Em código fortemente tipado, analise para Decimal/BigNumber para preservar centavos.
- Imagens: caminhos de imagem podem ser relativos ao protocolo (começar com //). Prefixe com https: em seu frontend para evitar problemas de conteúdo misto.
- Filtragem: A Pesquisa de Cartões pode retornar várias correspondências próximas. Deixe o usuário escolher por conjunto + número + variante antes de chamar Obter Preços de Cartões.
- Cache: Armazene em cache as respostas da Pesquisa de Cartões para consultas populares (por exemplo, “Lebron James”) uma vez que os metadados mudam com menos frequência do que os preços.
- Janela: days controla quão longe você busca. Mantenha alinhado com seu período de tempo de gráficos (por exemplo, 30/90/180) para evitar sobrecarga de busca.
Casos de uso práticos de esportes que você pode enviar esta semana
- Inventário de colecionador: Deixe os usuários pesquisarem um cartão, armazenem o card_id em seu banco de dados e apresentem a tendência de preço atual de 30–90 dias em sua visualização de coleção.
- Estimador de comp: Em uma página de listagem, pesquise por jogador + conjunto + número, obtenha os últimos preços de 90 dias para “PSA 10” e mostre um comp médio recente.
- Alertas de negócios: Trabalho noturno acessa Obter Preços de Cartões para card_ids em lista de observação e envia e-mails sobre quedas de preços em comparação com médias móveis de 7 dias ou 30 dias.
- Páginas de vitrine: Para jogadores de destaque, pré-busque resultados da Pesquisa de Cartões e vincule cada um a um gráfico de preços detalhado por grau.
Chamando de um agente de IA via MCP
Se você automatiza fluxos de trabalho com um cliente compatível com MCP, pode direcionar chamadas através do servidor MCP da Zyla. Configure seu cliente MCP com o endpoint MCP e sua chave de API, e então faça o agente emitir as mesmas solicitações GET HTTPS mostradas acima contra os URLs do hub Zyla. Veja a referência MCP aqui: MCP.
O fluxo é o mesmo: chame a Pesquisa de Cartões para obter card_id, depois chame Obter Preços de Cartões com card_id, dias e grau. Use os URLs e cabeçalhos exatos dos exemplos de cURL; seu cliente MCP lida com o transporte e a sessão.
Tratamento de erros e bordas
- Resultados de pesquisa vazios: Se a Pesquisa de Cartões retornar um array vazio, solicite ao usuário que amplie a consulta ou remova qualificadores de conjunto/variante da string de pesquisa.
- Múltiplos quase duplicados: Prefira correspondências exatas em conjunto e número para desambiguar variantes e reimpressões.
- Grau não encontrado: Se Obter Preços de Cartões retornar um array vazio para um grau raro, tente um grau diferente (por exemplo, “PSA 9”) ou relaxe a janela de dias.
- Throttling e cotas: O acesso é por assinatura + cota, não pago por chamada. Use cache local e debounce sua interface de usuário de autosugestão para minimizar chamadas. Para opções de acesso atuais, verifique a página da API.
Referência: endpoints e parâmetros exatos
Pesquisa de Cartões
- Método: GET
- URL: https://zylalabs.com/api/2511/sports-card-and-trading-card-api/2494/card-search
- Parâmetros obrigatórios:
- search: string (exemplo: Lebron James)
Obter Preços de Cartões
- Método: GET
- URL: https://zylalabs.com/api/2511/sports-card-and-trading-card-api/2495/get-card-prices
- Parâmetros obrigatórios:
- card_id: string (da Pesquisa de Cartões)
- days: string (exemplo: 90)
- grade: string (exemplo: PSA 10)
Lista de verificação QA antes de enviar
- UX de pesquisa: Mostre descrição, conjunto, número, variante e imagem. Deixe o usuário escolher um único cartão para reduzir incompatibilidades.
- Tipos de dados: Analise o preço como decimal, não float. Trate timestamps como UTC.
- Graus: Forneça um pequeno dropdown de graus comuns (por exemplo, “PSA 10”, “PSA 9”) para que os usuários não cometam erros de digitação em um grau e obtenham zero resultados.
- Resiliência: Lide com arrays vazios e campos inesperados sem travar seu trabalho ou interface de usuário.
- Cache: Armazene em cache os resultados da Pesquisa de Cartões por um curto TTL (por exemplo, horas), e armazene em cache séries de preços por um TTL mais curto se você atualizar gráficos com frequência.
FAQ
Como eu obtenho um card_id?
Use o endpoint de Pesquisa de Cartões com uma única string de pesquisa (por exemplo, “Lebron James 2003 Topps Chrome 111”). A resposta inclui um card_id para cada resultado. Escolha o correto (conjunto + número + variante) e passe-o para Obter Preços de Cartões.
Qual é o fuso horário de closing_date?
UTC. O sufixo “Z” indica UTC. Converta em sua interface de usuário se você quiser mostrar a hora local; mantenha armazenamento e análises em UTC para consistência.
Por que o preço é uma string?
Analisar como decimal evita problemas de precisão de ponto flutuante ao calcular médias ou somas. Converta strings para Decimal/BigNumber em sua linguagem de escolha.
Há um plano gratuito?
Não há plano gratuito. O acesso é por assinatura + cota. A primeira API em sua conta pode começar com um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.
Posso chamar esses endpoints de um IDE/agente de IA?
Sim. Configure seu cliente compatível com MCP com o servidor MCP da Zyla e sua chave de API, e então emita as mesmas solicitações GET mostradas nos exemplos de cURL. Veja a página MCP para detalhes.
Pronto para integrar isso ao seu aplicativo? Assine e obtenha sua chave na página de listagem: Começar teste de 7 dias na API de Cartões Esportivos e Cartões de Comércio. Então copie o cURL acima, troque pela sua chave, e você estará ao vivo.
Resposta oficial da API
[
{
"description": "LeBron James 2003 Topps Basketball",
"player": "Lebron James",
"set": "2003 Topps Basketball",
"number": "221",
"variant": "Base",
"card_id": "1588290260620x609083468203688000",
"image": "//s3.amazonaws.com/appforest_uf/f1588290324330x374737296708651100/2003-Topps-Basketball-LeBron-James-graded.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Basketball"
},
{
"description": "LeBron James 2003 Upper Deck Rookie Exclusives Basketball",
"player": "Lebron James",
"set": "2003 Upper Deck Rookie Exclusives Basketball",
"number": "1",
"variant": "Base",
"card_id": "1593982609906x272877681796710400",
"image": "//s3.amazonaws.com/appforest_uf/f1593982606419x316822824595257800/2003-Upper-Deck-Rookie-Exclusives-Lebron-James-1.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Upper Deck Rookie Exclusives Basketball"
},
{
"description": "LeBron James 2025 Topps Chrome Cactus Jack Basketball",
"player": "LeBron James",
"set": "2025 Topps Chrome Cactus Jack Basketball",
"number": "46",
"variant": "Base",
"card_id": "1782184797693x851477815192830800",
"image": "//s3.amazonaws.com/appforest_uf/f1598843985116x489100344198574160/05-Basketball.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Chrome Cactus Jack Basketball"
},
{
"description": "LeBron James 2003 Topps Chrome Basketball",
"player": "Lebron James",
"set": "2003 Topps Chrome Basketball",
"number": "111",
"variant": "Base",
"card_id": "1586412050491x786559417729941500",
"image": "//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1766768512710x492230808547762700/resize",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Chrome Basketball"
},
{
"description": "LeBron James 2024 Panini Prizm Basketball",
"player": "LeBron James",
"set": "2024 Panini Prizm Basketball",
"number": "130",
"variant": "Base",
"card_id": "1740403688997x505339465151470000",
"image": "//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1757384268822x692013733346557700/resize",…Resposta oficial da API
[
{
"description": "LeBron James 2003 Topps Basketball",
"player": "Lebron James",
"set": "2003 Topps Basketball",
"number": "221",
"variant": "Base",
"card_id": "1588290260620x609083468203688000",
"image": "//s3.amazonaws.com/appforest_uf/f1588290324330x374737296708651100/2003-Topps-Basketball-LeBron-James-graded.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Basketball"
},
{
"description": "LeBron James 2003 Upper Deck Rookie Exclusives Basketball",
"player": "Lebron James",
"set": "2003 Upper Deck Rookie Exclusives Basketball",
"number": "1",
"variant": "Base",
"card_id": "1593982609906x272877681796710400",
"image": "//s3.amazonaws.com/appforest_uf/f1593982606419x316822824595257800/2003-Upper-Deck-Rookie-Exclusives-Lebron-James-1.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Upper Deck Rookie Exclusives Basketball"
},
{
"description": "LeBron James 2025 Topps Chrome Cactus Jack Basketball",
"player": "LeBron James",
"set": "2025 Topps Chrome Cactus Jack Basketball",
"number": "46",
"variant": "Base",
"card_id": "1782184797693x851477815192830800",
"image": "//s3.amazonaws.com/appforest_uf/f1598843985116x489100344198574160/05-Basketball.jpg",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Chrome Cactus Jack Basketball"
},
{
"description": "LeBron James 2003 Topps Chrome Basketball",
"player": "Lebron James",
"set": "2003 Topps Chrome Basketball",
"number": "111",
"variant": "Base",
"card_id": "1586412050491x786559417729941500",
"image": "//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1766768512710x492230808547762700/resize",
"category": "Basketball",
"category_group": "Sports Cards",
"set_type": "Topps Chrome Basketball"
},
{
"description": "LeBron James 2024 Panini Prizm Basketball",
"player": "LeBron James",
"set": "2024 Panini Prizm Basketball",
"number": "130",
"variant": "Base",
"card_id": "1740403688997x505339465151470000",
"image": "//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1757384268822x692013733346557700/resize",…
