Mostra a conexão atual: conta da Pearfy operada, papel na Equipe, permissões, forma de acesso (login ou chave), escopos da credencial, validade, limites, perfil e ambiente. Não altera nada.
Sem parâmetros.
Pearfy MCP
33 ferramentas tipadas: 21 consultas e 12 alterações. Cada uma faz uma coisa só, com parâmetros validados antes de tocar em qualquer dado. Esta lista sai do mesmo registro que o servidor usa.
A IA escolhe a ferramenta pela sua pergunta. Você não precisa saber os nomes: eles estão aqui para quem integra, audita ou quer entender o que cada conexão pode fazer.
| Tipo | Como roda |
|---|---|
| Consulta | Roda direto. Só lê, nunca altera nada. |
| Alteração | A 1ª chamada devolve uma prévia; a 2ª, com o token de confirmação dessa prévia, executa. Reenviar acesso é a exceção: roda direto, com limite diário. |
| Dinheiro | Reembolso pelo login: código de 6 dígitos enviado ao seu e-mail, com teto por pedido e por dia. Cancelamento de assinatura e dinheiro vindo de chave de IA: aprovação no painel. |
| Aprovação no painel | A 2ª chamada não executa: cria um pedido que fica pendente até alguém com permissão aprovar em Pearfy MCP › Aprovações. |
Mostra a conexão atual: conta da Pearfy operada, papel na Equipe, permissões, forma de acesso (login ou chave), escopos da credencial, validade, limites, perfil e ambiente. Não altera nada.
Sem parâmetros.
Totais de vendas da conta num período (hoje, ontem, 7d, 30d, mês atual, mês anterior ou datas): pedidos, aprovadas, reembolsos, chargebacks, faturamento bruto, líquido do produtor e ticket médio, por moeda e somado em R$. Agregado no banco, sem limite de pedidos. Opcionalmente compara com o período anterior.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| periodo | enum | opc. | Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.hojeontem7d30dmes_atualmes_anteriorpersonalizadotudopadrão "30d" |
| de | data | opc. | Início (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| ate | data | opc. | Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| comparar | booleano | opc. | Inclui o período anterior de mesmo tamanho, para comparação. padrão false |
Escopo vendas:ler
Produtos (ou ofertas) que mais venderam num período, por faturamento bruto ou por número de vendas aprovadas, com reembolsos, chargebacks e líquido de cada um. Uma linha por produto e moeda.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| periodo | enum | opc. | Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.hojeontem7d30dmes_atualmes_anteriorpersonalizadotudopadrão "30d" |
| de | data | opc. | Início (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| ate | data | opc. | Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| por | enum | opc. | Agrupa por produto ou por oferta.produtoofertapadrão "produto" |
| ordenar_por | enum | opc. | faturamentoaprovadaspadrão "faturamento" |
| limite | inteiro | opc. | 1 a 20 · padrão 10 |
Escopo vendas:ler
Vendas de um período agrupadas por país do comprador (código ISO, ex.: BR, US) ou por estado (UF). Mostra pedidos, aprovadas e faturamento de cada região. Região vazia = não informada.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| periodo | enum | opc. | Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.hojeontem7d30dmes_atualmes_anteriorpersonalizadotudopadrão "30d" |
| de | data | opc. | Início (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| ate | data | opc. | Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| nivel | enum | opc. | País do comprador ou estado (UF) do endereço de cobrança.paisestadopadrão "pais" |
Escopo vendas:ler
Taxa de aprovação por método de pagamento (Pix gerado × pago, cartão, boleto) num período e os principais motivos de recusa de cartão. Útil para diagnosticar queda de vendas.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| periodo | enum | opc. | Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.hojeontem7d30dmes_atualmes_anteriorpersonalizadotudopadrão "30d" |
| de | data | opc. | Início (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| ate | data | opc. | Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
Escopo vendas:ler
Vendas da conta, da mais recente para a mais antiga, num período (data da venda, horário de Brasília), com filtro opcional por status, método de pagamento, produto e oferta. Inclui vendas em que a conta é co-produtora ou afiliada. Cada venda traz id, datas, status, método, parcelas, valores, produto, oferta, país e o comprador mascarado. Paginada por cursor.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| periodo | enum | opc. | Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.hojeontem7d30dmes_atualmes_anteriorpersonalizadotudopadrão "30d" |
| de | data | opc. | Início (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| ate | data | opc. | Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| status | lista de enum | opc. | Filtra pelos status (vazio = todos).aprovadoaguardando_pagamentorecusadoexpiradocanceladoreembolsadochargeback |
| metodo | lista de enum | opc. | Filtra pelos métodos de pagamento (vazio = todos).pixboletocardapple_paygoogle_pay |
| produto_id | id | opc. | Só vendas deste produto (UUID). |
| oferta_id | id | opc. | Só vendas desta oferta (UUID). |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo vendas:ler
Uma venda da conta pelo id (UUID ou os 8 caracteres do painel): status, datas da linha do tempo (criada, paga, reembolsada, cancelada), método, parcelas, produto, oferta, país, comprador mascarado, UTMs da origem e a quebra dos valores (taxa da Pearfy, comissões, líquido e taxa de chargeback, quando houver). Id de venda de outra conta não é encontrado.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| venda_id | id | obrig. | Id da venda: UUID completo ou os 8 primeiros caracteres mostrados no painel. |
| papel | enum | opc. | Escolhe a linha quando a conta aparece em mais de um papel na mesma venda.produtorcoprodutorafiliado |
Escopo vendas:ler
Vendas da conta (como produtora) feitas por um comprador, pelo e-mail completo, com igualdade exata. Mostra as compras com status, valores e produto; o comprador aparece mascarado. Limite de 30 buscas por hora por conexão.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| texto | obrig. | E-mail completo do comprador. Comparação exata, sem diferenciar maiúsculas. até 254 caracteres | |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo vendas:ler
Vendas reembolsadas e/ou com chargeback da conta, num período pela data da venda (horário de Brasília), da mais recente para a mais antiga. Cada uma traz valores, produto, comprador mascarado, data do reembolso e a taxa de chargeback debitada, quando houver. Paginada por cursor.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| periodo | enum | opc. | Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.hojeontem7d30dmes_atualmes_anteriorpersonalizadotudopadrão "30d" |
| de | data | opc. | Início (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| ate | data | opc. | Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| tipo | enum | opc. | reembolsochargebackambospadrão "ambos" |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo vendas:ler
Reembolsa uma venda aprovada da conta pelo valor total. A 1ª chamada devolve só a prévia; por login, a confirmação é um código de 6 dígitos enviado ao e-mail da pessoa conectada. Por chave, acima de R$ 500 ou com mais de 7 dias, vira pedido de aprovação no painel. Remove o acesso do comprador e cancela a assinatura ligada.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| venda_id | id | obrig. | Id da venda: UUID completo ou os 8 primeiros caracteres mostrados no painel. |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo reembolsos
Saldo da carteira da conta em R$: disponível para saque, a liberar, reserva de segurança, total sacado e saldo devedor, se houver. Quando a conta vende fora do Brasil, traz também o saldo internacional em dólar, separado e sem somar com o R$. Só consulta; não pede saque.
Sem parâmetros.
Escopo financeiro:ler
Lista os saques da carteira em R$ da conta, do mais recente para o mais antigo: código, status (processando, pago, rejeitado, cancelado), valor pedido, tarifa, líquido e datas do pedido e do pagamento. Filtra por status e período. Não traz dados bancários e não pede saque.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| status | enum | opc. | processando (pedido ainda a caminho), pago, rejeitado ou cancelado. Sem status = todos.processandopagorejeitadocancelado |
| periodo | enum | opc. | Data do pedido, no horário de Brasília. Padrão "tudo" (desde o início da conta). "personalizado" usa de e ate.hojeontem7d30dmes_atualmes_anteriorpersonalizadotudopadrão "tudo" |
| de | data | opc. | Início (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| ate | data | opc. | Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo financeiro:ler
Fotografia atual das assinaturas da conta: ativas, inadimplentes (em atraso), canceladas, concluídas, renovações nos próximos 30 dias, MRR bruto e líquido estimado e valor em atraso, por moeda. Para o período escolhido (hoje, 7d, 30d, mês atual, mês anterior, datas ou tudo): novas, canceladas e churn. Com mais de 2.000 assinaturas, o resultado vem marcado como parcial.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| periodo | enum | opc. | Janela de datas no horário de Brasília. "personalizado" usa de e ate. "tudo" = desde o início da conta.hojeontem7d30dmes_atualmes_anteriorpersonalizadotudopadrão "30d" |
| de | data | opc. | Início (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
| ate | data | opc. | Fim inclusivo (AAAA-MM-DD), só com periodo=personalizado. AAAA-MM-DD |
Escopo assinaturas:ler
Assinaturas da conta, da mais nova para a mais antiga, com situação, produto, plano, valor e intervalo de cada cobrança, método, próxima cobrança, datas de início e cancelamento e o assinante (nome abreviado e e-mail mascarado). Filtros por situação e por produto; paginado por cursor.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| status | lista de enum | opc. | Filtra por situação: active (ativa), trial (em teste), overdue (em atraso), canceled (cancelada), completed (concluída). Vazio = todas.activetrialoverduecanceledcompleted |
| produto_id | id | opc. | Só as assinaturas deste produto (id completo). |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo assinaturas:ler
Uma assinatura da conta pelo id (completo ou os 8 primeiros caracteres): situação, produto, plano, valor e intervalo, método, próxima cobrança, assinante mascarado e o histórico de cobranças (status, valor e datas), com total pago por moeda.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| assinatura_id | id | obrig. | Id da assinatura: UUID completo ou os 8 primeiros caracteres (como no painel). |
Escopo assinaturas:ler
Pede o cancelamento imediato de uma assinatura da conta. Vira pedido de aprovação no painel em todos os casos (o cancelamento no fim do ciclo ainda não existe). Encerra as cobranças, anula a fatura pendente e avisa o assinante; não devolve valor.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| assinatura_id | id | obrig. | Id da assinatura: UUID completo ou os 8 primeiros caracteres (como no painel). |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo assinaturas:cancelar
Produtos da própria conta (sem os excluídos e sem coproduções ou afiliações), mais recentes primeiro: id, ID público do painel, nome, tipo, cobrança, formas de entrega, status do produtor, moderação, preço da oferta padrão e número de ofertas ativas. Filtro opcional por status. Paginado por cursor.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| status | enum | opc. | rascunho, publicado ou arquivado filtram o status do produtor (como o filtro do painel); em_analise, reprovado ou pausado filtram a moderação da Pearfy.rascunhopublicadoarquivadoem_analisereprovadopausado |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo produtos:ler
Um produto da própria conta: dados gerais, se vende agora, link principal de checkout, todas as ofertas (preço, moedas, pagamento único ou assinatura e intervalo, ativa, padrão, link), resumo dos cupons e as pendências para publicar, pela mesma regra do painel. Aceita o ID público do painel, o UUID ou os 8 primeiros caracteres dele.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| produto_id | id | obrig. | ID público do painel (6 caracteres), UUID ou os 8 primeiros caracteres do UUID. até 36 caracteres |
Escopo produtos:ler
Monta o link público de checkout de uma oferta ativa da própria conta, o mesmo que o painel mostra na aba Links, com utm_source, utm_medium, utm_campaign, utm_content e utm_term opcionais. Não grava nada nem cria link personalizado. Oferta desativada não tem link; produto que ainda não vende volta com aviso.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| oferta_id | id | obrig. | UUID da oferta ou os 8 primeiros caracteres (ver pearfy_detalhar_produto). |
| utm_source | texto | opc. | — |
| utm_medium | texto | opc. | — |
| utm_campaign | texto | opc. | — |
| utm_content | texto | opc. | — |
| utm_term | texto | opc. | — |
Escopo produtos:ler
Cria um produto em RASCUNHO na própria conta, com a oferta padrão no preço informado (em centavos de real), pagamento único ou assinatura, pela mesma sequência da API v1 (triagem de conteúdo incluída). Nome e descrição com e-mail, telefone, CPF/CNPJ ou link fora da Pearfy são recusados. A 1ª chamada devolve a prévia e o token; a criação só acontece na 2ª, com o token. chave_idempotencia evita duplicar em repetição.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| nome | texto | obrig. | Nome do produto (2 a 120 caracteres). Sem e-mail, telefone, CPF/CNPJ ou link fora da Pearfy. até 120 caracteres |
| descricao | texto | opc. | Descrição (até 2.000 caracteres), com as mesmas restrições do nome. até 2000 caracteres |
| tipo | enum | opc. | cursoebookmentoriasoftwareassinaturapadrão "curso" |
| preco_centavos | inteiro | obrig. | Preço da oferta padrão em centavos de real (ex.: 9700 = R$ 97,00). até 9999900 |
| cobranca | enum | opc. | assinatura = cobrança recorrente (o tipo "assinatura" também liga isto).unicoassinaturapadrão "unico" |
| intervalo | enum | opc. | Frequência da assinatura; padrão mensal. Ignorado em pagamento único.mensaltrimestralsemestralanual |
| chave_idempotencia | texto | opc. | Opcional. Repetir a criação com a mesma chave (e os mesmos parâmetros) em até 24 h devolve o mesmo produto, sem criar outro. até 64 caracteres |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo produtos:escrever
Cria uma oferta (preço ou plano) num produto da própria conta, em centavos de real, com pagamento único ou assinatura (intervalo e limite de cobranças opcionais). A oferta nasce DESATIVADA e não vira a padrão: entra no checkout só quando ativada no painel ou por pedido aprovado no painel. Até 10 ofertas ativas por produto. A 1ª chamada devolve a prévia e o token; a criação só acontece na 2ª, com o token.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| produto_id | id | obrig. | ID público do painel (6 caracteres), UUID ou os 8 primeiros caracteres do UUID. até 36 caracteres |
| preco_centavos | inteiro | obrig. | Preço em centavos de real (ex.: 4700 = R$ 47,00). até 9999900 |
| nome | texto | opc. | Nome da oferta (até 80 caracteres), sem contato nem link fora da Pearfy. até 80 caracteres |
| intervalo | enum | opc. | Frequência, se a oferta for assinatura. Vazio = segue o produto (pagamento único ou a frequência do produto de assinatura).mensaltrimestralsemestralanual |
| limite_cobrancas | inteiro | opc. | Total de cobranças da assinatura (2 a 120). Vazio = sem limite. Só com intervalo. 2 a 120 |
| metodos | lista de enum | opc. | Formas de pagamento; padrão pix, cartao e boleto.pixcartaoboleto |
| parcelas_max | inteiro | opc. | Parcelas máximas no cartão (1 a 12); padrão 12. 1 a 12 |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo produtos:escrever
Altera nome, preço ou situação (ativa/desativada) de uma oferta da própria conta. A oferta padrão e a única ativa não são desativadas. Assinaturas já ativas seguem com o valor contratado. Ativar, reduzir preço com desconto acumulado acima de 50% (com o maior cupom ativo) e mudar preço de assinatura com pedido aguardando pagamento passam por aprovação no painel. A 1ª chamada devolve a prévia e o token; a alteração só acontece na 2ª, com o token.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| oferta_id | id | obrig. | UUID da oferta ou os 8 primeiros caracteres (ver pearfy_detalhar_produto). |
| nome | texto | opc. | Nome novo da oferta (até 80 caracteres), sem contato nem link fora da Pearfy. até 80 caracteres |
| preco_centavos | inteiro | opc. | Preço novo em centavos, na moeda base da oferta. Assinaturas já ativas seguem com o valor contratado. até 9999900 |
| ativa | booleano | opc. | false = tira a oferta do checkout; true = pede a ativação (sempre com aprovação no painel). |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo produtos:escrever
Remove uma oferta da própria conta pela mesma trava da API v1: a oferta padrão e a única ativa não saem, e a oferta que já teve pedidos é desativada em vez de apagada (o histórico e as assinaturas ativas não mudam). A 1ª chamada devolve a prévia e o token; a remoção só acontece na 2ª, com o token.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| oferta_id | id | obrig. | UUID da oferta ou os 8 primeiros caracteres (ver pearfy_detalhar_produto). |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo produtos:escrever
Cupons de desconto dos produtos da própria conta, mais recentes primeiro: código, tipo (percentual ou valor fixo em R$), valor, usos e limite, validade, se está ligado, situação no checkout agora (válido, desativado, agendado, expirado ou esgotado) e o produto. Filtros opcionais por produto e por ligado/desligado. Cupom de produto excluído não aparece.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| produto_id | id | opc. | Só os cupons deste produto (ID público, UUID ou 8 primeiros caracteres). até 36 caracteres |
| ativo | booleano | opc. | true = só os ligados pelo produtor; false = só os desligados. |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo produtos:ler
Cria um cupom de desconto num produto da própria conta: percentual (1 a 90%) ou valor fixo em centavos de real. A 1ª chamada devolve só a prévia e um token; a criação acontece na 2ª chamada, com os mesmos parâmetros e o token. Nasce ativo, com até 100 usos e até 30 dias. Mais usos, mais dias, desconto do produto acima de 50% ou chamada por chave de IA viram pedido de aprovação no painel.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| produto_id | id | obrig. | Produto da conta: UUID ou os 8 primeiros caracteres do id. |
| codigo | texto | obrig. | Código do cupom (3 a 30: letras, números, - ou _). Fica em maiúsculas. |
| tipo | enum | obrig. | percentual (1 a 90) ou fixo (centavos de real).percentualfixo |
| valor | inteiro | obrig. | percentual: de 1 a 90. fixo: desconto em centavos de real (R$ 10,00 = 1000). até 9999900 |
| max_usos | inteiro | opc. | Usos no total. Padrão 100. Acima de 100 vira pedido de aprovação no painel. 1 a 1000000 · padrão 100 |
| validade_dias | inteiro | opc. | Dias de validade a partir de hoje (horário de Brasília). Padrão 30. Acima de 30 vira pedido de aprovação no painel. 1 a 365 · padrão 30 |
| aplicar_em_adicionais | booleano | opc. | true = o desconto vale também sobre os adicionais (order bumps). padrão false |
| chave_idempotencia | texto | opc. | Opcional (8 a 80 caracteres). A mesma chave em 24 h devolve o cupom já criado em vez de criar outro. |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo cupons:escrever
Liga ou desliga um cupom de um produto da própria conta, achado pelo id ou pelo código exato. A 1ª chamada devolve só a prévia e um token; a alteração acontece na 2ª chamada, com os mesmos parâmetros e o token. Desligar confirma no chat. Ligar segue a regra de criação: cupom sem limite ou acima de 100 usos ou 30 dias, desconto do produto acima de 50% ou chamada por chave de IA viram pedido de aprovação no painel. Validade, usos e valor não mudam por aqui.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| cupom | texto | obrig. | Cupom da conta: o id (UUID) ou o código exato (sem diferenciar maiúsculas). até 36 caracteres |
| produto_id | id | opc. | Produto do cupom (UUID ou 8 primeiros caracteres). Necessário quando o mesmo código existe em mais de um produto. |
| ativo | booleano | obrig. | true = liga o cupom; false = desliga. |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo cupons:escrever
Alunos matriculados nas áreas de membros da conta, dos mais recentes aos mais antigos: nome curto, e-mail mascarado, produto e curso, data de matrícula, validade, situação do acesso (ativo, expirado, revogado, reembolsado), último acesso e progresso nas aulas. Filtra por produto e por situação; paginado por cursor.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| produto_id | id | opc. | Produto (UUID ou os 8 primeiros caracteres) cuja área de membros será listada. Sem ele, todos os produtos da conta. |
| status | enum | opc. | ativo = com acesso agora; expirado = o prazo do acesso passou; revogado = acesso cortado; reembolsado = acesso retirado por reembolso.ativoexpiradorevogadoreembolsado |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo alunos:ler
Reenvia ao comprador de uma venda aprovada da conta o e-mail de acesso à área de membros da Pearfy (criar senha, se ainda não criou; senão, entrar). Executa direto, sem prévia. Só para produto com área de membros e acesso ativo. Limites: 3 por venda e 30 por conta por dia.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| venda_id | id | obrig. | Venda aprovada da conta (UUID ou os 8 primeiros caracteres), como em pearfy_listar_vendas. |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo alunos:escrever
Webhooks de saída da conta: nome, domínio de destino (só o host), eventos assinados, se está ativo, produto a que se limita e o resumo das entregas dos últimos 7 dias (sucesso, falha, pendente) com a última entrega e o último status HTTP. Não mostra o endereço completo, o token de assinatura nem o conteúdo enviado.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| limite | inteiro | opc. | Webhooks por página (1 a 20). 1 a 20 · padrão 10 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo webhooks:ler
Histórico de entregas de um webhook da conta, das mais recentes às mais antigas: data, evento, situação (sucesso, falha, pendente), status HTTP da resposta, número de tentativas e próxima tentativa. Não mostra o conteúdo enviado nem a resposta do servidor de destino. Filtra por situação; paginado por cursor.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| webhook_id | id | obrig. | Webhook da conta (UUID ou os 8 primeiros caracteres), como em pearfy_listar_webhooks. |
| status | enum | opc. | sucesso = resposta 2xx; falha = esgotou as tentativas; pendente = aguardando nova tentativa.sucessofalhapendente |
| limite | inteiro | opc. | Itens por página (1 a 50). 1 a 50 · padrão 25 |
| cursor | texto | opc. | O proximo_cursor da página anterior. Vale 15 minutos e só com os mesmos filtros. até 200 caracteres |
Escopo webhooks:ler
Cadastra um webhook de saída da conta para um endereço HTTPS público, com os eventos escolhidos. Em todos os casos depende de aprovação no painel da Pearfy: a 1ª chamada devolve a prévia e um token; a 2ª, com o token, cria o pedido de aprovação. O token de assinatura do webhook não é devolvido.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| url | texto | obrig. | Endereço HTTPS público que vai receber os eventos. até 2048 caracteres |
| eventos | lista de enum | opc. | Eventos enviados. Sem eles: compra_aprovada.boleto_geradopix_geradocompra_recusadacompra_aprovadacompra_reembolsadachargebacksubscription_canceledsubscription_latesubscription_renewed |
| nome | texto | opc. | Nome para reconhecer o webhook no painel (até 60 caracteres). até 60 caracteres |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo webhooks:escrever
Muda o nome, os eventos ou liga/desliga um webhook da conta. A 1ª chamada devolve a prévia e um token; a 2ª, com o token, aplica. Trocar o endereço, religar, ou desligar (ou tirar eventos de) um webhook que entregou com sucesso nos últimos 30 dias depende de aprovação no painel.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| webhook_id | id | obrig. | Webhook da conta (UUID ou os 8 primeiros caracteres), como em pearfy_listar_webhooks. |
| nome | texto | opc. | Nome novo (até 60 caracteres). até 60 caracteres |
| eventos | lista de enum | opc. | Lista NOVA e completa de eventos (substitui a atual).boleto_geradopix_geradocompra_recusadacompra_aprovadacompra_reembolsadachargebacksubscription_canceledsubscription_latesubscription_renewed |
| ativo | booleano | opc. | false desliga o webhook; true religa (religar depende de aprovação no painel). |
| url | texto | opc. | Endereço HTTPS novo. Trocar o endereço depende de aprovação no painel. até 2048 caracteres |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo webhooks:escrever
Desativa um webhook ativo da conta: a Pearfy para de enviar eventos ao destino, e o webhook fica desativado no painel, de onde pode ser religado ou apagado. A 1ª chamada devolve a prévia e um token; a 2ª, com o token, aplica. Webhook que entregou com sucesso nos últimos 30 dias depende de aprovação no painel. Até 2 por dia.
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| webhook_id | id | obrig. | Webhook da conta (UUID ou os 8 primeiros caracteres), como em pearfy_listar_webhooks. |
| confirmacao | texto | opc. | Vazio na 1ª chamada (devolve a prévia). Na 2ª: o token pfy_cf_ da prévia, ou o código de 6 dígitos que a pessoa recebeu por e-mail. até 80 caracteres |
| observacao | texto | opc. | Motivo em uma frase, só para o registro (aparece como citação). até 300 caracteres |
Escopo webhooks:escrever