API로 외부 시스템과 연동하는 방법
조직 관리자가 API key를 발급하고 Webhook을 등록해, ERP·주문·결제 시스템과 청구스의 청구서·수납을 자동으로 맞추는 방법입니다.
알아두세요
이 가이드는 청구스 조직 관리자와 연동을 맡은 개발자를 위한 글입니다. 관리자는 1~4단계(key 발급·Webhook 등록)만 하시면 되고, 그 다음은 개발자에게 API 문서 주소를 전달하시면 됩니다. 문서는 로그인 없이 누구나 볼 수 있어요.
1. API 사용 조건 확인하기
섹션 제목: “1. API 사용 조건 확인하기”- 청구스 API는 현재 closed beta입니다. API access 메뉴는 청구스가 API 사용을 열어 준 조직의 조직 관리자에게만 보입니다.
- 메뉴가 보이지 않으면 아래 1대1 상담으로 API 사용을 요청해주세요. 활성화되면 같은 자리에 메뉴가 나타납니다.
- 준비물은 세 가지입니다.
- 조직 관리자 계정: API access 화면은 조직 관리자만 들어갈 수 있습니다.
- 연동할 시스템의 고정 IP(선택): 허용 IP를 지정하면 그 IP에서 온 요청만 받습니다.
- 수신 URL(선택): 수납 알림을 받을 HTTPS 주소입니다. Webhook을 쓸 때만 필요합니다.
쉽게 말해
API key는 우리 시스템이 청구스에 들어갈 때 쓰는 열쇠이고, Webhook은 청구스에서 수납이 생기면 우리 시스템에 알려주는 초인종이에요. 조회·생성만 필요하면 key 하나로 충분하고, 입금을 실시간으로 받고 싶을 때 Webhook을 더합니다.
2. API access 화면으로 이동하기
섹션 제목: “2. API access 화면으로 이동하기”
- API 설정은 부서 화면이 아니라 조직 홈에서 합니다.
- 사이드바 회사명 / 부서명 영역을 클릭하고 조직 홈으로 이동해주세요.
- 조직 홈 사이드바에서 열쇠 아이콘의 API access를 클릭하세요.
- 화면 위쪽에 API key 카드, 아래쪽에 Webhook 카드가 보이면 제대로 들어온 것입니다.
3. API key 발급하기
섹션 제목: “3. API key 발급하기”
- API key 카드 오른쪽 위의 API key 발급 버튼을 클릭하세요.
- 카드 안의 API 문서·Explorer (test console)·API 호출 로그 링크는 5단계에서 씁니다.
- 이름은 필수 데이터이므로 반드시 입력해주세요! 어떤 시스템이 쓰는 key인지 알아볼 수 있게 적습니다. (예: ‘ERP 서버’, ‘결제 배치’)
- 허용 IP (선택)는 한 줄에 하나씩 IP 또는 대역(CIDR)을 넣습니다. (예: ‘203.0.113.10’, ‘203.0.113.0/24’) 공란이면 어디서든 호출할 수 있습니다.
- 목록 밖에서 온 요청은 403으로 거부되고, 거부된 IP가 API 호출 로그에 남습니다.
- 발급 버튼을 클릭하면 key가 그 자리에서 한 번만 표시됩니다. 복사를 눌러 시스템의 비밀 저장소(secret manager)나 서버 환경변수에 바로 보관하세요.
유의사항
청구스는 key 원본을 저장하지 않습니다. 화면을 벗어나면 다시 볼 수 없으니 발급 직후에 꼭 복사하세요. 모든 key는 조직 관리자와 같은 권한으로 조직의 모든 부서 데이터를 다루므로, 채팅·이메일·소스코드·로그에 key를 남기지 마세요.
- 발급이 끝나면 카드 아래에 key 줄이 생깁니다. 이후에는 key 앞부분만 보이고 전체 값은 다시 표시되지 않습니다.
- 연동하는 시스템마다 key를 따로 발급하세요. 어느 key로 호출했는지 로그에 남고, 문제가 생긴 시스템의 key만 삭제할 수 있습니다. 조직당 최대 10개까지 발급됩니다.
| 버튼 | 하는 일 |
|---|---|
| 교체 | 이름과 허용 IP는 그대로 두고 key 값만 새로 만듭니다. 이전 key는 즉시 사용할 수 없게 됩니다. |
| 수정 | 이름과 허용 IP를 바꿉니다. key 값은 그대로입니다. |
| 삭제 | 이 key를 없앱니다. 이 key로 들어오는 요청은 401로 거부됩니다. |
TIP
서비스를 멈추지 않고 key를 바꾸려면 교체 대신 새 key를 하나 더 발급해 시스템에 먼저 옮겨 붙인 뒤, 옛 key의 '마지막 사용' 시각이 더 이상 갱신되지 않는 것을 확인하고 삭제하세요.
4. Webhook 등록하기 (선택)
섹션 제목: “4. Webhook 등록하기 (선택)”
- Webhook은 등록하지 않아도 API 조회·생성에는 문제가 없습니다. 청구스에서 생긴 수납 생성·수납 취소·청구서 수납 상태 변경을 실시간으로 받고 싶을 때만 등록하세요.
- Webhook 카드 오른쪽 위의 Webhook 등록 버튼을 클릭하세요.
- 수신 URL은 필수이며 반드시 https://로 시작해야 합니다. (예: ‘https://example.com/chungoose/webhook’) 리다이렉트는 따라가지 않습니다.
- 부서에서 어느 부서의 알림을 받을지 고릅니다. ‘모든 부서’를 켜두면 이후에 추가되는 부서도 자동으로 포함됩니다.
- 구독 event는 ‘수납 생성’, ‘수납 취소’, ‘청구서 수납 상태 변경’ 세 가지입니다. ‘모든 event’를 켜두면 이후 추가되는 event도 받습니다.
- 등록 버튼을 클릭하면 서명 secret이 한 번만 표시됩니다. API key와 마찬가지로 바로 복사해 수신 서버에 보관하세요.
- 수신 서버는 이 secret으로 “정말 청구스가 보낸 요청인지”를 검증합니다. 검증 방법과 요청 형식은 카드 안의 Webhook 가이드 (payload·서명·재시도) 링크에 코드 예시와 함께 있습니다.
- 등록된 Webhook 줄에서는 아래 네 가지를 할 수 있습니다.
| 버튼 | 하는 일 |
|---|---|
| Secret 재발급 | 새 secret을 한 번 표시합니다. 수신 서버의 secret을 바꿀 준비가 된 뒤 누르세요. |
| 중지 / 재개 | 중지하면 event를 보내지 않습니다. 수신 서버 점검 중일 때 사용합니다. |
| 삭제 | Webhook과 전송 기록을 지웁니다. |
| 최근 전송 N건 | 펼치면 event별 시도 횟수·응답 코드·오류가 보이고, 포기된 event를 다시 보낼 수 있습니다. |
- 수신 서버가 10초 안에 2xx로 응답하지 않으면 실패로 보고, 1분 → 5분 → 30분 → 2시간 → 12시간 → 24시간 뒤에 다시 보냅니다(총 7회). 그래도 실패하면 포기하고, 포기한 건은 ‘최근 전송’이나 Webhook 전송 로그에서 재전송할 수 있습니다.
5. 개발자에게 전달하고 첫 호출 확인하기
섹션 제목: “5. 개발자에게 전달하고 첫 호출 확인하기”
- 개발자에게는 아래 세 가지만 전달하면 됩니다.
- API 문서 주소: https://app.chungoose.ai/graphql/docs (카드의 API 문서 링크와 같은 곳, 로그인 불필요)
- API key: 3단계에서 복사한 값
- Webhook 서명 secret: 4단계에서 등록했다면
- 문서의 ‘Getting started’에 첫 호출 방법이, ‘Payment sync’(결제 연동)에 청구서 조회·생성과 수납 기록·Webhook 수신까지 연동에 필요한 전부가 순서대로 정리되어 있습니다. 왼쪽 메뉴의 Queries · Mutations · Types는 전체 스키마 레퍼런스입니다.
- 호출 주소와 인증은 아래 하나입니다.
| 항목 | 값 |
|---|---|
| Endpoint | POST https://app.chungoose.ai/graphql |
| 인증 헤더 | Authorization: Bearer cgs_api_… |
| 금액·날짜 | 금액은 원 단위 문자열(“22000”), 날짜는 YYYY-MM-DD, 시각은 ISO 8601 UTC |
- 지금 API로 할 수 있는 일은 다음과 같습니다.
| 하고 싶은 일 | 사용하는 것 |
|---|---|
| 청구서 목록·상세 조회 (외부 관리번호로 찾기 포함) | invoices, invoice |
| 수납(결제) 내역 조회, 취소된 수납 대조 | pmts |
| 고객·고객 담당자·공급자·공급 담당자·품목 조회 | customers, customerContacts vendors, vendorContacts products |
| 청구서 만들기 | createInvoice |
| 외부에서 받은 결제를 청구스 청구서에 수납으로 기록 | recordPmt |
| 수납 생성·취소·상태 변경을 실시간으로 받기 | Webhook |
- 코드를 짜기 전에 Explorer (test console)에서 바로 확인해볼 수 있어요. 오른쪽 Headers 칸에
{“Authorization”: “Bearer 발급받은 key”}를 넣고 Execute를 클릭하세요. key는 그 브라우저에만 저장됩니다. - Response 칸에 청구서 목록이 내려오면 성공입니다. 이어서 API access 카드의 API 호출 로그를 열면 방금 호출이 200으로 기록되어 있습니다. 이렇게 표시되면 연동 준비가 끝난 것입니다.
알아두세요
외부 시스템의 주문번호를 청구서의 외부 관리번호(externalId)로 넣어 두면, 이후 조회·수납 기록·Webhook 알림 모두 그 번호로 대조할 수 있습니다. 청구스 화면의 '대량 등록 → 청구서' 양식에 있는 외부 관리번호 열도 같은 값으로 저장되므로, 화면으로 만든 청구서도 API와 같은 번호로 맞출 수 있어요.
자주 묻는 질문 (FAQ)
섹션 제목: “자주 묻는 질문 (FAQ)”조직 홈에 API access 메뉴가 없어요.
아직 API가 열리지 않은 조직이거나, 조직 관리자가 아닌 계정입니다. API는 closed beta라 청구스가 조직별로 열어 드리고 있으니, 아래 1대1 상담으로 회사명과 연동 목적을 알려주시면 활성화해 드립니다.
API key를 복사하지 못하고 화면을 닫았어요. 다시 볼 수 있나요?
아니요! 청구스는 key 원본을 저장하지 않아 다시 보여드릴 수 없습니다. 해당 key 줄의 교체를 눌러 새 값을 받거나, 삭제 후 새로 발급하세요.
부서마다 다른 시스템과 연동할 수 있나요?
네! API key는 시스템마다 따로 발급하고, Webhook은 부서별로 다른 수신 URL을 등록하면 됩니다. 단, key 자체는 부서 구분 없이 조직의 모든 부서 데이터에 접근할 수 있으니 시스템 쪽에서 부서를 구분해 다뤄야 합니다.
Webhook을 놓쳤거나 수신 서버가 한동안 꺼져 있었어요.
총 7회까지 자동으로 다시 보내드리고, 그래도 실패한 건은 Webhook 전송 로그에서 재전송할 수 있습니다. 전송 기록은 90일 뒤 지워지니, 그보다 오래된 구간은 pmts 조회로 수납 내역을 대조하세요.
실제 청구서에 영향 없이 먼저 테스트해볼 수 있나요?
네! 조회 query(invoices, pmts 등)는 데이터를 바꾸지 않으니 실서버 key로 바로 확인하셔도 됩니다. 청구서 생성·수납 기록까지 미리 돌려보고 싶으시면 1대1 상담으로 요청해주세요. 테스트 환경을 안내해 드립니다.
청구스 API 연동은 key 하나와 수신 URL 하나로 청구서·수납이 우리 시스템과 실시간으로 맞춰지는 경험을 제공합니다!
📌 같이 보면 좋은 가이드
섹션 제목: “📌 같이 보면 좋은 가이드”찾으시는 내용이 없나요?
청구스 담당자가 화면을 함께 보며 바로 도와드립니다.