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
In this repository24 other files it gives its agents.
- amazon-ads-keyword-target-builderSkill
- amazon-ads-launch-playbookSkill
- amazon-ads-optimizationSkill
- amazon-ads-reports-troubleshootingSkill
- amazon-adsSkill
- amazon-ads-write-recoverySkill
- amazon-competitor-radarSkill
- amazon-dspSkill
- amazon-keyword-intelligenceSkill
- amazon-listing-auditSkill
- amazon-market-entrySkill
- amazon-mining-researchSkill
- amazon-pricing-signalsSkill
- amazon-reorder-planningSkill
- amazon-seller-centralSkill
- amazon-sp-campaign-launcherSkill
- fba-inventory-risk-dashboardSkill
- listing-create-publishSkill
- olist-tiny-erpSkill
- search-term-harvest-dashboardSkill
- super-listing-powerSkill
- titanos-ads-quickstartSkill
- titanos-mcp-setupSkill
- wasted-ad-spend-dashboardSkill
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
- Distinctive: line 11
Use esta skill quando o usuário / Use this skill when the user:
- Very specific: line 16
Use esta skill quando o usuário pedir para acessar Bling ERP pelo Titanos MCP.
- Very specific: line 66
Use somente tool catalogada.
≈ “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.
Files
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
- Rode
whoamie confirme plano, organização e scopes. - Rode
get_server_guide({ "topic": "full" })se as tools Bling não aparecerem. - Rode
get_bling_guidequando disponível. - Rode
list_bling_connectionse escolha umaconnection_idativa. - 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:
- Criar aplicativo público na Central de Extensões Bling (categoria "Soluções em IA").
- Configurar redirect URI do Titanos exatamente como
https://titanos.com.br/BlingCallback. - Autorizar OAuth no Titanos (
/conta/integracoes?tab=bling). - Criar API Key MCP com scopes Bling (preset
bling-erpou leitura). - Configurar Claude/Codex com
@titanos/mcp-agents@1eTITANOS_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)
| Scope | Quando precisa |
bling:connections:read | Listar conexões e dados da empresa |
bling:catalog:read | Consultar produtos, categorias, grupos, canais e depósitos |
bling:stock:read | Consultar saldos de estoque |
bling:orders:read | Consultar pedidos de vendas e compras |
bling:crm:read | Consultar contatos |
bling:logistics:read | Consultar logísticas, remessas e etiquetas |
bling:catalog:write | Criar/editar produtos, categorias, depósitos |
bling:stock:write | Criar/editar registros de estoque |
bling:orders:write | Criar/editar pedidos e lançamentos de estoque |
bling:crm:write | Criar/editar contatos |
NF-e, financeiro e escrita fiscal ficam fora da v1. Não peça write scopes para auditoria.
Tools esperadas
| Tool | Uso |
get_bling_guide | Guia embutido, 0 créditos |
list_bling_connections | Contas conectadas, 0 créditos |
bling_get_catalog | Lista endpoints REST v3 catalogados, scopes e path params |
bling_call_endpoint | Executa 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.
| Plano | Chamadas inclusas/mês |
| Extensão | Sem acesso |
| Launch | 100 |
| Grow | 800 |
| Scale | 2000 |
| Dominate | 5000 |
| Titan | 10000 |
| Empire / Enterprise | Ilimitado |
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, respeiteretry_after_secondsretornado 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:
- Leia o estado atual quando possível.
- Gere
idempotency_keyúnica por operação de negócio. - Peça confirmação humana para operações irreversíveis ou em massa.
- 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
| Sintoma | Causa provável | Ação |
SCOPE_MISSING | API Key sem scope Bling | Recriar key com preset bling-erp |
BLING_CONNECTION_NOT_FOUND | Conta não conectada | Conectar em /conta/integracoes?tab=bling |
BLING_CONNECTION_EXPIRED | Refresh token venceu | Reautorizar OAuth |
BLING_RATE_LIMITED | 3 req/s ou 120k/dia | Aguardar e reduzir paralelismo |
| Tool Bling não aparece | Package MCP desatualizado | Atualizar @titanos/mcp-agents |
Fontes oficiais
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
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.

