Para agentes de IA

Documentação para agentes: MCP e API de catálogo

Duas formas de integrar. A API REST do catálogo é pública e está ativa hoje - explora marcas, produtos e denominações sem qualquer passo de acesso. O servidor MCP acrescenta o checkout: um agente cria uma encomenda, paga uma fatura Lightning a partir da sua própria carteira e recebe um link de uso único com o código. Sem conta, sem cartão guardado, sem registo.

1 · API REST do catálogo (ativa agora)

Os endpoints de navegação são públicos e estão documentados com um esquema OpenAPI. As ferramentas de leitura de MCP abaixo são invólucros finos sobre eles, por isso podes construir diretamente contra a API se preferires HTTP simples.

Referência: api.giftcardshop.org/v1/docs (esquema em /v1/openapi.json).

2 · Servidor MCP (acesso antecipado)

O servidor MCP e o checkout autónomo com Lightning estão em acesso antecipado. As ferramentas de leitura funcionam contra a API ativa; create_order precisa de um segredo HMAC que fornecemos assim que entrares em contacto. A forma de integração está abaixo para que a possas preparar com antecedência.

Remoto (alojado)

Aponta qualquer cliente MCP por Streamable HTTP para https://api.giftcardshop.org/mcp - nada para instalar. As ferramentas de navegação são públicas; create_order e get_order_status precisam de um token bearer, disponível em acesso antecipado quando entrares em contacto.

{
  "mcpServers": {
    "giftcardshop": {
      "url": "https://api.giftcardshop.org/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Envia o teu token no cabeçalho Authorization, como mostrado acima. OAuth 2.1 completo - para acesso de escrita do ChatGPT/Claude - está no roteiro.

Configuração do cliente (stdio)

O servidor fala MCP por stdio. Aponta qualquer cliente MCP (Claude Desktop e outros) para ele:

{
  "mcpServers": {
    "giftcardshop": {
      "command": "npx",
      "args": ["-y", "@giftcardshop/mcp"],
      "env": { "GCS_INTERNAL_SECRET": "<64-hex>" }
    }
  }
}

Sem GCS_INTERNAL_SECRET as ferramentas de leitura continuam a funcionar e create_order indica que não está configurado.

Ambiente

Variável	Predefinição	Finalidade
`GCS_API_BASE`	`https://api.giftcardshop.org`	Base da API pública.
`GCS_INTERNAL_SECRET`	(não definido)	Segredo HMAC de 64 hex; ativa `create_order`. Não definido = apenas leitura.

Ferramentas

list_brandsreadGET /v1/brands

Lista as marcas de cartões-presente do catálogo.

`country`	`string?`	código de país ISO 3166-1 alpha-2, p. ex. US
`limit`	`number?`	de 1 a 100
`offset`	`number?`	0 ou mais (paginação)

search_productsreadGET /v1/products

Procura ou lista produtos compráveis.

`q`	`string?`	pesquisa de texto livre, p. ex. "amazon"
`brand`	`string?`	slug de marca
`country`	`string?`	código de país ISO 3166-1 alpha-2, p. ex. AT
`amount`	`number?`	denominação / valor nominal, p. ex. 5
`currency`	`string?`	ISO 4217, junto com amount, p. ex. EUR
`category`	`string?`	slug de categoria
`limit`	`number?`	de 1 a 100

get_productreadGET /v1/products/:id

Um produto com as suas denominações/variantes. É aqui que obténs o variantId, o montante e a moeda de que create_order precisa.

id string id do produto (obrigatório)

get_order_statusreadGET /v1/orders/:id

Estado de pagamento de uma encomenda e se o link de uso único com o código já está disponível.

orderId string obrigatório

create_orderwritePOST /internal/agent-orders (HMAC-signed)

Cria uma encomenda e obtém uma fatura Lightning para pagar. Precisa do variantId, do montante e da moeda de get_product.

`productId`	`string`	obrigatório
`variantId`	`string`	um id de denominação de get_product
`amount`	`string`	valor nominal como string decimal, p. ex. "50"
`currency`	`string`	ISO 4217, p. ex. EUR
`idempotencyKey`	`string`	chave única (8+ caracteres) para que uma nova tentativa nunca cobre duas vezes
`email`	`string?`	opcional: enviar também o link de revelação para este endereço

Um ? depois do tipo significa que o parâmetro é opcional. As ferramentas de leitura devolvem o JSON da API tal como está.

O fluxo de encomenda

Encontra um produto e lê as suas variantes com get_product - anota o variantId, amount e currency.
Chama create_order com uma idempotencyKey nova. Recebes uma fatura:

{
  "orderId": "ord_...",
  "invoiceId": "inv_...",
  "invoiceUrl": "https://btcpay.../i/inv_...",
  "bolt11": "lnbc...",        // present once the invoice is minted
  "sats": 12345,              // amount in satoshis
  "total": "52.50",
  "currency": "EUR",
  "expiresAt": "2026-01-01T00:00:00.000Z"
}

Paga a fatura Lightning (bolt11 / invoiceUrl) a partir da tua própria carteira.
Consulta get_order_status até indicar pago e o link de revelação estar disponível.
Abre o link de uso único para ler o código. Pode ser visto uma vez.

Pagamento

O agente paga uma fatura Lightning a partir da sua própria carteira. Os códigos de cartão-presente não são reembolsáveis, e é exatamente por isso que Lightning encaixa: liquidação instantânea, sem estornos, sem redes de cartões. O pagamento autónomo por chamada (L402) está no roteiro.

Obter acesso

Queres ligar um agente ao checkout? Entra em contacto e configuramos-te o servidor MCP e um segredo HMAC.

‹ Voltar à visão geral dos agentes