API de Customers | GoMoney

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 é:

taxa cadastrada no customer;
taxa cadastrada no user;
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

1 POST https://gmc-api.gomoney.me/api/customers
2 Authorization: Bearer {{accessToken}}
3 secret-key: {{secretKeyBase64}}
4 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

1 {
2   "taxId": "39053344705",
3   "name": "Cliente Externo 01",
4   "email": "cliente01@example.com"
5 }

Resposta de sucesso

1 {
2   "_id": "66f0b1b5c1f7b7dc0ce30001",
3   "userId": "66f0b1b5c1f7b7dc0ce20001",
4   "taxId": "39053344705",
5   "name": "Cliente Externo 01",
6   "email": "cliente01@example.com",
7   "deleted": false,
8   "balance": {
9     "currency": "BRL",
10     "amount": 0
11   },
12   "wallet": {
13     "address": "0x2222222222222222222222222222222222222222"
14   }
15 }

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

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

Resposta de sucesso

1 [
2   {
3     "_id": "66f0b1b5c1f7b7dc0ce30001",
4     "taxId": "39053344705",
5     "name": "Cliente Externo 01",
6     "email": "cliente01@example.com",
7     "deleted": false,
8     "wallet": {
9       "address": "0x2222222222222222222222222222222222222222"
10     }
11   }
12 ]

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

1 PATCH https://gmc-api.gomoney.me/api/customers/{{customerId}}
2 Authorization: Bearer {{accessToken}}
3 secret-key: {{secretKeyBase64}}
4 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

1 {
2   "name": "Cliente Externo 01 Atualizado",
3   "email": "cliente01.updated@example.com"
4 }

Resposta de sucesso

1 {
2   "_id": "66f0b1b5c1f7b7dc0ce30001",
3   "taxId": "39053344705",
4   "name": "Cliente Externo 01 Atualizado",
5   "email": "cliente01.updated@example.com"
6 }

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

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

Resposta de sucesso

1 {
2   "_id": "66f0b1b5c1f7b7dc0ce30001",
3   "deleted": true
4 }

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.