Trasferimenti e riconciliazione del contratto

Questa guida è rivolta a Agent Java SDK v0.3.0, Java 8+ e agli appalti pubblici contrassegnati. Gli esempi vengono eseguiti nel backend di un partner dopo aver inizializzato client in Avvio rapido.

Prerequisiti di esempio

Gli snippet Java condividono queste importazioni. Inizializza client utilizzando Quick Start e ottieni platformUserId dall’associazione salvata. Gli ID utente/ordine di esempio devono essere sostituiti con i tuoi valori persistenti.

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

Trasferimento di importo fisso

Utilizza transfer per i trasferimenti con importo fisso. Direction.IN significa trasferire dalla piattaforma partner a 6MM. Direction.OUT significa trasferimento da 6MM tornare alla piattaforma partner.

Utilizza stringhe o BigDecimal per gli importi. Non utilizzare double o float.

Trasferimento tramite 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);

Trasferimento tramite platformUserId

TransferResponse resp = client.transfer(TransferRequest.fixedByPlatformUserId(
        "AGT-ORDER-1002",
        "1188041528",
        Direction.OUT,
        "USDT",
        "5.00"));

Fornire entrambi gli ID

Se vengono forniti entrambi gli ID, il servizio verifica che puntino allo stesso utente vincolato.

TransferRequest req = TransferRequest
        .fixed("AGT-ORDER-1003", "agent-user-001", Direction.IN, "USDT", "20.00")
        .withPlatformUserId("1188041528");
TransferResponse resp = client.transfer(req);

Campi richiesta:

Campi di risposta:

Conferma d’ordine e idempotenza

Dopo che transfer viene chiamato, il servizio Agent chiama in modo sincrono il trading nucleo sul percorso principale. Nella maggior parte dei casi, la risposta API contiene già il file risultato del trading sincrono.

Requisiti di idempotenza:

• Utilizza un agentOrderNo per una transazione commerciale.
• Se HTTP scade o la rete si guasta, interroga prima lo stesso agentOrderNo.
• Webhooks può essere riprovato. Deduplicarli tramite chiave di idempotenza.

Trasferisci tutto

transferAllOut riporta il saldo prelevabile dal lato 6MM dell’utente al piattaforma partner.

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);

Da platformUserId:

TransferAllOutResponse resp = client.transferAllOut(
        TransferAllOutRequest.byPlatformUserId("AGT-ORDER-2002", "1188041528", "USDT"));

amount nella risposta è l’importo effettivamente trasferito.

Ordine inverso

Il reverse viene utilizzato per compensare un ordine di trasferimento andato a buon fine quando il backend supporta il flusso inverso. I casi tipici includono eccezioni agli ordini locali dei partner o rollback della riconciliazione manuale.

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);

Campi:

Note:

• L’inversione non è una normale operazione di annullamento.
• Anche gli ordini inversi devono essere idempotenti in base al numero dell’ordine.
• Dopo che un ordine originale è stato annullato, webhook può spingere l’ordine originale REVERSED stato finale.

Ordine delle interrogazioni

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);

Valori orderType supportati:

• TRANSFER_IN
• TRANSFER_OUT

Campi di risposta comuni:

Elenco ordini

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));

Consigli per l’impaginazione:

• page inizia da 1.
• Mantieni pageSize pari o inferiore a 100.
• Per i processi di riconciliazione, pagina per intervallo temporale e deduplica entro orderNo.

Fonte e guide correlate

• Fonte ufficiale v0.3.0
• Panoramica delle query e impaginazione
• Portafoglio di finanziamento
• Guida all’aggiornamento

Fondi callback di eventi

transfer.completed può trasportare SUCCESS, FAILED o un aggiornamento dell’ordine originale di REVERSED; reverse.completed è un evento terminale dell’ordine di inversione. transfer.dead significa che lo stato finale rimane non confermato dopo i nuovi tentativi e necessita di una riconciliazione manuale, non di un errore confermato. Il solo nome dell’evento non dimostra che i fondi siano stati accreditati.

La conferma di successo è diversa dal movimento di fondi riuscito: dopo aver registrato una notifica targetStatus=FAILED valida, restituisci anche HTTP 2xx. Persistenza della deduplicazione degli eventi fondi da parte di orderType:orderId:targetStatus all’interno dell’ambito del commerciante e environment.

Campi evento ed esempi di JSON. · Verifica della firma, risposte e tentativi