KMS_Backend_API.postman_collection.json

{
  "info": {
    "name": "KMS Backend API",
    "description": "Kaia Money Stream (KMS) 백엔드 API 컬렉션\n\n이 컬렉션은 블록체인 기반 실시간 자금 스트리밍 서비스를 위한 Mock API를 포함합니다.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_postman_id": "kms-backend-api-collection",
    "version": {
      "major": 1,
      "minor": 0,
      "patch": 0
    }
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "test_api_key_12345",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "http://localhost:3000",
      "type": "string"
    },
    {
      "key": "apiKey",
      "value": "test_api_key_12345",
      "type": "string"
    },
    {
      "key": "sampleStreamId",
      "value": "550e8400-e29b-41d4-a716-446655440000",
      "type": "string"
    },
    {
      "key": "sampleWalletAddress",
      "value": "0xfedcba0987654321fedcba0987654321fedcba09",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "스트림 관리",
      "item": [
        {
          "name": "스트림 생성",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"project_beta_2024_02\",\n  \"sender_wallet\": \"0x1234567890123456789012345678901234567890\",\n  \"receiver_wallet\": \"0xabcdef1234567890abcdef1234567890abcdef12\",\n  \"total_amount\": \"5000.000000\",\n  \"duration_in_seconds\": 2592000,\n  \"stream_type\": \"project\",\n  \"display_name\": \"베타 프로젝트 개발비\",\n  \"description\": \"2024년 베타 프로젝트 개발 계약\",\n  \"start_time\": \"2024-02-01T00:00:00Z\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams"]
            },
            "description": "새로운 머니 스트림을 생성하고 블록체인에 자금을 예치합니다.\n\n**처리 과정:**\n- API 키 검증 및 회사 정보 확인\n- 스트림 정보 DB 저장\n- 실시간 계산용 캐시 설정\n- 블록체인에 자금 예치 트랜잭션 실행"
          },
          "response": [
            {
              "name": "성공 응답",
              "originalRequest": {
                "method": "POST",
                "header": [
                  {
                    "key": "Content-Type",
                    "value": "application/json"
                  },
                  {
                    "key": "Authorization",
                    "value": "Bearer test_api_key_12345"
                  }
                ],
                "body": {
                  "mode": "raw",
                  "raw": "{\n  \"external_id\": \"project_beta_2024_02\",\n  \"sender_wallet\": \"0x1234567890123456789012345678901234567890\",\n  \"receiver_wallet\": \"0xabcdef1234567890abcdef1234567890abcdef12\",\n  \"total_amount\": \"5000.000000\",\n  \"duration_in_seconds\": 2592000,\n  \"stream_type\": \"project\",\n  \"display_name\": \"베타 프로젝트 개발비\",\n  \"description\": \"2024년 베타 프로젝트 개발 계약\"\n}"
                },
                "url": {
                  "raw": "{{baseUrl}}/api/v1/streams",
                  "host": ["{{baseUrl}}"],
                  "path": ["api", "v1", "streams"]
                }
              },
              "status": "Created",
              "code": 201,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "cookie": [],
              "body": "{\n  \"success\": true,\n  \"data\": {\n    \"stream_id\": \"bd547be2-cd88-4816-8747-d365f3204937\",\n    \"external_id\": \"project_beta_2024_02\",\n    \"status\": \"created\",\n    \"flow_rate\": \"0.001929\",\n    \"total_amount\": \"5000.000000\",\n    \"blockchain_stream_id\": null,\n    \"blockchain_tx_hash\": null,\n    \"created_at\": \"2025-08-24T08:16:17.757Z\",\n    \"estimated_completion\": \"2025-08-24T08:18:17.757Z\"\n  },\n  \"message\": \"USDT 스트림 생성 요청이 처리되었습니다. 블록체인 트랜잭션 완료까지 약 2분 소요됩니다.\"\n}"
            }
          ]
        },
        {
          "name": "스트림 목록 조회",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams?type=project&status=active&limit=20&offset=0&sort=created_at&order=desc",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams"],
              "query": [
                {
                  "key": "type",
                  "value": "project",
                  "description": "스트림 유형 (project, salary, subscription, dividend, donation)"
                },
                {
                  "key": "status",
                  "value": "active",
                  "description": "상태 필터 (active, paused, completed, failed)"
                },
                {
                  "key": "limit",
                  "value": "20",
                  "description": "페이지 크기 (기본 20, 최대 100)"
                },
                {
                  "key": "offset",
                  "value": "0",
                  "description": "페이지 오프셋"
                },
                {
                  "key": "sort",
                  "value": "created_at",
                  "description": "정렬 기준 (created_at, total_amount, status)"
                },
                {
                  "key": "order",
                  "value": "desc",
                  "description": "정렬 순서 (asc, desc)"
                },
                {
                  "key": "search",
                  "value": "",
                  "description": "검색어 (display_name, external_id에서 검색)",
                  "disabled": true
                }
              ]
            },
            "description": "회사별 스트림 목록을 필터링/정렬/페이징하여 조회합니다."
          },
          "response": []
        },
        {
          "name": "스트림 상세 조회",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams/{{sampleStreamId}}",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams", "{{sampleStreamId}}"]
            },
            "description": "스트림의 현재 상태와 실시간 계산된 잔액 정보를 조회합니다.\n\n**처리 과정:**\n- Redis 캐시나 DB에서 실시간 잔액 계산\n- DB에서 스트림 기본 정보 조회\n- 블록체인 동기화 상태 확인\n- 통합된 응답 데이터 반환"
          },
          "response": []
        }
      ],
      "description": "스트림 생성, 조회, 관리 관련 API"
    },
    {
      "name": "스트림 제어",
      "item": [
        {
          "name": "스트림 일시정지",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"reason\": \"예산 검토 필요\",\n  \"pause_duration\": 86400,\n  \"auto_resume\": true\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams/{{sampleStreamId}}/pause",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams", "{{sampleStreamId}}", "pause"]
            },
            "description": "활성 스트림을 일시정지하여 자금 흐름을 중단합니다."
          },
          "response": []
        },
        {
          "name": "스트림 재개",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams/{{sampleStreamId}}/resume",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams", "{{sampleStreamId}}", "resume"]
            },
            "description": "일시정지된 스트림을 재개합니다."
          },
          "response": []
        }
      ],
      "description": "스트림 일시정지, 재개 등 제어 관련 API"
    },
    {
      "name": "지갑 관리",
      "item": [
        {
          "name": "출금 가능 금액 조회",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/wallets/{{sampleWalletAddress}}/withdrawable",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "wallets", "{{sampleWalletAddress}}", "withdrawable"]
            },
            "description": "특정 지갑 주소의 총 출금 가능 금액을 조회합니다 (여러 스트림 합산)."
          },
          "response": []
        },
        {
          "name": "출금 실행",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"amount\": \"1000.000000\",\n  \"stream_ids\": [\"{{sampleStreamId}}\"]\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/wallets/{{sampleWalletAddress}}/withdraw",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "wallets", "{{sampleWalletAddress}}", "withdraw"]
            },
            "description": "실제 출금을 실행합니다 (Mock 구현)."
          },
          "response": []
        }
      ],
      "description": "지갑 관련 출금 기능 API"
    },
    {
      "name": "테스트 시나리오",
      "item": [
        {
          "name": "시나리오 1: 프로젝트 스트림 생성",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"project_gamma_2024_03\",\n  \"sender_wallet\": \"0x9876543210987654321098765432109876543210\",\n  \"receiver_wallet\": \"0x1111111111111111111111111111111111111111\",\n  \"total_amount\": \"10000.000000\",\n  \"duration_in_seconds\": 5184000,\n  \"stream_type\": \"project\",\n  \"display_name\": \"감마 프로젝트 개발비\",\n  \"description\": \"2024년 감마 프로젝트 블록체인 개발 계약\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams"]
            },
            "description": "새로운 프로젝트 스트림을 생성하는 테스트 시나리오"
          },
          "response": []
        },
        {
          "name": "시나리오 2: 급여 스트림 생성",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"salary_feb_2024\",\n  \"sender_wallet\": \"0x2222222222222222222222222222222222222222\",\n  \"receiver_wallet\": \"0x3333333333333333333333333333333333333333\",\n  \"total_amount\": \"3000.000000\",\n  \"duration_in_seconds\": 2678400,\n  \"stream_type\": \"salary\",\n  \"display_name\": \"2월 급여\",\n  \"description\": \"2024년 2월 정규 급여 지급\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams"]
            },
            "description": "급여 스트림을 생성하는 테스트 시나리오"
          },
          "response": []
        },
        {
          "name": "시나리오 3: 유효하지 않은 지갑 주소",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Authorization",
                "value": "Bearer {{apiKey}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_id\": \"test_invalid_wallet\",\n  \"sender_wallet\": \"invalid_wallet_address\",\n  \"receiver_wallet\": \"0x1111111111111111111111111111111111111111\",\n  \"total_amount\": \"1000.000000\",\n  \"duration_in_seconds\": 86400,\n  \"stream_type\": \"project\",\n  \"display_name\": \"테스트 스트림\",\n  \"description\": \"유효하지 않은 지갑 주소 테스트\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams"]
            },
            "description": "유효하지 않은 지갑 주소로 스트림 생성을 시도하는 에러 테스트 시나리오"
          },
          "response": []
        },
        {
          "name": "시나리오 4: 인증 실패",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer invalid_api_key",
                "description": "잘못된 API 키"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/streams",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "streams"]
            },
            "description": "잘못된 API 키로 인한 인증 실패 테스트 시나리오"
          },
          "response": []
        }
      ],
      "description": "다양한 테스트 시나리오를 포함한 API 테스트"
    }
  ],
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// 공통 전처리 스크립트",
          "console.log('KMS Backend API 요청 시작:', pm.info.requestName);"
        ]
      }
    },
    {
      "listen": "test",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// 공통 테스트 스크립트",
          "pm.test('응답 시간이 5초 이내', function () {",
          "    pm.expect(pm.response.responseTime).to.be.below(5000);",
          "});",
          "",
          "pm.test('Content-Type이 JSON', function () {",
          "    pm.expect(pm.response.headers.get('Content-Type')).to.include('application/json');",
          "});",
          "",
          "// 성공적인 응답에 대한 기본 구조 검증",
          "if (pm.response.code >= 200 && pm.response.code < 300) {",
          "    pm.test('응답에 success 필드가 존재', function () {",
          "        const jsonData = pm.response.json();",
          "        pm.expect(jsonData).to.have.property('success');",
          "    });",
          "}",
          "",
          "console.log('응답 상태:', pm.response.status, '응답 시간:', pm.response.responseTime + 'ms');"
        ]
      }
    }
  ]
}