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ávelPara quê
WAGEND_API_URLURL da API (padrão https://api.fiuit.com)
MCP_TOOLSETSConjuntos 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_PORTOnde escuta (padrão 127.0.0.1:8700)
MCP_ALLOWED_HOSTSHosts 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
FerramentaO que faz
find_businessBusca 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_offerO que o bot oferece, com preços já formatados.
find_slotsHorários livres de um serviço.
quote_orderCota 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_assetsOs 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_contextO 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_bookingReserva o horário por alguns minutos e manda para a pessoa um código por WhatsApp (padrão), Telegram ou email.
confirm_bookingConfirma com o código que a pessoa recebeu. Sem o código, o horário é liberado sozinho.
talk_to_businessConversa 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_conversationEncerra a conversa antes de vencer, se a pessoa pedir: o que vier depois começa sem os dados dela.
search_knowledgeResponde perguntas sobre o seu negócio com o que diz a sua base de conhecimento.
handoffPassa a conversa para uma pessoa da sua equipe quando o cliente pede.
request_taskPede 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_bookingsMostra as reservas e pedidos abertos da pessoa, só depois que ela confirmou um código na conversa.
cancel_booking, reschedule_bookingPedem 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.

FerramentaScopeFaz
list_servicesconfig:readServiços com duração e preço
find_slotsslots:readHorá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_slotbookings:writePré-reserva de 10 minutos
confirm_bookingbookings:writeConfirma uma pré-reserva com os dados do cliente
cancel_bookingbookings:writeCancela um agendamento. Exige confirm=true: sem ele só mostra o agendamento e não cancela
reschedule_bookingbookings:writeMove um agendamento existente para outro horário
get_bookingbookings:readDetalhe de um agendamento

Administração (admin): para o Dono operar o negócio pelo seu assistente de IA.

FerramentaScopeFaz
list_resourcesconfig:readEquipe, salas, máquinas e equipes, com o ícone e a cor, se tiverem
list_todaybookings:readAgendamentos do dia e o que está sem terminar, de vários dias, e o atravessa
block_timeconfig:write e bookings:readFecha dias inteiros de um recurso (máx. 31). Não cancela agendamentos existentes: devolve-os para uma pessoa decidir
list_service_pausesconfig:readLista as pausas por datas de um serviço
pause_serviceconfig:writePausa 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_serviceconfig:writeReabre um serviço pausado em um intervalo de datas
create_service, update_serviceconfig:writeCria ou altera um serviço, com seu formulário de agendamento
update_scheduleconfig:writeAltera o horário semanal ou o fuso horário
list_booking_series, get_booking_seriesbookings:readHorários fixos (agendamentos que se repetem, «toda terça às 20:00») e suas datas: com tarefa, puladas ou com conflito
create_booking_seriesbookings:writeCria 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_seriesbookings:writeEdita 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_coverageconfig:readCobertura do negócio: zonas ativas e o que acontece com o que fica de fora (out_of_coverage)
set_coverageconfig:writeEscolhe 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_statsbookings:readAgendamentos, ocupação e faltas por recurso; por padrão só pessoas, com quadras ou lugares passe kind=all
get_control_summarybookings: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_versionconfig:readFluxos (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_flowsettings:writeValida sem gravar; devolve impact com as tarefas a mover e shared_with
simulate_flowsettings:writeSimulado 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_flowsettings:writeCopia 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_flowsettings:writeEdita 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_flowsettings: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_flowsettings:writeApaga um fluxo sem uso e sem tarefas, após a confirmação
create_flow, update_flowsettings:writeCriam 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_imagesettings:writeGuarda a imagem de fundo de «Marcar sobre imagem» e devolve o id, publicado em sketch_background com update_flow
revert_flowconfig:read + settings:writeCria outra versão a partir da escolhida; preserva o histórico
get_flow_examples, get_base_states, get_flow_message_catalogconfig:readExemplos 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_usagebookings:readQuanto 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_traitsconfig:read / settings:writeCaracterí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_performancebookings: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.

FerramentaScopeFaz
list_tasksbookings: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_taskbookings:writeCria 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_taskbookings:writeDá horário a uma tarefa sem horário, ou muda o que ela tem; a API valida a disponibilidade
assign_taskbookings:writeAtribui pessoas ou recursos a uma tarefa
list_task_linesbookings:readItens da tarefa, seus dois blocos (serviços e produtos) e a margem (só com permissão de custos)
add_task_linebookings:writeSoma 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_linebookings:writeCorrige 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_linebookings:writeTira um item e reduz o valor a cobrar (nunca abaixo do já cobrado); exige confirm=true
list_task_checklistbookings:readChecklist da tarefa: os pontos a fazer, quais estão marcados e quem os marcou. Interno: o cliente não vê
add_task_checklist_itembookings:writeSoma 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_itembookings:writeMarca ou desmarca um ponto (done) ou muda o texto (name); expected_version evita sobrescrever outra pessoa
remove_task_checklist_itembookings:writeApaga um ponto do checklist; exige confirm=true
preview_task_discountpayments:adjustMostra como fica o total com um desconto, sem salvar nada
apply_task_discountpayments:adjustAplica ou altera o desconto da tarefa, em valor ou porcentagem (value em pontos-base); o técnico até 10 %; exige confirm=true
remove_task_discountpayments:adjustTira o desconto e o total volta à lista; exige confirm=true
preview_plan_discountprepaid:sellMostra como ficam as parcelas com um preço especial, de um plano a vender ou vendido, sem salvar nada
apply_plan_discountprepaid:sellPreço especial de um plano vendido, a partir da próxima parcela; só cobrança manual; exige confirm=true
remove_plan_discountprepaid:sellTira o preço especial: as parcelas seguintes voltam ao preço do plano; exige confirm=true
accept_work_item_offerbookings:writeAceita 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.

FerramentaScopeFaz
record_paymentpayments:recordRegistra 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_paymentpayments:voidAnula uma cobrança, com motivo obrigatório
expense_categoriesexpenses:readAs 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_listexpenses:readDespesas 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_recordexpenses:recordLanç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_voidexpenses:voidAnula uma despesa com motivo; uma despesa nunca é apagada. Exige confirm=true
income_recordpayments:recordRegistra 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_voidpayments:voidAnula 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_tagsexpenses:readAs 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_renameexpenses:recordRenomeia uma etiqueta; se outra já tem esse nome, junte-as com expense_tag_merge. Exige confirm=true
expense_tag_mergeexpenses:recordJunta 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_deleteexpenses:recordApaga uma etiqueta e a tira das despesas; as despesas não mudam. Exige confirm=true
expense_pendingexpenses:approveQuantas despesas lançadas pela equipe aguardam aprovação e quanto somam (sem as de teste)
expense_historyexpenses:readHistórico de uma despesa: quem, quando e o que mudou (antes e depois). Não há fechamento do mês
expense_getexpenses:readUma despesa: valor, categoria, data, status (aprovada, pendente, recusada ou anulada), comprovante e revisão. É o detalhe de uma despesa em Movimentações
expense_approveexpenses:approveAprova uma despesa pendente da equipe: a partir de agora soma. Ninguém aprova o que lançou. Exige confirm=true
expense_rejectexpenses:approveRecusa uma despesa pendente com motivo; fica recusada e não soma. Exige confirm=true
recurring_expense_listexpenses:readDespesas que se repetem (aluguel, salários fixos), com a próxima data e se estão ativas, pausadas ou encerradas
recurring_expense_createexpenses:recordCria 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_updateexpenses:recordMuda o valor ou o dia, pausa ou retoma, ou encerra, daqui em diante. Exige confirm=true
recurring_expense_skipexpenses:recordPula a próxima data sem lançar a despesa. Exige confirm=true
apply_refund_due_to_accountpayments: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_paymentpayments:refundDevolve 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_refundspayments:refundDevoluçõ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_getpayments:fiscalMarcador fiscal de uma cobrança e notas do emissor do negócio, se houver. A Fiuit nunca emite notas. Só Dono/Gerente
charge_fiscal_markpayments:fiscalMarca 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_issuepayments:fiscalPede 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_balancepayments:read_balanceSaldo de uma tarefa e, se quiser, seu histórico de cobranças
get_customer_accountcustomer_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_commissionscommissions:readComissõ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_settlementscommissions:readFechamentos 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_commissionscommissions: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_overviewfinance:analyzeResumo 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_resultfinance:analyzeResultado 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_linesfinance:analyzeDo 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_yearfinance:analyzeA 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_csvfinance:analyze e finance:exportExporta 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_packagefinance:analyze e finance:exportPede 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_projects lista todos (id, nome, slug, papel e permissões em cada um) e todas as ferramentas aceitam um project opcional com esse id ou slug, que o MCP envia no cabeçalho X-Wagend-Project. Com um só projeto não é preciso. Com vários e sem project, a ferramenta responde 400 project_required com 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_projects devolve o único projeto dela.
  • A lista de ferramentas é recortada. Só aparecem as que o token pode usar. get_task_balance e list_tasks com include_balance=true pedem payments:read_balance (permissão «Ver dinheiro»): se não estiver, a ferramenta não aparece ou responde 403 insufficient_scope. Para incluí-la é preciso conectar de novo marcando «Ver dinheiro» (só o dono concede). Os metadados de /.well-known/oauth-protected-resource publicam scopes_supported para 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 (409 order_below_paid).
  • Cobranças em dinheiro: record_payment com method: "cash" e a permissão payments: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_zone precisa de coordenadas (lat e lng), bairro, cidade ou CEP; com um endereço em texto livre sozinho devolve zone: null. Com coordenadas vence a área desenhada, e a zona de um endereço salvo do cliente usa essa mesma regra.
  • Clientes: list_customers sem include_sensitive=true devolve só id e locale; para escolher um cliente pelo nome é preciso include_sensitive=true (e customers:read).
  • Hábitos do cliente: get_customer_summary traz habits (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_proposal para montar o horário fixo com create_booking_series. list_customers filtra por habit (um estado: on_track, due, late, at_risk, lost; ou fixed_candidate); «quem eu perdi este mês?» é habit=lost com lost_since no primeiro dia do mês.
  • Linha do tempo: customer.updated e booking.updated trazem fields ou changed com 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.

FerramentaScopeFaz
partner_todaypartner:readA próxima ação, o progresso da carteira e os alertas
partner_clientspartner:readSeus clientes com plano, último uso, contagens e semáforo; ordem, cursor e filtro rápido quick
partner_client_detailpartner:readUm cliente e seus marcos. Um projeto fora da sua carteira dá 404 client_not_found
partner_activitypartner:readMarcos 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

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) e import_catalog_{pt,es,en}. São instruções fixas que citam ferramentas existentes; toda escrita continua com prévia e confirm=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 modelo fiuit://setup/{idioma}/examples/{chave} (serviços, fluxos, automações desligadas, perguntas e horário típico de um ramo; aplica-se com apply_examples).
  • Importar de arquivos (uma só importação): preview_products_csv aceita csv, file_base64, xlsx (Excel em base64) ou rows (até 2000 linhas que o modelo leu de um Excel, PDF ou foto), detecta as colunas sozinha e columns {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) e archive_missing (arquivar, nunca apagar, o que o arquivo não traz; vem desmarcada e lista o que arquiva); actions escolhe 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 (409 products.import_undo_stale), até 7 dias.
  • Serviços em lote: preview_services_import (mesmas fontes; colunas name, duration_min, price, team, full_day, bot_offered; só cria), confirm_services_import e undo_services_import, com config: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 de preview_services_import: nada é criado até confirm_services_import, e o preço é confirmado antes de salvar.
  • Origem: o MCP envia o nome do app (clientInfo ou User-Agent) em X-Wagend-Client-Name; a auditoria guarda como client junto ao ator mcp («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 / exemplosScope base
list_customers, get_customer, endereços, resumo e históricocustomers: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_customercustomers: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_assetcustomers: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 benscustomers: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 tarefacustomers: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, contadoresmessages: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 itensbookings:write
fill_stage_from_photo (FIU-672), propõe valores sem salvarbookings:write
«Dados do » da etapa (FIU-612): update_work_item_asset corrige o bem da tarefa (p. ex. a quilometragem) e, se for a mais recente do bem, o do contatobookings:write
Histórico, comentários, anexos e localização da tarefabookings:read
Detalhe do produto / categorias e sugestõesproducts:read / products:write
Vendas por produto (get_products_stats) / desempenho por pacote ou clube (get_prepaid_plans_stats); valores em dinheiro só com finance:analyzebookings:read / prepaid:read
Horários, zonas, recursos, automações e conhecimentoconfig:read / config:write
Resumo, relatórios, dívida, contas, clientes e previsão financeirosfinance: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 recebimentofinance:analyze
Disponibilidade/movimentos financeiros; caixa; configuração do caixapayments: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:

FerramentaScopeFaz
duplicate_serviceconfig:write (settings:write para copiar etapas)Cria uma cópia pausada de um serviço
delete_scheduleconfig:writeBaixa lógica: mantém as reservas futuras e as devolve
delete_service, delete_resource, delete_resource_groupconfig:writeSem 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_productproducts:writeIgual, com remove por padrão
set_product_photo, remove_product_photoproducts:writeDefine, 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_textproducts:writeLê 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_photoproducts:writeLê 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_variantproducts:read / products:writeTamanhos, 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_movementsproducts:writeCom «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_csvproducts:writePlanilha 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_removalconfig:write / products:writeO que aconteceria ao excluir: se apaga ou arquiva e quais tarefas futuras tem
restore_service, restore_resource, restore_resource_group, restore_productconfig:write / products:writeTira um item de «Arquivados»; volta pausado
get_bot_settings, update_bot_settingsconfig:read / config:writePersonalidade do bot (nome, tom, saudação, o que vende, fotos de produtos), versionada
create_prepaid_plan, update_prepaid_planprepaid:manageDefine 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_textprepaid:manageLê 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_automationsconfig:read / config:writeAutomações recomendadas pelo exemplo de negócio; são instaladas inativas e ativadas uma a uma
get_automation_stage_optionsconfig:readEtapas e ações válidas para as regras por etapa
preview_customer_noticesconfig:writePrévia dos avisos ao cliente com dados de exemplo; não envia nem salva
list_faq_suggestions, approve_faq_suggestion, dismiss_faq_suggestionconfig:read / config:writeFAQ 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_pagesconfig:readFontes web e listagens da base de conhecimento
preview_knowledge_source, create_knowledge_source, update_knowledge_source, refresh_knowledge_source, delete_knowledge_sourceconfig:writeRegistram, 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_queryconfig:writeConsultas HTTP ao vivo que o bot usa
apply_business_templatesettings:writeAplica 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_examplesettings:writeCompõ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_vocabularyconfig:read / settings:writeGlossário do projeto (como se chamam as tarefas, os clientes, a equipe)
export_project_templateconfig:readA 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_policyconfig:read / config:writePolítica do bot por canal: contato exigido, limite de respostas, encaminhamento e instrução do canal
update_feedback_settingssettings:writeConfigura as avaliações após o serviço (lidas com get_feedback_settings)
search_helpqualquer keyBusca 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.