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" }
}| Campo | Significado |
|---|---|
| avisos | Frases fixas da Pearfy sobre a resposta. Sempre presente, pode vir vazio. |
| paginacao | Só em listas. total aparece quando é barato calcular. |
| truncado | A lista foi cortada para caber na resposta; o cursor continua do primeiro item que ficou de fora. |
| parcial | A origem tem mais do que a ferramenta consegue somar (ex.: mais de 2.000 assinaturas). Refine o filtro. |
| periodo | A 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,tudooupersonalizadocomdeeate(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.
| Regra | Detalhe |
|---|---|
| Validade | 15 minutos a partir de cada página. |
| Preso à consulta | O 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ável | A primeira página fixa o instante da consulta: venda nova não empurra a lista enquanto você pagina. |
| Teto | 2.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.
| tipo | Quando aparece |
|---|---|
| validacao | Parâmetro recusado: período inválido, cursor vencido, campo fora do formato. |
| autenticacao | A pessoa saiu da Equipe ou o usuário não existe mais. Credencial ausente ou inválida é recusada antes, com HTTP 401. |
| escopo | A conexão ou a chave não tem a permissão da ferramenta. No login, a IA pode pedir de novo. |
| permissao | A sua permissão na Equipe não libera essa área. |
| nao_encontrado | O id não existe nesta conta. |
| ambiguo | O id curto casa com mais de um item: use o id completo. |
| conflito | O estado do item impede a ação (já reembolsada, já cancelada, item em execução). |
| limite | Teto atingido: limite do dia, prévias ou pedidos pendentes demais. |
| confirmacao_necessaria | Token ou código inválido, vencido ou de outros parâmetros. Peça uma prévia nova. |
| desligado_pela_conta | O dono desligou a IA, as alterações, as chaves ou os colaboradores em Controles. |
| conta_suspensa | Conta ou usuário bloqueado. |
| indisponivel | Ação pausada pela Pearfy ou que só pode ser feita pelo painel. |
| servidor | Falha interna. Pode tentar de novo em alguns segundos. |
Antes da ferramenta
| HTTP | Quando |
|---|---|
| 401 | Sem credencial ou credencial recusada. Vem com WWW-Authenticate apontando para os metadados de login. |
| 403 insufficient_scope | No login, a ferramenta precisa de mais permissão: o cliente reabre a tela da Pearfy. |
| 429 | Limite de chamadas por minuto. Respeite o Retry-After. |
| 413 | Corpo da requisição acima de 256 KB. |
| 400 | JSON inválido, lote com mais de 100 mensagens ou duas credenciais diferentes no mesmo pedido (credencial_ambigua). |
| 503 | Pearfy MCP pausado para manutenção. Respeite o Retry-After. |
Limites de uso
| Limite | Valor |
|---|---|
| Chamadas por conexão ou chave | 120 por minuto |
| Chamadas por conta | 300 por minuto |
| Alterações por conexão ou chave | 20 por minuto |
| Itens por página | até 50 (20 no ranking e nos webhooks) |
| Resposta | cerca 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.