Para agentes de IA

Documentación para agentes: MCP y API de catálogo

Dos formas de integrar. La API REST del catálogo es pública y está activa hoy - explora marcas, productos y denominaciones sin ningún paso de acceso. El servidor MCP añade el pago: un agente crea un pedido, paga una factura Lightning desde su propia cartera y recibe un enlace de un solo uso con el código. Sin cuenta, sin tarjeta archivada, sin registro.

1 · API REST del catálogo (activa ya)

Los endpoints de navegación son públicos y están documentados con un esquema OpenAPI. Las herramientas de lectura de MCP de abajo son envoltorios finos sobre ellos, así que puedes construir directamente contra la API si prefieres HTTP plano.

Referencia: api.giftcardshop.org/v1/docs (esquema en /v1/openapi.json).

2 · Servidor MCP (acceso anticipado)

El servidor MCP y el pago autónomo con Lightning están en acceso anticipado. Las herramientas de lectura funcionan contra la API activa; create_order necesita un secreto HMAC que proporcionamos cuando te pones en contacto. La forma de integración está abajo para que puedas prepararla con antelación.

Remoto (alojado)

Apunta cualquier cliente MCP por Streamable HTTP a https://api.giftcardshop.org/mcp - sin instalar nada. Las herramientas de navegación son públicas; create_order y get_order_status necesitan un token bearer, disponible en acceso anticipado cuando te pones en contacto.

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

Envía tu token en la cabecera Authorization, como se muestra arriba. OAuth 2.1 completo - para acceso de escritura desde ChatGPT/Claude - está en la hoja de ruta.

Configuración del cliente (stdio)

El servidor habla MCP por stdio. Apunta cualquier cliente MCP (Claude Desktop y otros) a él:

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

Sin GCS_INTERNAL_SECRET las herramientas de lectura siguen funcionando y create_order informa de que no está configurado.

Entorno

Variable	Por defecto	Propósito
`GCS_API_BASE`	`https://api.giftcardshop.org`	Base de la API pública.
`GCS_INTERNAL_SECRET`	(sin definir)	Secreto HMAC de 64 hex; habilita `create_order`. Sin definir = solo lectura.

Herramientas

list_brandsreadGET /v1/brands

Lista las marcas de tarjetas de regalo del catálogo.

`country`	`string?`	código de país ISO 3166-1 alpha-2, p. ej. US
`limit`	`number?`	de 1 a 100
`offset`	`number?`	0 o más (paginación)

search_productsreadGET /v1/products

Busca o lista productos comprables.

`q`	`string?`	búsqueda de texto libre, p. ej. "amazon"
`brand`	`string?`	slug de marca
`country`	`string?`	código de país ISO 3166-1 alpha-2, p. ej. AT
`amount`	`number?`	denominación / valor nominal, p. ej. 5
`currency`	`string?`	ISO 4217, junto con amount, p. ej. EUR
`category`	`string?`	slug de categoría
`limit`	`number?`	de 1 a 100

get_productreadGET /v1/products/:id

Un producto con sus denominaciones/variantes. Aquí obtienes el variantId, el importe y la moneda que necesita create_order.

id string id del producto (obligatorio)

get_order_statusreadGET /v1/orders/:id

Estado de pago de un pedido y si el enlace de un solo uso con el código ya está disponible.

orderId string obligatorio

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

Crea un pedido y obtén una factura Lightning para pagar. Necesita el variantId, el importe y la moneda de get_product.

`productId`	`string`	obligatorio
`variantId`	`string`	un id de denominación de get_product
`amount`	`string`	valor nominal como cadena decimal, p. ej. "50"
`currency`	`string`	ISO 4217, p. ej. EUR
`idempotencyKey`	`string`	clave única (8+ caracteres) para que un reintento nunca cobre dos veces
`email`	`string?`	opcional: envía también el enlace de revelado a esta dirección

Un ? después del tipo significa que el parámetro es opcional. Las herramientas de lectura devuelven el JSON de la API tal cual.

El flujo de pedido

Encuentra un producto y lee sus variantes con get_product - anota el variantId, amount y currency.
Llama a create_order con una idempotencyKey nueva. Obtienes una factura:

{
  "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 la factura Lightning (bolt11 / invoiceUrl) desde tu propia cartera.
Consulta get_order_status hasta que indique pagado y el enlace de revelado esté disponible.
Abre el enlace de un solo uso para leer el código. Se puede ver una vez.

Pago

El agente paga una factura Lightning desde su propia cartera. Los códigos de tarjeta de regalo no admiten devolución, y por eso Lightning encaja perfecto: liquidación instantánea, sin contracargos, sin redes de tarjetas. El pago autónomo por llamada (L402) está en la hoja de ruta.

Obtener acceso

¿Quieres conectar un agente al pago? Ponte en contacto y te configuramos el servidor MCP y un secreto HMAC.

‹ Volver al resumen de agentes