Docs

Docs

화면 사용법과 연동 규격을 정리한 매뉴얼입니다.

API 연동

결과 동기화

처리 결과를 조회로 가져가는 방법과 확정 답변이 잠기는 규칙입니다.

왜 조회(폴링) 방식인가#

이 시스템은 파트너 서버로 먼저 요청을 보내지 않습니다. 파트너가 주기적으로 GET /issues를 호출해 바뀐 것을 가져갑니다. 보내는 쪽이 실패를 책임지는 푸시 방식과 달리, 가져가는 쪽이 시점·재시도·반영을 모두 통제할 수 있어 누락 책임이 분명합니다.

변경분만 가져오기#

  • updatedFrom에 기준 시각을 넣으면 그 시각 이상으로 바뀐 이슈만 옵니다.
  • 결과는 수정 시각 오름차순입니다. 중간에 끊겨도 마지막 처리 지점부터 다시 시작할 수 있습니다.
  • 답변 내용만 고쳐진 경우도 잡히도록, 이슈 수정 시각과 확정 답변 수정 시각 중 늦은 쪽으로 비교합니다.
  • 한 번에 최대 100건. 페이지를 끝까지 돈 뒤 마지막 건의 수정 시각을 다음 커서로 저장합니다.

경계의 한 건은 다시 옵니다

비교가 이상(>=)이라 직전 마지막 건이 다음 조회에 한 번 더 포함됩니다. 이슈 ID 기준으로 덮어쓰도록(멱등) 만들면 문제가 없습니다.

조회 작업 예시
// 1분 이상 간격으로 반복 실행 (cron, 큐 워커 등)
let cursor = loadCursor() ?? "2026-01-01T00:00:00.000Z";
let page = 1;

while (true) {
  const res = await fetch(`${BASE}/issues?updatedFrom=${cursor}&perPage=100&page=${page}`, {
    headers: { "X-API-Key": process.env.CS_API_KEY },
  });
  const data = await res.json();
  if (!data.success) break;

  for (const issue of data.items) {
    upsertByIssueId(issue);            // 같은 이슈가 다시 와도 결과가 같게(멱등)
    if (issue.confirmedComment) notifyCustomer(issue);
  }

  if (page >= data.totalPages) {
    const last = data.items.at(-1);
    if (last) saveCursor(last.updatedAt); // 마지막 건의 수정 시각을 다음 커서로
    break;
  }
  page += 1;
}

BASE는 https://<도메인>/api/v1이고 API_KEY는 발급받은 키입니다. 호출 횟수 제한은 없지만 조회 주기는 1분 이상을 권장합니다.

확정 답변이 잠기는 시점#

담당자가 확정
동기화 대기중
파트너가 조회
응답에 실려 나감
잠김
확정 취소 불가
경우잠기는 시점
담당자가 확정한 답변을 파트너가 조회조회 응답에 실리는 즉시 (목록·상세 모두)
파트너가 API로 직접 확정확정과 동시에
내부에서 수동 동기화 처리누른 즉시

주의

테스트 삼아 한 조회도 잠급니다. 파트너에게 반영 준비가 끝난 뒤 조회를 시작하도록 안내하세요. 이미 잠긴 이슈를 다시 조회하는 것은 안전합니다.

잠겨도 답변을 수정·삭제하는 것은 가능합니다. 수정하면 대기중으로 돌아가 다음 조회에 바뀐 내용이 다시 실리고, 삭제하면 이슈가 진행중으로 돌아갑니다.

파트너가 답변을 쓰는 경우#

파트너 쪽 상담원이 먼저 답했다면 그 답변을 이 시스템에 기록할 수 있습니다.

  • 한 번에 끝낼 때: POST /issues/{id}/answer - 작성과 확정을 한 번에
  • 대화를 여러 번 주고받을 때: POST /issues/{id}/comments를 여러 번 부르고, 최종 답변 하나를 .../confirm
  • authorName은 매번 보내야 하며 화면에 그대로 표시됩니다.

재시도 규칙#

요청다시 보내도 되나
조회 (GET)항상 안전
이슈 접수 (POST /issues)응답을 못 받았다면 먼저 확인. 무작정 재시도하면 중복 접수
확정 (confirm, answer)이미 확정됐으면 422
5xx 오류간격을 늘려가며 재시도
4xx 오류재시도해도 같음. 요청을 고쳐야 함

각 요청의 세부 규격은 REST 레퍼런스를 보세요.