> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.6mm.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server. # Transferências e reconciliação de contratos Este guia é dirigido a **Agent Java SDK `v0.3.0`**, Java 8+ e ao contrato público assinalado. Os exemplos são executados num back-end de parceiro após a inicialização de `client` em [Início rápido](/pt-PT/sdk/agent-sdk/java/quick-start). ## Pré-requisitos de exemplo Os trechos Java partilham estas importações. Inicialize `client` utilizando o Quick Start e obtenha `platformUserId` a partir da ligação guardada. Os exemplos de IDs de utilizador/encomenda devem ser substituídos pelos seus próprios valores persistentes. ```java import com.sixmm.agent.*; import com.sixmm.agent.model.*; import java.util.*; ``` ## Transferência de montante fixo Utilize `transfer` para transferências de montante fixo. `Direction.IN` significa transferir da plataforma do parceiro para 6MM. `Direction.OUT` significa transferir de 6MM de volta à plataforma do parceiro. Utilize strings ou `BigDecimal` para os valores. Não utilize `double` ou `float`. ### Transferir por `agentUserId` ```java import com.sixmm.agent.model.Direction; import com.sixmm.agent.model.TransferRequest; import com.sixmm.agent.model.TransferResponse; TransferResponse resp = client.transfer(TransferRequest.fixed( "AGT-ORDER-1001", "agent-user-001", Direction.IN, "USDT", "10.00")); System.out.println(resp.orderNo); System.out.println(resp.orderStatus); System.out.println(resp.agentUserId); System.out.println(resp.platformUserId); ``` ### Transferir por `platformUserId` ```java TransferResponse resp = client.transfer(TransferRequest.fixedByPlatformUserId( "AGT-ORDER-1002", "1188041528", Direction.OUT, "USDT", "5.00")); ``` ### Forneça os dois IDs Se ambos os IDs forem fornecidos, o serviço validará que apontam para o mesmo utilizador vinculado. ```java TransferRequest req = TransferRequest .fixed("AGT-ORDER-1003", "agent-user-001", Direction.IN, "USDT", "20.00") .withPlatformUserId("1188041528"); TransferResponse resp = client.transfer(req); ``` Campos de solicitação: | Campo | Tipo | Obrigatório | Descrição | | ---------------- | ---------- | ---------------- | ----------------------------------------------------- | | `agentOrderNo` | string | Sim | Número de encomenda de parceiro globalmente exclusivo | | `agentUserId` | string | Condicionalmente | Obrigatório quando `platformUserId` está ausente | | `platformUserId` | string | Condicionalmente | Obrigatório quando `agentUserId` está ausente | | `direction` | enumeração | Sim | `IN` ou `OUT` | | `currency` | string | Não | Preenchido de `defaultCurrency` quando ausente | | `amount` | string | Sim | Sequência de valor decimal | Campos de resposta: | Campo | Tipo | Descrição | | ---------------- | ------ | --------------------------------------- | | `orderNo` | string | Número de encomenda da plataforma | | `orderStatus` | string | `SUCCESS`, `FAILED`, `PROCESSING`, etc. | | `agentUserId` | string | ID de utilizador do parceiro | | `platformUserId` | string | 6MM ID de utilizador externo | ## Confirmação de encomenda e idempotência Depois de `transfer` ser chamado, o serviço do Agente chama de forma síncrona a negociação núcleo no caminho principal. Na maioria dos casos, a resposta API já contém o resultado do núcleo de negociação síncrono. | Resultado | Significado | Ação do parceiro | | ------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `SUCCESS` | Transferência bem-sucedida | Marcar pedido local como bem-sucedido | | `FAILED` | A transferência foi rejeitada ou falhou | Guarde o motivo da falha e mostre-o quando apropriado | | `PROCESSING` | Tempo limite do núcleo de negociação ou incerteza da rede | Não tente novamente com um novo número de encomenda. Aguarde webhook ou ligue para `queryOrder` | Requisitos de idempotência: * Utilize um `agentOrderNo` para uma transação comercial. * Se HTTP expirar ou a rede falhar, consulte primeiro o mesmo `agentOrderNo`. * Webhooks pode ser tentado novamente. Desduplica-os por chave de idempotência. ## Transferir tudo `transferAllOut` move o saldo sacável do lado 6MM do utilizador de volta para o plataforma parceira. ```java import com.sixmm.agent.model.TransferAllOutRequest; import com.sixmm.agent.model.TransferAllOutResponse; TransferAllOutResponse resp = client.transferAllOut( TransferAllOutRequest.of("AGT-ORDER-2001", "agent-user-001", "USDT")); System.out.println(resp.orderStatus); System.out.println(resp.amount); ``` Por `platformUserId`: ```java TransferAllOutResponse resp = client.transferAllOut( TransferAllOutRequest.byPlatformUserId("AGT-ORDER-2002", "1188041528", "USDT")); ``` `amount` na resposta é o valor real transferido. ## Ordem inversa O reverso é utilizado para compensar uma ordem de transferência bem-sucedida quando o back-end suporta o fluxo reverso. Os casos típicos incluem exceções de pedidos locais de parceiros ou reversão de reconciliação manual. ```java import com.sixmm.agent.model.ReverseOrderRequest; import com.sixmm.agent.model.ReverseOrderResponse; ReverseOrderResponse resp = client.reverse(ReverseOrderRequest.of( "AGT-ORDER-1001", "REV-ORDER-1001", "partner order rollback")); System.out.println(resp.orderStatus); ``` Campos: | Campo | Tipo | Obrigatório | Descrição | | ---------------- | ------ | ----------- | --------------------------------------------- | | `origOrderNo` | string | Sim | Número da ordem de transferência original | | `reverseOrderNo` | string | Sim | Número de ordem inverso globalmente exclusivo | | `reverseReason` | string | Sim | Razão reversa | Notas: * A reversão não é uma operação normal de cancelamento. * As ordens inversas também devem ser idempotentes por número de ordem. * Depois de um pedido original ser revertido, webhook poderá empurrar o pedido original `REVERSED` estado final. ## Ordem de consulta ```java import com.sixmm.agent.model.OrderQueryType; import com.sixmm.agent.model.QueryOrderRequest; import com.sixmm.agent.model.QueryOrderResponse; QueryOrderResponse resp = client.queryOrder( QueryOrderRequest.of("AGT-ORDER-1001", OrderQueryType.TRANSFER_IN)); System.out.println(resp.status); System.out.println(resp.failReason); ``` Valores `orderType` suportados: * `TRANSFER_IN` * `TRANSFER_OUT` Campos de resposta comuns: | Campo | Tipo | Descrição | | ---------------- | ------ | ------------------------------- | | `orderType` | string | Tipo de pedido | | `orderNo` | string | Número de encomenda do parceiro | | `status` | string | Estado do pedido | | `direction` | string | `IN` ou `OUT` | | `transferMode` | string | `FIXED_AMOUNT` ou `ALL_OUT` | | `currency` | string | Moeda | | `amount` | string | Montante | | `agentUserId` | string | ID de utilizador do parceiro | | `platformUserId` | string | 6MM ID de utilizador externo | | `failReason` | string | Motivo da falha | | `createdAt` | string | Hora de criação | | `completedAt` | string | Tempo de conclusão | ## Listar pedidos ```java import com.sixmm.agent.model.ListOrdersRequest; import com.sixmm.agent.model.ListOrdersResponse; ListOrdersRequest req = ListOrdersRequest.page(1, 20); req.orderType = "TRANSFER_IN"; req.status = "SUCCESS"; req.startTime = "2026-06-01T00:00:00Z"; req.endTime = "2026-06-16T00:00:00Z"; ListOrdersResponse resp = client.listOrders(req); System.out.println(resp.total); resp.orders.forEach(order -> System.out.println(order.orderNo)); ``` Recomendações de paginação: * `page` começa em 1. * Mantenha `pageSize` igual ou inferior a 100. * Para trabalhos de reconciliação, paginar por intervalo de tempo e desduplicar até `orderNo`. ## Fonte e guias relacionados * [Fonte oficial v0.3.0](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [Visão geral da consulta e paginação](/pt-PT/sdk/agent-sdk/java/perpetual-queries) * [Carteira de financiamento](/pt-PT/sdk/agent-sdk/java/funding-wallet) * [Guia de atualização](/pt-PT/sdk/agent-sdk/java/upgrade) ## Retornos de chamada de eventos de fundos `transfer.completed` pode conter `SUCCESS`, `FAILED` ou uma atualização de encomenda original de `REVERSED`; `reverse.completed` é um evento terminal de ordem de reversão. `transfer.dead` significa que o estado final permanece não confirmado após novas tentativas e necessita de reconciliação manual, e não de uma falha confirmada. O nome do evento por si só não prova que os fundos foram creditados. O reconhecimento bem-sucedido é diferente da movimentação bem-sucedida de fundos: após o registo de uma notificação `targetStatus=FAILED` válida, devolva também HTTP 2xx. Persistir à desduplicação de eventos de fundos por `orderType:orderId:targetStatus` no âmbito do comerciante e `environment`. [Campos de evento e exemplos JSON](/pt-PT/sdk/agent-sdk/java/webhook-events) · [Verificação de assinaturas, respostas e novas tentativas](/pt-PT/sdk/security/webhooks-idempotency)