인증 (Auth)

1. 게스트 토큰 발급

비회원의 토큰을 발급받을 수 있습니다.

  • 비회원 토큰의 만료일은 발급일로부터 1개월입니다.

1.1. Example

$ curl 'https://api.moddo.kr/api/v1/user/guest/token' -i -X GET

1.2. HTTP

1.2.1. 요청

GET /api/v1/user/guest/token HTTP/1.1
Host: api.moddo.kr

1.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Set-Cookie: accessToken=access-token; Max-Age=0; Expires=Thu, 1 Jan 1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 133

{
  "accessToken" : "access-token",
  "refreshToken" : "refresh-token",
  "expiredAt" : "2026-05-02 14:40:20",
  "isMember" : false
}

1.3. Body

1.3.1. 응답

{
  "accessToken" : "access-token",
  "refreshToken" : "refresh-token",
  "expiredAt" : "2026-05-02 14:40:20",
  "isMember" : false
}

2. 액세스 토큰 재발급

`refreshToken`을 사용해 `accessToken`을 재발급받을 수 있습니다.

2.1. Example

$ curl 'https://api.moddo.kr/api/v1/user/reissue/token' -i -X PUT \
    -H 'Authorization: Bearer refresh-token'

2.2. HTTP

2.2.1. 요청

PUT /api/v1/user/reissue/token HTTP/1.1
Authorization: Bearer refresh-token
Host: api.moddo.kr
Content-Type: application/x-www-form-urlencoded

2.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 40

{
  "accessToken" : "new-access-token"
}

2.3. Body

2.3.1. 응답

{
  "accessToken" : "new-access-token"
}

3. 카카오톡 소셜 로그인

사용자가 카카오 소셜 로그인을 완료하면 인가 코드를 통해 카카오 `Access Token`을 발급받습니다. 발급된 토큰으로 카카오 사용자 정보를 조회한 뒤, 서비스의 `Access Token`을 생성해 쿠키로 전달합니다.

3.1. Example

$ curl 'https://api.moddo.kr/api/v1/login/oauth2/callback?code=test+code' -i -X GET

3.2. HTTP

3.2.1. 요청

GET /api/v1/login/oauth2/callback?code=test+code HTTP/1.1
Host: api.moddo.kr

3.2.2. 응답

HTTP/1.1 302 Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Set-Cookie: accessToken=access-token; Max-Age=0; Expires=Thu, 1 Jan 1970 00:00:00 GMT
Set-Cookie: accessToken=access-token; Max-Age=0; Expires=Thu, 1 Jan 1970 00:00:00 GMT
Location: https://www.moddo.kr
Location: https://www.moddo.kr

3.3. Body

3.3.1. 응답

4. 로그아웃

서비스 로그아웃과 카카오 로그아웃을 처리할 수 있습니다.

4.1. Example

$ curl 'https://api.moddo.kr/api/v1/logout' -i -X POST \
    --cookie 'accessToken=access-token'

4.2. HTTP

4.2.1. 요청

POST /api/v1/logout HTTP/1.1
Host: api.moddo.kr
Cookie: accessToken=access-token
Content-Type: application/x-www-form-urlencoded

4.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Set-Cookie: accessToken=; Max-Age=0; Expires=Thu, 1 Jan 1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 37

{
  "message" : "Logout successful"
}

4.3. Body

4.3.1. 응답

{
  "message" : "Logout successful"
}

5. 카카오 탈퇴

카카오 소셜 로그인 사용자의 서비스 탈퇴를 처리할 수 있습니다.

5.1. Example

$ curl 'https://api.moddo.kr/api/v1/unlink' -i -X DELETE \
    --cookie 'accessToken=access-token'

5.2. HTTP

5.2.1. 요청

DELETE /api/v1/unlink HTTP/1.1
Host: api.moddo.kr
Cookie: accessToken=access-token

5.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Set-Cookie: accessToken=; Max-Age=0; Expires=Thu, 1 Jan 1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 37

{
  "message" : "Unlink successful"
}

5.3. Body

5.3.1. 응답

{
  "message" : "Unlink successful"
}

6. 토큰 상태 확인

쿠키에 담긴 토큰의 유효성을 확인합니다.

6.1. Example

GET /api/v1/auth/check HTTP/1.1
Host: api.moddo.kr
Cookie: accessToken=valid-token

6.2. HTTP

6.2.1. 요청

$ curl 'https://api.moddo.kr/api/v1/auth/check' -i -X GET \
    --cookie 'accessToken=valid-token'

6.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 80

{
  "authenticated" : true,
  "user" : {
    "id" : 1,
    "role" : "USER"
  }
}

6.3. Body

6.3.1. 응답 (valid)

{
  "authenticated" : true,
  "user" : {
    "id" : 1,
    "role" : "USER"
  }
}

6.3.2. 응답 (invalid)

{
  "authenticated" : false,
  "reason" : "TOKEN_EXPIRED"
}
{
  "authenticated" : false,
  "reason" : "INVALID_TOKEN"
}

사용자 (User)

7. 사용자 정보 조회

로그인한 사용자의 정보를 조회할 수 있습니다.

7.1. Example

$ curl 'https://api.moddo.kr/api/v1/user' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

7.2. HTTP

7.2.1. 요청

GET /api/v1/user HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: api.moddo.kr

7.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 128

{
  "name" : "김모또",
  "email" : "moddo@example.com",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png"
}

7.3. Body

7.3.1. 요청

7.3.2. 응답

{
  "name" : "김모또",
  "email" : "moddo@example.com",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png"
}

캐릭터 (Character)

8. 캐릭터 조회

모임의 캐릭터를 조회할 수 있습니다.

  • ★: 러키 모또

  • ★★: 천사 모또 / 딸기 또또

  • ★★★: 마법사 또또 / 잠꾸러기 또또

8.1. Example

$ curl 'https://api.moddo.kr/api/v1/character?code=groupCode' -i -X GET \
    -H 'Accept: application/json'

8.2. HTTP

8.2.1. 요청

GET /api/v1/character?code=groupCode HTTP/1.1
Accept: application/json
Host: api.moddo.kr

8.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 229

{
  "id" : 1,
  "name" : "천사 모또",
  "rarity" : 2,
  "imageUrl" : "https://moddo-s3.s3.amazonaws.com/character/천사 모또-2.png",
  "imageBigUrl" : "https://moddo-s3.s3.amazonaws.com/character/천사 모또-2-big.png"
}

8.3. Body

8.3.1. 응답

{
  "id" : 1,
  "name" : "천사 모또",
  "rarity" : 2,
  "imageUrl" : "https://moddo-s3.s3.amazonaws.com/character/천사 모또-2.png",
  "imageBigUrl" : "https://moddo-s3.s3.amazonaws.com/character/천사 모또-2-big.png"
}

8.3.2. 응답 - 유효하지 않은 그룹 토큰

{
  "status" : 401,
  "message" : "토큰이 유효하지 않습니다."
}

8.3.3. 응답 - 누락된 그룹 토큰

{
  "status" : 401,
  "message" : "토큰이 없습니다."
}

도감 (Collection)

9. 도감 조회

로그인한 사용자의 캐릭터 수집 현황을 조회할 수 있습니다.

9.1. Example

$ curl 'https://api.moddo.kr/api/v1/collections' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

9.2. HTTP

9.2.1. 요청

GET /api/v1/collections HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: api.moddo.kr

9.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 201

{
  "collections" : [ {
    "id" : 1,
    "name" : "모또",
    "rarity" : 1,
    "acquiredAt" : "2026-04-02T14:40:25.888599321",
    "imageUrl" : "imageUrl",
    "imageBigUrl" : "imageBigUrl"
  } ]
}

9.3. Body

9.3.1. 응답

{
  "collections" : [ {
    "id" : 1,
    "name" : "모또",
    "rarity" : 1,
    "acquiredAt" : "2026-04-02T14:40:25.888599321",
    "imageUrl" : "imageUrl",
    "imageBigUrl" : "imageBigUrl"
  } ]
}

지출 (Expense)

10. 지출 내역 추가

지출 내역을 생성할 수 있습니다.

10.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/expenses' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "expenses" : [ {
    "amount" : 20000,
    "content" : "카페",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "amount" : 9000
    }, {
      "id" : 2,
      "amount" : 11000
    } ]
  } ]
}'

10.2. HTTP

10.2.1. 요청

POST /api/v1/groups/code/expenses HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 224
Host: api.moddo.kr

{
  "expenses" : [ {
    "amount" : 20000,
    "content" : "카페",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "amount" : 9000
    }, {
      "id" : 2,
      "amount" : 11000
    } ]
  } ]
}

Unresolved directive in expense.adoc - include::/home/runner/work/moddo-backend/moddo-backend/build/generated-snippets/expense-controller-test/create-expense/path-parameters.adoc[]

10.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 974

{
  "expenses" : [ {
    "id" : 1,
    "amount" : 100000,
    "content" : "하이디라오",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 50000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 50000
    } ]
  }, {
    "id" : 2,
    "amount" : 20000,
    "content" : "카페",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 9000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 11000
    } ]
  } ]
}

10.3. Body

10.3.1. 요청

{
  "expenses" : [ {
    "amount" : 20000,
    "content" : "카페",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "amount" : 9000
    }, {
      "id" : 2,
      "amount" : 11000
    } ]
  } ]
}

10.3.2. 응답

{
  "expenses" : [ {
    "id" : 1,
    "amount" : 100000,
    "content" : "하이디라오",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 50000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 50000
    } ]
  }, {
    "id" : 2,
    "amount" : 20000,
    "content" : "카페",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 9000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 11000
    } ]
  } ]
}

10.3.3. 응답 - 존재하지 않는 참여자

{
  "status" : 404,
  "message" : "해당 참여자를 찾을 수 없습니다."
}

11. 전체 지출 내역 조회

모임의 전체 지출 내역을 조회할 수 있습니다.

  • 날짜 기준 오름차순으로 조회됩니다.

  • 참여자별 지출 내역도 함께 조회됩니다.

11.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/expenses' -i -X GET

11.2. HTTP

11.2.1. 요청

GET /api/v1/groups/code/expenses HTTP/1.1
Host: api.moddo.kr

11.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 2272

{
  "expenses" : [ {
    "id" : 1,
    "amount" : 100000,
    "content" : "지출",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 1000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 50000
    } ]
  }, {
    "id" : 2,
    "amount" : 22000,
    "content" : "카페",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 10000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 12000
    } ]
  }, {
    "id" : 3,
    "amount" : 210000,
    "content" : "향수공방",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 70000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 70000
    }, {
      "id" : 3,
      "role" : "PARTICIPANT",
      "name" : "연노른자",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/2.png",
      "amount" : 70000
    } ]
  }, {
    "id" : 4,
    "amount" : 36000,
    "content" : "간술",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 12000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 12000
    }, {
      "id" : 3,
      "role" : "PARTICIPANT",
      "name" : "연노른자",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/2.png",
      "amount" : 12000
    } ]
  } ]
}

11.3. Body

11.3.1. 응답

{
  "expenses" : [ {
    "id" : 1,
    "amount" : 100000,
    "content" : "지출",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 1000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 50000
    } ]
  }, {
    "id" : 2,
    "amount" : 22000,
    "content" : "카페",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 10000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 12000
    } ]
  }, {
    "id" : 3,
    "amount" : 210000,
    "content" : "향수공방",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 70000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 70000
    }, {
      "id" : 3,
      "role" : "PARTICIPANT",
      "name" : "연노른자",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/2.png",
      "amount" : 70000
    } ]
  }, {
    "id" : 4,
    "amount" : 36000,
    "content" : "간술",
    "date" : "2025-02-03",
    "memberExpenses" : [ {
      "id" : 1,
      "role" : "MANAGER",
      "name" : "김모또",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
      "amount" : 12000
    }, {
      "id" : 2,
      "role" : "PARTICIPANT",
      "name" : "군계란",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
      "amount" : 12000
    }, {
      "id" : 3,
      "role" : "PARTICIPANT",
      "name" : "연노른자",
      "profile" : "https://moddo-s3.s3.amazonaws.com/profile/2.png",
      "amount" : 12000
    } ]
  } ]
}

12. 단일 지출 내역 조회

지출 내역 하나를 조회할 수 있습니다.

12.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/expenses/1' -i -X GET

12.2. HTTP

12.2.1. 요청

GET /api/v1/groups/code/expenses/1 HTTP/1.1
Host: api.moddo.kr

Unresolved directive in expense.adoc - include::/home/runner/work/moddo-backend/moddo-backend/build/generated-snippets/expense-controller-test/get-by-expense-id-success/path-parameters.adoc[]

12.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 271

{
  "id" : 1,
  "amount" : 25000,
  "content" : "카페",
  "date" : "2025-02-03",
  "memberExpenses" : [ {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "amount" : 12000
  } ]
}

12.3. Body

12.3.1. 응답

{
  "id" : 1,
  "amount" : 25000,
  "content" : "카페",
  "date" : "2025-02-03",
  "memberExpenses" : [ {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "amount" : 12000
  } ]
}

12.3.2. 응답 - 찾을 수 없는 지출 내역

{
  "status" : 404,
  "message" : "해당 지출내역을 찾을 수 없습니다. (Expense ID: 1)"
}

13. 지출 상세 내역 조회

정산의 전체 지출 상세 내역을 조회할 수 있습니다.

  • 날짜 기준 오름차순으로 정렬됩니다.

  • 참여자 이름은 목록 형태로 제공됩니다.

13.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/expenses/details' -i -X GET

13.2. HTTP

13.2.1. 요청

GET /api/v1/groups/code/expenses/details HTTP/1.1
Host: api.moddo.kr

Unresolved directive in expense.adoc - include::/home/runner/work/moddo-backend/moddo-backend/build/generated-snippets/expense-controller-test/get-expense-details-success/path-parameters.adoc[]

13.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 700

{
  "expenses" : [ {
    "id" : 1,
    "date" : "2025-02-03",
    "content" : "하이디라오",
    "totalAmount" : 100000,
    "groupMembers" : [ "김모또(총무)", "김반숙" ]
  }, {
    "id" : 2,
    "date" : "2025-02-03",
    "content" : "카페",
    "totalAmount" : 22000,
    "groupMembers" : [ "김모또(총무)", "김반숙" ]
  }, {
    "id" : 3,
    "date" : "2025-02-03",
    "content" : "향수공방",
    "totalAmount" : 210000,
    "groupMembers" : [ "김모또(총무)", "김반숙", "정에그" ]
  }, {
    "id" : 4,
    "date" : "2025-02-03",
    "content" : "간술",
    "totalAmount" : 36000,
    "groupMembers" : [ "김모또(총무)", "김반숙", "정에그" ]
  } ]
}

13.3. Body

13.3.1. 응답

{
  "expenses" : [ {
    "id" : 1,
    "date" : "2025-02-03",
    "content" : "하이디라오",
    "totalAmount" : 100000,
    "groupMembers" : [ "김모또(총무)", "김반숙" ]
  }, {
    "id" : 2,
    "date" : "2025-02-03",
    "content" : "카페",
    "totalAmount" : 22000,
    "groupMembers" : [ "김모또(총무)", "김반숙" ]
  }, {
    "id" : 3,
    "date" : "2025-02-03",
    "content" : "향수공방",
    "totalAmount" : 210000,
    "groupMembers" : [ "김모또(총무)", "김반숙", "정에그" ]
  }, {
    "id" : 4,
    "date" : "2025-02-03",
    "content" : "간술",
    "totalAmount" : 36000,
    "groupMembers" : [ "김모또(총무)", "김반숙", "정에그" ]
  } ]
}

14. 지출 내역 수정

지출 내역을 수정할 수 있습니다.

  • 경로의 `expenseId`를 기준으로 수정합니다.

14.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/expenses/1' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "amount" : 28000,
  "content" : "카페",
  "date" : "2025-02-02",
  "memberExpenses" : [ {
    "id" : 1,
    "amount" : 14000
  }, {
    "id" : 2,
    "amount" : 14000
  } ]
}'
$ echo '{
  "amount" : 28000,
  "content" : "카페",
  "date" : "2025-02-02",
  "memberExpenses" : [ {
    "id" : 1,
    "amount" : 14000
  }, {
    "id" : 2,
    "amount" : 14000
  } ]
}' | http PUT 'https://api.moddo.kr/api/v1/groups/code/expenses/1' \
    'Content-Type:application/json;charset=UTF-8'

14.2. HTTP

14.2.1. 요청

PUT /api/v1/groups/code/expenses/1 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 180
Host: api.moddo.kr

{
  "amount" : 28000,
  "content" : "카페",
  "date" : "2025-02-02",
  "memberExpenses" : [ {
    "id" : 1,
    "amount" : 14000
  }, {
    "id" : 2,
    "amount" : 14000
  } ]
}

Unresolved directive in expense.adoc - include::/home/runner/work/moddo-backend/moddo-backend/build/generated-snippets/expense-controller-test/update-expense-success/path-parameters.adoc[]

14.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

14.3. Body

14.3.1. 요청

{
  "amount" : 28000,
  "content" : "카페",
  "date" : "2025-02-02",
  "memberExpenses" : [ {
    "id" : 1,
    "amount" : 14000
  }, {
    "id" : 2,
    "amount" : 14000
  } ]
}

14.3.2. 응답

14.3.3. 응답 - 찾을 수 없는 지출 내역

{
  "status" : 404,
  "message" : "해당 지출내역을 찾을 수 없습니다. (Expense ID: 1)"
}

15. 지출 내역 삭제

지출 내역을 삭제할 수 있습니다.

15.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/expenses/1' -i -X DELETE

15.2. HTTP

15.2.1. 요청

DELETE /api/v1/groups/code/expenses/1 HTTP/1.1
Host: api.moddo.kr

Unresolved directive in expense.adoc - include::/home/runner/work/moddo-backend/moddo-backend/build/generated-snippets/expense-controller-test/delete-expense-success/path-parameters.adoc[]

15.2.2. 응답

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

16. 지출 이미지 URL 수정

지출 내역별 이미지 URL을 수정할 수 있습니다.

16.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/expenses/1/img' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "images" : [ "https://api.moddo.kr", "https://api.moddo.kr" ]
}'

16.2. HTTP

16.2.1. 요청

PUT /api/v1/groups/code/expenses/1/img HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 67
Host: api.moddo.kr

{
  "images" : [ "https://api.moddo.kr", "https://api.moddo.kr" ]
}

Unresolved directive in expense.adoc - include::/home/runner/work/moddo-backend/moddo-backend/build/generated-snippets/expense-controller-test/update-img-url-success/path-parameters.adoc[]

16.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

16.3. Body

16.3.1. 요청

{
  "images" : [ "https://api.moddo.kr", "https://api.moddo.kr" ]
}

모임 (Settlement)

17. 모임 생성

모임을 생성할 수 있습니다.

  • 모임을 생성하는 사용자의 `accessToken`이 필요합니다.

  • 생성할 모임의 이름을 요청 본문에 포함합니다.

  • 생성된 모임의 ID, 생성자(정산 담당자) ID, 생성 시간, 만료 시간, 계좌 정보를 확인할 수 있습니다.

  • 비회원이 생성한 모임은 1개월 후 자동 삭제됩니다.

17.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "name" : "모또 모임"
}'

17.2. HTTP

17.2.1. 요청

POST /api/v1/groups HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 30
Host: api.moddo.kr

{
  "name" : "모또 모임"
}

17.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 269

{
  "groupToken" : "code",
  "manager" : {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "userId" : 1,
    "isPaid" : true,
    "paidAt" : "2026-04-02T14:40:26.070554486"
  }
}

17.3. Body

17.3.1. 요청

{
  "name" : "모또 모임"
}

17.3.2. 응답

{
  "groupToken" : "code",
  "manager" : {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "userId" : 1,
    "isPaid" : true,
    "paidAt" : "2026-04-02T14:40:26.070554486"
  }
}

18. 계좌 추가

은행과 계좌 정보를 추가하거나 수정할 수 있습니다.

18.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/account' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "bank" : "우리은행",
  "accountNumber" : "1111-1111"
}'

18.2. HTTP

18.2.1. 요청

PUT /api/v1/groups/code/account HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 62
Host: api.moddo.kr

{
  "bank" : "우리은행",
  "accountNumber" : "1111-1111"
}
Table 1. /api/v1/groups/{code}/account
Parameter Description

code

정산 코드

18.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 235

{
  "id" : 1,
  "writer" : 1,
  "createdAt" : "2026-04-02T14:40:26.207456035",
  "expiredAt" : "2026-05-02T14:40:26.20746426",
  "bank" : "우리은행",
  "accountNumber" : "1111-1111",
  "deadline" : "2026-04-03T14:40:26.207473257"
}

18.3. Body

18.3.1. 요청

{
  "bank" : "우리은행",
  "accountNumber" : "1111-1111"
}

18.3.2. 응답

{
  "id" : 1,
  "writer" : 1,
  "createdAt" : "2026-04-02T14:40:26.207456035",
  "expiredAt" : "2026-05-02T14:40:26.20746426",
  "bank" : "우리은행",
  "accountNumber" : "1111-1111",
  "deadline" : "2026-04-03T14:40:26.207473257"
}

19. 모임 조회

모임 정보와 참여자 목록을 조회할 수 있습니다.

19.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code' -i -X GET

19.2. HTTP

19.2.1. 요청

GET /api/v1/groups/code HTTP/1.1
Host: api.moddo.kr
Table 2. /api/v1/groups/{code}
Parameter Description

code

정산 코드

19.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 293

{
  "id" : 1,
  "groupName" : "모또 모임",
  "members" : [ {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "userId" : 1,
    "isPaid" : true,
    "paidAt" : "2026-04-02T14:40:26.128795464"
  } ]
}

19.3. Body

19.3.1. 응답

{
  "id" : 1,
  "groupName" : "모또 모임",
  "members" : [ {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "userId" : 1,
    "isPaid" : true,
    "paidAt" : "2026-04-02T14:40:26.128795464"
  } ]
}

20. 모임 상단 조회

지출 내역 화면의 상단 정보를 조회할 수 있습니다.

20.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/header' -i -X GET

20.2. HTTP

20.2.1. 요청

GET /api/v1/groups/code/header HTTP/1.1
Host: api.moddo.kr
Table 3. /api/v1/groups/{code}/header
Parameter Description

code

정산 코드

20.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 168

{
  "groupName" : "모또 모임",
  "totalAmount" : 10000,
  "deadline" : "2026-04-03T14:40:26.187909543",
  "bank" : "우리은행",
  "accountNumber" : "1111-1111"
}

20.3. Body

20.3.1. 응답

{
  "groupName" : "모또 모임",
  "totalAmount" : 10000,
  "deadline" : "2026-04-03T14:40:26.187909543",
  "bank" : "우리은행",
  "accountNumber" : "1111-1111"
}

21. 모임(정산) 리스트 조회

사용자가 속한 정산 목록을 상태별로 조회할 수 있습니다.

21.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups?status=IN_PROGRESS&sort=LATEST&limit=20' -i -X GET

21.2. HTTP

21.2.1. 요청

GET /api/v1/groups?status=IN_PROGRESS&sort=LATEST&limit=20 HTTP/1.1
Host: api.moddo.kr
Parameter Description

status

정산 상태 (ALL | IN_PROGRESS | COMPLETED)

sort

정렬 방식 (LATEST | OLDEST )

limit

조회 개수 제한(min=1, max=100)

21.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 231

[ {
  "groupId" : 1,
  "groupCode" : "groupCode",
  "name" : "모또 모임",
  "totalAmount" : 10000,
  "totalMemberCount" : 5,
  "completedMemberCount" : 3,
  "createdAt" : "2026-02-22T18:14:13.285872",
  "completedAt" : null
} ]

21.3. Body

21.3.1. 응답

[ {
  "groupId" : 1,
  "groupCode" : "groupCode",
  "name" : "모또 모임",
  "totalAmount" : 10000,
  "totalMemberCount" : 5,
  "completedMemberCount" : 3,
  "createdAt" : "2026-02-22T18:14:13.285872",
  "completedAt" : null
} ]

22. 공유 링크 리스트 조회

사용자가 속한 정산의 공유 링크 목록을 조회할 수 있습니다.

22.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/list' -i -X GET

22.2. HTTP

22.2.1. 요청

GET /api/v1/groups/list HTTP/1.1
Host: api.moddo.kr

22.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 554

[ {
  "settlementId" : 1,
  "name" : "모또 모임",
  "groupCode" : "groupCode",
  "createdAt" : "2026-01-01T12:00:00",
  "completedAt" : null,
  "members" : [ {
    "id" : 1,
    "role" : "PARTICIPANT",
    "name" : "김반숙",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
    "userId" : 1,
    "isPaid" : false,
    "paidAt" : null
  } ]
}, {
  "settlementId" : 2,
  "name" : "두번째 모임",
  "groupCode" : "groupCode2",
  "createdAt" : "2026-01-02T12:00:00",
  "completedAt" : "2026-01-03T12:00:00",
  "members" : [ ]
} ]

22.3. Body

22.3.1. 응답

[ {
  "settlementId" : 1,
  "name" : "모또 모임",
  "groupCode" : "groupCode",
  "createdAt" : "2026-01-01T12:00:00",
  "completedAt" : null,
  "members" : [ {
    "id" : 1,
    "role" : "PARTICIPANT",
    "name" : "김반숙",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
    "userId" : 1,
    "isPaid" : false,
    "paidAt" : null
  } ]
}, {
  "settlementId" : 2,
  "name" : "두번째 모임",
  "groupCode" : "groupCode2",
  "createdAt" : "2026-01-02T12:00:00",
  "completedAt" : "2026-01-03T12:00:00",
  "members" : [ ]
} ]

모임원 (Member)

23. 모임원 조회

정산에 속한 전체 모임원을 조회할 수 있습니다.

  • `userId`는 해당 모임원에 연결된 사용자 ID입니다.

  • 아직 로그인 사용자가 선택하지 않은 참여자는 `userId`가 `null`로 내려갑니다.

  • `sortType`으로 정렬 기준을 지정할 수 있으며 기본값은 `CREATED`입니다.

23.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/members?sortType=CREATED' -i -X GET

23.2. HTTP

23.2.1. 요청

GET /api/v1/groups/code/members?sortType=CREATED HTTP/1.1
Host: api.moddo.kr
Table 4. /api/v1/groups/{code}/members
Parameter Description

code

정산 코드
Parameter Description

sortType

정렬 기준 (CREATED | NAME | PAID_AT)

23.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 444

{
  "members" : [ {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "userId" : 10,
    "isPaid" : true,
    "paidAt" : "2026-03-13T21:30:00"
  }, {
    "id" : 2,
    "role" : "PARTICIPANT",
    "name" : "김반숙",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
    "userId" : null,
    "isPaid" : false,
    "paidAt" : null
  } ]
}

23.3. Body

23.3.1. 응답

{
  "members" : [ {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "userId" : 10,
    "isPaid" : true,
    "paidAt" : "2026-03-13T21:30:00"
  }, {
    "id" : 2,
    "role" : "PARTICIPANT",
    "name" : "김반숙",
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
    "userId" : null,
    "isPaid" : false,
    "paidAt" : null
  } ]
}

24. 모임원 추가

기존 정산에 새로운 모임원을 추가할 수 있습니다.

역할(Enum)

  • MANAGER: 총무

  • PARTICIPANT: 참여자

24.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/members' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "name" : "김반숙"
}'

24.2. HTTP

24.2.1. 요청

POST /api/v1/groups/code/members HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 26
Host: api.moddo.kr

{
  "name" : "김반숙"
}
Table 5. /api/v1/groups/{code}/members
Parameter Description

code

정산 코드

24.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 184

{
  "id" : 1,
  "role" : "PARTICIPANT",
  "name" : "김반숙",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
  "userId" : 1,
  "isPaid" : false,
  "paidAt" : null
}

24.3. Body

24.3.1. 요청

{
  "name" : "김반숙"
}

24.3.2. 응답

{
  "id" : 1,
  "role" : "PARTICIPANT",
  "name" : "김반숙",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
  "userId" : 1,
  "isPaid" : false,
  "paidAt" : null
}

25. 참여자 선택

로그인 사용자가 아직 선택되지 않은 참여자를 선택할 수 있습니다.

  • 요청 body에 선택할 `memberId`를 전달합니다.

  • 한 사용자는 같은 정산에서 하나의 참여자만 선택할 수 있습니다.

25.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/members/assign' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "memberId" : 2
}'

25.2. HTTP

25.2.1. 요청

POST /api/v1/groups/code/members/assign HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 20
Host: api.moddo.kr

{
  "memberId" : 2
}
Table 6. /api/v1/groups/{code}/members/assign
Parameter Description

code

정산 코드

25.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 184

{
  "id" : 2,
  "role" : "PARTICIPANT",
  "name" : "김반숙",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
  "userId" : 3,
  "isPaid" : false,
  "paidAt" : null
}

25.3. Body

25.3.1. 요청

{
  "memberId" : 2
}

25.3.2. 응답

{
  "id" : 2,
  "role" : "PARTICIPANT",
  "name" : "김반숙",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
  "userId" : 3,
  "isPaid" : false,
  "paidAt" : null
}

26. 참여자 선택 해제

로그인 사용자가 본인이 선택한 참여자를 해제할 수 있습니다.

  • 요청 body에 해제할 `memberId`를 전달합니다.

26.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/members/unassign' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "memberId" : 2
}'

26.2. HTTP

26.2.1. 요청

POST /api/v1/groups/code/members/unassign HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 20
Host: api.moddo.kr

{
  "memberId" : 2
}
Table 7. /api/v1/groups/{code}/members/unassign
Parameter Description

code

정산 코드

26.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 187

{
  "id" : 2,
  "role" : "PARTICIPANT",
  "name" : "김반숙",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
  "userId" : null,
  "isPaid" : false,
  "paidAt" : null
}

26.3. Body

26.3.1. 요청

{
  "memberId" : 2
}

26.3.2. 응답

{
  "id" : 2,
  "role" : "PARTICIPANT",
  "name" : "김반숙",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
  "userId" : null,
  "isPaid" : false,
  "paidAt" : null
}

27. 결제 상태 변경

모임원의 결제 상태를 변경할 수 있습니다.

27.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/members/1' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "isPaid" : true
}'

27.2. HTTP

27.2.1. 요청

PUT /api/v1/groups/code/members/1 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 21
Host: api.moddo.kr

{
  "isPaid" : true
}
Table 8. /api/v1/groups/{code}/members/{memberId}
Parameter Description

code

정산 코드

memberId

모임원 ID

27.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 210

{
  "id" : 1,
  "role" : "PARTICIPANT",
  "name" : "김반숙",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
  "userId" : 1,
  "isPaid" : true,
  "paidAt" : "2026-04-02T14:40:19.368778347"
}

27.3. Body

27.3.1. 요청

{
  "isPaid" : true
}

27.3.2. 응답

{
  "id" : 1,
  "role" : "PARTICIPANT",
  "name" : "김반숙",
  "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
  "userId" : 1,
  "isPaid" : true,
  "paidAt" : "2026-04-02T14:40:19.368778347"
}

28. 모임원 삭제

참여자 ID로 모임원을 삭제할 수 있습니다.

  • 총무(MANAGER)는 삭제할 수 없습니다.

28.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/members/1' -i -X DELETE

28.2. HTTP

28.2.1. 요청

DELETE /api/v1/groups/code/members/1 HTTP/1.1
Host: api.moddo.kr
Table 9. /api/v1/groups/{code}/members/{memberId}
Parameter Description

code

정산 코드

memberId

삭제할 모임원 ID

28.2.2. 응답

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

입금 확인 요청 (PaymentRequest)

29. 입금 확인 요청 목록 조회

로그인한 사용자를 대상으로 들어온 입금 확인 요청 목록을 조회할 수 있습니다.

29.1. Example

$ curl 'https://api.moddo.kr/api/v1/payments' -i -X GET

29.2. HTTP

29.2.1. 요청

GET /api/v1/payments HTTP/1.1
Host: api.moddo.kr

29.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 214

{
  "paymentRequests" : [ {
    "requestedAt" : "2026-03-13T22:00:00",
    "paymentRequestId" : 1,
    "memberId" : 2,
    "name" : "김반숙",
    "profileUrl" : "profile-1.png",
    "totalAmount" : 12000
  } ]
}

29.3. Body

29.3.1. 응답

{
  "paymentRequests" : [ {
    "requestedAt" : "2026-03-13T22:00:00",
    "paymentRequestId" : 1,
    "memberId" : 2,
    "name" : "김반숙",
    "profileUrl" : "profile-1.png",
    "totalAmount" : 12000
  } ]
}

30. 입금 확인 요청 생성

정산 참여자가 총무에게 입금 확인 요청을 보낼 수 있습니다.

30.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/code/payments' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8'

30.2. HTTP

30.2.1. 요청

POST /api/v1/groups/code/payments HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: api.moddo.kr
Table 10. /api/v1/groups/{code}/payments
Parameter Description

code

정산 코드

30.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 172

{
  "id" : 1,
  "settlementId" : 1,
  "requestMemberId" : 2,
  "targetUserId" : 3,
  "requestedAt" : "2026-03-13T22:00:00",
  "processedAt" : null,
  "status" : "PENDING"
}

30.3. Body

30.3.1. 응답

{
  "id" : 1,
  "settlementId" : 1,
  "requestMemberId" : 2,
  "targetUserId" : 3,
  "requestedAt" : "2026-03-13T22:00:00",
  "processedAt" : null,
  "status" : "PENDING"
}

31. 입금 확인 요청 승인

총무가 입금 확인 요청을 승인할 수 있습니다.

31.1. Example

$ curl 'https://api.moddo.kr/api/v1/payments/1/approve' -i -X PATCH

31.2. HTTP

31.2.1. 요청

PATCH /api/v1/payments/1/approve HTTP/1.1
Host: api.moddo.kr
Content-Type: application/x-www-form-urlencoded
Table 11. /api/v1/payments/{paymentRequestId}/approve
Parameter Description

paymentRequestId

입금 확인 요청 ID

31.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 190

{
  "id" : 1,
  "settlementId" : 1,
  "requestMemberId" : 2,
  "targetUserId" : 1,
  "requestedAt" : "2026-03-13T22:00:00",
  "processedAt" : "2026-03-13T22:05:00",
  "status" : "APPROVED"
}

31.3. Body

31.3.1. 응답

{
  "id" : 1,
  "settlementId" : 1,
  "requestMemberId" : 2,
  "targetUserId" : 1,
  "requestedAt" : "2026-03-13T22:00:00",
  "processedAt" : "2026-03-13T22:05:00",
  "status" : "APPROVED"
}

32. 입금 확인 요청 거절

총무가 입금 확인 요청을 거절할 수 있습니다.

32.1. Example

$ curl 'https://api.moddo.kr/api/v1/payments/1/reject' -i -X PATCH

32.2. HTTP

32.2.1. 요청

PATCH /api/v1/payments/1/reject HTTP/1.1
Host: api.moddo.kr
Content-Type: application/x-www-form-urlencoded
Table 12. /api/v1/payments/{paymentRequestId}/reject
Parameter Description

paymentRequestId

입금 확인 요청 ID

32.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 190

{
  "id" : 1,
  "settlementId" : 1,
  "requestMemberId" : 2,
  "targetUserId" : 1,
  "requestedAt" : "2026-03-13T22:00:00",
  "processedAt" : "2026-03-13T22:05:00",
  "status" : "REJECTED"
}

32.3. Body

32.3.1. 응답

{
  "id" : 1,
  "settlementId" : 1,
  "requestMemberId" : 2,
  "targetUserId" : 1,
  "requestedAt" : "2026-03-13T22:00:00",
  "processedAt" : "2026-03-13T22:05:00",
  "status" : "REJECTED"
}

이미지 (Image)

33. 이미지 임시 저장

지출 내역 작성 완료 전에 이미지를 임시 저장할 수 있습니다.

33.1. Example

$ curl 'https://api.moddo.kr/api/v1/images/temp' -i -X POST \
    -H 'Content-Type: multipart/form-data;charset=UTF-8' \
    -F 'file=@image1.jpg;type=image/jpeg' \
    -F 'file=@image2.jpg;type=image/jpeg'

33.2. HTTP

33.2.1. 요청

POST /api/v1/images/temp HTTP/1.1
Content-Type: multipart/form-data;charset=UTF-8; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: api.moddo.kr

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=image1.jpg
Content-Type: image/jpeg

image-data
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=image2.jpg
Content-Type: image/jpeg

image-data
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

33.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 39

{
  "uniqueKeys" : [ "key1", "key2" ]
}

33.3. Body

33.3.1. 응답

{
  "uniqueKeys" : [ "key1", "key2" ]
}

34. 이미지 실제 저장

지출 내역 작성 후 임시 저장된 이미지를 실제 폴더에 업로드할 수 있습니다.

34.1. Example

$ curl 'https://api.moddo.kr/api/v1/images/update' -i -X POST \
    -d 'uniqueKey=key1&uniqueKey=key2'

34.2. HTTP

34.2.1. 요청

POST /api/v1/images/update HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.moddo.kr
Content-Length: 29

uniqueKey=key1&uniqueKey=key2

34.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 74

{
  "paths" : [ "https://bucket.s3.amazonaws.com/permanent/image1.jpg" ]
}

34.3. Body

34.3.1. 응답

{
  "paths" : [ "https://bucket.s3.amazonaws.com/permanent/image1.jpg" ]
}

모임원별 상세 지출 내역 (MemberExpenses)

35. 모임원별 상세 지출 내역 조회

받을 정산 금액 기준으로 참여자별 상세 지출 내역을 조회할 수 있습니다.

  • 입금 순, 이름 순으로 정렬되어 조회됩니다.

35.1. Example

$ curl 'https://api.moddo.kr/api/v1/groups/mockedCode/member-expenses' -i -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'

35.2. HTTP

35.2.1. 요청

GET /api/v1/groups/mockedCode/member-expenses HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: api.moddo.kr

35.2.2. 응답

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json;charset=UTF-8
Content-Length: 637

{
  "memberExpenses" : [ {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "totalAmount" : 10000,
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "isPaid" : true,
    "paidAt" : "2026-04-02T14:40:24.249136274",
    "expenses" : [ {
      "content" : "카페",
      "amount" : 10000
    } ]
  }, {
    "id" : 2,
    "role" : "PARTICIPANT",
    "name" : "군계란",
    "totalAmount" : 10000,
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
    "isPaid" : false,
    "paidAt" : null,
    "expenses" : [ {
      "content" : "카페",
      "amount" : 10000
    } ]
  } ]
}

35.3. Body

35.3.1. 응답

{
  "memberExpenses" : [ {
    "id" : 1,
    "role" : "MANAGER",
    "name" : "김모또",
    "totalAmount" : 10000,
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/MODDO.png",
    "isPaid" : true,
    "paidAt" : "2026-04-02T14:40:24.249136274",
    "expenses" : [ {
      "content" : "카페",
      "amount" : 10000
    } ]
  }, {
    "id" : 2,
    "role" : "PARTICIPANT",
    "name" : "군계란",
    "totalAmount" : 10000,
    "profile" : "https://moddo-s3.s3.amazonaws.com/profile/1.png",
    "isPaid" : false,
    "paidAt" : null,
    "expenses" : [ {
      "content" : "카페",
      "amount" : 10000
    } ]
  } ]
}