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:
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:
{ "customer_ids": [12345] }| Campo | Descrição |
|---|---|
customer_ids | Lista de 1 a 10 ids de clientes da sua empresa, sem repetição |
Resposta, 201:
{
"id": 987,
"token": "cs_prod_...",
"customer_ids": [12345],
"expires_at": "2026-11-16T21:30:00Z"
}| Campo | Descrição |
|---|---|
id | Identificador da sessão. Guarde para revogar |
token | Token da sessão, para entregar ao agente |
customer_ids | Os clientes da sessão |
expires_at | Quando a sessão expira (30 minutos após a criação) |
| Prefixo do token | Ambiente |
|---|---|
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:
| Status | Quando |
|---|---|
401 | Chave de API ausente, inválida, desabilitada ou expirada |
403 | A empresa não está ativa. Só empresas ativas criam sessões |
404 | Algum cliente da lista não é da sua empresa ou foi apagado (a resposta é a mesma nos dois casos) |
422 | customer_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 |
429 | Limite 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:
| Ambiente | URL do MCP |
|---|---|
| Produção | https://mcp.ninepay.com.br/mcp/customer |
| Sandbox | https://mcp.sandbox.ninepay.com.br/mcp/customer |
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:
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:
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.
| Ferramenta | O que faz |
|---|---|
get_my_account | Mostra quem é o cliente e qual empresa cobra, com e-mail e telefone mascarados |
list_open_payments | Lista as cobranças em aberto, com valor, vencimento, dias de atraso e links para pagar. Aceita page |
get_payment | Mostra uma cobrança, a partir do payment_uuid que veio da lista, com os links |
list_subscriptions | Lista as assinaturas e a situação de cada uma, incluindo quantas cobranças estão em atraso |
list_invoices | Lista as notas fiscais, com os links para ver e baixar. Aceita from, to (YYYY-MM-DD) e page |
get_bank_slip | Gera 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_code | Gera 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:
{
"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:
{
"payment_uuid": "9f1c...",
"pix_code": "00020126...",
"expires_at": "2026-11-16T22:00:00+00:00",
"value": 15000,
"reused": true
}| Campo | Descrição |
|---|---|
digitable_line | Linha digitável do boleto |
bar_code | Código de barras do boleto |
due_date | Vencimento do boleto, YYYY-MM-DD |
value | Valor em centavos |
pdf_url | PDF 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_code | PIX copia e cola |
expires_at | Até quando o PIX pode ser pago |
reused | true 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:
| Caso | O 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 andamento | A 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.
| Rota | O que devolve |
|---|---|
GET /api/v1/customer/me | customer_name, company_name, email_masked, phone_masked |
GET /api/v1/customer/me/payments | Cobranç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-slip | Segunda via do boleto |
POST /api/v1/customer/me/payments/{uuid}/pix | Segunda via do PIX |
GET /api/v1/customer/me/subscriptions | Assinaturas |
GET /api/v1/customer/me/invoices | Notas 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-DDe os horários em ISO-8601. - As respostas identificam cobranças, assinaturas e notas pelo
uuid. Ids sequenciais não aparecem.
Limites
| Limite | Valor |
|---|---|
| Criação de sessões | 600 por minuto, por empresa |
| Chamadas ao MCP | 60 por minuto, por sessão |
| Duração da sessão | 30 minutos, sem renovação |
| Clientes por sessão | De 1 a 10 |
Acima dos limites, a resposta é 429. O limite de chamadas vale tanto para o MCP quanto para a API de leitura.