대량 주문 실행 전 API를 통한 잔액 확인

대기열 실행 전 잔액을 조회해야 하는 이유

최신 잔액 확인 없이 대량 주문을 실행하면 부분 실패가 발생합니다. 처음 몇 건의 요청은 생성되지만 이후 요청은 자금 부족 오류를 받게 됩니다. 병렬 전송, 서로 다른 서비스, 하나의 계정으로 작업하는 여러 프로세스가 얽힌 상황에서는 이런 문제를 해결하기가 가장 어렵습니다.

실행에 중요한 것은 총 충전 금액이나 개인 계정의 회계상 잔액이 아닙니다. 새 주문을 생성하는 시점에 서비스가 차감을 허용하는 금액이 필요합니다. 활성 요청에 대한 금액은 이미 예약되어 있을 수 있지만, 최종 차감은 아직 거래 내역에 반영되지 않았을 수 있습니다.

대기열 예산은 계정의 총액이 아니라 사용 가능한 잔액 필드와 비교하세요.

잔액 메서드 응답의 형태

필드 이름은 각 플랫폼의 문서에서 정하지만, 편리한 잔액 메서드 계약은 보통 total, available, reserved, currency, updated_at을 반환합니다. 아래는 연동 시 참고할 수 있는 구조 예시입니다. 모든 서비스에 통용되는 응답이 아니라 이해하기 쉬운 데이터 스키마의 예시입니다.

요청은 다음과 같을 수 있습니다:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

응답:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

이 예시에서 total은 계정의 전체 자금, available은 새 주문에 사용할 수 있는 금액, reserved는 이전에 생성된 작업에 대한 금액입니다. 검증은 일치합니다: 125.80에서 41.30을 빼면 84.50입니다. currency 필드는 계산 단위를 정하고, updated_at은 데이터가 얼마나 최신인지 파악하는 데 도움이 됩니다.

available과 reserved를 해석하는 방법

available 필드는 실행 여부를 결정하는 데 사용합니다. 대기열이 80.00이고 available이 84.50이라면, API가 별도 수수료를 추가하지 않거나 주문 생성 시점에 가격을 재계산하지 않는 경우에만 자금이 충분합니다. reserved 필드는 사용 가능한 잔액에 더하지 않습니다. 이 금액은 이미 점유되어 있습니다.

reserved에는 processing, pending 또는 review 상태인 주문의 비용이 포함될 수 있으며, 정확한 범위는 플랫폼 규칙에 따라 다릅니다. 때로는 취소, 부분 완료 또는 수동 검토 후에 예약이 해제됩니다. 따라서 주문 목록을 바탕으로 직접 계산하는 것은 추가 검증 용도로만 사용할 수 있습니다.

• total은 충전 및 차감 내역과 대조하는 데 적합합니다.
• available은 새 대기열의 실행 승인에 적합합니다.
• reserved는 활성 작업에 이미 얼마나 많은 자금이 잠겨 있는지 보여줍니다.
• currency는 하나의 계정으로만 작업하더라도 무시할 수 없습니다.
• updated_at은 로그와 오래된 응답 진단에 유용합니다.

balance 필드만 있는 응답은 처리하기 더 간단하지만 단점이 있습니다. 이 자금이 즉시 사용 가능한지, 아니면 일부가 다른 주문에 이미 묶여 있는지 알 수 없습니다.

API 문서에서 금액 형식을 확인하세요

예시에서 금액은 숫자 84.5가 아니라 문자열 "84.50"으로 전달됩니다. 이러한 형식은 서비스가 반환한 정확한 값을 유지합니다. API가 소수점이 있는 문자열을 사용한다면, 즉시 부동 소수점 숫자로 변환하여 float로 비교해서는 안 됩니다.

예를 들어 계산 결과가 기대한 84.50 대신 84.499999가 나올 수 있습니다. 예산 경계에서는 이로 인해 대기열을 잘못 통과시키거나 반대로 중단시킬 수 있습니다. 문자열 소수점 값을 다루는 작업에는 고정 소수점 정밀도를 지원하는 십진수 데이터 타입을 사용하세요.

또 다른 일반적인 계약은 정수 최소 단위입니다. 이 경우 응답에 "available_minor": 8450과 "currency": "USD"가 포함될 수 있고, 주문 가격은 "price_minor": 1250일 수 있습니다. 통화 규칙이 소수점 두 자리를 가정한다면, 이러한 API 내에서 8450은 84.50을 의미합니다. 값을 100으로 나누는 것은 문서에 명시된 경우에만 가능합니다.

통화와 가격 형식을 혼합하지 마세요

대기열을 계산하기 전에 잔액의 currency를 가격 메서드 또는 주문 생성 응답의 통화와 비교하세요. 잔액이 한 통화를 반환하고 서비스 카탈로그가 다른 통화를 반환한다면 숫자를 직접 대입할 수 없습니다. 플랫폼 자체에서 제공하는 계산이나 별도의 검증된 환전 메서드가 필요합니다.

자체적으로 사전 환전하는 것은 계획 수립에 편리하지만 단점이 있습니다. 서비스가 차감 시점에 다른 환율, 수수료 또는 반올림 규칙을 적용할 수 있습니다. API가 잔액 통화로 최종 비용을 반환하는 매개변수로 주문을 보내거나, 생성 직전에 가격 계산을 받는 것이 더 안정적입니다.

가격 메서드가 "price": "12.345"를 반환하고 잔액이 소수점 두 자리로 값을 저장한다면 반올림 규칙을 확인하세요. 자동으로 내림하지 마세요. 실제 차감이 더 높을 수 있습니다. 대기열 승인에는 API가 주문의 최종 비용이라고 하는 금액을 사용하세요.

첫 요청 전에 대기열 예산을 계산하세요

실행 전에 모든 요청을 모으고 볼륨, 선택한 서비스, 지역, 추가 옵션 및 별도로 전달되는 경우 수수료를 고려하여 비용을 계산하세요. available을 인터페이스의 기본 가격과 비교하지 마세요. API에서는 총액이 특정 주문의 매개변수에 따라 달라질 수 있습니다.

대기열에 세 건의 주문이 있다고 가정해 봅시다. 가격 계산 API가 이들에 대해 balance.currency에 명시된 것과 동일한 통화로 18.40, 27.15, 31.60을 반환했습니다. 예산은 77.15입니다. balance.available이 84.50이라면 계획된 실행 후 7.35가 남습니다. available이 76.90이라면 전체 대기열을 실행할 수 없습니다.

1. 각 주문의 실제 매개변수로 가격을 조회합니다.
2. 형식과 통화를 변경하지 않고 최종 비용을 합산합니다.
3. 예산을 최신 잔액 응답의 available과 비교합니다.
4. 잔액이 충분하면 해당 금액을 로컬 실행 예약으로 고정합니다.
5. 각 요청 생성 후 확인된 비용만큼 로컬 예약을 줄입니다.

여유분은 추가 차감 시 거절 위험을 줄이지만 단점이 있습니다. 대기열이 완전히 처리될 수 있었음에도 사용 가능한 자금의 일부가 사용되지 않고 남습니다.

전송 직전에 두 번째 확인을 하세요

캠페인 준비 중에 받은 잔액은 빠르게 최신성을 잃습니다. 계산과 실행 사이에 다른 운영자, 자동화 또는 활성 주문이 available과 reserved를 변경할 수 있습니다. 대기열을 구성한 후 그리고 첫 요청 직전에 재조회가 필요합니다.

작업 흐름은 두 단계로 구성됩니다. 먼저 가격을 조회하고 예산을 평가한 다음, balance를 다시 요청합니다. available 값이 줄어들어 계산된 금액보다 낮아지면 대기열 전체를 보내지 않습니다. 최종 확인과 실행 사이에는 같은 계정에서 다른 차감을 수행해서는 안 됩니다.

전체 실행에 하나의 요청을 사용하면 API 부하가 줄어들지만, 긴 대기열이 아직 처리되는 동안 사용 가능한 잔액이 변경될 수 있다는 단점이 있습니다.

자금이 부족할 때 대기열을 실행하는 방법

available이 예산보다 적다면 일부가 통과할 것이라는 기대를 가지고 모든 요청을 보내지 마세요. 대기열을 사용 가능한 한도에 맞는 비용의 패키지로 나누세요. 잔액이 76.90인 예시에서는 45.55에 해당하는 처음 두 주문을 보낸 후 중단할 수 있습니다. 31.60에 해당하는 세 번째 주문은 재확인이 필요합니다.

배치 처리 시 요청 순서를 명시적으로 지정하세요. 우선순위가 높은 주문을 먼저 보내거나 비용이 비슷한 패키지를 구성할 수 있습니다. 각 방식에는 단점이 있습니다. 우선순위 순서는 덜 중요한 항목을 미루게 되고, 가격순 정렬은 원래 캠페인 계획을 어길 수 있습니다.

• 현재 available을 초과하지 않는 금액으로 패키지를 구성합니다.
• 패키지에서 주문을 생성하고 해당 식별자를 저장합니다.
• 응답을 기다리거나 타임아웃 후 작업 상태를 확인합니다.
• API 한도나 서비스 규칙에서 요구하는 경우 일시 중지합니다.
• 다음 패키지 전에 balance를 다시 요청합니다.

각 패키지 후에는 이전 잔액에서 로컬로 차감한 금액만이 아니라 새로운 API 응답을 기준으로 삼으세요. 로컬 계산은 제어에 유용하지만, 환불, 외부 차감 및 예약 재계산을 보지 못합니다.

병렬 전송 시 예산을 보호하세요

순차 처리에서는 주문 확인 후 로컬 한도를 줄이는 것으로 충분합니다. 병렬 모델에서는 두 워커가 동시에 available 84.50을 보고 각각 60.00의 지출을 계획할 수 있습니다. 두 결정은 개별적으로는 타당해 보이지만, 합치면 사용 가능한 잔액을 초과합니다.

보호를 위해서는 공유 로컬 예약 카운터나 원자적으로 접근되는 대기열이 필요합니다. 전송 전에 워커는 이 카운터에서 주문 금액을 점유하려고 시도합니다. 여유 한도가 부족하면 요청은 잔액 재확인을 기다리는 상태로 남습니다.

• 순차 대기열은 제어하기 더 쉽지만 실행 속도가 느립니다.
• 병렬 전송은 실행 시간을 단축하지만 공유 예산 잠금이 필요합니다.
• 로컬 예약은 충돌을 줄이지만 워커 장애 후 멈출 수 있습니다.
• API 측 예약이 더 안정적이지만 모든 플랫폼에서 제공되지는 않습니다.

응답을 받기 전에 프로세스가 종료되었다면 로컬 예약을 즉시 사용된 것으로도, 사용 가능한 것으로도 간주할 수 없습니다. 먼저 외부 식별자나 작업 조회 메서드로 주문이 생성되었는지 확인하세요.

API에서 제공하는 경우 예약 기능을 사용하세요

일부 API는 작업 집합에 대한 예약을 생성하거나 주문을 두 단계(계산, 금액 잠금, 확인)로 처리할 수 있습니다. 이러한 방식에서는 확인과 차감 사이에 다른 프로세스가 계정 자금을 사용할 수 있는 창이 줄어듭니다.

이러한 메서드가 있다면 예약 식별자, 금액, 통화, 유효 기간 및 상태를 저장하세요. 그런 다음 API 계약에서 요구하는 경우 주문 생성 시 이 식별자를 전달합니다. 대기열이 완료된 후에는 사용되지 않은 부분과 잠금 해제 여부를 대조하세요.

API 예약이 모든 문제를 해결하지는 않습니다. 유효 기간이 짧거나, 수수료를 포함하지 않거나, 확인 오류 후 해제될 수 있습니다. 로컬 예약은 구현하기 더 간단하지만, 애플리케이션 외부에서 발생한 지출로부터 보호하지 못한다는 단점이 있습니다.

잔액 오류와 잔액 0을 구분하세요

오류 코드 응답, 타임아웃 또는 요청 빈도 제한은 available이 0이라는 의미가 아닙니다. 대규모 실행이 이에 의존한다면 마지막으로 알려진 값을 자동으로 대입하지 마세요. 최신 잔액을 가져올 수 없다면 대기열을 일시 중지해야 합니다.

주문 생성 시 거절은 별도로 처리하세요. 자금 부족과 관련될 수 있지만, 잘못된 서비스 식별자, 허용되지 않는 볼륨, 채널 제한 또는 동일 작업의 중복과도 관련될 수 있습니다. 오류 코드와 텍스트는 요청의 외부 식별자와 함께 저장하세요.

• 인증 오류 시 액세스를 갱신한 후에만 요청을 반복하세요.
• 요청 한도 시 API 규칙에 따라 일시 중지하세요.
• 생성 타임아웃 시 먼저 작업이 실제로 나타났는지 확인하세요.
• 자금 부족 오류 시 패키지를 중단하고 balance를 다시 요청하세요.

타임아웃 후 중복을 생성하지 마세요

타임아웃은 서버가 요청을 처리하지 않았다는 것이 아니라 클라이언트가 응답을 받지 못했다는 의미입니다. 확인 없이 다시 보내면 두 번째 주문이 생성되고 자금이 다시 점유될 수 있습니다. 자동 재시도가 여러 번 설정된 대기열에서는 특히 위험합니다.

API가 client_order_id, external_id 또는 idempotency_key 필드를 지원한다면 고유한 외부 주문 식별자를 전달하세요. 요청을 보내기 전에 이를 저장하세요. 타임아웃 후 이 값으로 작업을 찾거나 이전에 받은 식별자로 상태를 요청하세요.

확인 없는 재시도는 더 빠르지만 단점은 분명합니다. 주문 중복, 이중 예약, 그리고 예산 계산과 실제 차감 간의 불일치가 발생할 수 있습니다.

실행 로그에 무엇을 저장할지

로그는 대량 작업의 진행 상황을 복원하고 특정 패키지가 왜 중단되었는지 설명하는 데 도움이 됩니다. 각 실행에 대해 두 번의 확인 시간, total, available, reserved, currency, 계산된 예산, 로컬 예약 크기 및 요청의 외부 식별자 목록을 저장하세요.

각 생성 시도에 대해 비용, 응답 코드, 작업의 기술 식별자 및 최종 상태를 기록하세요. 비밀 정보는 로그에 포함되지 않습니다. 인증 토큰, API 키, 전체 요청 헤더 및 개인 데이터는 기록 전에 마스킹하거나 제외해야 합니다.

전체 로깅은 디버깅에 편리하지만 단점이 있습니다. 필터링 없이는 액세스 데이터와 고객 정보가 저장소에 들어갈 수 있습니다.

소규모 대기열에서 스키마를 테스트하세요

대규모 실행 전에 짧은 시나리오를 진행하세요. balance를 받고, 최종 가격을 요청하고, 제한된 패키지를 생성하고, 다시 balance를 요청한 후 available과 reserved의 예상 변화를 실제 응답과 비교합니다. 이렇게 하면 서비스가 언제 금액을 예약하고 언제 최종 차감하는지 파악할 수 있습니다.

테스트 패키지가 높은 부하에서도 동일한 동작을 보장하지는 않습니다. 한도, 병렬 프로세스 또는 특정 서비스의 제한이 작동할 수 있습니다. 따라서 대량 대기열에서는 계속 실행을 패키지로 나누고, 그 사이에 사용 가능한 잔액을 확인하며, 각 거절을 개별적으로 분석하세요.