---
agentTools:
  projectIndex: https://docs.ninepay.com.br/llms.txt
  projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2
---

# 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](/docs/mcp-server), 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](/docs/autenticacao)).
- **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:

```bash
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] }
```

| Campo | Descrição |
| --- | --- |
| `customer_ids` | Lista 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"
}
```

| 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](/docs/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](#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` |

```text 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:

```bash 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:

```bash
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`:

```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
}
```

| 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-DD` e 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.

## Próximos passos

- [Autenticação](/docs/autenticacao)
- [Ambiente de testes](/docs/sandbox)
- [MCP Server da documentação](/docs/mcp-server)
