> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.gomoney.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.gomoney.me/_mcp/server.

# API de Customers

## Requisitos de autenticação

Todos os endpoints de customers exigem:

* `Authorization: Bearer {{accessToken}}`
* `secret-key: {{secretKeyBase64}}`

O token utilizado nessas rotas é o mesmo retornado pelo login em `https://api-pix.gomoney.me/auth/login`, feito com o `email` e a `senha` do acesso criado como `INTEGRATION` e mantido com `INTEGRATION_ONLY`.

## Regras de taxa

A hierarquia aplicada nas emissões PIX é:

1. taxa cadastrada no `customer`;
2. taxa cadastrada no `user`;
3. taxa geral de `settings`.

## Endpoints disponíveis

| Método   | Caminho                   | Finalidade                                               |
| -------- | ------------------------- | -------------------------------------------------------- |
| `POST`   | `/customers`              | Cria um novo customer vinculado ao usuário autenticado.  |
| `GET`    | `/customers/all`          | Lista todos os customers ativos do usuário autenticado.  |
| `PATCH`  | `/customers/{customerId}` | Atualiza um customer pertencente ao usuário autenticado. |
| `DELETE` | `/customers/{customerId}` | Realiza a exclusão lógica de um customer.                |

## Criar customer

```http
POST https://gmc-api.gomoney.me/api/customers
Authorization: Bearer {{accessToken}}
secret-key: {{secretKeyBase64}}
Content-Type: application/json
```

### Corpo da requisição

| Campo   | Tipo     | Obrigatório | Descrição              |
| ------- | -------- | ----------- | ---------------------- |
| `taxId` | `string` | Sim         | Documento do customer. |
| `name`  | `string` | Sim         | Nome do customer.      |
| `email` | `string` | Sim         | E-mail do customer.    |

### Exemplo de requisição

```json
{
  "taxId": "39053344705",
  "name": "Cliente Externo 01",
  "email": "cliente01@example.com"
}
```

### Resposta de sucesso

```json
{
  "_id": "66f0b1b5c1f7b7dc0ce30001",
  "userId": "66f0b1b5c1f7b7dc0ce20001",
  "taxId": "39053344705",
  "name": "Cliente Externo 01",
  "email": "cliente01@example.com",
  "deleted": false,
  "balance": {
    "currency": "BRL",
    "amount": 0
  },
  "wallet": {
    "address": "0x2222222222222222222222222222222222222222"
  }
}
```

### Códigos de retorno

| Código | Significado                                   | Ação recomendada                                             |
| ------ | --------------------------------------------- | ------------------------------------------------------------ |
| `201`  | Customer criado com sucesso.                  | Persistir o identificador retornado para conciliação futura. |
| `400`  | Dados inválidos ou obrigatórios ausentes.     | Revisar documento, e-mail e estrutura do corpo.              |
| `401`  | Sessão ou credencial de integração inválidas. | Renovar o token e revisar a `secret-key`.                    |

## Listar customers

```http
GET https://gmc-api.gomoney.me/api/customers/all
Authorization: Bearer {{accessToken}}
secret-key: {{secretKeyBase64}}
```

### Resposta de sucesso

```json
[
  {
    "_id": "66f0b1b5c1f7b7dc0ce30001",
    "taxId": "39053344705",
    "name": "Cliente Externo 01",
    "email": "cliente01@example.com",
    "deleted": false,
    "wallet": {
      "address": "0x2222222222222222222222222222222222222222"
    }
  }
]
```

### Códigos de retorno

| Código | Significado                                   | Ação recomendada                                            |
| ------ | --------------------------------------------- | ----------------------------------------------------------- |
| `200`  | Lista retornada com sucesso.                  | Usar os identificadores recebidos para operações seguintes. |
| `401`  | Sessão ou credencial de integração inválidas. | Renovar o token e revisar a `secret-key`.                   |

## Atualizar customer

```http
PATCH https://gmc-api.gomoney.me/api/customers/{{customerId}}
Authorization: Bearer {{accessToken}}
secret-key: {{secretKeyBase64}}
Content-Type: application/json
```

### Parâmetro de rota

| Parâmetro    | Tipo     | Obrigatório | Descrição                          |
| ------------ | -------- | ----------- | ---------------------------------- |
| `customerId` | `string` | Sim         | Identificador interno do customer. |

### Exemplo de requisição

```json
{
  "name": "Cliente Externo 01 Atualizado",
  "email": "cliente01.updated@example.com"
}
```

### Resposta de sucesso

```json
{
  "_id": "66f0b1b5c1f7b7dc0ce30001",
  "taxId": "39053344705",
  "name": "Cliente Externo 01 Atualizado",
  "email": "cliente01.updated@example.com"
}
```

### Códigos de retorno

| Código | Significado                                     | Ação recomendada                                        |
| ------ | ----------------------------------------------- | ------------------------------------------------------- |
| `200`  | Customer atualizado com sucesso.                | Sincronizar os dados atualizados no seu sistema.        |
| `400`  | Corpo inválido.                                 | Revisar os campos enviados e seus formatos.             |
| `401`  | Sessão ou credencial de integração inválidas.   | Renovar o token e revisar a `secret-key`.               |
| `403`  | O customer não pertence ao usuário autenticado. | Verificar titularidade e contexto da conta usada.       |
| `404`  | Customer não encontrado.                        | Confirmar o identificador informado e seu estado atual. |

## Remover customer

```http
DELETE https://gmc-api.gomoney.me/api/customers/{{customerId}}
Authorization: Bearer {{accessToken}}
secret-key: {{secretKeyBase64}}
```

### Resposta de sucesso

```json
{
  "_id": "66f0b1b5c1f7b7dc0ce30001",
  "deleted": true
}
```

### Códigos de retorno

| Código | Significado                                     | Ação recomendada                                        |
| ------ | ----------------------------------------------- | ------------------------------------------------------- |
| `200`  | Customer removido logicamente com sucesso.      | Atualizar o estado do customer no seu sistema.          |
| `401`  | Sessão ou credencial de integração inválidas.   | Renovar o token e revisar a `secret-key`.               |
| `403`  | O customer não pertence ao usuário autenticado. | Verificar titularidade e contexto da conta usada.       |
| `404`  | Customer não encontrado.                        | Confirmar o identificador informado e seu estado atual. |