# Monetarie Partner API v1 - Guia da coleção Postman

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

Este guia acompanha a coleção `Monetarie-Partner-API.postman_collection.json` e explica como autenticar e consumir o catálogo `/api/partner/v1` do Core da Monetarie.

A Partner API é a interface servidor a servidor sobre a qual a própria Monetarie integra o seu aplicativo e o seu internet banking. Toda chamada de catálogo é escopada ao parceiro dono da credencial: um parceiro só enxerga e movimenta as contas, os clientes e os webhooks que ele mesmo criou.

## Como obter as credenciais (client_id e client_secret)

As credenciais são geradas no painel administrativo do Core (coreadmin), em **Administração > Parceiros**. O passo a passo completo está em [`guia-coreadmin-parceiros.md`](./guia-coreadmin-parceiros.md). Em resumo:

1. Acesse o coreadmin e abra **Parceiros**.
2. Cadastre o parceiro (nome e documento, CPF ou CNPJ).
3. Em **Gerenciar chaves**, crie uma chave selecionando as permissões (escopos) e, se desejar, os IPs permitidos.
4. Copie o `client_id` e o `client_secret` exibidos. O `client_secret` aparece **uma única vez** e não pode ser recuperado depois.
5. Entregue o `client_id` e o `client_secret` ao integrador por um canal seguro.

Se o `client_secret` for perdido, revogue a chave e gere uma nova.

## Autenticação OAuth2

A autenticação usa o fluxo OAuth2 `client_credentials`. O parceiro troca o seu `client_id` e o seu `client_secret` por um token Bearer de curta duração e usa esse token em todas as demais chamadas.

1. Faça um POST em `/api/partner/v1/oauth/token` com corpo `application/x-www-form-urlencoded`:
   - `grant_type=client_credentials`
   - `client_id=<seu client_id>`
   - `client_secret=<seu client_secret>`
2. A resposta traz `access_token`, `token_type` (sempre `Bearer`), `expires_in` (em segundos) e `scope` (os escopos concedidos).
3. Use o token em todas as chamadas seguintes no cabeçalho `Authorization: Bearer <access_token>`.

O endpoint de token aceita corpo `application/x-www-form-urlencoded` (padrão OAuth2 da RFC 6749, seção 4.4) ou `application/json`. O token tem validade de 8 horas (28800 segundos). O escopo concedido é a interseção dos escopos solicitados com as permissões da chave do parceiro.

### Como usar na coleção

1. Importe `Monetarie-Partner-API.postman_collection.json` no Postman.
2. Abra a coleção, vá em **Variables** e preencha:
   - `baseUrl` (veja a nota abaixo)
   - `client_id`
   - `client_secret`
3. Rode primeiro a requisição `OAuth > Obter token`. O script de teste salva automaticamente o `access_token` na variável da coleção.
4. Rode em seguida `OAuth > Verificar credencial (ping)`. É a primeira chamada de sanidade da integração: responde `200` ecoando o `partner_id` da credencial, confirmando que ela está ativa e apontando para o parceiro esperado.
5. A partir daí execute qualquer outra requisição. Todas já enviam `Authorization: Bearer {{access_token}}`.

Quando o token expirar (8 horas), basta rodar de novo `OAuth > Obter token` para renová-lo.

## Nota sobre a base URL

A coleção vem com `baseUrl` apontando para o host interno de homologação `http://coreapi-h.monetarie.internal`. Esse host só resolve dentro da rede privada da Monetarie (zona `monetarie.internal`), com a VPN ativa. Em outros ambientes, ajuste `baseUrl` para o endpoint correto do Core. Não use barra no final.

## Escopos

Cada endpoint exige um escopo específico. A coleção está organizada por domínio e cada requisição indica, na sua descrição, o escopo necessário.

- `pix:read` - consultar chaves DICT, consultar chave externa, status de PIX e status de cobrança.
- `pix:write` - registrar e excluir chave DICT, enviar PIX, devolver PIX e criar cobrança.
- `account:read` - listar e detalhar contas e consultar saldo.
- `statement:read` - consultar extrato e obter comprovante.
- `transfer:read` - status de transferência e listar favoritos.
- `transfer:write` - enviar TED, transferência interna e criar/excluir favorito.
- `customer:create` - cadastrar cliente.
- `customer:read` - consultar cliente.
- `webhook:read` - listar e detalhar webhooks e ler o catálogo de eventos.
- `webhook:write` - registrar, atualizar, excluir, rotacionar segredo, testar e reenviar webhooks.

## Valores monetários

- Entradas de PIX e de transferências usam centavos (número inteiro). Exemplo: `1500` representa R$ 15,00.
- Saldo, extrato e comprovante saem em reais (número com casas decimais).

## Idempotência

As operações de escrita que movem dinheiro (cadastrar cliente, enviar PIX, enviar TED e transferência interna) aceitam o cabeçalho `Idempotency-Key`. Reenvios com a mesma chave retornam a resposta original, evitando duplicidade.

## Recursos em destaque

- **QR estático com valor em aberto ou fixo** (`PIX > Criar QR estático`): sem `amount`, o pagador digita o valor; com `amount` em centavos, o valor fica fixo no código. O QR estático é reutilizável e não expira.
- **Devolução de PIX recebido** (`PIX > Devolver PIX`): devolve um PIX recebido pela conta dentro da janela regulamentar de 90 dias, com devolução parcial permitida até o restante devolvível. A trilha completa fica em `PIX > Trilha de devoluções da transação`.

Os detalhes de cada recurso, com exemplos de resposta e recusas, estão no portal do parceiro (páginas PIX e Webhooks).

## Estrutura da coleção

- **OAuth** - emissão do token de acesso e verificação da credencial (ping).
- **Clientes** - cadastrar e consultar cliente.
- **Contas e saldo** - listar e detalhar contas, saldo, extrato e comprovante.
- **PIX** - chaves DICT, consulta DICT, QR estático, envio, devolução e trilha de devoluções, status e cobrança.
- **Transferências** - TED, transferência interna, status e favoritos.
- **Webhooks** - cadastro, listagem, atualização, rotação de segredo, teste, reenvio e catálogo de eventos.

## Documentação interativa

A especificação OpenAPI completa e o Swagger UI ficam em `/api/swaggerui` no mesmo Core. Lá você encontra todos os esquemas de requisição e resposta, os códigos de erro e os escopos por operação.

## Segurança

Nunca versione o `client_id`, o `client_secret`, o `access_token` nem o segredo de webhook. As variáveis da coleção vêm em branco de propósito para que cada parceiro preencha as suas credenciais localmente.