CleverInvo API로 인보이스 발행 자동화하는 방법

매월 몇 건 이상의 인보이스를 보낸다면, 프로세스를 자동화하고 싶었을 것입니다. 프로젝트 관리 도구에서 프로젝트가 완료되면 자동으로 인보이스가 생성되거나, CRM에서 거래가 성사되면 인보이스가 만들어지거나, 매월 리테이너 고객 전체의 인보이스를 폼을 50번 클릭하지 않고 일괄 생성하고 싶을 수 있습니다.

CleverInvo API가 이 모든 것을 가능하게 합니다. 이 가이드에서는 기본 사항을 다룹니다: 인증, 고객 생성, 인보이스 생성, Webhook 설정.

---

사전 요건

API는 Business 플랜에서 사용 가능합니다. 필요한 것:

1. Business 플랜의 CleverInvo 계정
2. API 키 (대시보드 > API 키에서 생성)
3. REST API와 JSON에 대한 기본 지식

모든 API 요청은 HTTPS를 사용하고 JSON 응답을 반환합니다. 기본 URL:

https://cleverinvo.com/api/v1

인증

Authorization 헤더에 API 키를 포함합니다:

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

---

고객 관리

인보이스를 만들기 전에 시스템에 고객이 필요합니다.

고객 생성

curl -X POST https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme 주식회사",
    "email": "[email protected]",
    "address": "서울특별시 강남구 비즈니스로 123",
    "taxId": "123-45-67890",
    "phone": "+82-2-1234-5678"
  }'

고객 목록

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://cleverinvo.com/api/v1/clients?page=1&limit=20"

---

인보이스 생성

API의 진정한 가치가 빛나는 부분입니다. 단일 API 호출로 전문적이고 번호가 매겨진 인보이스를 생성할 수 있습니다.

인보이스 생성

curl -X POST https://cleverinvo.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cli_abc123def456",
    "currency": "KRW",
    "issueDate": "2026-03-01",
    "dueDate": "2026-03-31",
    "lineItems": [
      {
        "description": "웹사이트 리디자인 - 1단계",
        "quantity": 1,
        "unitPrice": 5000000
      },
      {
        "description": "프론트엔드 개발",
        "quantity": 40,
        "unitPrice": 150000
      }
    ],
    "notes": "거래해 주셔서 감사합니다.",
    "terms": "30일 이내 결제. 연체 시 월 1.5% 이자 부과."
  }'

시스템은 자동으로:

• 다음 순차 인보이스 번호 할당
• 항목 합계, 소계, 총계 계산
• PDF 생성 및 URL 반환
• 상태를 DRAFT로 설정

세금 포함 인보이스

세금을 포함하려면 각 항목에 taxRate를 추가합니다:

{
  "lineItems": [
    {
      "description": "컨설팅 서비스",
      "quantity": 20,
      "unitPrice": 200000,
      "taxRate": 10
    }
  ]
}

---

인보이스 상태 관리

인보이스는 수명 주기를 거칩니다: DRAFT(초안), SENT(발송됨), VIEWED(조회됨), PAID(결제됨), PARTIALLY_PAID(일부 결제), OVERDUE(연체).

# 발송됨으로 표시
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "SENT"}'

# 결제됨으로 표시
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "PAID"}'

---

일반적인 연동 패턴

패턴 1: CRM에서 인보이스

CRM에서 거래가 성사되면 자동으로 고객을 생성하고 (신규인 경우) 인보이스를 발행:

async function onDealClosed(deal) {
  let client = await cleverinvo.clients.findByEmail(deal.customerEmail);
  if (!client) {
    client = await cleverinvo.clients.create({
      name: deal.customerName,
      email: deal.customerEmail,
    });
  }

  await cleverinvo.invoices.create({
    clientId: client.id,
    currency: deal.currency,
    issueDate: new Date().toISOString().split("T")[0],
    dueDate: addDays(new Date(), 30).toISOString().split("T")[0],
    lineItems: deal.products.map((p) => ({
      description: p.name,
      quantity: p.quantity,
      unitPrice: p.price,
    })),
  });
}

패턴 2: 월간 리테이너 청구

매월 1일에 모든 리테이너 고객의 인보이스를 생성:

async function generateMonthlyInvoices() {
  const clients = await cleverinvo.clients.list({ isActive: true });

  for (const client of clients.data) {
    if (client.retainerAmount) {
      await cleverinvo.invoices.create({
        clientId: client.id,
        currency: "KRW",
        lineItems: [
          {
            description: `월간 리테이너 - ${format(today, "yyyy년 M월")}`,
            quantity: 1,
            unitPrice: client.retainerAmount,
          },
        ],
      });
    }
  }
}

---

속도 제한

플랜	제한
Business	분당 100건 요청

제한 초과 시 API는 429 Too Many Requests와 Retry-After 헤더를 반환합니다.

---

오류 처리

모든 오류는 일관된 JSON 구조를 반환합니다:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "clientId는 필수입니다",
    "details": [
      {"field": "clientId", "message": "이 필드는 필수입니다"}
    ]
  }
}

코드	HTTP 상태	의미
UNAUTHORIZED	401	유효하지 않거나 누락된 API 키
FORBIDDEN	403	현재 플랜에서 API 미지원
NOT_FOUND	404	리소스가 존재하지 않음
VALIDATION_ERROR	422	요청 데이터가 유효하지 않음
RATE_LIMITED	429	요청 과다
INTERNAL_ERROR	500	서버 오류 (지원팀 문의)

---

다음 단계

CleverInvo API는 기존 워크플로우에 맞도록 설계되었습니다 — 간단한 cron 작업이든 복잡한 다중 시스템 연동이든. 하나의 사용 사례부터 시작하여 동작을 확인한 후 확장하세요.

전체 API 문서는 /docs/api에서 확인할 수 있습니다.

API 키 받기 ->