---
name: comprar-con-fintoc
description: Busca productos en comercios conectados a Fintoc y cómpralos para tu dueño con un link de pago. Solo HTTP, sin MCP y sin registrarte.
---

# Comprar con Fintoc por HTTP

Con esta guía puedes buscar productos de un comercio (por ejemplo PepeStore) y comprarlos para tu dueño.
Son llamadas HTTP con JSON. **No necesitas registrarte, ni credenciales, ni MCP:** creas un link de pago, se
paga una vez en el checkout de Fintoc (lo pagas tú o tu dueño) y el comercio prepara el pedido.

Base: `https://fintoc-agentic-mcp.onrender.com`

## 1. Busca productos

```bash
curl -s 'https://fintoc-agentic-mcp.onrender.com/catalog/search?q=coca%20zero'
```

Cada producto en `data` trae `id`, `merchant`, `name`, `price` y `currency` (en pesos chilenos, sin
decimales), `available` y `purchasable`. Compra solo productos con `purchasable: true`.

Muchos productos también traen `attributes` con datos verificados (por ejemplo, azúcares por 100 ml),
cada uno con su fuente (`source_url`) y la frase exacta que lo dice (`quote`).

Para filtrar por un dato, primero mira qué datos tiene la categoría y después filtra **dentro de esa
categoría**:

```bash
curl -s https://fintoc-agentic-mcp.onrender.com/catalog/categories
curl -s 'https://fintoc-agentic-mcp.onrender.com/catalog/search?category=bebidas_isotonicas_y_energeticas&filters=%7B%22azucares_totales_g_100%22%3A%7B%22lte%22%3A1%7D%7D&missing=include'
```

`filters` es JSON (`{"azucares_totales_g_100": {"lte": 1}}`) y necesita `category`. Con
`missing=include`, los productos que no tienen el dato vienen aparte, en `unknown`. **"Sin dato" no es
"no cumple":** dile a tu dueño que no lo sabemos, no que el producto no lo cumple.

Si quieres, envía `X-Agent-Name: <tu nombre>` para que sepamos qué agente busca. Guardamos el texto de
las búsquedas y los filtros por 90 días para saber qué buscan los agentes y ayudar al comercio a
completar su catálogo. Busca productos, no escribas datos personales de tu dueño en `q`.

## 2. Crea el checkout

```bash
curl -s -X POST https://fintoc-agentic-mcp.onrender.com/checkout \
  -H 'Content-Type: application/json' \
  -d '{"merchant": "pepestore", "product_id": "prod_69", "quantity": 2, "customer_email": "dueno@ejemplo.cl"}'
```

- `merchant` es el campo `merchant` del producto en la búsqueda.
- Para varios productos: `{"merchant": "pepestore", "items": [{"product_id": "prod_69", "quantity": 2}, {"product_id": "prod_18"}]}`.
- `customer_email` es opcional: ahí llega el comprobante del pago.

Respuesta (`201`):

```json
{
  "object": "checkout",
  "id": 42,
  "token": "plink_…",
  "status": "pending",
  "payment_url": "https://fintoc-agentic-mcp.onrender.com/pay/plink_…",
  "amount": 1800,
  "currency": "CLP",
  "expires_at": "…",
  "status_url": "https://fintoc-agentic-mcp.onrender.com/checkout/plink_…",
  "next_step": "Paga en payment_url si tu dueño te dio un medio de pago para comprar; si no, pásale payment_url…"
}
```

`payment_url` es el checkout de Fintoc, con el monto y el comercio. Se paga con tarjeta o banco:

- Si tu dueño te dio un medio de pago para comprar (por ejemplo, una tarjeta), puedes pagar ahí tú.
- Si no, pásale `payment_url` tal cual y paga él.

El precio y el stock los fija el comercio, así que `amount` puede no ser la suma de los precios que viste.

## 3. Consulta el estado

```bash
curl -s 'https://fintoc-agentic-mcp.onrender.com/checkout/plink_…'
```

Usa `status_url` tal cual: el token `plink_…` es la llave de tu checkout, guárdalo.

| `status` | Qué significa | Qué hacer |
|---|---|---|
| `pending` | Todavía no se paga | Espera y vuelve a consultar (cada 10 a 30 segundos está bien) |
| `paid` | Pagó; el comercio está confirmando | Vuelve a consultar en unos segundos |
| `fulfilled` | Listo | Dale a tu dueño el `confirmation_code`, que es su código de retiro |
| `expired` | Venció sin pago (por defecto, a las 24 horas) | Crea otro checkout si todavía quiere comprar |
| `failed` | No se pudo completar | Lee `error`; si corresponde, crea otro checkout |

Cada respuesta trae `next_step` con lo que corresponde hacer.

## Cómo hablarle a tu dueño

- "Te paso un link para pagar" (o "Listo, lo pagué") y "Listo, tu código de retiro es PEPE-1234".
- No le hables de tokens, checkouts, ids ni estados internos.
- Si un dato del producto no está verificado, díselo así: "no tengo ese dato confirmado".

## Errores

Los errores vienen como `application/problem+json`, con `code`, `detail` y `fix`. El `fix` dice qué
hacer.

| `code` | HTTP | Qué hacer |
|---|---|---|
| `merchant_required` | 422 | Envía `merchant` (el campo `merchant` del producto en la búsqueda) |
| `invalid_items` | 422 | Cada producto necesita `product_id` y `quantity` entre 1 y 99 |
| `category_required` | 422 | Los `filters` necesitan `category` |
| `merchant_not_found` | 404 | Usa el `merchant` de los resultados de búsqueda |
| `merchant_not_purchasable` | 409 | Ese comercio todavía no vende a agentes; compra solo productos con `purchasable: true` |
| `registration_required` | 401 | Ese comercio solo vende a agentes registrados; pídele a tu dueño la credencial |
| `unauthorized` | 401 | Enviaste una credencial que no sirve: quita el header `Authorization` |
| `rate_limited` | 429 | Espera un rato antes de reintentar |
| `merchant_error` | 502 | Revisa el `product_id`; si persiste, intenta más tarde |
| `merchant_timeout` | 504 | Reintenta en unos segundos |
| `checkout_not_found` | 404 | Usa el `status_url` que devolvió `POST /checkout` |

Si repites un `POST /checkout`, se crea otro link. No se cobra nada hasta que alguien paga, pero paga o pasa
solo uno.

## Opcional: registrarte

No hace falta para comprar con link de pago. Sirve si tu dueño quiere que su historial de compras quede a
nombre de tu agente, o para comprar con una tarjeta que tu dueño conecta una vez a Fintoc, sin pasar por
el checkout en cada compra (eso va por MCP y lo autoriza él):

```bash
curl -s -X POST https://fintoc-agentic-mcp.onrender.com/agents/register \
  -H 'Content-Type: application/json' \
  -d '{"name": "mi-agente", "merchant": "pepestore"}'
```

La respuesta trae `agent_secret` (se muestra una sola vez). Úsalo como `Authorization: Bearer <agent_secret>`
en las mismas llamadas de arriba.