# Guia coreadmin - Parceiros e chaves de API

Documentação da **Monetarie Sociedade de Crédito Direto S.A.** (SCD, ISPB 46026562).

Este guia mostra, passo a passo, como cadastrar um parceiro e gerar as chaves de API (o par `client_id` e `client_secret`) que o integrador usará na Partner API (`/api/partner/v1`). Tudo é feito pela própria tela do painel administrativo do Core (coreadmin), sem comando de banco e sem intervenção técnica.

## Quem pode acessar

A tela fica em **Administração > Parceiros** no menu lateral do coreadmin. O acesso é restrito a administradores. O administrador master (`admin@monetarie.com.br`) já tem acesso. Para liberar outros perfis, conceda a permissão `admin.parceiros` ao grupo desejado em **Perfis**.

## Passo 1 - Cadastrar o parceiro

1. No coreadmin, abra **Administração > Parceiros**.
2. Clique em **Novo parceiro**.
3. Preencha:
   - **Nome**: o nome do parceiro (por exemplo, a marca do aplicativo que vai integrar).
   - **Documento**: o CPF ou o CNPJ do parceiro, somente números.
4. Clique em **Criar**.

O parceiro nasce com status **Ativa** e fica vinculado à instituição (entidade) em que você está logado. Ele aparece na lista, com a contagem de chaves zerada.

## Passo 2 - Gerar uma chave de API

1. Na linha do parceiro, clique em **Gerenciar chaves**.
2. Na seção **Nova chave**, preencha:
   - **Nome da chave**: um rótulo para identificar o uso, por exemplo `Produção` ou `Homologação`. Você pode criar várias chaves para o mesmo parceiro (uma por ambiente, por exemplo).
   - **Permissões**: marque os escopos que essa chave poderá usar. Os escopos estão agrupados por domínio (Contas, Extrato, PIX, Transferências, Pagamentos, Clientes, Webhooks). Marque apenas o que o integrador realmente precisa; o princípio é o de menor privilégio.
   - **IPs permitidos** (opcional): informe um IP ou um bloco CIDR por linha para restringir de onde a chave pode ser usada. Deixe em branco para permitir qualquer origem.
3. Clique em **Criar chave**.

### Copie o secret na hora

Ao criar a chave, abre-se a janela **Chave de API criada** com o `client_id` e o `client_secret`. Use os botões **Copiar** de cada campo.

- O `client_secret` é exibido **uma única vez** e não pode ser recuperado depois.
- Se você fechar a janela sem copiar, será necessário revogar a chave e gerar uma nova.

Entregue o `client_id` e o `client_secret` ao integrador por um canal seguro (não envie por e-mail comum nem por mensagem aberta). Com esse par, o integrador obtém o token Bearer pelo fluxo OAuth2 descrito no guia da coleção Postman.

## Passo 3 - Acompanhar e administrar as chaves

Ainda em **Gerenciar chaves**, a seção **Chaves existentes** lista as chaves do parceiro com o nome, o `client_id`, a quantidade de permissões e o status. As ações disponíveis são:

- **Revogar**: desativa a chave imediatamente. O integrador para de conseguir token na hora. Use ao desligar uma integração ou em caso de suspeita de vazamento.
- **Reativar**: volta uma chave revogada para o status ativo.
- **Excluir**: remove a chave de vez. Prefira revogar quando quiser manter o histórico.

## Mapa de escopos

Os escopos controlam o que cada chave pode fazer na Partner API:

- `account:read` - consultar contas e saldo.
- `account:write` - criar e alterar contas.
- `statement:read` - consultar extrato.
- `pix:read` - consultar PIX (chaves, DICT e status).
- `pix:write` - enviar PIX e criar cobranças e chaves.
- `transfer:read` - consultar transferências.
- `transfer:write` - enviar TED e transferências internas.
- `payment:read` - consultar pagamentos.
- `payment:write` - efetuar pagamentos.
- `customer:read` - consultar clientes.
- `customer:create` - cadastrar clientes.
- `webhook:read` - consultar webhooks.
- `webhook:write` - gerenciar webhooks.

## Boas práticas

- Crie uma chave por ambiente e por finalidade, com o mínimo de escopos.
- Use a lista de IPs permitidos sempre que o integrador tiver origem de rede fixa.
- Faça rotação periódica: gere a nova chave, atualize o integrador e só então revogue a antiga.
- Nunca registre o `client_secret` em documento, planilha, repositório ou mensagem aberta.