> For the complete documentation index, see [llms.txt](https://api-kit.prix.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-kit.prix.im/platform/search-tax-bill.md).

# 세금계산서 목록 조회 API

세금계산서 목록을 조회할 수 있는 API를 제공합니다.

프릭스에서 발행한 세금계산서 목록을 조회할 수 있는 API입니다.

* API 권한이 연결된 멤버가 속한 팀에 세금계산서 권한이 있어야 합니다.
* 프릭스에 저장된 발행 정보를 제공하며, 발행 이후의 국세청 전송·취소 등 실시간 상태는 포함되지 않습니다.

<br>

## `GET` kit-api/v1/tax-bills

Method: GET\
Endpoint: kit-api/v1/tax-bills

<br>

## Example

```
...kit-api/v1/tax-bills?issueDateAfter=2026-08-01&issueDateBefore=2026-08-31&limit=100
```

<br>

## Request Query

| Key             | Description                                | Required |
| --------------- | ------------------------------------------ | -------- |
| limit           | 목록 개수 (default 10, max 100)                | no       |
| offset          | 스킵할 목록 개수                                  | no       |
| issueDateAfter  | 발행일이 해당 날짜 이후인 세금계산서 조회 (date)             | no       |
| issueDateBefore | 발행일이 해당 날짜 이전인 세금계산서 조회 (date, 해당 일자 포함)   | no       |
| customerIds     | 해당 id 속성을 가진 고객들과 연결된 세금계산서 조회 (콤마 구분)     | no       |
| dealUuids       | 해당 uuid 속성을 가진 프로젝트들과 연결된 세금계산서 조회 (콤마 구분) | no       |
| hasSchedule     | 일정 연결 여부로 조회 (true, false)                 | no       |
| createdAtAfter  | 해당 날짜 이후 생성된 세금계산서 조회 (date)               | no       |
| createdAtBefore | 해당 날짜 이전 생성된 세금계산서 조회 (date)               | no       |

<br>

## Response

* 목록은 생성일 내림차순으로 정렬됩니다.
* 연결된 멤버에게 조회 권한이 없는 프로젝트는 `deal`이 null로 제공됩니다.

```json
{
  "ok": true, // api 성공
  "data": {
    "total": 1,
    "taxBills": [
      {
        "id": 31,
        "managementKey": "PRIX-20260801-0001", // 바로빌 관리번호
        "ntsSendKey": "20260801410000000001", // 국세청 승인번호 (없으면 null)
        "status": "CREATED", // CREATED(발행), MODIFIED(수정세금계산서)
        "issueDate": "2026-08-01T00:00:00.000Z", // 발행일(작성일)
        "purposeType": "INVOICE", // RECEIVED(영수), INVOICE(청구)
        "modifyCode": null, // 수정 사유 (MISTAKE, AMOUNT_CHANGED, REFUND, CONTRACT_CANCELATION, LETTER_OF_CREDIT, DOUBLE_ISSUANCE. 없으면 null)
        "amount": 1100000, // 합계
        "supplyAmount": 1000000, // 공급가액
        "taxAmount": 100000, // 세액
        "remark": "8월 자문료", // 비고 (없으면 null)
        "customer": { "id": 1, "title": "A컴퍼니", "customKey": "A5-k159402" }, // 연결된 고객 (없으면 null)
        "taxBillCustomer": {
          // 발행 시점의 공급받는자 정보
          "title": "A컴퍼니",
          "registrationNumber": "123-45-67890",
          "ceo": "김대표",
          "address": "서울특별시 서초구 프릭스로 551"
        },
        "deal": { "uuid": "38432ad8-a21f-43b3-9912-44295e3ecca1", "name": "A사 법률 자문", "customKey": "P-2026-001" }, // 연결된 프로젝트 (없거나 권한 없으면 null)
        "scheduleId": 21, // 연결된 일정 id (없으면 null)
        "parentTaxBillId": null, // 수정세금계산서의 원본 세금계산서 id (없으면 null)
        "createdAt": "2026-08-01T09:00:00.000Z", // 생성일
        "updatedAt": "2026-08-01T09:00:00.000Z" // 변경일
      }
    ]
  }
}
```

<br>

```json
{
  "ok": false, // api 실패
  "message": "error message", // Error가 존재하면 message(string)로 전달
  "errorCode": "ERROR_CODE"
}
```

<br>

## Error Codes

| Status Code | Error Code            | Description                |
| ----------- | --------------------- | -------------------------- |
| 403         | FORBIDDEN\_PERMISSION | 연결된 멤버의 팀에 세금계산서 권한이 없는 경우 |

<br>