> 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 Adição de Saldos ## 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étodo | Caminho | Finalidade | | ------ | -------------------------------- | ------------------------------------------------------------------------ | | `POST` | `/transactions/add-balance` | Emite uma cobrança adição de saldo para a integração documentada. | | `GET` | `/transactions/add-balance/all` | Lista 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 ```http POST https://gmc-api.gomoney.me/api/transactions/add-balance Authorization: Bearer {{accessToken}} secret-key: {{secretKeyBase64}} Origin: {{allowedOrigin}} Content-Type: application/json ``` ### Corpo da requisição | Campo | Tipo | Obrigatório | Descrição | | -------------------- | -------- | ----------- | -------------------------------------------------- | | `amount` | `number` | Sim | Valor da adição. | | `customerIdentifier` | `string` | Sim | `_id` ou `taxId` do customer associado à cobrança. | | `currency` | `enum` | Sim | BRL, 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 ```json { "customerIdentifier": "66f0b1b5c1f7b7dc0ce20001", "amount": 1000, "currency": "GMC" } ``` ### Resposta de sucesso ```json { "title": "Success", "balanceTransaction": { "_id": "66f0b1b5c1f7b7dc0ce40001", "user": "66f0b1b5c1f7b7dc0ce20001", "status": "COMPLETED", "summary": { "totalItems": 1, "completedItems": 1, "failedItems": 0, "totalTargetGmc": 1000, }, "items": [ { "customerIdentifier": "66f0b1b5c1f7b7dc0ce20001", "sourceAmount": 1000, "sourceCurrency": "GMC", "targetGmcAmount": "1000", "status": "COMPLETED", "error": null, "customerWalletAddress": "0x...", "destinationWalletAddress": "0x...", "fees": { "fixedBrl": 0, "percentageBrl": 0, "totalBrl": 0, "issueTaxBrl": 0, "issueTaxRate": 0, "ixedFeeSource": "not-applied", "percentageFeeSource": "not-applied", "issueTaxSource": "not-applied", }, "conversion": { "brlPerGmc": 0, "usdtBrlRate": 0, "sourceAmountBrl": 0, }, "blockchain": { "mintHash": null, "approveHash": null, "transferHash": null, }, "processedAt": "1783378670", } ], "createdAt": "1783378670", "updatedAt": "1783378670", } } ``` ### Códigos de retorno | Código | Significado | Ação recomendada | | ------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | `201` | Adição criada com sucesso. | Persistir `_id`, `txid`, `customerIdentifier` e as evidências. | | `400` | Dados inválidos, valor inconsistente ou `customerIdentifier` ausente/inválido. | Revisar valor e vínculo com customer. | | `401` | Token, `secret-key` ou `Origin` inválidos para a integração. | Renovar o token e revisar credencial e domínio liberado. | | `403` | Usuário sem permissão para a operação. | Confirmar que o acesso usado é do tipo `INTEGRATION` com `INTEGRATION_ONLY` ativo. | | `503` | Fluxo GMC indisponível temporariamente. | Reprocessar em janela operacional permitida. | ## Listar adições de saldo ```http GET https://gmc-api.gomoney.me/api/transactions/add-balance/all Authorization: Bearer {{accessToken}} secret-key: {{secretKeyBase64}} Origin: {{allowedOrigin}} Content-Type: application/json ``` ### Parâmetros de query | Parâmetro | Tipo | Obrigatório | Descrição | | ------------- | ----------------- | ----------- | ----------------------- | | `initialDate` | `string` (`date`) | Não | Data inicial do filtro. | | `finalDate` | `string` (`date`) | Não | Data final do filtro. | ### Resposta de sucesso ```json { "title": "Success", "balanceTransaction": { "_id": "66f0b1b5c1f7b7dc0ce40001", "user": "66f0b1b5c1f7b7dc0ce20001", "status": "COMPLETED", "summary": { "totalItems": 1, "completedItems": 1, "failedItems": 0, "totalTargetGmc": 1000, }, "items": [ { "customerIdentifier": "66f0b1b5c1f7b7dc0ce20001", "sourceAmount": 1000, "sourceCurrency": "GMC", "targetGmcAmount": "1000", "status": "COMPLETED", "error": null, "customerWalletAddress": "0x...", "destinationWalletAddress": "0x...", "fees": { "fixedBrl": 0, "percentageBrl": 0, "totalBrl": 0, "issueTaxBrl": 0, "issueTaxRate": 0, "ixedFeeSource": "not-applied", "percentageFeeSource": "not-applied", "issueTaxSource": "not-applied", }, "conversion": { "brlPerGmc": 0, "usdtBrlRate": 0, "sourceAmountBrl": 0, }, "blockchain": { "mintHash": null, "approveHash": null, "transferHash": null, }, "processedAt": "1783378670", } ], "createdAt": "1783378670", "updatedAt": "1783378670", }, "recordsFiltered": 1, "recordsTotal": 1, } ``` ### Códigos de retorno | Código | Significado | Ação recomendada | | ------ | ---------------------------- | --------------------------------------------------------------- | | `200` | Lista retornada com sucesso. | Usar os identificadores recebidos para consulta ou conciliação. | | `401` | Token inválido. | Renovar a sessão da API com o acesso de integração correto. | ## Consultar adição de saldo por ID ```http GET https://gmc-api.gomoney.me/api/transactions/add-balance/{{id}} Authorization: Bearer {{accessToken}} secret-key: {{secretKeyBase64}} Origin: {{allowedOrigin}} Content-Type: application/json ``` ### Parâmetro de rota | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | -------- | ----------- | -------------------------------- | | `id` | `string` | Sim | Identificador interno da adição. | ### Resposta de sucesso ```json { "title": "Success", "balanceTransaction": { "_id": "66f0b1b5c1f7b7dc0ce40001", "user": "66f0b1b5c1f7b7dc0ce20001", "status": "COMPLETED", "summary": { "totalItems": 1, "completedItems": 1, "failedItems": 0, "totalTargetGmc": 1000, }, "items": [ { "customerIdentifier": "66f0b1b5c1f7b7dc0ce20001", "sourceAmount": 1000, "sourceCurrency": "GMC", "targetGmcAmount": "1000", "status": "COMPLETED", "error": null, "customerWalletAddress": "0x...", "destinationWalletAddress": "0x...", "fees": { "fixedBrl": 0, "percentageBrl": 0, "totalBrl": 0, "issueTaxBrl": 0, "issueTaxRate": 0, "ixedFeeSource": "not-applied", "percentageFeeSource": "not-applied", "issueTaxSource": "not-applied", }, "conversion": { "brlPerGmc": 0, "usdtBrlRate": 0, "sourceAmountBrl": 0, }, "blockchain": { "mintHash": null, "approveHash": null, "transferHash": null, }, "processedAt": "1783378670", } ], "createdAt": "1783378670", "updatedAt": "1783378670", } } ``` ### Códigos de retorno | Código | Significado | Ação recomendada | | ------ | ----------------------------------------------------------------- | -------------------------------------------------------------- | | `200` | Adição encontrada. | Atualizar a conciliação e o estado interno da adição. | | `401` | Token inválido. | Renovar a sessão da API com o acesso de integração correto. | | `417` | Cobranç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;