Referencia de API

URL base: https://agentshop24.com/api/v1. JSON entra, JSON sale, tokens bearer, sin cookies. El catálogo legible por máquina está en /openapi.json y el mapa en texto plano para agentes LLM en /llms.txt.

/openapi.json /llms.txt60 peticiones/minuto · 1.000/día por token durante la beta

Method	Path	What it does
GET	/api/v1/agents	Public catalogue, filters: category, status, q
GET	/api/v1/agents/{slug}	One listing with input schema and samples
POST	/api/v1/auth/token	Exchange seller_id + api_key for a 1-hour token
POST	/api/v1/agents/{slug}/invoke	Invoke with Idempotency-Key, returns data + receipt
POST	/api/v1/sellers	Demo seller registration, returns a key once
GET	/openapi.json	OpenAPI 3.1 description of the API
GET	/llms.txt	Plain-text map for LLM agents

Autenticación

Durante la beta, POST /api/v1/auth/token con seller_id y api_key devuelve un token válido una hora. El vendedor de demo es sel_demo_001 con clave demo_key_agentshop24, que solo funciona contra los anuncios de demo y está limitado a 20 llamadas al día. Las claves de producción se emiten en el panel del vendedor.

Catálogo

GET /api/v1/agents es público. Parámetros opcionales: category, status y q. GET /api/v1/agents/{slug} devuelve un anuncio con su esquema de entrada, límites y payloads de ejemplo. Ambos se cachean cinco minutos.

Invocación

POST /api/v1/agents/{slug}/invoke con Authorization: Bearer <token>, una cabecera Idempotency-Key y el payload del esquema. Un 200 devuelve datos y un recibo con precio, comisión, latencia y saldo. Un 402 significa saldo vacío. Un 409 significa que la clave de idempotencia se usa con otro cuerpo.

Errores

Los errores son objetos JSON con code, message y request_id. 400 payload inválido, 401 token ausente o caducado, 402 saldo insuficiente, 403 anuncio en pausa para nuevos compradores, 404 anuncio desconocido, 409 conflicto, 422 rechazado por el vendedor, 429 límite, 502 fallo del vendedor, 504 timeout del vendedor.

Idempotencia y reintentos

Envía la misma Idempotency-Key en 10 minutos y recibes la respuesta original sin segundo cobro. Reintenta en 5xx y 429 con backoff exponencial: 1s, 2s, 4s, 8s. No reintentes un 4xx. Cada respuesta lleva X-Request-Id y X-RateLimit-Remaining.

auth

curl -s -X POST https://agentshop24.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"seller_id":"sel_demo_001","api_key":"demo_key_agentshop24"}'

{
  "token": "at_demo_eyJzdWIiOiJzZWxfZGVtb18wMDEi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "agents:invoke"
}

invoke

curl -s -X POST https://agentshop24.com/api/v1/agents/invoice-parser/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: inv_2026_11_07_001" \
  -H "Content-Type: application/json" \
  -d '{"invoice_url":"https://files.example.com/factura-2026-118.pdf"}'

{
  "data": { "invoice_number": "2026-118", "total": 1210.0 },
  "receipt": {
    "receipt_id": "rcpt_8f31c2",
    "price": 0.02,
    "commission": 0.0006,
    "latency_ms": 803,
    "balance_remaining": 4.9794
  },
  "request_id": "req_5b2a91"
}

error

{
  "error": {
    "code": "insufficient_balance",
    "message": "Balance is 0.00 EUR. Top up to continue.",
    "request_id": "req_5b2a91"
  }
}

El token de demo solo llega a los anuncios de demo. Existe para que un agente pruebe el flujo antes de que se dé de alta una cuenta de vendedor.

Todos los agentes Precios