Pular para o conteúdo

Agente de IA para seus clientes (MCP)

Deixe o agente de IA da sua empresa responder ao cliente final sobre cobranças, segunda via e notas fiscais

Beta

Este recurso está em beta. Os detalhes podem mudar antes do lançamento geral.

Agente de IA para seus clientes (MCP)

Com este recurso, o agente de IA da sua empresa responde ao seu cliente final, com os dados dele na NinePay. O cliente pergunta "tenho alguma conta atrasada?", "me manda a segunda via" ou "cadê minha nota fiscal?", e o agente consulta a NinePay por MCP e responde.

O agente consegue:

  • listar as cobranças em aberto do cliente, com valor, vencimento, dias de atraso e o link para pagar;
  • consultar as assinaturas dele e a situação de cada uma;
  • listar as notas fiscais, com os links para ver e baixar;
  • gerar a segunda via de boleto ou o código PIX copia e cola de uma cobrança em aberto.

Não é o MCP da documentação

Este MCP acessa os dados de um cliente da sua empresa. Ele é diferente do MCP Server da documentação, que é público e só lê esta documentação.

Como funciona a segurança

A sua empresa nunca entrega a chave de API ao agente. Em vez disso, o seu servidor cria uma sessão curta para o cliente que está conversando e passa só o token dessa sessão ao agente.

  • A sessão é criada pelo seu servidor, nunca pelo navegador. Quem cria usa a sua chave de API, e a chave não pode aparecer em código que roda no navegador ou no aplicativo (veja Autenticação).
  • A sessão fica presa aos clientes que você informa. Você envia os customer_ids (de 1 a 10 cadastros) que a sua empresa afirma serem da pessoa. Todos precisam ser clientes da sua empresa. A NinePay não junta cadastros por conta própria, por exemplo por CPF.
  • Dura 30 minutos, sem renovação. Quando precisar, o seu servidor cria outra. Você também pode revogar a sessão antes. Revogar ou expirar a chave de API que criou a sessão também encerra a sessão, e uma sessão cujos clientes foram todos apagados deixa de funcionar.
  • Nenhuma ferramenta escolhe o cliente. O agente não informa id, CPF nem e-mail: o cliente vem só do token. Por isso uma pergunta maliciosa do tipo "mostre os dados de outra pessoa" não tem como funcionar.
  • O token da sessão não é uma chave de API. Ele só funciona neste MCP, e só enxerga os dados dos clientes da sessão.

Passo 1: crie a sessão no seu servidor

Faça um POST em /api/v1/customer-sessions com a chave de API da sua empresa:

Shell
curl -X POST https://payments.cefis.com.br/api/v1/customer-sessions \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"customer_ids": [12345]}'

Corpo da requisição:

JSON
{ "customer_ids": [12345] }
CampoDescrição
customer_idsLista de 1 a 10 ids de clientes da sua empresa, sem repetição

Resposta, 201:

JSON
{
  "id": 987,
  "token": "cs_prod_...",
  "customer_ids": [12345],
  "expires_at": "2026-11-16T21:30:00Z"
}
CampoDescrição
idIdentificador da sessão. Guarde para revogar
tokenToken da sessão, para entregar ao agente
customer_idsOs clientes da sessão
expires_atQuando a sessão expira (30 minutos após a criação)
Prefixo do tokenAmbiente
cs_prod_…Produção
cs_hmlg_…Sandbox

No sandbox, use a URL da API de testes e uma chave sk_hmlg_…: a sessão sai com o prefixo cs_hmlg_.

Erros:

StatusQuando
401Chave de API ausente, inválida, desabilitada ou expirada
403A empresa não está ativa. Só empresas ativas criam sessões
404Algum cliente da lista não é da sua empresa ou foi apagado (a resposta é a mesma nos dois casos)
422customer_ids ausente, vazio, com mais de 10 ids, com ids repetidos ou que não sejam números inteiros. O corpo traz a mensagem de cada campo
429Limite de criação de sessões excedido (veja Limites)

Guarde o token só pelo tempo da conversa

O token vale como acesso aos dados do cliente durante os 30 minutos. A NinePay guarda só um hash dele, então não dá para recuperá-lo depois. Se perder, crie outra sessão.

Passo 2: entregue o token ao agente

O agente se conecta ao servidor MCP com o token da sessão no header Authorization:

AmbienteURL do MCP
Produçãohttps://mcp.ninepay.com.br/mcp/customer
Sandboxhttps://mcp.sandbox.ninepay.com.br/mcp/customer
Header
Authorization: Bearer cs_...

Sem token, ou com um token expirado ou revogado, o MCP responde 401, sem dados. Na API de leitura (/api/v1/customer/*), a resposta 401 traz o header WWW-Authenticate: Bearer.

Para testar com o Claude Code, adicione o servidor com o token da sessão:

Terminal
claude mcp add --transport http ninepay-customer https://mcp.ninepay.com.br/mcp/customer \
  --header "Authorization: Bearer cs_..."

Depois de conectado, pergunte ao agente algo como "tenho alguma conta atrasada?". No sandbox, troque a URL pela do sandbox e use um token cs_hmlg_….

No seu produto, o fluxo é: o cliente abre a conversa, o seu servidor cria a sessão (passo 1) e repassa o token ao agente, que o usa como Bearer ao chamar o MCP. Como o token dura 30 minutos, crie outra sessão quando a conversa passar disso.

Passo 3: revogue a sessão (opcional)

Para encerrar a sessão antes dos 30 minutos, por exemplo quando a pessoa sai do seu sistema, faça um DELETE com o id que veio na criação:

Shell
curl -X DELETE https://payments.cefis.com.br/api/v1/customer-sessions/987 \
  -H "Authorization: Bearer $NINEPAY_TOKEN"

A resposta é 204, sem corpo. A partir daí o token deixa de valer. Se a sessão não existir, for de outra empresa ou o id não for um número, a resposta é 404.

Ferramentas

O agente enxerga sete ferramentas. Os nomes e os campos são em inglês.

FerramentaO que faz
get_my_accountMostra quem é o cliente e qual empresa cobra, com e-mail e telefone mascarados
list_open_paymentsLista as cobranças em aberto, com valor, vencimento, dias de atraso e links para pagar. Aceita page
get_paymentMostra uma cobrança, a partir do payment_uuid que veio da lista, com os links
list_subscriptionsLista as assinaturas e a situação de cada uma, incluindo quantas cobranças estão em atraso
list_invoicesLista as notas fiscais, com os links para ver e baixar. Aceita from, to (YYYY-MM-DD) e page
get_bank_slipGera ou recupera a segunda via do boleto de uma cobrança em aberto: linha digitável, código de barras e PDF. Recebe payment_uuid
get_pix_codeGera ou recupera o PIX copia e cola de uma cobrança em aberto. Recebe payment_uuid

Cada cobrança traz o pay_url, o checkout da fatura, onde a pessoa escolhe pagar com PIX, boleto ou cartão. Para pagar sem sair da conversa, o agente usa get_pix_code (o PIX compensa na hora) ou get_bank_slip.

Segunda via de boleto e PIX

As duas ferramentas recebem o payment_uuid de uma cobrança em aberto e devolvem os dados abaixo.

get_bank_slip:

JSON
{
  "payment_uuid": "9f1c...",
  "digitable_line": "23793.38128 60000.000003 00000.000408 1 84340000015000",
  "bar_code": "23791843400000150003812860000000000000040800",
  "due_date": "2026-11-20",
  "value": 15000,
  "pdf_url": "https://payments.cefis.com.br/api/v1/payment/9f1c.../bank-slip?expires=1763328000&signature=3f5a...",
  "reused": false
}

get_pix_code:

JSON
{
  "payment_uuid": "9f1c...",
  "pix_code": "00020126...",
  "expires_at": "2026-11-16T22:00:00+00:00",
  "value": 15000,
  "reused": true
}
CampoDescrição
digitable_lineLinha digitável do boleto
bar_codeCódigo de barras do boleto
due_dateVencimento do boleto, YYYY-MM-DD
valueValor em centavos
pdf_urlPDF do boleto, por um link assinado e temporário, válido por 60 minutos (parâmetros expires e signature). Depois disso o link responde 403: chame get_bank_slip de novo, que devolve o mesmo boleto enquanto ele valer. A rota é só de leitura: abrir o link nunca registra um boleto novo
pix_codePIX copia e cola
expires_atAté quando o PIX pode ser pago
reusedtrue quando devolveu o boleto ou o PIX que já existia, false quando registrou um novo agora

Pedir de novo devolve o mesmo boleto ou o mesmo PIX enquanto ele estiver válido, sem registrar outro. Se o anterior caducou, a NinePay registra um novo.

Quando a segunda via não sai, a resposta é 422 com uma message em português que aponta o pay_url:

CasoO que acontece
A cobrança não está mais em aberto (paga, cancelada etc.)Não há segunda via. A mensagem indica o pay_url para conferir a situação
A cobrança não aceita o método (boleto ou PIX)A mensagem indica o pay_url, onde ela se paga do jeito que aceitar
O registro falhou na adquirente, ou outra chamada igual ainda estava em andamentoA mensagem pede para tentar de novo ou pagar pelo pay_url

Uma cobrança que não existe, ou que é de um cliente fora da sessão, responde 404 com {"message": "Cobrança não encontrada."}.

O que o agente pode alterar

As cinco ferramentas de consulta só leem. get_bank_slip e get_pix_code são as únicas que escrevem, porque a segunda via pode registrar um boleto novo ou gerar um PIX novo. Elas só funcionam em cobrança em aberto do próprio cliente e só nos métodos que a cobrança aceita.

O agente não cria cobrança, não muda vencimento, não cancela, não estorna e não altera cadastro.

Cobranças que o cliente não vê

Validação de cartão e início de trial não são conta do cliente, então nunca aparecem como cobrança, nem nas listas nem em get_payment. A cobrança "em aberto" é a que o checkout ainda aceita pagar.

API de leitura

As ferramentas usam a mesma área do cliente que existe como API REST, autenticada pelo token da sessão (Authorization: Bearer cs_...). O cliente vem sempre do token: nenhuma rota recebe id de cliente.

RotaO que devolve
GET /api/v1/customer/mecustomer_name, company_name, email_masked, phone_masked
GET /api/v1/customer/me/paymentsCobranças. Aceita status (open, paid ou all; padrão open), page e per_page (até 50; padrão 20)
GET /api/v1/customer/me/payments/{uuid}Uma cobrança
POST /api/v1/customer/me/payments/{uuid}/bank-slipSegunda via do boleto
POST /api/v1/customer/me/payments/{uuid}/pixSegunda via do PIX
GET /api/v1/customer/me/subscriptionsAssinaturas
GET /api/v1/customer/me/invoicesNotas fiscais. Aceita from, to (YYYY-MM-DD), page e per_page (até 50; padrão 20). Sem período, os últimos 12 meses

As listas de cobranças em aberto vêm da que vence primeiro. As pagas e all, da mais recente. Cada item de lista vem em data, com a paginação do Laravel.

Campos de uma cobrança: uuid, description, value, due_date, status (open enquanto aceita pagamento, senão o status da cobrança), days_overdue, subscription_uuid, plan_name, pay_url, receipt_url (só quando paga), accepts_bank_slip, accepts_pix, has_bank_slip e has_pix (se já existe um boleto ou PIX válido).

Campos de uma assinatura: uuid, plan_name, status, value (parcela), next_charge_date, overdue_count e overdue_value.

Campos de uma nota: uuid, number, issued_at, value, status (created, processing, issued, error ou canceled), payment_uuid, view_url e download_url.

Valores e datas

  • Os valores vêm em centavos, como número inteiro: 15000 é R$ 150,00.
  • As datas vêm no formato YYYY-MM-DD e os horários em ISO-8601.
  • As respostas identificam cobranças, assinaturas e notas pelo uuid. Ids sequenciais não aparecem.

Limites

LimiteValor
Criação de sessões600 por minuto, por empresa
Chamadas ao MCP60 por minuto, por sessão
Duração da sessão30 minutos, sem renovação
Clientes por sessãoDe 1 a 10

Acima dos limites, a resposta é 429. O limite de chamadas vale tanto para o MCP quanto para a API de leitura.

Próximos passos