Google Sheets com Cotações da B3: Tutorial Apps Script 2026

=BRAPI_PRICE("PETR4"; $A$1)
=BRAPI_PRICE("MXRF11"; $A$1)
=BRAPI_PRICE("IVVB11"; $A$1)

/**
 * Retorna o preço atual de um ativo via brapi.dev.
 *
 * Uso:
 * =BRAPI_PRICE("PETR4"; $A$1)
 *
 * @param {string} ticker Código do ativo, como PETR4, VALE3, MXRF11 ou IVVB11.
 * @param {string} token Token da API brapi.dev.
 * @return {number|string} Preço atual ou mensagem de erro.
 * @customfunction
 */
function BRAPI_PRICE(ticker, token) {
  if (!ticker) return "Informe um ticker";

  var apiToken = normalizeCellValue_(token);
  if (!apiToken) return "Token ausente";

  var symbol = String(ticker).trim().toUpperCase();
  var data = fetchBrapiQuote_(symbol, apiToken);
  var result = data && data.results && data.results[0];

  if (!result) return "Sem dados";

  return result.regularMarketPrice || result.lastPrice || result.close || "Preço não encontrado";
}

function fetchBrapiQuote_(symbol, token) {
  var cache = CacheService.getScriptCache();
  var cacheKey = "brapi:" + symbol;
  var cached = cache.get(cacheKey);

  if (cached) {
    return JSON.parse(cached);
  }

  var url = "https://brapi.dev/api/quote/" + encodeURIComponent(symbol);
  var response = UrlFetchApp.fetch(url, {
    muteHttpExceptions: true,
    headers: {
      Authorization: "Bearer " + token,
      "User-Agent": "GoogleSheets-brapi/1.0",
    },
  });

  var status = response.getResponseCode();
  var body = response.getContentText();

  if (status < 200 || status >= 300) {
    throw new Error("brapi HTTP " + status + ": " + body.slice(0, 160));
  }

  cache.put(cacheKey, body, 300);
  return JSON.parse(body);
}

function normalizeCellValue_(value) {
  if (value && typeof value === "object" && value.length) {
    return value[0][0];
  }

  return value ? String(value).trim() : "";
}

=BRAPI_PRICE("PETR4"; $A$1)

/**
 * Retorna um campo da resposta da brapi.dev.
 *
 * Uso:
 * =BRAPI_DATA("PETR4"; $A$1; "regularMarketChangePercent")
 *
 * @param {string} ticker Código do ativo.
 * @param {string} token Token da API.
 * @param {string} field Campo desejado.
 * @return {number|string} Valor do campo.
 * @customfunction
 */
function BRAPI_DATA(ticker, token, field) {
  if (!ticker) return "Informe um ticker";
  if (!field) return "Informe um campo";

  var apiToken = normalizeCellValue_(token);
  if (!apiToken) return "Token ausente";

  var symbol = String(ticker).trim().toUpperCase();
  var key = String(field).trim();
  var data = fetchBrapiQuote_(symbol, apiToken);
  var result = data && data.results && data.results[0];

  if (!result) return "Sem dados";

  if (result[key] === undefined || result[key] === null) {
    return "Campo não encontrado";
  }

  return result[key];
}

=BRAPI_DATA("PETR4"; $A$1; "shortName")
=BRAPI_DATA("PETR4"; $A$1; "regularMarketChangePercent")
=BRAPI_DATA("PETR4"; $A$1; "regularMarketVolume")