MCP e agentes de IA
Conecte Claude, ChatGPT ou seu próprio agente ao servidor MCP da Fiuit para buscar horários, agendar e operar o negócio com sua chave de API.
Atualizado:
A Fiuit inclui um servidor MCP (Model Context Protocol) para que os agentes de IA usem o mesmo motor do bot de WhatsApp: mesmas pré-reservas, mesma validação e mesmo registro de auditoria. O servidor é um cliente fino da API: cada ferramenta chama a API com a sua mesma chave, então o MCP nunca dá mais permissões do que a chave.
O servidor hospedado é https://mcp.fiuit.com/ (https://mcp.fiuit.com/mcp é o mesmo endereço). Para conectar o Claude ou o ChatGPT com um botão, sem copiar chaves, siga Conectar o Fiuit à sua IA. O que vem a seguir é para conectá-lo com uma chave de API ou executá-lo você mesmo.
Material do partner
O conjunto partner inclui partner_courses, partner_league, partner_kit e partner_news: cursos revisados com seu progresso e pontuação, sua liga, mensagens e modelos com seu link de indicação e novidades prontas para compartilhar. As quatro ferramentas são de leitura, aceitam lang (pt, es ou en) e só aparecem com o scope partner:read.
Funcionam com chave de API ou conexão OAuth. Leem o partner de quem criou a chave ou autorizou a conexão, enquanto continuar sendo membro ativo do projeto. Se ainda não houver cursos revisados, a lista vem vazia; o progresso fica no navegador e não pode ser consultado pelo MCP.
Executar o servidor
Você precisa de Python 3.12+ e uv.
cd packages/mcp
uv sync
WAGEND_API_URL=https://api.fiuit.com MCP_PORT=8700 uv run python -m wagend_mcp
# escucha en http://127.0.0.1:8700/ (Streamable HTTP)
Variáveis:
| Variável | Para quê |
|---|---|
WAGEND_API_URL | URL da API (padrão https://api.fiuit.com) |
MCP_TOOLSETS | Conjuntos a expor: booking, admin, tasks, payments, customers, inbox, finance, partner e setup (configuração pouco usada: serviços, recursos, horários, fluxos, automações, site, loja, zonas e contas de cobrança). Padrão: os nove; sem setup a lista cai para umas 130 ferramentas |
MCP_HOST, MCP_PORT | Onde escuta (padrão 127.0.0.1:8700) |
MCP_ALLOWED_HOSTS | Hosts permitidos (proteção contra DNS rebinding) |
Conectar um cliente
A autenticação é uma chave de API no header Authorization. Sem uma chave com formato válido, o servidor responde 401 antes de entrar no protocolo.
Com o Claude Code:
claude mcp add --transport http wagend http://127.0.0.1:8700/ \
--header "Authorization: Bearer wg_live_xxx"
Ou com a configuração JSON de qualquer cliente que suporte HTTP:
{
"mcpServers": {
"wagend": {
"type": "http",
"url": "http://127.0.0.1:8700/",
"headers": { "Authorization": "Bearer wg_live_xxx" }
}
}
}
Para testar sem um agente: npx @modelcontextprotocol/inspector (transporte Streamable HTTP, a mesma URL e o header).
MCP público para os assistentes de IA dos seus clientes
Além do MCP do negócio (com chave), a Fiuit publica um MCP sem chave para os assistentes de IA das pessoas (ChatGPT, Claude, Gemini e outros): https://mcp.fiuit.com/clientes. Com ele, um assistente pode encontrar o seu negócio, ver o que o seu bot oferece e pedir um horário para uma pessoa real.
claude mcp add --transport http fiuit-clientes https://mcp.fiuit.com/clientes
| Ferramenta | O que faz |
|---|---|
find_business | Busca por nome ou subdomínio exato, ou por texto do diretório («padel Uruguaiana»). Até 10 resultados por página e 3 páginas, em ordem neutra: proximidade, horário livre nesse dia e aberto agora. |
list_offer | O que o bot oferece, com preços já formatados. |
find_slots | Horários livres de um serviço. |
quote_order | Cota um pedido de produtos: cada linha com seu preço e o total, já formatados. Só cota (não reserva nem pede nada); para mudar o carrinho, cota de novo. Só nos negócios que a têm habilitada. |
my_assets | Os bens da pessoa (o veículo dela), só numa conversa verificada. Só lê: para salvar ou corrigir um, a pessoa conta ao negócio pelo talk_to_business. Só tipos que o negócio já ativou. Só nos negócios que têm isso habilitado. |
my_context | O contexto da pessoa, só numa conversa verificada: o primeiro nome dela, o que está ativo (reservas e pedidos abertos, planos com o que resta, se tem uma cobrança pendente, sem valor) e o que costuma reservar ou comprar (serviço, dia, período e recurso). Serve para cumprimentá-la pelo nome e sugerir uma vez repetir o de sempre, buscando de verdade com find_slots ou quote_order. Nada da equipe (nem notas nem etiquetas). Só nos negócios que têm isso habilitado. |
request_booking | Reserva o horário por alguns minutos e manda para a pessoa um código por WhatsApp (padrão), Telegram ou email. |
confirm_booking | Confirma com o código que a pessoa recebeu. Sem o código, o horário é liberado sozinho. |
talk_to_business | Conversa com o bot do negócio, como pelo WhatsApp. Devolve conversation para continuar a conversa e a resposta com valores e datas já formatados. |
end_conversation | Encerra a conversa antes de vencer, se a pessoa pedir: o que vier depois começa sem os dados dela. |
search_knowledge | Responde perguntas sobre o seu negócio com o que diz a sua base de conhecimento. |
handoff | Passa a conversa para uma pessoa da sua equipe quando o cliente pede. |
request_task | Pede um serviço sem horário (uma avaliação, um orçamento) em nome da pessoa, só depois que ela confirmou um código na conversa. |
my_bookings | Mostra as reservas e pedidos abertos da pessoa, só depois que ela confirmou um código na conversa. |
cancel_booking, reschedule_booking | Pedem para cancelar ou mudar o horário de uma reserva da pessoa: chega um código novo e só com ele é feito. |
O assistente nunca confirma sozinho: sempre é preciso o código que chega para a pessoa. Só aparecem negócios com o site publicado e «Aceitar agentes de IA» ligado; o diretório mostra só os que também têm «Aparecer no diretório da Fiuit». Os dois vêm ligados e mudam com update_site (accept_agents, in_directory), pela API (PATCH /v1/site) ou pedindo para o Wagy. Produtos e planos são pedidos pelo site do negócio. As mesmas rotas estão na API sem credencial: /v1/public/agents/*.
Conversar com o bot (talk_to_business). Responde o mesmo bot do WhatsApp, com as suas regras: o que vende, as etapas, a passagem para uma pessoa, o tom e a saudação. A conversa aparece no Mensagens marcada «Via IA» e a sua equipe pode assumir; se assumir, o assistente lê a resposta da pessoa. Para reservar um horário o assistente precisa mandar o nome e o telefone (ou o email) da pessoa: o «sim» ao resumo não confirma, a pessoa recebe um código e a reserva só fica com confirm_booking. Até a pessoa confirmar um código na conversa, pedir sem horário, cancelar ou remarcar não se faz por um assistente. Cada conversa gasta uso de IA do seu plano, como qualquer canal. Rotas na API: POST /v1/public/agents/businesses/{business}/conversations e .../conversations/{conversation_id}/messages (POST para mandar, GET para ler, com espera opcional).
Sessão verificada. Quando a pessoa confirma o código de uma reserva pedida na conversa, a conversa não é cortada: continua 24 horas na ficha dela (verified_until). O bot cumprimenta pelo nome e conhece as reservas, pedidos e planos dela (a dívida, só o total). Reservar ou pedir de novo sem cobrança não pede outro código; cancelar, remarcar e pagar pedem um novo a cada vez, que chega ao contato que a pessoa confirmou e se usa em confirm_booking. A conversa não renova as 24 horas: só outro código confirmado. Depois desse prazo, ou numa conversa nova, o assistente começa sem dados da pessoa; com end_conversation (DELETE .../conversations/{conversation_id}) a pessoa encerra antes.
Ferramentas
As ferramentas de tarefas e cobranças só aparecem na lista se a chave tiver o scope de que precisam (uma chave sem permissões de cobrança não as vê nem pode usá-las). Nas demais, cada uma só funciona se a chave tiver o scope; caso contrário, devolve o erro 403 da API. As escritas ficam auditadas com ator mcp.
Cada ferramenta traz suas anotações MCP: readOnlyHint (só lê), destructiveHint (cancela, apaga, anula ou devolve dinheiro), idempotentHint e openWorldHint (escreve para um cliente, cobra com um provedor ou publica na internet). Assim o ChatGPT e o Claude sabem o que podem usar sem pedir confirmação. Ao conectar, o servidor se apresenta como Fiuit e diz ao modelo por onde começar (list_today, list_tasks, list_conversations).
Agendamentos (booking): para assistentes que agendam em nome de um cliente.
| Ferramenta | Scope | Faz |
|---|---|---|
list_services | config:read | Serviços com duração e preço |
find_slots | slots:read | Horários disponíveis de um serviço entre duas datas ou de um dia de abertura (day, inclui a noite depois das 00:00) |
hold_slot | bookings:write | Pré-reserva de 10 minutos |
confirm_booking | bookings:write | Confirma uma pré-reserva com os dados do cliente |
cancel_booking | bookings:write | Cancela um agendamento. Exige confirm=true: sem ele só mostra o agendamento e não cancela |
reschedule_booking | bookings:write | Move um agendamento existente para outro horário |
get_booking | bookings:read | Detalhe de um agendamento |
Administração (admin): para o Dono operar o negócio pelo seu assistente de IA.
| Ferramenta | Scope | Faz |
|---|---|---|
list_resources | config:read | Equipe, salas, máquinas e equipes, com o ícone e a cor, se tiverem |
list_today | bookings:read | Agendamentos do dia e o que está sem terminar, de vários dias, e o atravessa |
block_time | config:write e bookings:read | Fecha dias inteiros de um recurso (máx. 31). Não cancela agendamentos existentes: devolve-os para uma pessoa decidir |
list_service_pauses | config:read | Lista as pausas por datas de um serviço |
pause_service | config:write | Pausa um serviço de uma data a outra (inclusive) sem bloquear os recursos que o atendem: os outros serviços deles seguem sendo oferecidos |
resume_service | config:write | Reabre um serviço pausado em um intervalo de datas |
create_service, update_service | config:write | Cria ou altera um serviço, com seu formulário de agendamento |
update_schedule | config:write | Altera o horário semanal ou o fuso horário |
list_booking_series, get_booking_series | bookings:read | Horários fixos (agendamentos que se repetem, «toda terça às 20:00») e suas datas: com tarefa, puladas ou com conflito |
create_booking_series | bookings:write | Cria um horário fixo: mesmo serviço e cliente a cada 1 a 4 semanas, em um ou vários dias, até uma data (máx. um ano) ou um número de vezes (máx. 52). Cada data é uma tarefa normal cobrada nesse dia. Sem confirm=true devolve a prévia (datas das próximas 8 semanas e quais têm conflito); as com conflito são puladas com skip_dates ou skip_conflicts |
update_booking_series, cancel_booking_series | bookings:write | Edita ou cancela a série toda ou, com from_date, «esta e as seguintes». As datas futuras não iniciadas nem cobradas são refeitas (ou canceladas sem aviso); o passado ou cobrado não muda. «Só esta» é reschedule_booking ou cancel_booking dessa tarefa. Exigem confirm=true |
get_coverage | config:read | Cobertura do negócio: zonas ativas e o que acontece com o que fica de fora (out_of_coverage) |
set_coverage | config:write | Escolhe o que fazer fora da cobertura (também com uma entrega que não chega a essa zona): out_of_coverage = take (aceitar e avisar) ou reject (não aceitar) |
get_stats | bookings:read | Agendamentos, ocupação e faltas por recurso; por padrão só pessoas, com quadras ou lugares passe kind=all |
get_control_summary | bookings:read (conversas com messages:read, valores com finance:analyze) | «Como estamos?»: atenção agora, tarefas em andamento por etapa, números do período (vendido, recebido, a receber) e saturação por dia da semana e hora. Filtros opcionais date_from/date_to (padrão hoje), service_id e resource_id. Somente leitura; o que a key não pode ver chega null As etapas são contadas por serviço e pelo estado real da tarefa. Recebido usa a data do pagamento, mesmo se o trabalho pertence a outro dia; pagamentos em análise são os pendentes atuais, inclusive de tarefas sem data. Cada resposta mantém uma única visão temporal do projeto. |
list_flows, get_flow, list_flow_versions, get_flow_version | config:read | Fluxos (o percurso de etapas que os serviços escolhem), seus serviços, saídas e requisitos; histórico de versões. get_flow também traz procedure: o fluxo como texto por idioma, gerado de novo a partir da versão vigente |
validate_flow | settings:write | Valida sem gravar; devolve impact com as tarefas a mover e shared_with |
simulate_flow | settings:write | Simulado de entrada de um fluxo por intenção: onde cai cada frase de entry (a enviada, sem salvar) e se colide; usa a IA do projeto nas frases que as palavras-chave não decidem |
copy_flow | settings:write | Copia um fluxo (também de sistema) em um próprio e independente com outro nome, após a confirmação; nenhum serviço muda |
customize_flow | settings:write | Edita um fluxo de sistema na cópia própria do negócio (a cria na primeira vez e passa para ela os serviços que usavam a base), após a confirmação |
restore_flow | settings:write | «Voltar ao original» a partir da cópia própria: os serviços voltam ao fluxo de sistema e as tarefas abertas terminam com a versão que tinham |
delete_flow | settings:write | Apaga um fluxo sem uso e sem tarefas, após a confirmação |
create_flow, update_flow | settings:write | Criam um fluxo ou publicam uma versão após prévia e confirmação; publicar move as tarefas de todos os serviços do fluxo. Cada etapa pode trazer bot_offers (o que o bot oferece enquanto a tarefa está ali; um item inexistente dá 422 bot_offer_unknown_item) |
upload_stage_image | settings:write | Guarda a imagem de fundo de «Marcar sobre imagem» e devolve o id, publicado em sketch_background com update_flow |
revert_flow | config:read + settings:write | Cria outra versão a partir da escolhida; preserva o histórico |
get_flow_examples, get_base_states, get_flow_message_catalog | config:read | Exemplos de fluxo para copiar, estados fixos do motor e as variáveis protegidas com o texto padrão da mensagem ao cliente de cada etapa |
get_flow_usage | bookings:read | Quanto cada fluxo é usado: sem flow_id, as tarefas que entraram nos últimos 7 dias contra os 7 anteriores; com flow_id, entradas e concluídas por dia e as tarefas abertas por etapa com a espera média (bottleneck, a etapa que mais trava). Somente leitura. |
get_business_traits, set_business_traits | config:read / settings:write | Características do negócio (do catálogo fechado: «agenda do local», «com espaços», «vende produtos»…) e o rótulo livre do ramo, só informativo. Salvar substitui a lista e o rótulo após a confirmação; omitir business_label ou enviar null apaga o rótulo. Para mantê-lo, consulte get_business_traits e envie o rótulo ao salvar; não muda as regras de reserva nem a agenda |
get_item_performance | bookings:read (serviço, produto); prepaid:read (plano) | Desempenho de um serviço, produto ou pacote/clube em quantidades (concluídas, unidades, vendidos, ativos hoje) por dia, semana ou mês, com o período anterior. Com uma chave são os totais do negócio (scope: business). Nunca traz valores: eles ficam no Financeiro. |
Tarefas (tasks): tarefas com e sem horário, as "a agendar" e a fila.
| Ferramenta | Scope | Faz |
|---|---|---|
list_tasks | bookings:read (e payments:read_balance se pedir saldo) | Lista tarefas por estado, a agendar (scheduling_state=pending), sem atribuição (unassigned=true), atrasadas (late=true), fila, origem (origin=conversation é o pedido pelo chat) e, opcionalmente, com o saldo e filtro por estado de pagamento da página. Com flow_id deixa as tarefas de um fluxo e com group_by (stage, status, resource, priority, type, tag, day, zone, customer ou flow) soma as contagens por grupo; com group_by=stage e flow_id traz todas as etapas do fluxo em ordem, como as colunas do Quadro do painel; statuses e resource_ids filtram por «qualquer um destes» estados ou recursos antes de paginar; group_by=tag expõe o texto livre das etiquetas e exige include_sensitive=true com customers:read; match aplica os critérios de uma visualização do Trabalho: vários estados, uma data com seu campo e um período relativo (hoje, mês passado, últimos N dias…) resolvido no fuso do projeto, e grupos «ou» (any_of) |
create_task | bookings:write | Cria uma tarefa com horário, de fila ou a agendar sem horário (schedule_later=true); com flow_id de um fluxo por intenção, uma tarefa sem serviço (reclamação, orçamento), sem horário nem valor; com internal=true, uma tarefa da equipe sem cliente (de um serviço sem preço) |
schedule_task | bookings:write | Dá horário a uma tarefa sem horário, ou muda o que ela tem; a API valida a disponibilidade |
assign_task | bookings:write | Atribui pessoas ou recursos a uma tarefa |
list_task_lines | bookings:read | Itens da tarefa, seus dois blocos (serviços e produtos) e a margem (só com permissão de custos) |
add_task_line | bookings:write | Soma um serviço ou produto do catálogo, ou um item livre com preço e custo opcional; aumenta o valor a cobrar, exige confirm=true |
edit_task_line | bookings:write | Corrige preço (também de um item do catálogo, só nessa tarefa), quantidade e custo; num item livre, também o nome; exige confirm=true |
remove_task_line | bookings:write | Tira um item e reduz o valor a cobrar (nunca abaixo do já cobrado); exige confirm=true |
list_task_checklist | bookings:read | Checklist da tarefa: os pontos a fazer, quais estão marcados e quem os marcou. Interno: o cliente não vê |
add_task_checklist_item | bookings:write | Soma um ponto ao checklist («revisar freios»); não mexe no valor a cobrar nem no que o cliente vê. Desfaz-se apagando |
change_task_checklist_item | bookings:write | Marca ou desmarca um ponto (done) ou muda o texto (name); expected_version evita sobrescrever outra pessoa |
remove_task_checklist_item | bookings:write | Apaga um ponto do checklist; exige confirm=true |
preview_task_discount | payments:adjust | Mostra como fica o total com um desconto, sem salvar nada |
apply_task_discount | payments:adjust | Aplica ou altera o desconto da tarefa, em valor ou porcentagem (value em pontos-base); o técnico até 10 %; exige confirm=true |
remove_task_discount | payments:adjust | Tira o desconto e o total volta à lista; exige confirm=true |
preview_plan_discount | prepaid:sell | Mostra como ficam as parcelas com um preço especial, de um plano a vender ou vendido, sem salvar nada |
apply_plan_discount | prepaid:sell | Preço especial de um plano vendido, a partir da próxima parcela; só cobrança manual; exige confirm=true |
remove_plan_discount | prepaid:sell | Tira o preço especial: as parcelas seguintes voltam ao preço do plano; exige confirm=true |
accept_work_item_offer | bookings:write | Aceita uma oferta («Oferecer…») da etapa atual da tarefa (vêm em offers no detalhe da tarefa): um produto entra nessa tarefa com o preço do catálogo e aumenta o valor a cobrar; um serviço cria outra tarefa, independente, para o mesmo cliente. Exige confirm=true; nunca aceita um preço |
As ferramentas de itens mantêm identificadores, quantidades e valores na resposta mínima. Para ver nomes e unidades, use include_sensitive=true com o escopo de leitura indicado. Se alterarem o total de um orçamento aceito, podem enviar uma revisão ao cliente; por isso exigem confirmação.
Cobranças (payments): cobranças manuais e saldos. Os saldos são sempre calculados pela API; o MCP não soma nem subtrai.
| Ferramenta | Scope | Faz |
|---|---|---|
record_payment | payments:record | Registra uma cobrança manual (dinheiro, cartão, transferência, Pix, Mercado Pago ou outro; a forma de pagamento é obrigatória e fica na auditoria), opcionalmente dividida entre tarefas |
void_payment | payments:void | Anula uma cobrança, com motivo obrigatório |
expense_categories | expenses:read | As 11 categorias de despesa do projeto (nomes fixos, tipo e se está oculta). «Comissões da equipe» é uma linha calculada: não se lança à mão |
expense_list | expenses:read | Despesas lançadas por período, categoria ou recurso; total_minor é somado pela API (só aprovadas: sem pendentes, recusadas, anuladas nem de teste; status filtra por estado). Com tag_id, só as despesas com essa etiqueta: o total não se soma com o de outra etiqueta, porque uma despesa pode ter várias. Sem recurso, a despesa é «Geral» |
expense_record | expenses:record | Lança uma despesa na moeda do projeto (data local, nunca futura). Exige confirm=true; se o valor for alto para o negócio (a partir do dobro do valor mensal do plano), também confirm_high_amount=true, uma segunda confirmação da pessoa. Aceita tags (etiquetas por nome; as novas são criadas) e, sem category_id, usa a categoria que a primeira etiqueta que tiver uma lembra (se nenhuma, 409 expense.category_required) |
expense_void | expenses:void | Anula uma despesa com motivo; uma despesa nunca é apagada. Exige confirm=true |
income_record | payments:record | Registra uma receita que não passou por uma tarefa («+ Receita»): uma venda rápida com a sua cobrança. O vendido é uma categoria (product_sale, rental, tip, other_income), um serviço ou um produto (income_options lista). collection: paid (já recebido, com method), mercadopago (fica a receber; o link é criado à parte com create_payment_link, sempre com o OK da pessoa) ou debt (exige customer_id). Sem cliente vai para «Venda sem cliente». Sem confirm=true devolve a prévia sem gravar |
income_void | payments:void | Anula uma receita com motivo: os recibos ficam anulados e ela deixa de contar. Um pagamento do Mercado Pago já creditado é devolvido, não anulado |
expense_tags | expenses:read | As etiquetas de despesas do projeto («moto», «loja centro»), as mais usadas primeiro, com a categoria que cada uma lembra e quantas despesas a têm |
expense_tag_rename | expenses:record | Renomeia uma etiqueta; se outra já tem esse nome, junte-as com expense_tag_merge. Exige confirm=true |
expense_tag_merge | expenses:record | Junta duas etiquetas: as despesas de uma passam para a que fica e a outra é apagada. Não dá para desfazer. Exige confirm=true |
expense_tag_delete | expenses:record | Apaga uma etiqueta e a tira das despesas; as despesas não mudam. Exige confirm=true |
expense_pending | expenses:approve | Quantas despesas lançadas pela equipe aguardam aprovação e quanto somam (sem as de teste) |
expense_history | expenses:read | Histórico de uma despesa: quem, quando e o que mudou (antes e depois). Não há fechamento do mês |
expense_get | expenses:read | Uma despesa: valor, categoria, data, status (aprovada, pendente, recusada ou anulada), comprovante e revisão. É o detalhe de uma despesa em Movimentações |
expense_approve | expenses:approve | Aprova uma despesa pendente da equipe: a partir de agora soma. Ninguém aprova o que lançou. Exige confirm=true |
expense_reject | expenses:approve | Recusa uma despesa pendente com motivo; fica recusada e não soma. Exige confirm=true |
recurring_expense_list | expenses:read | Despesas que se repetem (aluguel, salários fixos), com a próxima data e se estão ativas, pausadas ou encerradas |
recurring_expense_create | expenses:record | Cria uma despesa que se repete toda semana ou todo mês; a Fiuit lança sozinha em cada data, uma única vez. Exige confirm=true |
recurring_expense_update | expenses:record | Muda o valor ou o dia, pausa ou retoma, ou encerra, daqui em diante. Exige confirm=true |
recurring_expense_skip | expenses:record | Pula a próxima data sem lançar a despesa. Exige confirm=true |
apply_refund_due_to_account | payments:adjust | «Usar para outra dívida»: um pagamento tardio separado «a devolver» (refund_due) passa ao saldo do cliente e cobre as dívidas mais antigas. Exige confirm=true; a API recusa com uma reclamação aberta no Mercado Pago |
refund_payment | payments:refund | Devolve ao cliente (total ou parcial) uma cobrança do Mercado Pago, com motivo; sem valor, tudo o que resta. Exige confirm=true com a chave da prévia: repeti-la não devolve duas vezes e nunca se devolve mais do que o recebido. Responde succeeded, failed (o Mercado Pago recusou), pending (é tentada de novo sozinha, consultando antes o Mercado Pago) ou review (o Mercado Pago não confirmou: não é pedida de novo, o valor fica reservado e Dono/Gerente recebe um aviso). Só Dono/Gerente |
get_payment_refunds | payments:refund | Devoluções de uma cobrança: o devolvido, o que está em andamento e o que ainda pode ser devolvido (ou por que não) |
charge_fiscal_get | payments:fiscal | Marcador fiscal de uma cobrança e notas do emissor do negócio, se houver. A Fiuit nunca emite notas. Só Dono/Gerente |
charge_fiscal_mark | payments:fiscal | Marca se uma cobrança leva nota: não exige, pendente ou emitida fora da Fiuit (com número e data). Só cobranças com dinheiro recebido. Exige confirm=true. Só Dono/Gerente |
charge_fiscal_issue | payments:fiscal | Pede a nota fiscal (NFS-e) com o Fiuit Fiscal, ou tenta de novo se falhou, sem emitir duas notas por cobrança. Só projetos com país fiscal Brasil (senão, fiscal.country_not_supported) e cobranças em reais com dinheiro recebido. Exige confirm=true. Só Dono/Gerente. Ativar o Fiuit Fiscal e marcar uma nota cancelada no portal do município são feitos no painel |
get_task_balance | payments:read_balance | Saldo de uma tarefa e, se quiser, seu histórico de cobranças |
get_customer_account | customer_balance:read (e customer_account:read para o detalhe) | Conta corrente do cliente: saldo, pagamentos antecipados e dívidas; com include_movements=true, detalhe por tarefa e cobranças |
get_commissions | commissions:read | Comissões da equipe calculadas pela API sobre o recebido: com day, o dia por pessoa (recebido por meio, gorjetas, comissão, ajustes e caixa); sem day, o relatório entre start e end. refund_amount_unavailable lista as tarefas com reembolso parcial sem valor informado, que ainda contam inteiras. Somente leitura |
get_commission_settlements | commissions:read | Fechamentos de comissões de um período: valores congelados, ajustes automáticos que já congelaram de outros períodos e o pendente de passar ao próximo período aberto. Somente leitura |
settle_commissions | commissions:settle | «Fechar comissões»: congela o período de uma pessoa em um lançamento que não é reescrito, com motivo. Uma mudança posterior (anulação, devolução ou regra) vira ajuste automático no primeiro dia ainda aberto. Fechar de novo o mesmo período devolve o mesmo lançamento. Exige confirm=true |
finance_overview | finance:analyze | Resumo de Finanças calculado pela API: Entrou, Saiu e Ficou realizados de 2 períodos anteriores e do atual, e o que falta do atual e do seguinte, certo (já recebido, despesas fixas) ou previsto (saldo sem pagar, comissão da equipe estimada, despesas aguardando aprovação). Só coisas com data. |
finance_result | finance:analyze | Resultado calculado pela API, com basis cash (caixa, padrão) ou accrual (competência, DRE: o que foi feito no período, recebido ou não, com «a receber» à parte). No caixa: Entrou (recebido menos devolvido), Saiu (despesas aprovadas, comissões da equipe e taxas de cobrança informadas) e Ficou, com margem e o período anterior, por período, recurso, serviço ou categoria. Despesas sem recurso ou serviço ficam como «Geral», sem rateio. missing_expenses avisa que entrou dinheiro e não há despesas lançadas. Somente leitura |
finance_result_lines | finance:analyze | Do que se compõe um número do Resultado: os recebimentos, devoluções, taxas de cobrança, comissões da equipe e despesas aprovadas que ele soma, com valor com sinal, dia, categoria, recurso, serviço, pessoa e cliente. Abre-se uma linha (row, «Geral» com general), Entrou ou Saiu (side) ou um tipo (kind), ou uma célula da DRE do ano (dre); total_minor é o número aberto mesmo que a lista seja cortada em limit. Somente leitura |
finance_year | finance:analyze | A DRE do ano, mês a mês: receita bruta, devoluções, impostos, custos diretos, lucro bruto, despesas operacionais por categoria e o resultado de cada mês (sobrou ou faltou), em caixa ou por competência (basis). O total do ano é o de finance_result. Somente leitura |
export_finance_result_csv | finance:analyze e finance:export | Exporta o Resultado do período como CSV para o contador: um movimento por linha (cobrança, devolução, taxa de cobrança, comissão da equipe ou despesa) com categoria, recurso, serviço, pessoa, cliente, valor legível e valor em unidade menor com sinal; a soma é o que ficou. Mesmo separador e decimais do Excel no país da moeda. Até 50.000 movimentos. O Excel de 8 abas é baixado pela API REST. Fica registrado |
create_finance_package · list_finance_packages · get_finance_package | finance:analyze e finance:export | Pede o pacote para o contador do período (Excel de 8 abas e resumo em PDF de uma página, com os mesmos números do Resultado) e consulta o seu estado. Se for pequeno volta pronto com um link de download que vale 5 minutos; se for grande é montado à parte. Com chave de API não inclui as fotos dos comprovantes: essas só são baixadas pelo painel. O arquivo vence em 48 horas. Fica registrado |
| list_prepaid_plans | prepaid:read | Pacotes (N sessões com validade), planos de clube (N por mês) e assinaturas (preço fixo por mês, sem contar usos) do catálogo, com preço, valor por unidade e limite por dia/faixa |
| get_customer_plans | prepaid:read | Pacotes, clube e assinaturas de um cliente: unidades restantes, reservadas, validade e mensalidade pendente. Cada período é uma parcela, uma tarefa que se cobra (period.booking_id); open_fees traz as parcelas a cobrar (tarefa, vencimento e valor) e next_due_at o próximo vencimento. active = em dia, past_due = alguma parcela vencida sem pagar. Pagar uma parcela = cobrar a tarefa dela (record_payment com esse booking_id); não há ferramenta à parte |
| sell_prepaid_plan | prepaid:sell e payments:record | Vende um plano cobrado na hora (dinheiro, cartão, transferência, Pix, Mercado Pago ou outro; a forma de pagamento fica na auditoria). Sem cobrar (unpaid=true), a parcela 1 fica A cobrar e é cobrada como qualquer tarefa (record_payment com o seu booking_id), como as parcelas seguintes. Um clube ou assinatura com cartão é vendido com o e-mail do cliente (payer_email), só se list_prepaid_plans trouxer card_billing_available=true: fica aguardando autorização e devolve checkout_url, o link do Mercado Pago para o cliente autorizar o cartão (para isso basta prepaid:sell). Se o cliente já tem esse plano com cartão vigente, responde 409 prepaid_card_sale_exists com o subscription_id dessa venda: não se vende outra. Exige confirm=true |
| cancel_prepaid_plan | prepaid:sell (reembolso: também payments:void e payments:record) | Cancela: não nascem mais parcelas e as já criadas não mudam (uma em aberto continua sendo dívida; a resposta as traz em open_fees); libera as sessões de tarefas futuras. Com refund=true devolve o não consumido da parcela do período vigente de um plano cobrado na hora (o vencido se perde). Exige confirm=true |
| extend_prepaid_plan | prepaid:sell | Estende manualmente a validade de um pacote ou clube (ou reabre um pacote vencido). Ao vencer, o não usado se perde. Exige confirm=true |
| remove_task_plan | prepaid:sell | Tira o plano de uma tarefa: libera a unidade e a tarefa volta ao valor normal. Necessário antes de trocar o cliente ou o serviço. Exige confirm=true |
cancel_booking também exige confirm=true: sem ele devolve o agendamento e confirmation_required, e não cancela nada. Mostre o agendamento à pessoa antes de repetir a chamada com confirm=true.
record_payment e void_payment movimentam dinheiro: exigem confirm=true e, sem ele, não executam a operação monetária (o protocolo pode consultar GET /me). Passe sempre idempotency_key para tentar de novo sem cobrar duas vezes; os limites de valor e a detecção de duplicados são os da API. received_by é a associação de quem recebeu o dinheiro: com uma chave de API é obrigatório.
expense_record, expense_void, income_record, income_void, expense_approve, expense_reject e os recurring_expense_* que escrevem também são dinheiro: exigem confirm=true e idempotency_key. Renomear, juntar e apagar etiquetas não movem dinheiro, mas também exigem confirm=true (sem idempotency_key). Para corrigir uma despesa a partir de um agente, anule e lance de novo; a edição com histórico é feita no painel. A foto ou o PDF do comprovante de uma despesa não passa pelo MCP nem por uma chave de API: é anexado com a sessão do painel.
A preparação sem confirm devolve idempotency_key; a confirmação exige essa chave ou uma do agente (1-128 caracteres). Reutilize a mesma chave, destino e payload em todas as tentativas, mesmo quando a resposta se perder. Uma operação nova exige outra chave, mesmo com uma cobrança idêntica.
Por padrão, list_tasks omite contatos, endereço exato, coordenadas, notas e formulário. include_sensitive=true solicita o detalhe e exige também customers:read. Os movimentos de get_customer_account e o histórico de get_task_balance omitem nomes dos recebedores, notas e motivos; o mesmo parâmetro exige também payments:read. Chaves mode=test só veem ferramentas de leitura.
As escritas de configuração, de tarefas e de cobranças exigem confirm=true. Sem ele, a ferramenta não executa a escrita (pode consultar dados para a prévia): devolve confirmation_required com o que enviaria, para o agente mostrar a uma pessoa e repetir com a confirmação.
Conexão com OAuth: permissões e ferramentas que não aparecem
Quando o dono conecta o Claude ou o ChatGPT (veja Conecte sua IA), a IA usa um token com as permissões que ele marcou na página de permissões. O que muda em relação a uma chave de API:
- Vários projetos numa conexão. Uma chave de API é de um projeto; uma conexão OAuth pode cobrir vários.
list_projectslista todos (id, nome, slug, papel e permissões em cada um) e todas as ferramentas aceitam umprojectopcional com esse id ou slug, que o MCP envia no cabeçalhoX-Wagend-Project. Com um só projeto não é preciso. Com vários e semproject, a ferramenta responde400 project_requiredcom a lista para a IA perguntar; um projeto que não é da conexão dá403 project_not_in_connection, exista ou não. As permissões e o papel são revistos a cada chamada, no projeto escolhido. Com uma chave de API,list_projectsdevolve o único projeto dela. - A lista de ferramentas é recortada. Só aparecem as que o token pode usar.
get_task_balanceelist_taskscominclude_balance=truepedempayments:read_balance(permissão «Ver dinheiro»): se não estiver, a ferramenta não aparece ou responde403 insufficient_scope. Para incluí-la é preciso conectar de novo marcando «Ver dinheiro» (só o dono concede). Os metadados de/.well-known/oauth-protected-resourcepublicamscopes_supportedpara o cliente saber o que pedir. - Editar os produtos de um pedido (
replace_task_items) pede sóbookings:write; não precisa ver dinheiro. O valor a cobrar é recalculado e a API não deixa baixar o pedido abaixo do que já foi cobrado (409order_below_paid). - Cobranças em dinheiro:
record_paymentcommethod: "cash"e a permissãopayments:record(«Registrar cobranças e enviar links de pagamento»). Ajustar à mão o valor a cobrar (payments:adjust) não é concedido por OAuth: é feito no painel. - Zona de um endereço:
match_zoneprecisa de coordenadas (latelng), bairro, cidade ou CEP; com um endereço em texto livre sozinho devolvezone: null. Com coordenadas vence a área desenhada, e a zona de um endereço salvo do cliente usa essa mesma regra. - Clientes:
list_customersseminclude_sensitive=truedevolve sóidelocale; para escolher um cliente pelo nome é precisoinclude_sensitive=true(ecustomers:read). - Hábitos do cliente:
get_customer_summarytrazhabits(com que frequência vem, dia e faixa, serviço, data esperada e estado pelo ritmo dele:on_track,due,late,at_risk,lost) e, se for candidato,fixed_proposalpara montar o horário fixo comcreate_booking_series.list_customersfiltra porhabit(um estado:on_track,due,late,at_risk,lost; oufixed_candidate); «quem eu perdi este mês?» éhabit=lostcomlost_sinceno primeiro dia do mês. - Linha do tempo:
customer.updatedebooking.updatedtrazemfieldsouchangedcom os nomes dos campos editados, nunca os valores.
Painel do parceiro (partner)
Se você é parceiro da Fiuit, sua IA pode ler sua carteira com as mesmas regras do seu painel. Todas são só leitura (readOnlyHint) e pedem o scope partner:read: por OAuth, a permissão «Ver sua carteira de parceiro», que a página de permissões só oferece a um parceiro. Sem esse scope, elas não aparecem na lista.
| Ferramenta | Scope | Faz |
|---|---|---|
partner_today | partner:read | A próxima ação, o progresso da carteira e os alertas |
partner_clients | partner:read | Seus clientes com plano, último uso, contagens e semáforo; ordem, cursor e filtro rápido quick |
partner_client_detail | partner:read | Um cliente e seus marcos. Um projeto fora da sua carteira dá 404 client_not_found |
partner_activity | partner:read | Marcos dos seus clientes, do mais novo ao mais antigo |
O parceiro é quem emitiu a credencial (criou a chave ou autorizou a conexão), nunca um dado do pedido. Uma chave com o scope emitida por outra pessoa dá 403 partner_required; se o parceiro é desativado ou sai do projeto da credencial, ela para de funcionar na próxima chamada. Só contagens e estados: nem o conteúdo dos negócios nem seus valores. Criar um projeto para um cliente continua sendo só pelo painel.
Exemplos de pedidos
- "Agende um corte com o João amanhã de manhã, no nome do Carlos."
- "Bloqueie a máquina de laser na próxima segunda por manutenção e me diga quais agendamentos ficam afetados."
- "Quantas faltas tivemos este mês?"
- "Mostre as tarefas sem atribuição e dê horário a elas amanhã às 10."
- "Registre uma cobrança em dinheiro de 50.000 da Ana pela última tarefa e me diga o saldo."
Docs para LLMs
/llms.txtlista todas as páginas da documentação./llms-full.txtcontém a documentação completa em Markdown.
Fluxos: as ferramentas de um fluxo exigem flow_id (list_flows); create_service e update_service aceitam flow_id para escolher o fluxo de um serviço. update_flow valida antes da prévia (impact e shared_with, os serviços que compartilham o fluxo e mudam todos); confirm=true cria versão. Fluxos de sistema não se editam diretamente: customize_flow dá a cópia própria (que se edita com update_flow) e restore_flow volta ao original; ou copy_flow (ou create_flow) e atribua-o. delete_flow apaga um fluxo sem uso nem tarefas. revert_flow cria outra versão (leitura config:read e escrita settings:write). validate_flow, get_flow_examples e get_base_states completam a configuração.
«Como a tarefa aparece»: update_flow com task_view escolhe o que vai no topo da tarefa (main: auto, when = Quando, destination = Destino, order = Pedido ou none = nada), o interruptor «Itens» (items: desligado, a tarefa não oferece «+ Adicionar item»; os itens já lançados continuam visíveis). chips (cliente e cobrança) já não tem efeito: é aceito por compatibilidade e ignorado. O que você não envia fica igual e clear_task_view=true volta ao automático. Sem confirm mostra task_view_diff com o antes e o depois; não cria versão nem move tarefas e vale também para um fluxo de sistema. Cada tarefa traz o ajuste vigente em task_view.
MCP inclui get_work_item_next_steps, move_work_item_stage e use_work_item_tool. Escritas exigem confirm=true e Idempotency-Key. complete_task foi removida. Cobrança eletrônica pendente F4-29. get_work_item_stage_history (scope bookings:read) lê o histórico imutável de etapas (máximo 100). Scopes: leitura bookings:read; mover e usar ferramentas bookings:write (mais payments:record ao cobrar); editar etapas do serviço settings:write. Um 403 (permissão ou scope), 409 (stage_conflict, already_claimed) ou 422 (stage_requirements_missing) chega ao agente sem alteração; repetir com a mesma idempotency_key e corpo devolve o mesmo resultado sem duplicar. A Wagy explica a capacidade vigente e o painel inclui Próximo passo e o editor de etapas. Os efeitos habilitados entram no outbox; isso não comprova entrega ao cliente.
Preencher com a foto (FIU-672): fill_stage_from_photo lê uma foto da tarefa e propõe os campos de texto ou número da etapa que seguem vazios. Não salva nada: os valores são confirmados com move_work_item_stage. O duvidoso não vem e o já salvo não é sobrescrito. Mesmas permissões de concluir a etapa. Cada leitura desconta da IA do plano; sem cota responde ai_limit_reached.
create_service e update_service aceitam price_per_time («Preço por tempo», com confirm=true): ao mudar a duração de uma tarefa desse serviço, o valor é recalculado na proporção, exceto com cobrança ou sinal registrados ou um valor ajustado à mão.
create_service e update_service aceitam duration_options (as durações que o cliente escolhe ao reservar, por exemplo 1 h, 1 h 30 e 2 h: [{"minutes": 90, "price_cents": 17000000}], até 6; sem preço, na proporção; com confirm=true); clear_duration_options as remove. find_slots e hold_slot aceitam duration_min (uma dessas durações): a reserva é uma só tarefa com essa duração e seu preço; outra duração responde 422 duration_not_offered.
create_service e update_service aceitam location_mode (local, customer_address, customer_choice ou remote: a distância, sem endereço) e meeting_url, o link http(s) da reunião de um serviço remote cadastrado pelo negócio (o Fiuit não o gera); clear_meeting_url o remove e mudar para outro modo o apaga. O bot e os lembretes enviam esse link no lugar de um endereço.
update_service aceita title_template: as peças do título das tarefas desse serviço (de 1 a 3: customer, order, address, number ou field:<chave> de um campo do formulário ou de uma etapa), unidas por « · »; clear_title_template volta para «Cliente · Pedido». update_task_metadata aceita title para escrever o título de uma tarefa à mão (fica fixo) ou null para voltar ao automático. As duas são escritas: mostram a proposta com a mudança e se aplicam com confirm=true.
update_service também muda a antecedência e o cancelamento: lead_time_min (minutos mínimos antes do horário; 0 = sem mínimo), max_advance_days (até quantos dias à frente se agenda; clear_max_advance_days = sem limite) e cancel_policy ({"deposit_refund_hours": N}, de 1 a 2160: cancelar com pelo menos N horas devolve o sinal pago pelo Mercado Pago; exige também payments:refund; clear_cancel_policy a remove). create_service e update_service aceitam accepts_chat_requests (os clientes pedem pelo chat sem escolher horário) e bot_offered (false: o bot não o oferece). Se o formulário de um serviço repete chaves dos itens do seu fluxo, o erro 422 invalid_service_stages nomeia cada chave repetida.
create_service e update_service aceitam booking_payment («Cobrança ao reservar»: none, deposit ou total) e deposit_cents, com confirm=true. Com total o horário cobra o valor completo da tarefa pelo fluxo do sinal; deposit sem sinal retorna 422. Os valores são validados antes de chamar a API.
Também aceitam full_day («Dia inteiro»): deixa-se e retira-se, e o cliente escolhe o dia, não o horário. Há um só horário por dia, da abertura ao fechamento; com um local que atende 3 ao mesmo tempo, entram 3 por dia. Não vale para um serviço que atribui uma pessoa (uma equipe com um recurso staff): responde 422 service_full_day_invalid.
list_tasks(date_from=…, date_to=…, include_carried=true) soma as tarefas iniciadas que passaram do fim e continuam ocupando o lugar nessas datas (serviço de dia inteiro ou sem pessoa, até 7 dias depois do fim): vêm com carried_over=true e carried_until. É a mesma regra da disponibilidade, com o scope bookings:read.
list_tasks mostra por padrão (fees=due) só as mensalidades de clubes e assinaturas que venceram ou vencem dentro dos dias de aviso do plano, como Hoje e Trabalho: não traz as pagas, as perdoadas nem as cobradas sozinhas no cartão enquanto a cobrança estiver em dia. Com fees=all traz todas (por exemplo, para ver o histórico de mensalidades de um cliente).
create_service e update_service aceitam chat_payment («Cobrança pelo chat», com confirm=true): mode (on_delivery|ask|link), prepare (anyway|after_payment) unpaid (keep|cancel) e remind (booleano: um único lembrete ao cliente antes de o link vencer); não leva valores, o link é pelo saldo da tarefa que o Fiuit calcula e exige o Mercado Pago pronto.
update_service aceita payment_requirement: required|optional|off: mostra uma proposta e com confirm=true usa o mesmo PATCH do catálogo (config:write). Alterar a regra cria uma versão auditada; o executor aplica a política vigente do serviço aos destinos completed. Com payments_enabled=false explícito não exige resolver cobrança nem apaga saldos (mudança em relação a F3-177).
Mercado Pago
Brasil e Argentina conectam apenas por OAuth. Chile, Uruguai, Colômbia, México e Peru conectam apenas por token em Pagamentos. Paraguai não oferece Mercado Pago. Contas existentes são preservadas.
Com conta de produção e serviço com sinal, BRL/ARS geram um link que vence antes da reserva temporária. No Brasil, o Pix é pago dentro do Mercado Pago. O portal mostra o link e o chat o envia pela conversa disponível.
A reserva fica aguardando sinal até verificar o pagamento. Pré-pagamento aplicado cobre ou reduz o sinal. Pagamento tardio exige revisão da equipe: não reconfirma nem devolve dinheiro automaticamente.
Uma tentativa rejeitada ou cancelada permite tentar o checkout novamente. Se um pagamento tardio deixar dinheiro não aplicado em revisão, a reserva pendente vence e libera o horário; o recibo e o aviso são preservados. A conciliação detecta pagamentos adicionais também quando chegam juntos na busca do Mercado Pago.
Uma cobrança tardia, devolvida ou contestada sem sinal aplicado conserva recibo e revisão ao liberar o horário. Um estado local cancelado não prova ausência de dinheiro: exige consulta final. A tolerância de 24 horas por perda de credenciais só libera uma reserva sem cobertura aplicada nem links substituídos sem verificar.
A disponibilidade de MP inclui country (país de cobrança conforme a moeda do negócio) mesmo sem conta; Pix só BR. Sem novas ferramentas, scopes ou ações de reembolso.
Antes de vencer uma reserva, o worker concilia todos os links eletrônicos pendentes de verificação, inclusive os substituídos e cancelados por mudança de valor, mesmo com nova tentativa adiada. Se uma consulta falhar ou faltar acesso a um link substituído, o horário é preservado. Recibos já verificados mantêm seu estado financeiro.
Um pagamento no prazo pelo link anterior é aplicado mesmo quando parcial: reduz o pendente e gera um link pela diferença. A reserva continua aguardando sinal e mantém o horário; o link pela diferença mantém o prazo original e nunca passa de duas horas antes do horário. Quando o prazo termina, fica em revisão sem novos links ou avisos ao cliente; Dono/Gerente recebe um aviso na primeira retenção parcial. Confirmar exige cobrir o total. Perder credenciais depois não remove a cobertura aplicada. A equipe deve concluir a cobrança ou resolver a reserva; não há devolução automática.
Checkout Pro recebe apenas contato e descrição conhecidos. O nome na fatura usa letras e números ASCII, sem acentos ou símbolos, com até 13 caracteres. O retorno abre o portal privado do cliente por seu link existente; sem link vigente ou após revogação, volta a /payment-return, uma página neutra sem dados do cliente. O retorno nunca cria nem revoga portais. O token fica no fragmento e não confirma pagamento. O receptor exige HTTPS público e rejeita .test, .example, .invalid e .localhost. Os testes habilitam explicitamente seus domínios reservados; produção não habilita.
Um POST de criação ambíguo libera a vaga após sete dias de buscas vazias bem-sucedidas, com aviso ao negócio e auditoria. Erro, pagamento observado ou perda de credenciais reinicia a janela. Dono/Gerente pode confirmar «Liberar a vaga» na revisão: cancela com auditoria e conserva o dinheiro registrado, sem reembolso. Exige tasks:work e payments:accounts_configure no painel; nenhuma ferramenta ou API key usa esse motivo reservado.
F4-25: get_mercadopago_account (payments:read) informa também workspace_currency, mismatch (currency ou country se a conta recebe em outra moeda ou país que o projeto: não são criados links), methods (link, Pix, QR e cartão com available e o motivo reason quando não estão disponíveis; QR e cartão ainda não existem) e deposit_hold_minutes. list_mercadopago_charges (payments:read, só leitura) lista as últimas cobranças do Mercado Pago com estado, valor, propósito e tarefa, sem dados do pagador nem link. A conta é conectada e o sinal de cada serviço é editado em Finanças → Cobranças.
F4-23: get_mercadopago_account inclui o método point (maquininha Point Smart; motivo terminal_required se não há maquininha vinculada) e account.point_terminal_id. Vincular a maquininha e «Cobrar com Point» são só do painel: não há ferramenta MCP (as operações não aceitam API key).
F4-20: create_payment_link (payments:link) cria o link do Mercado Pago pelo saldo de uma tarefa («Cobrar»); sem amount_minor, o valor é calculado pela API. Sem confirm devolve uma prévia com idempotency_key; confirm=true exige essa chave. deliver="conversation" também envia pela conversa do cliente. Um link aberto com o mesmo valor é reutilizado; com outro valor aberto responde 409 payment.link_pending.
F4-92: «Cobrar uma parte». create_payment_link aceita amount_minor opcional (inteiro na unidade menor, o que uma pessoa indicou): cria um link próprio por essa parte, que convive com outras partes abertas. A soma das cobranças abertas nunca passa do saldo: se não couber, responde 422 payment_part_exceeds_balance com remaining_minor (o que falta cobrir) e open_minor. Repetir com a mesma idempotency_key devolve a mesma parte; outra chave é outra parte, mesmo com o mesmo valor. Sem valor, o link cobra o que sobra sem parte. cancel_payment_charge (payments:link, confirm=true) anula um link aberto, seja uma parte ou o link pelo saldo (QR e Point só pelo painel); um já pago responde 409 payment.charge_not_open. O histórico de get_task_balance com include_charges=true marca cada parte com part=true. O QR e o Point com valor são só do painel.
Avaliações após o serviço
get_feedback(kind, identifier) (bookings:read): booking, service, customer, resource; 0–100. get_feedback_settings (config:read).
O que o bot vende: bot_offer (config:read) devolve o que o bot oferece hoje no chat (tipos habilitados, serviços, produtos de cada modalidade de pedido, planos e o link «ver tudo ou contratar»). stages lista as etapas de fluxos que reduzem essa lista; com flow_id e stage juntos, devolve o que veria um cliente com a tarefa nessa etapa. list_services e search_products trazem bot_offered por item: desligado, o bot não o nomeia nem o vende. Link por item: create_service e update_service aceitam offer_url (clear_offer_url o remove) e save_product o recebe no produto; https, até 500 caracteres. Se existir, o bot o mostra junto do item; se não, usa o link do bot. bot_offer o devolve em cada serviço, produto e plano. search_products aceita stock (out, low, in), missing (photo, price, category; repetível), variant (tamanho ou cor) e sort (name, price_asc, price_desc, stock_asc, best_selling, recent); q busca também por SKU. O cursor vale só com o mesmo sort e os mesmos filtros.
Buscar na sua loja: get_store_search mostra a busca de produtos ao vivo na sua loja online (Nuvemshop, WooCommerce, Shopify, Make, n8n ou uma URL própria): o modelo, a URL de busca com {q}, o mapeamento de campos, o serviço de pedidos pelo chat em que entram os produtos, quantos resultados o bot mostra e se está ativa; das credenciais só diz os nomes. list_store_search_presets traz os modelos prontos. save_store_search a cria ou edita e disable_store_search a desliga: os dois mostram antes e depois sem gravar e só mudam com confirm=true. As credenciais vão em headers, ficam criptografadas e nunca são devolvidas. test_store_search faz a mesma busca que o bot e mostra os produtos com o preço. Todas pedem products:write.
Atendimento do bot: bot_tree (config:read) devolve a árvore de atendimento do bot: os ramos (serviços, produtos, assinaturas, fluxos próprios, perguntas, meus horários e falar com uma pessoa) com se estão pausados, se podem ser pausados e para qual tarefa e fluxo leva cada um. Pausar serviços, produtos ou assinaturas é o campo sells de «O que o bot vende». Os ramos vêm na ordem em que o bot os oferece, com o flow_id da raiz, sua saudação (greeting) e a ordem salva (order): update_flow nesse flow_id com order ou greeting os altera (config:write, a mesma permissão de «O que o bot vende»). Um ramo próprio pausado também pode ser ordenado e mantém seu lugar. A raiz não é desativada nem duplicada.
Percurso das conversas: bot_tree_funnel (config:read) diz, por ramo do atendimento do bot e nos últimos dias (days, 7 por padrão), quantas conversas criaram uma tarefa, foram respondidas, passaram para uma pessoa ou pararam, e em que passo; bot_conversation_path mostra por onde uma conversa passou e onde parou. Não incluem o que o cliente escreveu.
Seu site: get_site (config:read) mostra «Atendimento → Site»: modelo (booking, catalog ou showcase), seções opcionais marcadas (galeria, equipe e recursos, avaliações, planos), os textos da capa e «Quem somos», o subdomínio (negocio.fiuit.app) e se está publicado. update_site muda esses campos e publish_site / unpublish_site o ligam ou desligam (config:write); os três mostram antes e depois sem gravar e só mudam com confirm=true. O site nasce desligado. O que ele mostra do catálogo é o mesmo que o bot oferece (bot_offer), e as perguntas frequentes são as do bot. O subdomínio tem de 3 a 40 letras minúsculas, números e hífens, sem nomes reservados nem repetidos; mudá-lo em um site publicado desliga o link anterior (não há redirecionamento) e exige confirm_link_break: true dentro de changes; sem ele a API responde 409 e nada muda. Se a Fiuit revogar um site, ele não pode ser publicado de novo até ser restaurado. «Feito com Fiuit» aparece no rodapé do site: com um plano pago, sai com made_with_fiuit: false (can_hide_made_with_fiuit diz se o seu plano permite); no plano grátis a API responde 409 e ele continua visível.
Base dos documentos (FIU-774, FIU-795): uma só base por marca para orçamento, recibo e extrato de conta. get_quote_base (config:read) mostra «Configurações → Documentos»: as marcas (cabeçalho com logo e dados da empresa, rodapé e cabeçalho de página), os blocos fixos (termos e condições, garantia, confidencialidade) com os documentos em que cada um sai (document_types: quote, receipt, statement) e as variáveis disponíveis. Sem nada configurado devolve configured: false e uma única marca com id: null, a do projeto: não é preciso configurar nada. preview_quote_base (config:read, não salva nada) mostra como um envio do documento pedido a congelaria (document_type: quote por padrão, receipt ou statement; só saem os blocos dele), com valores de exemplo de cliente e orçamento. create_quote_brand e update_quote_brand (config:write) cadastram ou corrigem os dados de uma marca e sempre pedem confirm=true: use só dados que o negócio te der, nunca invente a razão social nem o documento. Os blocos fixos são textos legais que o negócio escreve no painel ou pela API; não há ferramenta para redigi-los, escolher em quais documentos saem, apagar marcas nem enviar o logo.
O Dono pode ativar avaliações após concluir uma tarefa: formulário configurável, link de uso único, marca da empresa e indicadores de satisfação com amostra mínima. Comentários seguem permissões de privacidade. Uma nota baixa entra em atenção e gera aviso por email e Telegram, conforme preferências e disponibilidade. Desligado por padrão; o envio depende do canal e de sua janela. A entrega pode repetir o mesmo link após falha do worker; a resposta continua única.
F3-143 inclui estado de admissão nas leituras de conversas da API. A Caixa de entrada continua excluída do MCP: bloquear/liberar contatos exige sessão Dono/Gerente no painel (contacts:moderate). Não há ferramenta externa de moderação nem desafio anti-bot nesta entrega inicial.
A política do Telegram é configurada no painel ou por propostas confirmadas do Wagy. WebChat pode exigir Turnstile ao abrir sessão. São superfícies públicas/painel, sem scopes de API key: MCP não abre sessões WebChat nem modera contatos.
A revisão com sinal eletrônico já aplicado não dispara consultas finais repetidas. As cobranças restantes usam tentativas limitadas; webhooks verificados continuam sendo processados. Uma criação ambígua usa espera exponencial até um dia entre consultas durante a janela de sete dias de buscas vazias bem-sucedidas; a liberação ocorre na próxima consulta, no máximo um dia depois de completar a janela. Erros, pagamentos observados ou perda de credenciais reiniciam a evidência vazia.
Turnos guiados, desfazer e recomeçar a entrevista inicial exigem sessão Dono e CSRF do painel; não são ferramentas MCP. A API pública de setup está pendente (F3-220).
confirm_booking aplica as validações atuais do core: uma pré-reserva pendente cujo serviço foi desativado retorna 409 service_inactive. Uma confirmação já gravada mantém seu replay. Turnos, desfazer e recomeçar a entrevista exigem sessão Dono e CSRF; continuam fora do MCP.
A revisão e união da identidade de clientes (F3-154) exige sessão Dono/Gerente com CSRF no painel. MCP não oferece união por contatos declarados; coincidências não verificam identidade. Códigos e união com recebimentos ainda estão pendentes.
As regras de reconfirmação e alerta por falta de resposta (F3-75) são configuradas pela API de automações e continuam excluídas do MCP. Só avisam após uma solicitação enviada sem resposta. Não há tool MCP para responder reconfirmações ou liberar horários por silêncio.
Importar produtos (F3-153, FIU-859): export_products_csv(template=false), preview_products_csv(csv) e confirm_products_import(import_id, confirm=false, actions) no toolset admin; escopo products:write, inclusive para exportar. A prévia não altera produtos. Confirmar exige confirm=true, é atômico e idempotente por ID (resultado por 7 dias); a prévia vence em 30 minutos e mudanças no catálogo/moeda exigem repetir. Máximo 1 MiB / 2000 linhas; UTF-8, valores com regra única (PYG/CLP inteiros; BRL «1,500» ambíguo). Wagy indica o painel para o arquivo; não confirma CSV no chat.
Configuração pelo Claude ou ChatGPT (FIU-525)
Guia para o dono: Configure a Fiuit com o Claude ou o ChatGPT.
- Prompts (
prompts/list), um por tarefa e idioma, sem argumentos:setup_from_scratch_{pt,es,en}(entrevista curta como a da Wagy: agenda, horário, o que vende, como cobra),setup_bot_and_knowledge_{pt,es,en}(bot e base de conhecimento) eimport_catalog_{pt,es,en}. São instruções fixas que citam ferramentas existentes; toda escrita continua com prévia econfirm=true. A auditoria de configuração (audit_setup) chega numa entrega separada. - Recursos:
fiuit://setup/{pt,es,en}/guide(boas práticas e ramos de exemplo, Markdown) e o modelofiuit://setup/{idioma}/examples/{chave}(serviços, fluxos, automações desligadas, perguntas e horário típico de um ramo; aplica-se comapply_examples). - Importar de arquivos (uma só importação):
preview_products_csvaceitacsv,file_base64,xlsx(Excel em base64) ourows(até 2000 linhas que o modelo leu de um Excel, PDF ou foto), detecta as colunas sozinha ecolumns{cabeçalho: coluna}as corrige (name,unit,price,category,sku,ean,stock,option1/value1…). Devolve as contagens de cada ação:update(atualizar dados),create(criar o que não achou),stock(quantidades, só se o arquivo as traz) earchive_missing(arquivar, nunca apagar, o que o arquivo não traz; vem desmarcada e lista o que arquiva);actionsescolhe as caixas. Um arquivo só com código e quantidade mexe só no estoque.undo_products_import(import_id, confirm)desfaz TUDO o que foi aplicado (dados, criações, estoque e arquivados) enquanto ninguém mexer (409products.import_undo_stale), até 7 dias. - Serviços em lote:
preview_services_import(mesmas fontes; colunasname,duration_min,price,team,full_day,bot_offered; só cria),confirm_services_importeundo_services_import, comconfig:write. A API monta a tabela e valida. preview_service_from_text(config:write): lê um texto livre («corte 30 min R$ 80 com lavagem opcional») e propõe nome, duração, preço e adicionais sugeridos. Devolve a mesma prévia depreview_services_import: nada é criado atéconfirm_services_import, e o preço é confirmado antes de salvar.- Origem: o MCP envia o nome do app (
clientInfoou User-Agent) emX-Wagend-Client-Name; a auditoria guarda comoclientjunto ao atormcp(«MCP · Claude»). Não dá permissões.
Operações do negócio (F4-45)
O servidor do repositório adiciona 76 ferramentas: clientes/endereços (customers), Mensagens (inbox),
finanças somente leitura (finance), transições de tarefa (tasks) e catálogo, horários, automações
e conhecimento JSON (admin). Os sete conjuntos ficam ativos por padrão.
tools/list publica o scope e os esquemas de path (IDs), query (filtros) e body (comando JSON).
Não envie URL ou projeto. Novas escritas mostram a prévia e uma chave; repita com confirm=true e
idempotency_key estável. A API valida permissões, requisitos e disponibilidade ao confirmar;
a prévia não garante sucesso.
| Área / exemplos | Scope base |
|---|---|
list_customers, get_customer, endereços, resumo e histórico | customers:read |
create_customer, update_customer, salvar/excluir endereço; excluir um cliente (preview_customer_deletion, delete_customer: sem histórico é apagado, com histórico fica arquivado) e restore_customer | customers:write |
Veículos do cliente (FIU-609): list_customer_assets, get_customer_asset / create_customer_asset (basta a placa ou o modelo), update_customer_asset, delete_customer_asset | customers:read / customers:write |
Adicionar dado com texto livre (FIU-962): add_customer_detail distribui «tel 11 95555-1234, tem um Fiat Uno ABC1D23» em contato, endereço, notas e bens | customers:write + customers:read |
Histórico de um carro (FIU-611): list_customer_asset_tasks; e assets (asset_id ou um carro novo com text: «Modelo ou placa») ao criar ou editar uma tarefa | customers:read / bookings:write |
Tipos de bem: list_customer_asset_types / ativar Veículos com create_customer_asset_type ({"preset": "vehicle"}) ou desativá-lo (active: false: os carros ficam só para leitura) | customers:read / config:write |
list_conversations, list_conversation_messages, contadores | messages:read |
send_conversation_message, modo, resolver, lida, intenção, abrir conversa e add_conversation_note (aviso do sistema, nunca enviado ao cliente) | messages:write |
move_work_item_stage, use_work_item_tool, remover horário, metadata e itens | bookings:write |
fill_stage_from_photo (FIU-672), propõe valores sem salvar | bookings:write |
«Dados do update_work_item_asset corrige o bem da tarefa (p. ex. a quilometragem) e, se for a mais recente do bem, o do contato | bookings:write |
| Histórico, comentários, anexos e localização da tarefa | bookings:read |
| Detalhe do produto / categorias e sugestões | products:read / products:write |
Vendas por produto (get_products_stats) / desempenho por pacote ou clube (get_prepaid_plans_stats); valores em dinheiro só com finance:analyze | bookings:read / prepaid:read |
| Horários, zonas, recursos, automações e conhecimento | config:read / config:write |
| Resumo, relatórios, dívida, contas, clientes e previsão financeiros | finance:analyze |
Números de recebimentos (get_finance_collections): bruto, devolvido, tarifa do Mercado Pago, comissão da Fiuit e líquido por método, serviço e dia ou semana, mais o estimado sem recebimento | finance:analyze |
| Disponibilidade/movimentos financeiros; caixa; configuração do caixa | payments:read; cash:read; cash:configure |
Clientes omitem nomes, contatos, documentos e endereços por padrão; outras vistas sensíveis omitem
texto livre e contatos. include_sensitive=true exige o scope de leitura anunciado, além do scope
base; habilita conteúdo de mensagens/comentários. Finanças preservam valores, avisos e estimativas da
API. Uma ação que cobra precisa também da permissão financeira do core: bookings:write não basta.
As exclusões caem de 134 para 58. Ainda não há equivalência completa com o painel: 26 rotas não
aceitam API key (escrita de comentários, resumos de conversa e outras; acompanhamento F4-47).
Continuam fora sessão/notificações pessoais, SSE, simulador, segredos/webhooks, transferências
binárias/CSV em massa e novas escritas de dinheiro. Consulte o catálogo com sua chave. Uma mensagem
pending não confirma entrega ao cliente.
Avisos ao cliente e histórico
Configure avisos por serviço para pedidos sem horário, atribuição, alterações e progresso. Começam desligados. Consulte tentativas enviadas, omitidas, adiadas ou com falha em Configuração, Atividade e na ficha do cliente. O histórico conserva 90 dias sem copiar mensagens ou contatos; enviado não confirma entrega. Wagy e MCP consultam os mesmos resultados.
list_customer_notice_deliveries, get_customer_notice_policies: config:read. update_customer_notice_policy: config:write, confirm=true.
get_notices_overview (config:read) devolve o índice «Avisos»: tudo o que o cliente recebe, ordenado a partir do horário, com o valor efetivo de cada aviso, por que está parado e onde se edita. Com config:write, set_notice_item_enabled liga ou desliga um aviso na sua fonte (regra, política por serviço, etapa ou fluxo) e set_all_notices_enabled é «desligar todos os avisos a clientes»; ambas pedem confirm=true. Vale o mais específico: o interruptor de cada aviso decide, e o geral vence tudo. As linhas de etapa publicam o fluxo e exigem também settings:write; sem essa permissão, toggleable=false e a escrita retorna 403.
PUT e revert preservam a regra de cobrança vigente do catálogo em todas as etapas completed. Salvar payment_requirement novamente repara versões divergentes; restaurar o histórico não altera a cobrança.
A revisão de uma reserva vencida com links substituídos compartilha a espera crescente de toda a reserva, até um dia. Cada consulta final lê todas as preferências ainda não resolvidas; um erro impede a liberação e reinicia a evidência vazia. Webhooks verificados continuam ativos.
O link vence 15 minutos antes da reserva; se o prazo for curto, a margem é metade do tempo disponível, com mínimo de 5 minutos. A página e o chat mostram o horário do link. A reserva mantém seu próprio prazo para verificar aprovações demoradas. Um estado local expired não bloqueia um pagamento verificado e aprovado a tempo: cobre o sinal se a reserva ainda estiver pendente; se já estiver encerrada ou o pagamento for tardio, conserva o dinheiro e pede revisão, sem reabrir nem devolver automaticamente. Se o link duraria menos de 5 minutos (com a margem mínima, menos de 10 minutos até o prazo da reserva), ele não é criado: fica o pagamento manual. Um pagamento tardio com a vaga já liberada fica separado «a devolver» (refund_due) na tarefa, na conta do cliente e no Financeiro, com um aviso à equipe por pagamento: não é descontado de outras dívidas do cliente até chegar a devolução do Mercado Pago ou a equipe (Dono/Gerente) passá-lo ao saldo com «Usar para outra dívida» (auditado). Com uma reclamação aberta no Mercado Pago (in_mediation) não é marcado «a devolver»: não devolva até que seja resolvida. Nada é automático.
As unidades reservadas também se perdem ao vencer: a tarefa volta ao preço normal e a equipe recebe um aviso. Uma falha de consumo retorna prepaid_consumption_failed e mantém a tarefa sem concluir. Tire o plano antes de ajustar o valor ou a cobrança; as notas internas podem ser editadas.
Se a janela expirar durante o envio, outro canal utilizável do mesmo cliente será tentado. A marca no-se-pudo-avisar tem um espaço reservado além das vinte etiquetas de negócio, sem substituí-las. Reconfirmações e pedidos de avaliação permanecem na conversa original e não mudam de canal.
Configurar o negócio por MCP e ajuda da Fiuit (FIU-397)
Tudo o que o onboarding monta também se configura por MCP, com as permissões da API key:
| Ferramenta | Scope | Faz |
|---|---|---|
duplicate_service | config:write (settings:write para copiar etapas) | Cria uma cópia pausada de um serviço |
delete_schedule | config:write | Baixa lógica: mantém as reservas futuras e as devolve |
delete_service, delete_resource, delete_resource_group | config:write | Sem mode pausa (reativa com update_* e active=true). mode=remove apaga se não tem histórico e arquiva se tem; archive arquiva; delete apaga ou falha com 409 catalog_item_has_history. Com tarefas futuras falha com 409 catalog_item_future_bookings e a lista delas |
delete_product | products:write | Igual, com remove por padrão |
set_product_photo, remove_product_photo | products:write | Define, substitui ou remove a foto do produto que o bot envia no chat: image_url (https pública; o Fiuit baixa sem seguir endereços privados, até 2 MiB) ou image_base64 (PNG, JPEG ou WebP). Sem confirm mostra produto, tipo e tamanho |
suggest_product_from_text | products:write | Lê um texto («tênis tamanho 42, R$ 150, estoque 10») e propõe nome, tamanho, preço, estoque, categoria, cor e material. Não salva nada: o preço é confirmado antes de salvar. |
suggest_product_from_photo | products:write | Lê a foto de um produto (url https pública, ou image em base64 com mime) e propõe nome, categoria, cor, material, uma descrição de vendedor e sinônimos; nunca o preço. Com product_id, só o que está vazio. Não salva nada: o aceito se salva com save_product e a foto com set_product_photo. Gasta energia de IA do plano |
list_product_variants, set_product_options, create_product_variant, update_product_variant, delete_product_variant | products:read / products:write | Tamanhos, cores e outras opções do produto (até 3) e suas variantes, cada uma com SKU, código de barras (EAN) e preço próprio opcional. available=true lista só as que podem ser vendidas. As escritas pedem confirm=true |
adjust_product_stock, list_stock_movements | products:write | Com «controlar estoque» ligado no produto (save_product, track_stock): define (qty) ou soma e subtrai (delta) as unidades de uma variante, nunca abaixo de zero, e lista os movimentos (venda, devolução, manual, importação) |
export_product_variants_csv | products:write | Planilha de variantes e estoque (uma linha por variante, por SKU, EAN ou produto e opções); volta a ser importada com preview_products_csv, a importação única de produtos, variantes e estoque (também o arquivo diário do seu sistema: CSV, Latin-1 e com ponto e vírgula) |
get_service_removal, get_resource_removal, get_resource_group_removal, get_product_removal | config:write / products:write | O que aconteceria ao excluir: se apaga ou arquiva e quais tarefas futuras tem |
restore_service, restore_resource, restore_resource_group, restore_product | config:write / products:write | Tira um item de «Arquivados»; volta pausado |
get_bot_settings, update_bot_settings | config:read / config:write | Personalidade do bot (nome, tom, saudação, o que vende, fotos de produtos), versionada |
create_prepaid_plan, update_prepaid_plan | prepaid:manage | Define pacotes e clube: preço, unidades, validade, cotas e serviços, e suas parcelas: vencimento (due_rule: signup, month_start, month_end ou fixed_day com due_day 1–28), dias de aviso (notice_days, 5 por padrão), first_fee_full (sem ela a parcela 1 é proporcional) e fluxo da adesão (flow_id). Um preço novo vale para a próxima parcela de cada assinatura ativa (sem aviso ao cliente; a resposta traz live_subscriptions). Vender continua sendo sell_prepaid_plan |
suggest_plan_from_text | prepaid:manage | Lê um texto («pacote 4 cortes R$ 280, vence em 60 dias») e propõe tipo, nome, preço, unidades, validade e serviços. Não salva nada: é dinheiro, é mostrado e com o OK se cria com create_prepaid_plan |
list_recommended_automations, install_recommended_automations, set_recommended_automation_active, activate_recommended_automations, undo_recommended_automations | config:read / config:write | Automações recomendadas pelo exemplo de negócio; são instaladas inativas e ativadas uma a uma |
get_automation_stage_options | config:read | Etapas e ações válidas para as regras por etapa |
preview_customer_notices | config:write | Prévia dos avisos ao cliente com dados de exemplo; não envia nem salva |
list_faq_suggestions, approve_faq_suggestion, dismiss_faq_suggestion | config:read / config:write | FAQ automático: as perguntas que dois ou mais clientes fizeram, sem dados pessoais e com uma resposta proposta (se houver de onde tirar). Aprovar (como está ou editada) a soma à base de conhecimento; descartar faz com que não volte. As duas pedem confirmação |
list_knowledge_sources, get_knowledge_source, list_knowledge_source_pages | config:read | Fontes web e listagens da base de conhecimento |
preview_knowledge_source, create_knowledge_source, update_knowledge_source, refresh_knowledge_source, delete_knowledge_source | config:write | Registram, pausam, atualizam ou apagam uma fonte (apagar também remove o que ela importou) |
list_live_queries, create_live_query, update_live_query, test_live_query, disable_live_query | config:write | Consultas HTTP ao vivo que o bot usa |
apply_business_template | settings:write | Aplica o modelo de ramo (barbearia, estética, clínica…): vocabulário, automações e fluxos inativos. Só num projeto novo e vazio; não se escolhe de novo |
apply_examples, undo_example | settings:write | Compõe de 1 a 3 exemplos por parte (vocabulário, fluxos, automações, catálogo) e os desfaz sem mexer no que o negócio mudou |
get_vocabulary, update_vocabulary | config:read / settings:write | Glossário do projeto (como se chamam as tarefas, os clientes, a equipe) |
export_project_template | config:read | A configuração do projeto como modelo (fluxos, catálogo, planos, ajuda, bot e automações), sem dados de clientes nem segredos |
get_bot_channel_policies, update_bot_channel_policy | config:read / config:write | Política do bot por canal: contato exigido, limite de respostas, encaminhamento e instrução do canal |
update_feedback_settings | settings:write | Configura as avaliações após o serviço (lidas com get_feedback_settings) |
search_help | qualquer key | Busca na ajuda da Fiuit: guias de uso, «O que acontece se…?» e políticas de produto vigentes, com o link do guia e do contato. Não lê dados do negócio |
As credenciais de fontes e consultas ao vivo não passam pelo MCP: são cadastradas no painel e a API nunca as devolve. Fica de fora só o que não faz sentido abrir: a sessão e o CSRF do painel, os streams, o simulador, os segredos de webhooks e canais, o sino pessoal, os downloads binários grandes (vem o link), a conversa guiada do onboarding (os resultados dela estão acima), revogar um link de avaliação e o cancelamento da assinatura.
Etiquetas de cada escrita. Toda ferramenta que escreve declara na descrição e em _meta["wagend/labels"] se avisa o cliente (notifies_customer), se movimenta dinheiro (moves_money) e se é reversível, com a ferramenta que a desfaz (inverse). O que chega ao cliente ou movimenta dinheiro sempre deve ter a confirmação explícita de uma pessoa.
Pausar e duplicar
Pausar deixa de oferecer o serviço para novos pedidos no bot, reserva pública, Wagy e MCP. As tarefas já agendadas continuam normalmente. Reativar volta a oferecê-lo. Pausar e desativar são a mesma ação.
No detalhe abra ⋯ → Duplicar ou Pausar. No desktop também há um menu na lista. Wagy propõe as duas ações e aguarda a confirmação do plano. MCP permite pausar com update_service(active=false, confirm=true); duplicar é duplicate_service (cópia pausada, com confirmação).
API: POST /v1/services/{id}/duplicate, Idempotency-Key, config:write; settings:write para copiar etapas.
Clube com pagamento pendente
list_prepaid_subscriptions lista as assinaturas do projeto com dívida e pausa (limit/offset); as assinaturas (membresías) trazem standing: em dia, em carência (grace, com os dias que faltam) ou bloqueada (blocked, não cobre até pagar e se libera sozinha ao pagar). Com unpaid=true, só as que estão sem pagamento (clube ou assinatura), com o nome do cliente e os meses em atraso (months_due), as bloqueadas primeiro e o clube no fim. A resposta traz unpaid_count, o total de pendentes do projeto, mesmo que haja mais que o limit. set_prepaid_benefits pausa um clube com pagamento pendente ou reativa benefícios com confirm=true, sem cobrar nem apagar a dívida. Ambas exigem prepaid:benefits. Pagar uma parcela não reativa: reative com set_prepaid_benefits.
Com a assinatura bloqueada, hold_slot e a criação de tarefas do assinante para os serviços dessa assinatura devolvem 409 membership_blocked (com plan): é preciso regularizar a mensalidade e ela é liberada sozinha ao pagar.
Se o seu projeto ficar «Aguardando pagamento» (o pagamento do plano da Fiuit não chegou e a carência venceu), todas as ferramentas devolvem 402 workspace_awaiting_payment, inclusive as de leitura, até o pagamento ser creditado.
Fluxos v2
Fluxos v2: validate_flow, create_flow e update_flow recebem flow com
format:2, stages e exits. A prévia retorna impact (total, até 100 mudanças, by_service e shared_with);
confirm=true confirma publicar/restaurar e mover tarefas abertas à primeira etapa
do mesmo estado base, sem executar avisos de entrada. A equipe vê todos os itens;
com visible_to cliente, o bot pede esses itens e aperta esses botões pelo chat onde a tarefa nasceu (origem
customer_chat no histórico). Uma etapa pode avançar sozinha: item timer com timer: {until: duration|task_start|task_end|no_reply, minutes, to}
(to é um botão da etapa sem itens obrigatórios; task_start e task_end vão sem minutes, seguem a hora de início ou de fim da tarefa e só existem em fluxos com horário) ou auto: payment_received em um botão (a tarefa totalmente paga pelo
Mercado Pago). A tarefa traz stage_deadline para a contagem regressiva e o avanço fica no histórico com origem auto. Se o avanço falhar, a tarefa traz auto_advance_failed até alguém movê-la. Um pagamento lançado à mão também dispara auto: payment_received. Além disso, auto: customer_replied (o cliente escreveu por qualquer canal depois de entrar na etapa) e auto: form_completed (preenchidos os itens obrigatórios que o cliente vê; a etapa precisa de pelo menos um), um por evento em cada etapa; o motivo fica em data.automatic.
move_work_item_stage e
use_work_item_tool exigem from_stage; envie também config_version lido na
tarefa. Um 409 stage_conflict exige atualizar a leitura. Os requisitos dos botões
usam item.<chave>; Encerrar sem concluir usa exit.reason e guarda motivo privado.
Restaurar v1 retorna 422 version_format_unsupported. V2 não inclui link público
do cliente, simulador, itens de pagamento/produtos ou condições. A cobrança manual
atual mantém as regras do serviço.
SLA e escalonamento (F3-595), só com until: duration: alert: {roles} ou alert: {resource: assignee} no lugar de to avisa a equipe ao vencer e a tarefa fica na etapa (um aviso por entrada; stage_deadline.alert é true); by_item: {item, minutes: {opção: min}} pega os minutos da resposta de um item de opções (sem resposta vale minutes) e from: created conta desde a criação. Num fluxo na fila, a etapa de entrada (held) aceita um temporizador duration para escalar o que ninguém pegou. Limite: 43200 minutos (30 dias corridos).
get_work_item_stage_history retorna ator, origem (source), classe (kind) e itens com rótulos históricos, incluindo movimentos por publicação. São os últimos 100 eventos, do mais recente ao mais antigo; a API aceita order=asc para apresentá-los cronologicamente. Fotos e assinaturas são referências privadas: obter o arquivo exige o download autorizado da tarefa. visible_to limita apenas o cliente; a equipe mantém o acesso autorizado às suas tarefas. Wagy pode explicar esse percurso por get_work_item com seu acesso vigente.
O item live_location («Localização em tempo real») não é preenchido por MCP nem por formulário: ao entrar nessa etapa o bot da equipe no Telegram pede ao responsável que compartilhe a localização em tempo real e o item é cumprido com a primeira posição. A última posição de uma tarefa é lida com GET /v1/bookings/{id}/location-events (mesmas permissões da tarefa); o mapa da equipe (GET /v1/tasks/live-locations) é só do painel.
Confira todos os serviços antes de mudar um fluxo
Ao alterar etapas compartilhadas, você vê quais outros serviços mudam e confirma o alcance atualizado.
Várias fotos: o item photo aceita max_photos (de 1 a 10; sem o campo, uma). Com mais de 1, move_work_item_stage recebe uma lista de ids de anexo para essa chave. Com o item obrigatório basta uma foto, e uma a mais é rejeitada. Cada foto conta na cota da tarefa (20 arquivos e 50 MB).
«Marcar sobre imagem»: o item sketch aceita sketch_background, o id devolvido por upload_stage_image (PNG, JPEG ou WebP, até 2 MiB). Sem esse campo, quem completa a etapa anexa uma imagem.
update_flow / revert_flow: Envie em shared_with_ack os IDs de validation.impact.shared_with revisados e aceitos. Em caso de 409 stage_shared_unconfirmed, valide novamente e peça nova confirmação; não repita automaticamente.
A lista inclui todos os serviços do fluxo, inclusive o editado.
get_work_item_journey (tasks, bookings:read) lê o percurso completo de uma tarefa com seus mapas históricos: eventos cronológicos e versões v2 referenciadas, incluindo etapas removidas. Mantém o acesso autorizado e não substitui versões ausentes pelo fluxo atual. Por padrão retorna chaves e datas; include_sensitive=true permite consultar rótulos, atores e respostas históricas com bookings:read.
configure_customer_habits propõe e salva quando um cliente está Para voltar, Atrasado, Em risco ou Perdido pelo próprio ritmo: due_window (0,15), late_multiple (1,5), at_risk_multiple (2), lost_multiple (3) e lost_cap_days (limite opcional); o que você não passa volta ao padrão e null volta tudo (escopo settings:write, confirm=true). Não há tela para isso no painel.
configure_pay_info propõe e salva os dados para pagar sem Mercado Pago (chave Pix, dados bancários), um texto por idioma: texts com pt, es ou en, até 600 caracteres cada; {} os apaga (scope settings:write, confirm=true). O bot os mostra quando a cobrança pelo chat é «perguntar» e o Mercado Pago não está pronto; «Já paguei» só avisa a equipe e nunca registra uma cobrança. A leitura desses dados é do painel e do Wagy: a chave de API não lê GET /v1/workspace; a resposta confirmada devolve o que foi salvo.
configure_chat_payment propõe e salva a cobrança pelo chat padrão do negócio (scope settings:write, confirm=true). update_service usa chat_payment para uma regra própria e inherit_chat_payment=true para voltar ao padrão (scope config:write, confirm=true). O servidor calcula o valor; essas ferramentas não criam links.
O cancelamento da assinatura (GET /v1/subscription, POST e DELETE /v1/subscription/cancellation) é só para a sessão do Dono no painel: uma API key recebe 403 e não há ferramenta MCP. O Wagy lê o estado e leva à tela, mas não cancela.
get_control_summary: A atenção coincide com Hoje: late respeita a tolerância do projeto; notice_undelivered só abertas; feedback_review inclui finalizadas; out_of_coverage só abertas e excluídas de sem zona. Os motivos podem se sobrepor: não some os contadores.
list_tasks(attention="notice_undelivered") usa a mesma seleção do contador do Controle. attention aceita os oito motivos de atenção, combina outros filtros antes de paginar e agrupar e não adiciona datas implícitas. Mantém o scope bookings:read.
Os fluxos por intenção podem declarar entry ao serem criados ou editados: quando usá-los, exemplos, exclusões, palavras-chave e se o cliente pode iniciá-los. O MCP permite visualizar essas alterações antes de confirmar. Há no máximo oito intenções ativas. O bot coleta os dados iniciais pelo chat e pede confirmação antes de criar a tarefa; a criação direta pelo MCP continua sendo uma ação explícita.
Com list_tasks(group_by="flow"), flow_capabilities retorna só outcomes e delivery: os status permitidos pelos fluxos ativos do projeto, mesmo sem tarefas, sem nomes nem IDs. Uma fila de atendimento no local não implica entregas.
Ao salvar características, o vocabulário é montado automaticamente se ainda não houver um salvo; suas edições são mantidas. Para mudar os nomes, use Configurações → Vocabulário ou peça ao Wagy e confirme a proposta. A edição do vocabulário exige sessão do painel; não é oferecida por MCP.
Proponha uma nova característica com Wagy
get_trait_catalog (config:read): pt/es/en. list_trait_proposals(cursor) (config:read). propose_trait(trait, confirm=false) / confirm=true (settings:write). Wagy prepara um nome e perguntas em três idiomas. Revise a proposta e confirme o envio: ela fica como etiqueta própria até a equipe aprovar, rejeitar ou unir a outra. Não muda como você atende seus clientes.
O que acontece se acabar a cota do canal de assistentes de IA?
A cota é por negócio: 600 chamadas de IA e 200 conversas novas por dia, e até 10 horários reservados temporariamente ao mesmo tempo. Pessoas diferentes compartilham essas cotas e também podem esgotá-las. Você recebe um aviso nas notificações de Atendimento → Canais; o canal volta quando a cota se renova ou os horários são liberados. Os outros canais continuam funcionando. Se o limite de IA for atingido durante uma resposta, o bot pede para esperar sem encaminhar a conversa por esse motivo.
Motivos de encerramento
get_flow → exits.close.reasons / exits.cancel.reasons: {key, label: {pt, es, en}}; update_flow → confirm=true. get_outcome_reasons(start, end, service_id?, resource_id?) → bookings:read.
Configure os motivos em Meu negócio → Etapas. Ao encerrar, escolha um ou Outro com uma explicação. Cancelar permite omitir. Em Resultados você vê a quantidade por fluxo, saída e motivo.
list_tasks(sales="hide") exclui todas as vendas rápidas de «+ Receita» (como Hoje e a agenda). sales="work" mantém as vendas com saldo junto ao trabalho normal (como Trabalho); sales="only" lista só vendas rápidas e sales="all" (padrão) inclui tudo. O filtro se aplica antes de paginar e contar; não muda permissões nem valores.
list_tasks(pay="unpaid"|"partial"|"paid") aplica o estado de pagamento a toda a seleção antes de contar e paginar, junto com os outros filtros. paid inclui pagamentos excedentes; sem cobrança ou estado desconhecido não corresponde. Exige payments:read_balance e mantém o alcance atribuído da equipe. O parâmetro anterior payment_status mantém seu filtro apenas na página.