API 레퍼런스

비즈니스 플랜

CleverInvo를 워크플로에 통합하세요. 프로그래밍 방식으로 클라이언트를 관리하고, 청구서를 생성하고, PDF를 다운로드할 수 있습니다.

인증

모든 API 요청에는 Bearer 토큰이 필요합니다. 대시보드에서 API 키를 생성한 다음 Authorization 헤더에 포함하세요.

curl -X GET https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer cinv_your_api_key"

클라이언트

GET/api/v1/clients

모든 활성 클라이언트를 나열합니다. 페이지네이션과 검색을 지원합니다.

응답
{
  "data": [
    {
      "id": "clx...",
      "name": "Acme Corp",
      "email": "[email protected]",
      "address": "123 Main St, New York, NY 10001",
      "taxId": "US-123456789",
      "phone": "+1-555-0100",
      "notes": "Net 30 terms",
      "isActive": true,
      "createdAt": "2024-01-15T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/clients

새 클라이언트를 생성합니다. 플랜의 클라이언트 제한이 적용됩니다.

요청 본문
{
  "name": "Acme Corp",
  "email": "[email protected]",
  "address": "123 Main St, New York, NY 10001",
  "taxId": "US-123456789",
  "phone": "+1-555-0100",
  "notes": "Net 30 terms"
}
응답
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
GET/api/v1/clients/:id

ID로 단일 클라이언트를 가져옵니다.

응답
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
PUT/api/v1/clients/:id

클라이언트를 업데이트합니다. 모든 필드를 수정할 수 있습니다.

요청 본문
{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+1-555-0200"
}
응답
{
  "data": {
    "id": "clx...",
    "name": "Acme Corporation",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0200",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
}
DELETE/api/v1/clients/:id

클라이언트를 소프트 삭제합니다. isActive를 false로 설정합니다. 기존 청구서가 있는 클라이언트는 하드 삭제할 수 없습니다.

응답
204 No Content

청구서

GET/api/v1/invoices

청구서를 나열합니다. 페이지네이션, 검색 및 clientId 또는 상태별 필터링을 지원합니다.

응답
{
  "data": [
    {
      "id": "clx...",
      "clientId": "clx...",
      "invoiceNumber": "INV-0001",
      "currency": "USD",
      "issueDate": "2024-06-01",
      "dueDate": "2024-07-01",
      "subtotal": 5000.00,
      "taxTotal": 500.00,
      "discountTotal": 0,
      "total": 5500.00,
      "status": "SENT",
      "createdAt": "2024-06-01T00:00:00.000Z",
      "client": {
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/invoices

청구서를 생성하고 PDF를 자동으로 생성합니다. 플랜 제한이 적용됩니다.

요청 본문
{
  "clientId": "clx...",
  "invoiceNumber": "INV-0042",
  "currency": "USD",
  "issueDate": "2024-06-01",
  "dueDate": "2024-07-01",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Thank you for your business",
  "terms": "Payment due within 30 days"
}
응답
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 5500.00,
    "status": "DRAFT"
  }
}
GET/api/v1/invoices/:id

항목 및 클라이언트 정보를 포함한 전체 청구서 세부 정보를 가져옵니다.

응답
{
  "data": {
    "id": "clx...",
    "clientId": "clx...",
    "invoiceNumber": "INV-0042",
    "currency": "USD",
    "issueDate": "2024-06-01",
    "dueDate": "2024-07-01",
    "lineItems": [
      {
        "description": "Web Development",
        "quantity": 40,
        "unitPrice": 125.00,
        "amount": 5000.00,
        "taxRate": 10
      }
    ],
    "subtotal": 5000.00,
    "taxTotal": 500.00,
    "discountTotal": 0,
    "total": 5500.00,
    "status": "SENT",
    "notes": "Thank you for your business",
    "terms": "Payment due within 30 days",
    "sentViaEmail": true,
    "sentAt": "2024-06-01T12:00:00.000Z",
    "paidAt": null,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "client": {
      "name": "Acme Corp",
      "email": "[email protected]"
    }
  }
}
PUT/api/v1/invoices/:id

청구서를 업데이트합니다. 초안 청구서만 수정할 수 있습니다.

요청 본문
{
  "dueDate": "2024-07-15",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 50,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Updated scope"
}
응답
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 6875.00,
    "status": "DRAFT"
  }
}
DELETE/api/v1/invoices/:id

청구서와 생성된 PDF를 영구적으로 삭제합니다.

응답
204 No Content
GET/api/v1/invoices/:id/pdf

청구서를 PDF 파일로 다운로드합니다. Content-Disposition 헤더가 포함된 바이너리 PDF를 반환합니다.

응답
Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-0042.pdf"

<binary PDF data>

페이지네이션

목록 엔드포인트는 다음 쿼리 매개변수를 허용합니다:

매개변수기본값설명
page1페이지 번호 (최소: 1)
limit20페이지당 항목 수 (1–100)
search—이름, 이메일 또는 청구서 번호로 필터링 (최대 255자)
clientId—클라이언트별 청구서 필터링 (청구서만)
status—상태별 필터링: DRAFT, SENT, VIEWED, PAID, PARTIALLY_PAID, OVERDUE
GET /api/v1/clients?page=2&limit=10&search=acme

오류

API는 표준 HTTP 상태 코드를 반환합니다. 오류 응답에는 error 필드가 포함된 JSON 본문이 포함됩니다.

상태 코드설명
400Bad Request — 잘못된 매개변수 또는 누락된 필수 필드
401Unauthorized — 잘못되거나 누락된 API 키
403Forbidden — 플랜 제한 도달 (클라이언트, 청구서 또는 기능)
404Not Found — 리소스가 존재하지 않거나 접근할 수 없음
429Too Many Requests — 속도 제한 초과
500Internal Server Error — 예기치 않은 오류, 나중에 다시 시도하세요
{
  "error": "Missing required field: name"
}

속도 제한

API 요청은 API 키당 분당 120개 요청로 제한됩니다.

제한을 초과하면 요청은 429 Too Many Requests를 반환합니다. 재시도하기 전에 기다리세요.