SDK 통합 문제 해결

지원 요청을 에스컬레이션하기 전에 Trading Widget, Agent SDK, 서명, webhook, 시간 초과 및 환경 문제를 진단하세요.

실패한 작업에 대한 환경, 타임스탬프, 비즈니스 식별자로 시작하세요. 구조화된 검사는 일반적으로 구성 문제를 인증, 네트워크 및 비동기 처리 문제와 분리합니다.

권장 진단 순서

영향을 받는 환경과 베이스 URL 를 확인하세요.
UTC 시간 범위와 첫 번째 실패한 요청을 기록합니다.
모듈을 식별합니다: Trading Widget, Agent SDK, REST API, WebSocket 또는 webhook.
요청 ID, 파트너 사용자 ID, agentOrderNo, 주문 ID 또는 webhook 이벤트 ID를 캡처합니다.
최근 코드, 자격 증명, IP 화이트리스트 또는 배포 변경 사항을 확인하세요.
가장 작은 안전 테스트 케이스로 재현합니다.

징후	가능한 원인	고치다
iframe은 파트너 로컬 도메인을 요청합니다.	baseUrl이 누락되었습니다.	baseUrl: ‘https://app.6mm.com’를 전달합니다.
iframe이 보이지 않거나 매우 짧습니다.	상위 컨테이너에는 높이가 없습니다.	컨테이너 높이 또는 통과 높이를 설정합니다.
token_provider_missing	파트너 토큰 모드에는 공급자가 없습니다.	인증을 추가합니다.tokenProvider.
인증 교환 실패	유효하지 않거나 만료되었거나 일치하지 않는 삽입 토큰	백엔드 토큰 응답과 channelId을 확인하세요.

Agent SDK 문제

징후	가능한 원인	고치다
서명이 거부됨	잘못된 비밀, 시계 드리프트 또는 수동으로 변경된 서명된 필드	SDK가 서명 필드를 생성하고 서버 시간을 동기화하도록 합니다.
중복 자금 이동 위험	시간 초과 후 사용된 새 주문 번호	먼저 원본 agentOrderNo으로 쿼리하세요.
PROCESSING 실패로 처리됨	보류 상태를 잘못 이해함	webhook을 기다리거나 queryOrder에 전화하세요.
Webhook가 여러 번 처리되었습니다.	멱등성 없는 재시도 동작	멱등성 키 및 최종 상태 확인을 추가합니다.

캡처할 증거

완성	유용한 증거
Trading Widget	페이지 URL, SDK 버전 경로, 브라우저 콘솔, 실패한 네트워크 요청, `onError` 페이로드 및 컨테이너 크기.
Agent SDK	SDK 언어/버전, 기본 URL, UTC 타임스탬프, 요청 ID, `agentOrderNo`, 응답 코드 및 삭제된 로그입니다.
Webhook	배달 시간, 이벤트 또는 비즈니스 키, 서명 유효성 검사 결과, 처리 상태 및 삭제된 원시 본문 해시입니다.
REST API	메서드, 경로, 환경, 요청 ID, 응답 코드 및 삭제된 매개변수입니다.

비밀번호, 액세스 토큰, API 비밀, 전체 서명, 개인 키 또는 수정되지 않은 개인 데이터를 진단에 포함하지 마세요.

에스컬레이션하기 전에

작업이 재시도해도 안전하다고 문서화된 경우에만 재시도하세요.
시간 초과 후에는 새 식별자를 만드는 대신 원래 비즈니스 식별자를 쿼리하세요.
서명 오류가 있는지 시스템 시계와 자격 증명 환경을 확인하세요.
첫 번째 실패와 이후의 재시도 결과를 유지합니다.
사용 지원 요청 템플릿 완전하고 수정된 보고서를 보내려면

관련 문서

Trading Widget 빠른 시작

스크립트 로딩, 컨테이너 크기, 구성 및 콜백을 확인합니다.

비밀 및 서명

Agent SDK 자격 증명, 시계 및 서명된 필드를 확인하세요.

Webhooks & 멱등성

콜백 확인 및 중복 이벤트 처리를 검토하세요.

Java v0.3.0 진단

징후	확인 및 복구
자금 요청에 알 수 없는 결과가 있습니다.	원본 `agentOrderNo`을 유지하세요. 원래 환경에서 `queryWalletTransfer`를 호출하세요. `queryOrder`를 사용하지 마세요.
시뮬레이션 UI에 예상치 못한 자금이 표시됨	백엔드 `environment`와 별도로 프런트엔드 `tradingMode`를 확인하세요. 계정 `isSimulatedUser`는 요청을 라우팅하지 않습니다.
쿼리 오류 `6905`	공유 파트너 할당량 사용을 중단한 다음 동일한 커서를 다시 시도하고 SDK을 통해 필터링합니다.
쿼리 오류 `6904`	동시 쿼리를 줄이고 시간 창을 좁힙니다. 지속되는 경우 지원팀에 문의하세요.
유효하지 않거나 만료된 커서	동일한 고정 기록 창을 다시 시작하고 저장된 기록을 중복 제거합니다.
새로운 Java 메서드가 누락되었습니다.	공개 태그 `v0.3.0`와 비교하여 해결된 Maven 아티팩트를 확인하세요. 아티팩트 정책에 따라 충돌하는 종속성을 제거합니다.

쿼리 및 오류 참조 · 업그레이드 가이드

Webhook 수신 문제

징후	점검 및 취급
실패 반환 후 재시도 없음 JSON	엔드포인트가 여전히 HTTP 200을 반환하는지 확인하세요. 전달은 본문의 성공 표시기가 아닌 HTTP 상태만 사용합니다.
401 또는 409 이후에도 재시도가 계속됩니다.	2xx가 아닌 응답은 기존 재시도 정책을 따릅니다. 서명, 알림 내용 또는 판매자 구성을 조사합니다.
청산 경고에 대한 빈 멱등성 키	현재 `WebhookVerifier.idempotencyKey`는 자금 이벤트 ID만 추출합니다. 서명 및 소유권을 확인한 후 `notificationId`을 검증하고 판매자 코드에 경고 키를 생성합니다. 빈 키를 사용하지 마십시오.
성공적으로 처리된 후 중복 알림	판매자 및 `environment` 범위 내에서 중복 제거를 유지합니다. 동일한 중복에 대해서는 2xx를 반환합니다. 충돌을 기록하고 다른 본문을 가진 동일한 ID에 대해 2xx가 아닌 것을 반환합니다.
경고가 처리되지 않았습니다.	`liquidation.warning` 및 과거 `LIQUIDATION_WARNING`를 수락합니다. 사용자, 에피소드 또는 이벤트 유형별로 고유한 알림 ID를 그룹화하여 삭제하지 마세요.
수락된 알림이 보류 중인 작업을 잃습니다.	2xx를 반환하기 전에 안정적으로 작업을 저장하세요. 메모리 내 비동기 작업을 시작하는 것만으로는 충분하지 않습니다.

이벤트 필드 및 호환성 · HTTP 응답 및 안정적인 승인