Referência Técnica

API de Adição de Saldos

Endpoints, parâmetros e exemplos para criação e consulta de cobranças

View as Markdown

Requisitos de autenticação

Para emitir a adição, use:

  • Authorization: Bearer {{accessToken}} com o token obtido no login do acesso INTEGRATION_ONLY
  • secret-key: {{secretKeyBase64}}
  • Origin: {{allowedOrigin}}

Os endpoints de consulta exigem:

  • Authorization: Bearer {{accessToken}}

Endpoints disponíveis

MétodoCaminhoFinalidade
POST/transactions/add-balanceEmite uma cobrança adição de saldo para a integração documentada.
GET/transactions/add-balance/allLista as adições do usuário autenticado com filtro opcional por período.
GET/transactions/add-balance/{id}Consulta o detalhe de uma adição específica.

Adição de saldo em GMC

1POST https://gmc-api.gomoney.me/api/transactions/add-balance
2Authorization: Bearer {{accessToken}}
3secret-key: {{secretKeyBase64}}
4Origin: {{allowedOrigin}}
5Content-Type: application/json

Corpo da requisição

CampoTipoObrigatórioDescrição
amountnumberSimValor da adição.
customerIdentifierstringSim_id ou taxId do customer associado à cobrança.
currencyenumSimBRL, USDT, GMC ou USD

Regras operacionais

  • A secret-key precisa pertencer ao mesmo usuário do token Bearer;
  • O header Origin precisa corresponder ao domínio liberado na integração;
  • customerIdentifier é obrigatório e pode ser enviado como _id ou taxId;
  • As taxas seguem a hierarquia customer -> user -> settings;
  • A wallet operacional do usuário precisa estar cadastrada e aprovada para o direcionamento dos recebimentos em GMC.

Exemplo de requisição

1{
2  "customerIdentifier": "66f0b1b5c1f7b7dc0ce20001",
3  "amount": 1000,
4  "currency": "GMC"
5}

Resposta de sucesso

1{
2  "title": "Success",
3  "balanceTransaction": {
4    "_id": "66f0b1b5c1f7b7dc0ce40001",
5    "user": "66f0b1b5c1f7b7dc0ce20001",
6    "status": "COMPLETED",
7    "summary": {
8        "totalItems": 1,
9        "completedItems": 1,
10        "failedItems": 0,
11        "totalTargetGmc": 1000,
12    },
13    "items": [
14        {
15          "customerIdentifier": "66f0b1b5c1f7b7dc0ce20001",
16          "sourceAmount": 1000,
17          "sourceCurrency": "GMC",
18          "targetGmcAmount": "1000",
19          "status": "COMPLETED",
20          "error": null,
21          "customerWalletAddress": "0x...",
22          "destinationWalletAddress": "0x...",
23          "fees": {
24            "fixedBrl": 0,
25            "percentageBrl": 0,
26            "totalBrl": 0,
27            "issueTaxBrl": 0,
28            "issueTaxRate": 0,
29            "ixedFeeSource": "not-applied",
30            "percentageFeeSource": "not-applied",
31            "issueTaxSource": "not-applied",
32          },
33          "conversion": {
34            "brlPerGmc": 0,
35            "usdtBrlRate": 0,
36            "sourceAmountBrl": 0,
37          },
38          "blockchain": {
39            "mintHash": null,
40            "approveHash": null,
41            "transferHash": null,
42          },
43          "processedAt": "1783378670",
44        }
45    ],
46    "createdAt": "1783378670",
47    "updatedAt": "1783378670",
48  }
49}

Códigos de retorno

CódigoSignificadoAção recomendada
201Adição criada com sucesso.Persistir _id, txid, customerIdentifier e as evidências.
400Dados inválidos, valor inconsistente ou customerIdentifier ausente/inválido.Revisar valor e vínculo com customer.
401Token, secret-key ou Origin inválidos para a integração.Renovar o token e revisar credencial e domínio liberado.
403Usuário sem permissão para a operação.Confirmar que o acesso usado é do tipo INTEGRATION com INTEGRATION_ONLY ativo.
503Fluxo GMC indisponível temporariamente.Reprocessar em janela operacional permitida.

Listar adições de saldo

1GET https://gmc-api.gomoney.me/api/transactions/add-balance/all
2Authorization: Bearer {{accessToken}}
3secret-key: {{secretKeyBase64}}
4Origin: {{allowedOrigin}}
5Content-Type: application/json

Parâmetros de query

ParâmetroTipoObrigatórioDescrição
initialDatestring (date)NãoData inicial do filtro.
finalDatestring (date)NãoData final do filtro.

Resposta de sucesso

1{
2  "title": "Success",
3  "balanceTransaction": {
4    "_id": "66f0b1b5c1f7b7dc0ce40001",
5    "user": "66f0b1b5c1f7b7dc0ce20001",
6    "status": "COMPLETED",
7    "summary": {
8        "totalItems": 1,
9        "completedItems": 1,
10        "failedItems": 0,
11        "totalTargetGmc": 1000,
12    },
13    "items": [
14        {
15          "customerIdentifier": "66f0b1b5c1f7b7dc0ce20001",
16          "sourceAmount": 1000,
17          "sourceCurrency": "GMC",
18          "targetGmcAmount": "1000",
19          "status": "COMPLETED",
20          "error": null,
21          "customerWalletAddress": "0x...",
22          "destinationWalletAddress": "0x...",
23          "fees": {
24            "fixedBrl": 0,
25            "percentageBrl": 0,
26            "totalBrl": 0,
27            "issueTaxBrl": 0,
28            "issueTaxRate": 0,
29            "ixedFeeSource": "not-applied",
30            "percentageFeeSource": "not-applied",
31            "issueTaxSource": "not-applied",
32          },
33          "conversion": {
34            "brlPerGmc": 0,
35            "usdtBrlRate": 0,
36            "sourceAmountBrl": 0,
37          },
38          "blockchain": {
39            "mintHash": null,
40            "approveHash": null,
41            "transferHash": null,
42          },
43          "processedAt": "1783378670",
44        }
45    ],
46    "createdAt": "1783378670",
47    "updatedAt": "1783378670",
48  },
49  "recordsFiltered": 1,
50  "recordsTotal": 1,
51}

Códigos de retorno

CódigoSignificadoAção recomendada
200Lista retornada com sucesso.Usar os identificadores recebidos para consulta ou conciliação.
401Token inválido.Renovar a sessão da API com o acesso de integração correto.

Consultar adição de saldo por ID

1GET https://gmc-api.gomoney.me/api/transactions/add-balance/{{id}}
2Authorization: Bearer {{accessToken}}
3secret-key: {{secretKeyBase64}}
4Origin: {{allowedOrigin}}
5Content-Type: application/json

Parâmetro de rota

ParâmetroTipoObrigatórioDescrição
idstringSimIdentificador interno da adição.

Resposta de sucesso

1{
2  "title": "Success",
3  "balanceTransaction": {
4    "_id": "66f0b1b5c1f7b7dc0ce40001",
5    "user": "66f0b1b5c1f7b7dc0ce20001",
6    "status": "COMPLETED",
7    "summary": {
8        "totalItems": 1,
9        "completedItems": 1,
10        "failedItems": 0,
11        "totalTargetGmc": 1000,
12    },
13    "items": [
14        {
15          "customerIdentifier": "66f0b1b5c1f7b7dc0ce20001",
16          "sourceAmount": 1000,
17          "sourceCurrency": "GMC",
18          "targetGmcAmount": "1000",
19          "status": "COMPLETED",
20          "error": null,
21          "customerWalletAddress": "0x...",
22          "destinationWalletAddress": "0x...",
23          "fees": {
24            "fixedBrl": 0,
25            "percentageBrl": 0,
26            "totalBrl": 0,
27            "issueTaxBrl": 0,
28            "issueTaxRate": 0,
29            "ixedFeeSource": "not-applied",
30            "percentageFeeSource": "not-applied",
31            "issueTaxSource": "not-applied",
32          },
33          "conversion": {
34            "brlPerGmc": 0,
35            "usdtBrlRate": 0,
36            "sourceAmountBrl": 0,
37          },
38          "blockchain": {
39            "mintHash": null,
40            "approveHash": null,
41            "transferHash": null,
42          },
43          "processedAt": "1783378670",
44        }
45    ],
46    "createdAt": "1783378670",
47    "updatedAt": "1783378670",
48  }
49}

Códigos de retorno

CódigoSignificadoAção recomendada
200Adição encontrada.Atualizar a conciliação e o estado interno da adição.
401Token inválido.Renovar a sessão da API com o acesso de integração correto.
417Cobrança não encontrada ou sem vínculo com o usuário autenticado.Confirmar o identificador informado e a titularidade da conta.

Fluxo após o adição

Depois da confirmação do adição, a plataforma:

  1. Valida os parâmetros;
  2. Víncula o adição ao customer indicado;
  3. Atualiza o status e hashs;
  4. Disponibiliza a adição atualizada para consulta;