# Inter Empresas

Inter Empresas é a primeira instituição disponível na Referência da API de Gestão de Boletos, e a implementação de referência: tudo nesta página acontece por trás dos mesmos endpoints descritos no guia da [Referência da API de Gestão de Boletos](/docs/boleto/management-api).

## Estabelecendo uma conexão

Inter autentica com quatro artefatos — um Client ID, um Client Secret, uma chave privada e um certificado — criados dentro do próprio Internet Banking do Inter. O [tutorial do Banco Inter Empresas](/docs/developer-tools/tutorials/inter-pj) orienta sobre como produzi-los.

<Callout variant="warning" title="Ative as permissões corretas">
Ao criar a integração no Inter, ative os escopos **Boleto** e **Extrato**. Uma credencial que não possui o escopo Boleto conecta-se com sucesso e depois falha na primeira tentativa de emissão, o que é um lugar confuso para descobrir o problema.
</Callout>

Existem duas maneiras de transformar essas credenciais em uma conexão:

```mermaid
graph TD
  A[Credenciais do Inter] --> B[Conectar através do Pluggy Connect<br/>cria um Item]
  A --> C[Enviar credenciais diretamente<br/>POST /boleto-connections]
  B --> D[POST /boleto-connections/from-item]
  C --> E[Conexão de Boleto]
  D --> E
```

Passar por um Item é o melhor padrão quando você já coleta dados da conta para o mesmo cliente: uma conexão, um conjunto de credenciais, e o cliente autoriza uma vez. Enviar credenciais diretamente é para quando não há um Item para reutilizar.

## Como o Inter reporta um pagamento

Inter nos notifica, e traduzimos seu vocabulário nos status que a API expõe:

| Inter `situacao` | Torna-se |
|---|---|
| `RECEBIDO` | `PAID` |
| `MARCADO_RECEBIDO` | `PAID` |
| `ATRASADO` | `OVERDUE` |
| `PROTESTO` | `PROTESTED` |
| `A_RECEBER` | ignorado — o boleto simplesmente ainda está aberto |

Quando um boleto se torna `PAID`, o Inter também reporta o que foi realmente pago e como, que vai para `amountPaid` e `paymentOrigin`. `paymentOrigin` é tipicamente `PIX` ou `BOLETO`, refletindo como o pagador escolheu liquidar.

<Callout variant="info" title="Cancelamentos não chegam por webhook">
Um boleto que você cancela através do [POST /boletos/{id}/cancel](/reference/boleto-cancel) é marcado como `CANCELLED` imediatamente, como parte dessa chamada. Mas um boleto cancelado diretamente dentro do próprio portal do Inter não será atualizado do nosso lado — esse caminho não produz nenhuma mudança de status que você possa observar. Se sua equipe de operações cancela boletos no Inter em vez de através da API, trate nosso status como autoritativo apenas para boletos cancelados através da API.
</Callout>

## Autenticando as notificações

Inter publica os intervalos de IP de onde suas notificações se originam, e aceitamos apenas callbacks desses endereços. Nada é necessário de você — a notificação que você recebe é nosso próprio webhook `boleto/updated`, autenticado da mesma forma que todos os outros webhooks do Pluggy.

## Vale a pena saber antes de você entrar em produção

- **`nossoNumero` é do Inter, e seu formato é do Inter.** Não o analise ou assuma uma largura; ele difere do que outra instituição retornará para a mesma cobrança.
- **Um pagamento atrasado é normal.** O Inter aceita pagamento após a data de vencimento, então um boleto pode passar de `ABERTO → ATRASADO → PAGO`. Manipuladores que param de ouvir uma vez que um boleto está atrasado perdem receita real.
- **Teste o caminho de pagamento parcial.** `amountPaid` pode ser menor ou maior que `amount` uma vez que descontos, multas ou juros se aplicam. O [Sandbox](/docs/boleto/sandbox) o produz sob demanda: emita um boleto com um valor terminando em `,01` e ele será pago pela metade.