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.

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.

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

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

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.

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:

Campos de resposta:

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.

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.

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:

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.

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:

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

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:

Listar pedidos

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
• Visão geral da consulta e paginação
• Carteira de financiamento
• Guia de atualização

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 · Verificação de assinaturas, respostas e novas tentativas