Desenvolvedores

API da loja de vales-presente da Bidali

Uma API JSON gratuita e somente leitura para o catálogo de vales-presente deste site: países, categorias, moedas e marcas, com valores, instruções de resgate e termos. Sem cadastro e sem chave de API.

Início rápido Especificação OpenAPI

Início rápido

Suas primeiras requisições

Cada endpoint é uma requisição GET que retorna JSON. Copie um comando e execute.

Liste os países com vales-presente

curl -s https://giftcards.bidali.com/api/v1/countries

Encontre vales-presente de supermercado no Canadá

curl -s "https://giftcards.bidali.com/api/v1/countries/canada/brands?category=groceries&limit=5"

Consulte uma marca: valores, resgate e termos

curl -s https://giftcards.bidali.com/api/v1/countries/canada/brands/doordash-ca

Leia qualquer página em Markdown

curl -s -H "Accept: text/markdown" https://giftcards.bidali.com/brands/canada/doordash-ca

Referência

Endpoints

Todos os caminhos são relativos a https://giftcards.bidali.com. O documento OpenAPI descreve cada parâmetro e cada resposta.

Endpoints
Caminho	Método	O que retorna
`/api/v1`	`GET`	Describe the Catalogue API
`/api/v1/countries`	`GET`	List the countries with gift cards
`/api/v1/categories`	`GET`	List the gift card categories
`/api/v1/currencies`	`GET`	List the currencies gift cards are priced in
`/api/v1/countries/{country}/brands`	`GET`	List the brands on sale in a country
`/api/v1/countries/{country}/brands/{brand}`	`GET`	Get one brand: amounts, redemption and terms
`/api/v1/openapi.json`	`GET`	Get this OpenAPI document as JSON
`/api/v1/openapi.yaml`	`GET`	Get this OpenAPI document as YAML

Legível por máquinas

Tudo o que um agente pode ler

OpenAPI 3.1

/openapi.json e /openapi.yaml descrevem cada endpoint, parâmetro e resposta, para geradores de SDK e chamadas de ferramentas.

Páginas em Markdown

Envie Accept: text/markdown para qualquer página, ou adicione .md ao caminho (/index.md para a página inicial), para recebê-la em Markdown.

llms.txt

/llms.txt explica a loja em linguagem simples e quando usá-la.

Erros

Os erros são JSON, com o status HTTP adequado: 400 para um parâmetro ausente ou inválido, 404 para país, marca ou caminho desconhecido, 405 para qualquer método que não seja GET, e 502 ou 504 quando o serviço do catálogo falha. O campo code não muda; o campo hint diz o que fazer em seguida.

{
  "error": {
    "code": "country_not_found",
    "message": "No country matches \"atlantis\".",
    "hint": "Use a slug or an ISO 3166-1 alpha-2 code from GET /api/v1/countries.",
    "docs": "https://giftcards.bidali.com/developers#errors"
  }
}

As respostas ficam em cache por até cinco minutos. Uma página traz no máximo 100 marcas: siga pagination.next para ver o restante.

Comprar via código

Compre vales-presente com a Gift Card API da Bidali

Esta API só lê o catálogo. Para comprar vales-presente a partir do seu próprio software ou de um agente de IA, use a Gift Card API da Bidali. Ela funciona com chaves de API e está em acesso antecipado.

O acesso por MCP chegará em breve.

Ler a documentação Gift Card API Falar com vendas

Perguntas de desenvolvedores

Preciso de uma chave de API?

Não para a API do catálogo deste site: ela é pública e somente leitura. A Gift Card API da Bidali, que faz pedidos, usa chaves de API.

Posso comprar um vale-presente com esta API?

Não, ela só lê o catálogo. Envie a pessoa para a página da marca neste site (links.page em cada resposta) para comprar, ou use a Gift Card API da Bidali para comprar via código.

Existe um limite de requisições?

Não há um limite publicado. As respostas ficam em cache por alguns minutos, então busque uma lista uma vez e reutilize-a.

Existe um servidor MCP?