agentleFS
gavasquesgavasques/titanos-agent-skills/skills/bling-erp/SKILL.md

bling-erp

Skill0 starsChanged 3 months agoMITView on GitHub

Bling ERP v3 via Titanos MCP para Claude, Codex e outros agentes. Use quando precisar conectar, consultar ou operar Bling API v3 com multi-contas, OAuth, billing por chamada, quotas, rate limits (3 req/s, 120k/dia), idempotência e webhooks.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use esta skill quando o usuário / Use this skill when the user:

    line 11
  2. Very specific:

    Use esta skill quando o usuário pedir para acessar Bling ERP pelo Titanos MCP.

    line 16
  3. Very specific:

    Use somente tool catalogada.

    line 66

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Bling ERP — MCP Titanos

Quando usar / When to Use This Skill

Use esta skill quando o usuário / Use this skill when the user:

  • Pede para conectar, consultar ou operar Bling ERP pelo Titanos
  • Precisa da API Bling v3 (OAuth, quotas, webhooks, rate limits)
  • Menciona Bling via MCP (não tokens OAuth no .env local)

Use esta skill quando o usuário pedir para acessar Bling ERP pelo Titanos MCP. O Titanos é o broker: o agente usa TITANOS_API_KEY; tokens OAuth do Bling ficam criptografados no Titanos, nunca no .env local.

Comece sempre

  1. Rode whoami e confirme plano, organização e scopes.
  2. Rode get_server_guide({ "topic": "full" }) se as tools Bling não aparecerem.
  3. Rode get_bling_guide quando disponível.
  4. Rode list_bling_connections e escolha uma connection_id ativa.
  5. Se faltar tool ou scope, pare e explique: integração Bling ainda não publicada, key sem scope, ou conta Bling não conectada.

Setup do usuário

O usuário conecta a conta no painel Titanos, não no cliente MCP:

  1. Criar aplicativo público na Central de Extensões Bling (categoria "Soluções em IA").
  2. Configurar redirect URI do Titanos exatamente como https://titanos.com.br/BlingCallback.
  3. Autorizar OAuth no Titanos (/conta/integracoes?tab=bling).
  4. Criar API Key MCP com scopes Bling (preset bling-erp ou leitura).
  5. Configurar Claude/Codex com @titanos/mcp-agents@1 e TITANOS_API_KEY.

OAuth Bling: authorization code expira em 1 minuto (exchange imediato no callback). Access token expira em 6 horas; refresh token em 30 dias. Se a conexão estiver expirada, peça reautorização no Titanos.

Scopes (v1)

ScopeQuando precisa
bling:connections:readListar conexões e dados da empresa
bling:catalog:readConsultar produtos, categorias, grupos, canais e depósitos
bling:stock:readConsultar saldos de estoque
bling:orders:readConsultar pedidos de vendas e compras
bling:crm:readConsultar contatos
bling:logistics:readConsultar logísticas, remessas e etiquetas
bling:catalog:writeCriar/editar produtos, categorias, depósitos
bling:stock:writeCriar/editar registros de estoque
bling:orders:writeCriar/editar pedidos e lançamentos de estoque
bling:crm:writeCriar/editar contatos

NF-e, financeiro e escrita fiscal ficam fora da v1. Não peça write scopes para auditoria.

Tools esperadas

ToolUso
get_bling_guideGuia embutido, 0 créditos
list_bling_connectionsContas conectadas, 0 créditos
bling_get_catalogLista endpoints REST v3 catalogados, scopes e path params
bling_call_endpointExecuta endpoint catalogado por tool

Mapeamento HTTP Titanos: POST /api/mcp/bling/guide, GET /api/mcp/bling/connections, POST /api/mcp/bling/catalog e POST /api/mcp/bling/call.

Use somente tool catalogada. Nunca tente URL livre.

Custos e quotas

Chamadas de setup e guias custam 0. Cada chamada REST v3 enviada ao Bling custa 5 créditos ou consome quota inclusa do plano.

PlanoChamadas inclusas/mês
ExtensãoSem acesso
Launch100
Grow800
Scale2000
Dominate5000
Titan10000
Empire / EnterpriseIlimitado

Informe custo estimado antes de loops grandes. Retries idempotentes não devem cobrar novamente.

Rate limits Bling

  • 3 req/s e 120.000 req/dia por conta (global).
  • Em 429, respeite retry_after_seconds retornado pelo Titanos.
  • Filtros de data com intervalo > 1 ano são rejeitados (HTTP 400 na API) — use intervalos ≤ 366 dias.

Paginação

Produtos usam pagina e limite (default 100). Leia uma página, processe, avance pagina até a página vir com menos de 100 itens.

Exemplo bling_call_endpoint:

{
  "tool": "bling_produtos_list",
  "connection_id": "<uuid>",
  "query": { "pagina": 1, "limite": 100 }
}

Pedidos de vendas: bling_pedidos_vendas_list com dataInicial/dataFinal (máx. 1 ano).

Idempotência

Para POST/PUT/PATCH/DELETE:

  1. Leia o estado atual quando possível.
  2. Gere idempotency_key única por operação de negócio.
  3. Peça confirmação humana para operações irreversíveis ou em massa.
  4. Em timeout, repita com a mesma idempotency_key.

Formato sugerido:

bling:{connection_id}:{tool}:{natural_id}:{YYYYMMDDHHmm}

Retries

Retry apenas para 408, 429 e 5xx com backoff. Em 429, aguarde o tempo indicado. Não retry 400, 401, 403, 404. Em 401, a conexão pode ter expirado; peça reautorização.

Webhooks

Webhooks Bling usam HMAC-SHA256 (X-Bling-Signature-256) com o client_secret do app. O Titanos persiste eventos e processa de forma assíncrona. Eventos product.* e stock.* atualizam produtos já sincronizados em Meus Produtos.

Quando analisar webhook:

  • Trate como sinal; reconsulte a API antes de decisões críticas.
  • Não registre payload bruto com tokens em respostas ao usuário.

Prompts úteis

Liste minhas conexões Bling no Titanos MCP e diga qual está ativa. Não faça writes.
Use a conexão Bling ativa para listar produtos (bling_produtos_list), página por página, respeitando rate limit.
Liste pedidos de vendas dos últimos 7 dias (bling_pedidos_vendas_list) e resuma por situação.

Erros comuns

SintomaCausa provávelAção
SCOPE_MISSINGAPI Key sem scope BlingRecriar key com preset bling-erp
BLING_CONNECTION_NOT_FOUNDConta não conectadaConectar em /conta/integracoes?tab=bling
BLING_CONNECTION_EXPIREDRefresh token venceuReautorizar OAuth
BLING_RATE_LIMITED3 req/s ou 120k/diaAguardar e reduzir paralelismo
Tool Bling não aparecePackage MCP desatualizadoAtualizar @titanos/mcp-agents

Fontes oficiais

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.