Pearfy MCP

Respostas, erros e limites

Toda ferramenta responde no mesmo formato, com dados prontos para a conversa e erros que dizem o que fazer em seguida.

Formato da resposta

A resposta vem em structuredContent e, para clientes que só leem texto, em content[0].text: uma linha de resumo seguida do mesmo JSON. Falha sai com isError: true.

Sucesso
{
  "ok": true,
  "dados": { "…": "específico de cada ferramenta" },
  "avisos": [],
  "paginacao": { "por_pagina": 25, "tem_mais": true, "proximo_cursor": "c2.…", "total": 312, "limite_paginacao": false },
  "truncado": false,
  "parcial": false,
  "periodo": { "de": "2026-10-16T00:00:00-03:00", "ate": "2026-11-14T10:32:00-03:00" }
}
CampoSignificado
avisosFrases fixas da Pearfy sobre a resposta. Sempre presente, pode vir vazio.
paginacaoSó em listas. total aparece quando é barato calcular.
truncadoA lista foi cortada para caber na resposta; o cursor continua do primeiro item que ficou de fora.
parcialA origem tem mais do que a ferramenta consegue somar (ex.: mais de 2.000 assinaturas). Refine o filtro.
periodoA janela de datas usada, no horário de Brasília. Em "tudo", de vale "inicio".

Dinheiro, datas e ids

  • Dinheiro vem sempre como { "centavos": 19700, "moeda": "BRL", "formatado": "R$ 197,00" }. Moedas diferentes nunca são somadas: vendas internacionais aparecem em USD, e a soma em reais vem num campo próprio.
  • Datas em ISO 8601 no horário de Brasília (-03:00).
  • Período: hoje, ontem, 7d, 30d (padrão), mes_atual, mes_anterior, tudo ou personalizado com de e ate (AAAA-MM-DD, até 400 dias).
  • Ids: as ferramentas que recebem um item (venda, assinatura, oferta, cupom) aceitam o UUID completo ou os 8 primeiros caracteres que o painel mostra; as de produto aceitam também o código público de 6 caracteres. Filtros de produto e oferta nas listas aceitam só o UUID. Se um id curto casar com dois itens, a resposta é ambiguo.

Dados mascarados

  • Comprador, assinante e aluno aparecem como Maria S. e ma***@gmail.com.
  • Nenhuma ferramenta devolve CPF, telefone, endereço, IP, dados de cartão ou id do processador de pagamento.
  • Textos de terceiros (nome de produto, oferta, cupom, webhook) chegam limpos: sem caracteres invisíveis, sem formatação e com links trocados por (link omitido). É a defesa contra instruções escondidas nos seus próprios dados.

Paginação

Listas usam limite (padrão 25, máximo 50; no ranking de produtos e na lista de webhooks, 1 a 20, padrão 10) e cursor. Para a próxima página, repita a chamada com os mesmos filtros e cursor igual ao proximo_cursor recebido.

RegraDetalhe
Validade15 minutos a partir de cada página.
Preso à consultaO cursor é assinado e só vale para a mesma credencial, a mesma ferramenta e os mesmos filtros. O limite pode mudar entre páginas.
Lista estávelA primeira página fixa o instante da consulta: venda nova não empurra a lista enquanto você pagina.
Teto2.000 itens por consulta. No teto, limite_paginacao vem true: refine o período ou os filtros.

Erros

Erro
{
  "ok": false,
  "tipo": "conflito",
  "codigo": "estado_mudou",
  "mensagem": "O item mudou entre a prévia e a confirmação.",
  "proximo_passo": "Peça uma prévia nova (chame sem confirmacao).",
  "fatal": false,
  "tentar_em_segundos": null
}

fatal: true quer dizer que repetir a mesma chamada não resolve. proximo_passo é sempre um texto fixo da Pearfy.

tipoQuando aparece
validacaoParâmetro recusado: período inválido, cursor vencido, campo fora do formato.
autenticacaoA pessoa saiu da Equipe ou o usuário não existe mais. Credencial ausente ou inválida é recusada antes, com HTTP 401.
escopoA conexão ou a chave não tem a permissão da ferramenta. No login, a IA pode pedir de novo.
permissaoA sua permissão na Equipe não libera essa área.
nao_encontradoO id não existe nesta conta.
ambiguoO id curto casa com mais de um item: use o id completo.
conflitoO estado do item impede a ação (já reembolsada, já cancelada, item em execução).
limiteTeto atingido: limite do dia, prévias ou pedidos pendentes demais.
confirmacao_necessariaToken ou código inválido, vencido ou de outros parâmetros. Peça uma prévia nova.
desligado_pela_contaO dono desligou a IA, as alterações, as chaves ou os colaboradores em Controles.
conta_suspensaConta ou usuário bloqueado.
indisponivelAção pausada pela Pearfy ou que só pode ser feita pelo painel.
servidorFalha interna. Pode tentar de novo em alguns segundos.

Antes da ferramenta

HTTPQuando
401Sem credencial ou credencial recusada. Vem com WWW-Authenticate apontando para os metadados de login.
403 insufficient_scopeNo login, a ferramenta precisa de mais permissão: o cliente reabre a tela da Pearfy.
429Limite de chamadas por minuto. Respeite o Retry-After.
413Corpo da requisição acima de 256 KB.
400JSON inválido, lote com mais de 100 mensagens ou duas credenciais diferentes no mesmo pedido (credencial_ambigua).
503Pearfy MCP pausado para manutenção. Respeite o Retry-After.

Limites de uso

LimiteValor
Chamadas por conexão ou chave120 por minuto
Chamadas por conta300 por minuto
Alterações por conexão ou chave20 por minuto
Itens por páginaaté 50 (20 no ranking e nos webhooks)
Respostacerca de 20.000 caracteres de JSON; acima disso a lista é truncada, com aviso
A ferramenta pearfy_quem_sou devolve esses limites, a conta conectada e as permissões concedidas. É o primeiro passo quando algo é recusado. Limites diários de alterações em Alterações e segurança.