AI용

AI 코딩 어시스턴트가 Crisphive 연동을 구축하는 데 필요한 모든 것 — 바로 붙여 넣을 수 있는 프롬프트, 기계가 읽을 수 있는 리소스, API 핵심 정보를 한곳에 모았습니다.

AI로 설치하기

다음 프롬프트를 AI 코딩 어시스턴트에 붙여 넣어 연동을 부트스트랩할 수 있습니다:

Read the Crisphive backend integration skill at
https://api.crisphive.com/developers/SKILL.md and the OpenAPI spec at
https://api.crisphive.com/developers/openapi.json.

Then implement a client for my backend that:
1. Authenticates with an API key as a Bearer token (chsk_test_… for sandbox)
2. Creates a customer and a job request
3. Keeps job requests in sync by polling GET /v1/job-requests/changes
   with the next_since cursor

모든 응답은 하나의 엔벨로프 형태 — { error_code, message, errors, data } — 를 사용하므로, 생성된 클라이언트들이 단일 응답 파서를 공유할 수 있습니다.

기계가 읽을 수 있는 리소스

두 파일 모두 API가 직접 제공하므로 항상 배포된 버전과 일치합니다. 문서 페이지를 컨텍스트에 복사하는 대신 어시스턴트가 이 URL을 직접 참조하게 하세요.

리소스	내용
`SKILL.md`	에이전트를 위해 작성된 간결한 연동 가이드: 인증, 응답 엔벨로프, 핵심 예약 흐름, 흔한 함정.
`openapi.json`	전체 OpenAPI 명세 — 모든 엔드포인트, 요청/응답 스키마, 오류 코드. 타입이 지정된 클라이언트 생성에 활용하세요.

어시스턴트가 알아야 할 핵심 정보

기본 URL은 https://api.crisphive.com/v1입니다. sandbox와 live는 동일한 경로를 사용하며, 환경은 키 접두사(chsk_test_… vs chsk_live_…)로 결정됩니다.
모든 요청은 Authorization: Bearer <api key>로 인증합니다. 키는 만료됩니다 — 유효 기간은 생성 시에 선택하며(기본 30일, 1일부터 365일까지) 절대 연장할 수 없습니다. 갱신하려면 교체 키를 만들고 기존 키를 폐기하세요(환경당 최대 50개의 활성 키). 만료된 키는 API_KEY_EXPIRED와 함께 401을 반환하며, API_KEY_INVALID와 구분됩니다. 키는 전체 접근 권한을 갖거나 특정 권한 스코프로 제한되며(예: 고객 목록 읽기 권한 없이 작업 요청 생성), 항상 하나의 워크스페이스와 하나의 환경(라이브 또는 샌드박스)에 고정됩니다. 키는 서버 측에 보관하세요.
error_code가 0이면 성공이고, 그 외 값은 오류입니다. 유효성 검사 실패 시 errors에 필드별 세부 정보가 담깁니다.
리소스를 다시 나열하는 대신 반환된 next_since 커서로 GET /v1/job-requests/changes를 폴링해 데이터를 미러링하세요.
이벤트(예약, 고객, 기사)가 발생하는 즉시 푸시받으려면 웹훅을 사용하세요. 엔드포인트를 노출할 수 없는 경우에는 변경 피드가 풀(pull) 방식의 대안입니다.

더 나은 결과를 위한 팁

어시스턴트에게 먼저 SKILL.md를 읽히세요. 컨텍스트에 들어갈 만큼 작으면서도 전체 명세 없이 대부분의 연동 질문에 답할 수 있습니다.
모델이 필드 이름을 추측하게 두지 말고 openapi.json에서 요청/응답 타입을 생성하세요.
sandbox 키(chsk_test_…)로 개발하고, 흐름이 끝까지 동작한 뒤에만 live로 전환하세요.
디버깅할 때는 HTTP 상태만이 아니라 error_code를 확인하세요.