Referencia API

v1.4.0 — El Motor de Recibos para Creadores

TL;DR - RESUMEN PARA AGENTES DE IA

StatsReceipt API permite generar recibos estéticos de RRSS y MRR SaaS mediante REST o el protocolo MCP. Endpoint principal: `/receipt/create-from-agent`. Parámetros clave: `apiKey` (stats-mcp-v1), `identifier`, `type` (social/mrr), `username` y métricas. Soporta layouts `compact`, `standard`, `deep-dive` y `canvas`. Límite gratuito: 3 recibos/día.

Genera recibos compartibles y súper estéticos de RRSS y MRR (SaaS) desde tus agentes de IA (o en tu propia web). Esta API te permite integrar el "Motor" de StatsReceipt en cualquier workflow externo.

Autenticación

Toda petición HTTP debe incluir una API Key. Puedes pasarla en el JSON body (`apiKey`) o como cabecera HTTP (`X-Agent-Key`).

Base URLhttps://statsreceipt.com/api

Sample Keystats-mcp-v1

Invocación para Agentes (Protocolo MCP)

Si eres un Agente de Inteligencia Artificial (ej. en Claude Desktop o Cursor) conectado a través del protocolo MCP (Stdio o SSE), debes usar la llamada JSON-RPC `tools/call`. No uses HTTP clásico a no ser que estés montando una web.

El servidor MCP se encargará internamente de las validaciones de API key. La respuesta al agente contendrá una `url` pública. **Esa es la URL que debes proporcionarle al usuario** para que pueda ver y compartir la imagen real de sus métricas y diagnóstico.

Ejemplo de Payload JSON-RPC (MCP)

{
  "jsonrpc": "2.0",
  "id": "agent-req-001",
  "method": "tools/call",
  "params": {
    "name": "generate_creator_receipt",
    "arguments": {
      "username": "StatsAura",
      "platform": "tiktok",
      "followers": 125000,
      "theme": "aura",
      "layout": "compact"
    }
  }
}

Endpoints Principales

POST/receipt/create-from-agent

Name: generate_creator_receipt

Crea una entrada verificada y devuelve una URL única de visualización.

Request Body (JSON)

Campo	Tipo	Req	Descripción
apiKey	string	YES	Shared secret API key
identifier	string	YES	Unique ID (e.g. email or hash)
type	string	YES	Enforce `social` for this endpoint
username	string	YES	Display name (e.g. @FranDev)
theme	string	OPT	e.g. `aura`, `zima`, `midnight`
layout	string	OPT	e.g. `compact`, `deep-dive`...
platform	string	YES	`x`, `tiktok`, `instagram`, `linkedin`
followers	number	YES	Total follow count
views	number	OPT	Impressions/Views total
posts	number	OPT	Total content count
reposts	number	OPT	Shares total
replies	number	OPT	Comments total
growth	number	OPT	Growth in last 30d (%)

Ejemplo de Invocación REST (JS / cURL)

fetch("https://statsreceipt.com/api/receipt/create-from-agent", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: "stats-mcp-v1",
    identifier: "user_identifier_123",
    type: "social",
    username: "StatsAura",
    platform: "tiktok",
    followers: 125000,
    theme: "zima",
    layout: "deep-dive"
  })
})
.then(res => res.json())
.then(data => console.log("Your URL:", data.url));

Ejemplo de Respuesta HTTP (Webhooks/Apps)

{
  "success": true,
  "id": "abc123xyz",
  "url": "https://statsreceipt.com/r/abc123xyz",
  "rank": "TOP 5% 🚀",
  "diagnosis": "Viral Machine"
}

POST/receipt/create-from-agent

MCP Tool: generate_verified_mrr_receipt

Genera el recibo fiscal visual de ingresos MRR para startups SaaS. Ideal para reportes Build in Public y VC Updates.

Payload Parameters

Field	Tipo	Req	Descripción
apiKey	string	Yes*	Only if using HTTP API directly (Not via MCP).
identifier	string	Yes*	Alphanumeric unique user session ID. Only if using HTTP API directly.
type	string	Yes	MUST BE `mrr` exactly.
brandName	string	Yes	TrustMRR Slug (e.g. `stripe`)
theme	string	No	e.g. `aura`, `gold`
layout	string	No	e.g. `deep-dive`, `canvas`

Ejemplo de Invocación REST (JS / cURL)

fetch("https://statsreceipt.com/api/receipt/create-from-agent", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: "stats-mcp-v1",
    identifier: "user_identifier_123",
    type: "mrr",
    brandName: "Acme Inc",
    mrr: 15400,
    growth: 12.5,
    theme: "gold",
    layout: "canvas"
  })
})
.then(res => res.json())
.then(data => console.log("Your URI:", data.url));

Límites de Uso y Errores

Cada "identifier" tiene un límite de 3 recibos gratuitos cada 24 horas.

401: Invalid API Key
429: Daily limit exhausted
500: Database / Connection error