Developer documentation

Your developer dashboard lists all your apps and delivery summaries for each installation (webhooks sent and whether they failed). It never shows the retailer's business data: you will only see that delivery #123 to installation #45 failed with HTTP 500, not their actual sales or customers.

{
  "key": "acme.puntos",
  "name": "Acme Loyalty",
  "description": "Purchase rewards program",
  "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": "loyalty-widget", "name": "Loyalty widget" }],
    "automationActions": [{ "key": "add_points", "name": "Add points" }]
  },
  "endpoints": {
    "baseUrl": "https://acme.dev",
    "webhookPath": "/webhook"
  }
}

Currently, *:read scopes grant access to each Public API resource listed below. *:write scopes are reserved for future use. Request only the permissions your app needs, since retailers see each one on the consent screen before installation.

Available resources (all read-only and paginated with page/perPage):

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

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

When you declare dashboard.card under extensions.admin, Stockcito sends a signed GET request to {baseUrl}/stockcito-ui/dashboard-card and renders your response as a card in the retailer's Dashboard. You never send HTML. Instead, send a declarative node tree with a closed set of values, so nothing outside the supported interface can be injected.

// Your server responds to GET /stockcito-ui/dashboard-card
{
  "type": "card",
  "title": "Points balance",
  "children": [
    { "type": "text", "value": "1,240 active points", "weight": "bold" },
    { "type": "badge", "label": "+80 this week", "tone": "success" },
    { "type": "link", "label": "View details", "href": "https://acme.dev/panel" }
  ]
}

Available nodes: text, badge, link, stack (groups children in a row or column) and card (nests the others). Each level is limited to 20 children and responses to 20 KB. If your server is down, too slow or returns invalid data, Stockcito hides the card without breaking the retailer's Dashboard.

Each signed request includes X-Stockcito-Timestamp and X-Stockcito-Signature: sha256=..., calculated from the signing key, timestamp, a period, then the path. Verify it on your server and reject timestamps more than five minutes away to prevent replay attacks.

Verify the signature in Node/Express:

const crypto = require("crypto")

const SIGNING_KEY = process.env.STOCKCITO_SIGNING_KEY // issued by Stockcito at installation
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("Invalid or expired timestamp")
  }

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

  // timingSafeEqual prevents timing attacks.
  
  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("Invalid signature")

  res.json({
    type: "card",
    title: "Points balance",
    children: [{ type: "text", value: "1,240 active points", weight: "bold" }],
  })
})

Declare each module with a stable key and display name in extensions.dna. In Studio → Home design, the retailer can choose which module to add. Stockcito requests its content from {baseUrl}/stockcito-ui/dna/{key} using the same signed UI protocol, validates it against the supported node schema, and caches successful content for 60 seconds per retailer. Public visitors see the rendered module; your app never receives direct access to the store or its database.

GET https://acme.dev/stockcito-ui/dna/reviews-widget · X-Stockcito-Timestamp · X-Stockcito-Signature

Each action in extensions.automationActions becomes available when the retailer builds a rule such as “when X happens, do Y.” When triggered, Stockcito sends a signed POST to {baseUrl}/stockcito-actions/{actionKey}, with the event payload in the body.

POST /stockcito-actions/add_points
Content-Type: application/json
X-Stockcito-Timestamp: 1735689600
X-Stockcito-Signature: sha256=<HMAC of the body with your key>

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

Verify the signature as you do for UI extensions, but here the HMAC covers the timestamp, a period, then the body (the complete JSON, not a path). Return HTTP 2xx on success. A transient HTTP 4xx/5xx (for example, a temporary outage) triggers retries with backoff. Do not return 2xx for a permanent failure you have identified: Stockcito would treat it as successfully processed.

Complete minimal server (Node, no framework): receives the action, verifies the body signature and responds:

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/add_points") {
    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("Invalid signature")
      return
    }

    const { orderId, total, customerId } = JSON.parse(body)
    // Add points, create a shipment, or run your business logic here.
    console.log(`Order ${orderId} for ${customerId}: $${total}`)

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

To charge for your app, connect your own Mercado Pago account from /developers (the same OAuth flow retailers use for store payments, for you as a developer). Purchases are charged to your Mercado Pago token; Stockcito keeps a platform fee, and the app stays inactive until the payment webhook confirms the funds were credited.

An initial TypeScript SDK (packages/sdk-ts) provides types for Public API resources. It is not published to a public registry such as npm yet. For now, the supported integration is direct HTTP + JSON, documented above and available from any language.