Olist Tiny 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 Olist/Tiny ERP pelo Titanos
• Precisa de multi-contas, OAuth, quotas ou webhooks Tiny REST v3
• Menciona Olist Tiny via MCP (não tokens OAuth no .env local)

Use esta skill quando o usuário pedir para acessar Olist Tiny ERP pelo Titanos MCP. O Titanos deve ser o broker: o agente usa TITANOS_API_KEY; tokens OAuth da Olist 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 Olist não aparecerem.
3. Rode get_olist_guide quando disponível.
4. Rode list_olist_connections e escolha uma connection_id ativa.
5. Se faltar tool ou scope, pare e explique: integração Olist ainda não publicada, key sem scope, ou conta Olist não conectada.

Setup do usuário

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

1. Criar aplicativo no ERP da Olist/Tiny.
2. Configurar redirect URI do Titanos exatamente como https://titanos.com.br/TinyCallback.
3. Autorizar OAuth no Titanos.
4. Criar API Key MCP com scopes Olist.
5. Configurar Claude/Codex com @titanos/mcp-agents@1 e TITANOS_API_KEY.

OAuth oficial: access token expira em 4 horas e refresh token em 1 dia. Se a conexão estiver expirada, peça reautorização no Titanos.

Scopes

Não peça write scopes para tarefas de auditoria. Para writes financeiros, fiscais, estoque ou preço em massa, peça confirmação humana antes de aplicar.

Tools esperadas

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

Use somente recursos/operações catalogados. Nunca tente URL livre.

Custos e quotas

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

Informe custo estimado antes de loops grandes. Retries internos e replay idempotente não devem cobrar novamente.

Recursos Olist REST v3

Famílias principais: categorias, contas a pagar, contas a receber, contatos, CRM, dados da empresa, depósitos, estoque, expedição, logística, formas de pagamento/recebimento, intermediadores, listas de preços, marcas, notas fiscais, ordens de compra, ordens de serviço, pedidos, produtos, separação, serviços, tags de produtos, usuários e vendedores.

Dados financeiros, fiscais e de pedidos podem conter informações sensíveis. Resuma por padrão; só exponha dados pessoais completos se o usuário pedir e tiver permissão.

Paginação e alto volume

Não tente carregar tudo de uma vez.

• Use filtros de data, SKU, situação ou página sempre que possível.
• Leia uma página, processe, então avance.
• Respeite X-RateLimit-Remaining e X-RateLimit-Reset.
• Não rode múltiplos loops paralelos na mesma connection_id sem necessidade.
• Para sincronização grande, prefira job assíncrono Titanos em vez de loop MCP longo.

Idempotência

Para POST/PUT/DELETE:

1. Leia o estado atual quando possível.
2. Use dry_run: true se a tool suportar.
3. Gere idempotency_key.
4. Peça confirmação humana para operações irreversíveis ou financeiras/fiscais.
5. Se houver timeout, repita com a mesma idempotency_key; não crie outra.

Formato sugerido:

olist:{connection_id}:{resource}:{operation}:{natural_id_or_hash}:{YYYYMMDDHHmm}

Retries e rate limits

Retry apenas para 408, 429 e 5xx com backoff. Em 429, aguarde o reset informado. Não retry 400, 401, 403, 404 ou validação. Em 401, a conexão pode ter expirado; peça reautorização se o Titanos não conseguir refresh.

Webhooks

Webhooks Olist são configurados dentro da conta ERP. A Olist espera HTTP 200 e pode reenviar até 10 vezes com delay progressivo. Eventos principais: vendas, pedidos enviados, estoque e notas fiscais autorizadas.

Quando analisar webhook:

• Trate como sinal, não como verdade final se a decisão for crítica.
• Reconsulte a Olist antes de ação financeira, fiscal ou de estoque.
• Não registre payload bruto com PII em respostas ao usuário.

Prompts úteis

Liste minhas conexões Olist no Titanos MCP e diga qual está ativa. Não faça writes.

Use a conexão Olist ativa para listar produtos alterados nos últimos 7 dias. Processe página por página e respeite rate limit.

Audite pedidos Olist dos últimos 3 dias e destaque pedidos sem rastreio. Não altere nada.

Prepare uma atualização de estoque para o SKU ABC-123. Leia o saldo atual, rode dry_run e peça confirmação antes de aplicar.

Consulte contas a receber vencidas no mês corrente e gere um resumo por cliente, sem expor CPF/CNPJ completo.

Erros comuns

Fontes oficiais

• https://api-docs.erp.olist.com/documentacao/comecando/criando-um-aplicativo
• https://api-docs.erp.olist.com/documentacao/comecando/autenticacao
• https://api-docs.erp.olist.com/documentacao/comecando/limites-de-consulta
• https://api-docs.erp.olist.com/documentacao/webhooks/webhooks
• https://api-docs.erp.olist.com/api-reference/categorias/obter-categoria-por-identificador