Transferencias y conciliación de contratos

Esta guía está dirigida a Agent Java SDK v0.3.0, Java 8+ y el contrato público etiquetado. Los ejemplos se ejecutan en un backend asociado después de inicializar client en Inicio rápido.

Requisitos previos de ejemplo

Los fragmentos Java comparten estas importaciones. Inicialice client usando el Inicio rápido y obtenga platformUserId del enlace guardado. Los ID de usuario/pedido de ejemplo deben reemplazarse con sus propios valores persistentes.

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

Transferencia de cantidad fija

Utilice transfer para transferencias de monto fijo. Direction.IN significa transferir desde la plataforma de socios a 6MM. Direction.OUT significa transferir desde 6MM volver a la plataforma de socios.

Utilice cadenas o BigDecimal para cantidades. No utilice double o 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"));

Proporcionar ambas identificaciones

Si se proporcionan ambos ID, el servicio valida que apunten al mismo usuario 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 solicitud:

Campos de respuesta:

Confirmación de pedido e idempotencia

Después de llamar a transfer, el servicio del Agente llama sincrónicamente a la plataforma comercial. núcleo en el camino principal. En la mayoría de los casos, la respuesta API ya contiene el resultado central comercial sincrónico.

Requisitos de idempotencia:

• Utilice un agentOrderNo para una transacción comercial.
• Si HTTP se agota el tiempo de espera o la red falla, consulta el mismo agentOrderNo primero.
• Webhooks se puede volver a intentar. Deduplicarlos por clave de idempotencia.

Transferir todo hacia afuera

transferAllOut mueve el saldo del lado retirable 6MM del usuario de regreso al plataforma de socios.

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 en la respuesta es el monto real transferido.

Orden inverso

La inversión se utiliza para compensar una orden de transferencia exitosa cuando el backend apoya el flujo inverso. Los casos típicos incluyen excepciones de pedidos locales de socios o reversión manual de la conciliación.

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:

• La marcha atrás no es una operación de cancelación normal.
• Las órdenes inversas también deben ser idempotentes por número de orden.
• Después de revertir una orden original, webhook puede empujar la orden original REVERSED estado final.

Orden 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 admitidos:

• TRANSFER_IN
• TRANSFER_OUT

Campos de respuesta comunes:

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

Recomendaciones de paginación:

• page comienza desde 1.
• Mantenga pageSize en 100 o menos.
• Para trabajos de conciliación, página por ventana de tiempo y deduplicación por orderNo.

Guías fuente y relacionadas

• Fuente oficial v0.3.0
• Descripción general de consultas y paginación
• Cartera de financiación
• Guía de actualización

Devoluciones de llamadas de eventos de fondos

transfer.completed puede llevar SUCCESS, FAILED, o una actualización del pedido original de REVERSED; reverse.completed es un evento terminal de orden de reversión. transfer.dead significa que el estado final permanece sin confirmar después de los reintentos y necesita una conciliación manual, no un error confirmado. El nombre del evento por sí solo no prueba que se hayan acreditado los fondos.

El reconocimiento exitoso es distinto del movimiento de fondos exitoso: después de registrar una notificación targetStatus=FAILED válida, devuelve también HTTP 2xx. Persistir en la deduplicación de eventos de fondos por parte de orderType:orderId:targetStatus dentro del alcance del comerciante y environment.

Campos de eventos y JSON ejemplos · Verificación de firma, respuestas y reintentos