Documentación para developers

Desde tu panel de developer ves todas tus apps, y para cada instalación un resumen de entregas (webhooks enviados, si fallaron o no) — pero nunca el contenido de negocio del comercio (no ves sus ventas ni sus clientes reales, solo que "la entrega #123 a la instalación #45 falló con HTTP 500").

{
  "key": "acme.puntos",
  "name": "Acme Puntos",
  "description": "Programa de puntos por compra",
  "category": "Crecimiento",
  "version": "1.0.0",
  "author": { "name": "Acme SRL", "url": "https://acme.dev" },
  "roles": ["owner", "admin"],
  "scopes": ["orders:read", "customers:read"],
  "events": ["order.paid"],
  "extensions": {
    "admin": ["dashboard.card"],
    "dna": [{ "key": "puntos-widget", "name": "Widget de puntos" }],
    "automationActions": [{ "key": "sumar_puntos", "name": "Sumar puntos" }]
  },
  "endpoints": {
    "baseUrl": "https://acme.dev",
    "webhookPath": "/webhook"
  }
}

Hoy los scopes de *:read son los que habilitan cada recurso de la Public API (ver más abajo). Los de *:write quedan declarados para uso futuro — pedilos solo si tu app realmente los necesita, ya que el comercio los ve todos en la pantalla de consentimiento antes de instalarte.

Recursos disponibles (todos de solo lectura, paginados con page/perPage):

curl "https://api.stockcito.com/api/public/v1/products?page=1&perPage=20" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Stockcito-Version: 2026-09"

# {"data":[...], "total":123, "page":1, "perPage":20}

Si declarás dashboard.card en extensions.admin, Stockcito le hace un GET firmado a {baseUrl}/stockcito-ui/dashboard-card y renderiza lo que respondas como una tarjeta más en el Dashboard del comercio. Nunca mandás HTML: mandás un árbol de nodos declarativos, con enums cerrados, para que nunca puedas inyectar nada fuera de lo previsto.

// Tu servidor responde esto a GET /stockcito-ui/dashboard-card
{
  "type": "card",
  "title": "Puntos acumulados",
  "children": [
    { "type": "text", "value": "1.240 puntos activos", "weight": "bold" },
    { "type": "badge", "label": "+80 esta semana", "tone": "success" },
    { "type": "link", "label": "Ver detalle", "href": "https://acme.dev/panel" }
  ]
}

Nodos disponibles: text, badge, link, stack (agrupa en fila o columna) y card (anida los anteriores). Máximo 20 hijos por nivel y 20KB de respuesta — si tu servidor está caído, tarda demasiado, o responde algo inválido, Stockcito simplemente no muestra la tarjeta, nunca rompe el Dashboard del comercio.

Cada request firmado incluye X-Stockcito-Timestamp y X-Stockcito-Signature: sha256=..., calculada como HMAC-SHA256(tu_clave_de_firma, timestamp + "." + path). Verificala del lado del servidor y rechazá cualquier timestamp con más de 5 minutos de diferencia, para evitar ataques de repetición.

Verificar la firma en Node/Express:

const crypto = require("crypto")

const SIGNING_KEY = process.env.STOCKCITO_SIGNING_KEY // te lo dio Stockcito al instalarte
const TOLERANCE_SECONDS = 300

app.get("/stockcito-ui/dashboard-card", (req, res) => {
  const timestamp = req.header("X-Stockcito-Timestamp")
  const signatureHeader = req.header("X-Stockcito-Signature") || ""
  const path = req.path // "/stockcito-ui/dashboard-card"

  const now = Math.floor(Date.now() / 1000)
  if (!timestamp || Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) {
    return res.status(401).send("Timestamp inválido o vencido")
  }

  const expected = crypto
    .createHmac("sha256", SIGNING_KEY)
    .update(`${timestamp}.${path}`)
    .digest("hex")

  // timingSafeEqual evita que un atacante deduzca la firma midiendo cuánto
  // tarda la comparación carácter por carácter.
  const received = signatureHeader.replace("sha256=", "")
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))

  if (!valid) return res.status(401).send("Firma inválida")

  res.json({
    type: "card",
    title: "Puntos acumulados",
    children: [{ type: "text", value: "1.240 puntos activos", weight: "bold" }],
  })
})

Cada módulo que declarás en extensions.dna aparece como una opción para que el comercio lo agregue a su tienda desde el Studio (Diseño del inicio). Stockcito te pide el contenido en GET {baseUrl}/stockcito-ui/dna/{key} — mismo esquema de nodos y misma firma que dashboard.card — y lo cachea 60 segundos por comercio, porque acá el que ve el contenido es cualquier visitante anónimo de la tienda, no solo el dueño logueado.

Cada acción en extensions.automationActions queda disponible para que el comercio arme una regla tipo "cuando pase X, hacé Y". Cuando se dispara, Stockcito te manda un POST firmado a {baseUrl}/stockcito-actions/{actionKey} con el payload del evento en el body.

POST /stockcito-actions/sumar_puntos
Content-Type: application/json
X-Stockcito-Timestamp: 1735689600
X-Stockcito-Signature: sha256=<hmac del body con tu clave>

{ "orderId": 4821, "total": 15400, "customerId": 92 }

Verificá la firma igual que en las extensiones de UI, pero acá el HMAC se calcula sobre timestamp + "." + body (el JSON completo, no un path). Respondé HTTP 2xx si todo salió bien. Si tu respuesta es un error, importa la diferencia: un HTTP 4xx/5xx transitorio (tu servidor caído un momento) hace que Stockcito reintente con backoff; un 2xx que vos mismo interpretás como "falla definitiva" de tu lado no debería devolverse como error HTTP, porque Stockcito no tiene forma de distinguir eso de un problema de red.

Servidor mínimo completo (Node, sin frameworks) — recibe la acción, verifica la firma sobre el body, y responde:

const http = require("http")
const crypto = require("crypto")

const SIGNING_KEY = process.env.STOCKCITO_SIGNING_KEY

http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/stockcito-actions/sumar_puntos") {
    res.writeHead(404).end()
    return
  }

  let body = ""
  req.on("data", (chunk) => { body += chunk })
  req.on("end", () => {
    const timestamp = req.headers["x-stockcito-timestamp"]
    const received = (req.headers["x-stockcito-signature"] || "").replace("sha256=", "")

    const expected = crypto
      .createHmac("sha256", SIGNING_KEY)
      .update(`${timestamp}.${body}`)
      .digest("hex")

    if (received.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
      res.writeHead(401).end("Firma inválida")
      return
    }

    const { orderId, total, customerId } = JSON.parse(body)
    // ... tu lógica: sumar puntos, crear el envío, lo que sea ...
    console.log(`Pedido ${orderId} de ${customerId} por $${total}`)

    res.writeHead(200, { "Content-Type": "application/json" })
    res.end(JSON.stringify({ ok: true }))
  })
}).listen(3000)

Para cobrar, conectás tu propia cuenta de Mercado Pago desde /developers (el mismo flujo de OAuth que usa un comercio para cobrar en su tienda, aplicado a vos como developer). Cuando alguien compra tu app, se le cobra con tu token de Mercado Pago — Stockcito se queda con un porcentaje como comisión de plataforma — y tu app queda desactivada hasta que el webhook de pago confirma que se acreditó.

Hay un SDK inicial en TypeScript (packages/sdk-ts) que tipa los recursos de la Public API. Todavía no está publicado en ningún registro público (npm) — por ahora, la forma soportada de integrarte es HTTP + JSON directo, documentado más arriba, que funciona igual desde cualquier lenguaje.