# Visão geral

A **Partner API** da Monetarie é a interface servidor a servidor pela qual o seu sistema cria clientes, abre e consulta contas, envia PIX e TED e recebe webhooks. Toda chamada do 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.

## Base URL

A coleção e os exemplos usam a variável `{{baseUrl}}`. Aponte para o endpoint informado pela Monetarie para o seu ambiente. Não use barra no final.

```
{{baseUrl}}/api/partner/v1
```

A Monetarie fornece a URL base de homologação e a de produção no momento da habilitação do parceiro.

## Fluxo de integração

1. Receba o seu `client_id` e `client_secret` (gerados no painel da Monetarie).
2. Troque essas credenciais por um token de acesso em `POST /api/partner/v1/oauth/token`. Veja [Autenticação](/autenticacao).
3. Use o token no cabeçalho `Authorization: Bearer <access_token>` em todas as demais chamadas.
4. Para operações que movem dinheiro, envie um cabeçalho `Idempotency-Key` para evitar duplicidade.
5. Cadastre [webhooks](/endpoints/webhooks) para receber eventos de forma assíncrona.

## 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.

## Erros

As respostas de erro seguem um formato consistente, com o código HTTP apropriado:

```json
{
  "error": {
    "status": 403,
    "message": "Permissão insuficiente para esta operação"
  }
}
```

| Código | Significado |
|---|---|
| `400` | Requisição malformada |
| `401` | Token ausente, inválido ou expirado |
| `403` | Escopo insuficiente ou recurso de outro parceiro |
| `404` | Recurso não encontrado |
| `422` | Dados inválidos (validação) |
| `429` | Muitas requisições |

Dois endpoints usam um formato próprio, por seguirem padrões específicos:

- O endpoint de token (`POST /oauth/token`) segue o padrão OAuth2 e responde `{ "error": "...", "error_description": "..." }`.
- A validação de campos ao registrar ou atualizar webhook devolve um mapa de erros por campo: `{ "errors": { "url": ["mensagem"] } }`.

## Ferramentas

- **Postman:** [baixe a coleção](/Monetarie-Partner-API.postman_collection.json) e preencha as variáveis `baseUrl`, `client_id` e `client_secret`. A coleção já cuida do token e do cabeçalho `Authorization`.
- **Referência interativa:** a especificação do contrato (OpenAPI) fica disponível no ambiente do Core informado pela Monetarie.