consultar_transacoes_cartoes

Query quarterly payment card transaction data from Brazil's Central Bank, including transaction volume and value statistics for analysis.

Instructions

Consulta estoque e transações de cartões de pagamento por trimestre. Retorna dados sobre quantidade e valor das transações realizadas com cartões.

Input Schema

TableJSON Schema

Name	Required	Description
`trimestre`	Yes	Ano e trimestre no formato YYYYQ (exemplo: '20234')
`top`	No	Número máximo de registros a retornar (padrão: 100)
`ordenar_por`	No	Campo para ordenação (exemplo: 'Trimestre desc')
`filtro`	No	Filtro OData para refinar a consulta

Implementation Reference

src/index.ts:325-348 (handler)

MCP tool handler for 'consultar_transacoes_cartoes'. Extracts input parameters, fetches data from BCB's 'Quantidadeetransacoesdecartoes' OData endpoint using the shared fetchBCBData helper, and returns the JSON response as text content.

case "consultar_transacoes_cartoes": {
  const { trimestre, top = 100, ordenar_por, filtro } = args as {
    trimestre: string;
    top?: number;
    ordenar_por?: string;
    filtro?: string;
  };

  const data = await fetchBCBData(`Quantidadeetransacoesdecartoes(trimestre=@trimestre)?@trimestre='${trimestre}'`, {
    formato: "json",
    top,
    orderby: ordenar_por,
    filter: filtro,
  });

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify(data, null, 2),
      },
    ],
  };
}

src/index.ts:120-145 (schema)

Input schema definition for the 'consultar_transacoes_cartoes' tool, defining parameters including the required 'trimestre' in YYYYQ format, optional top, ordenar_por, and filtro.

{
  name: "consultar_transacoes_cartoes",
  description: "Consulta estoque e transações de cartões de pagamento por trimestre. Retorna dados sobre quantidade e valor das transações realizadas com cartões.",
  inputSchema: {
    type: "object",
    properties: {
      trimestre: {
        type: "string",
        description: "Ano e trimestre no formato YYYYQ (exemplo: '20234')",
      },
      top: {
        type: "number",
        description: "Número máximo de registros a retornar (padrão: 100)",
      },
      ordenar_por: {
        type: "string",
        description: "Campo para ordenação (exemplo: 'Trimestre desc')",
      },
      filtro: {
        type: "string",
        description: "Filtro OData para refinar a consulta",
      },
    },
    required: ["trimestre"],
  },
},

src/http-server.ts:329-352 (handler)

MCP tool handler for 'consultar_transacoes_cartoes' in the HTTP/SSE server's createMCPServer function. Identical logic to index.ts handler.

case "consultar_transacoes_cartoes": {
  const { trimestre, top = 100, ordenar_por, filtro } = args as {
    trimestre: string;
    top?: number;
    ordenar_por?: string;
    filtro?: string;
  };

  const data = await fetchBCBData(`Quantidadeetransacoesdecartoes(trimestre=@trimestre)?@trimestre='${trimestre}'`, {
    formato: "json",
    top,
    orderby: ordenar_por,
    filter: filtro,
  });

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify(data, null, 2),
      },
    ],
  };
}

src/http-server.ts:110-135 (schema)

Input schema definition for the 'consultar_transacoes_cartoes' tool in http-server.ts, identical to index.ts.

{
  name: "consultar_transacoes_cartoes",
  description: "Consulta estoque e transações de cartões de pagamento por trimestre. Retorna dados sobre quantidade e valor das transações realizadas com cartões.",
  inputSchema: {
    type: "object",
    properties: {
      trimestre: {
        type: "string",
        description: "Ano e trimestre no formato YYYYQ (exemplo: '20234')",
      },
      top: {
        type: "number",
        description: "Número máximo de registros a retornar (padrão: 100)",
      },
      ordenar_por: {
        type: "string",
        description: "Campo para ordenação (exemplo: 'Trimestre desc')",
      },
      filtro: {
        type: "string",
        description: "Filtro OData para refinar a consulta",
      },
    },
    required: ["trimestre"],
  },
},

src/index.ts:37-52 (helper)

Shared helper function used by all tool handlers, including 'consultar_transacoes_cartoes', to make HTTP requests to the BCB Olinda API and handle errors.

async function fetchBCBData(endpoint: string, params: QueryParams = {}) {
  try {
    const url = buildUrl(endpoint, params);
    const response = await axios.get(url, {
      headers: {
        "Accept": "application/json"
      }
    });
    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      throw new Error(`Erro ao consultar API do BCB: ${error.message}`);
    }
    throw error;
  }
}

BCB Payment Methods MCP Server