# headless

> 홈택스·은행·카드 데이터를 표준 스키마와 headless REST API 로 제공하는 한국 금융 데이터 수집 플랫폼.
> Bearer API Key (`h6s_live_...`) 인증, 응답은 `ContractRecord` sealed 계층의 8 variants.

AI 에이전트가 처음 시작할 때의 표준 진입 경로. 페이로드·필드 명세는 `/llms-full.txt`.

1. **Device Flow 시작 (RFC 8628)** — `POST https://api.h6s.ai/api/v1/auth/device`. 응답의 `verificationUriComplete` 를 사용자에게 표시.
2. **사용자가 콘솔 웹에서 처리** — 사용자가 `https://h6s.ai/console` 에서 가입/로그인하고 디바이스 코드를 승인. 그 외 액션 없음.
3. **API key 자동 수령 + 데이터 호출** — 동일 deviceCode 로 `POST https://api.h6s.ai/api/v1/auth/device/token` 폴링. 승인되면 응답에 `apiKey` 평문이 1회 노출되므로 그대로 `Authorization: Bearer h6s_live_...` 로 `https://api.h6s.ai/api/v1/...` 호출.

## Auth & API Key

- **콘솔 웹 (사용자 액션)** — `https://h6s.ai/console`
  - 가입·로그인·워크스페이스 관리·디바이스 승인은 모두 여기서.
  - 외부 클라이언트는 콘솔 백엔드 API 를 직접 호출하지 않는다.
- **Device Flow endpoint (디바이스 직접 호출)** — RFC 8628 표준상 외부 디바이스가 직접 호출.
  - `POST https://api.h6s.ai/api/v1/auth/device` — deviceCode / userCode 발급.
  - `POST https://api.h6s.ai/api/v1/auth/device/token` — pollIntervalSeconds 간격 폴링. 승인 후 첫 폴링에서 `apiKey` 평문 1회 반환.
- **Open API (데이터 호출)** — `https://api.h6s.ai`
  - 헤더 `Authorization: Bearer h6s_live_...` 만 있으면 워크스페이스가 자동 해석된다.

## Open API

- [DataJob](https://api.h6s.ai/llms-full.txt#api-v1-data-jobs): 스크래핑 수집 요청 생성/조회

## Contract Schemas

- [bank.accounts.cb.v1](https://api.h6s.ai/api/v1/schemas/bank.accounts.cb.v1): 연결된 뱅킹 프로바이더의 모든 계좌 목록
- [bank.transactions.cb.v1](https://api.h6s.ai/api/v1/schemas/bank.transactions.cb.v1): 연결된 뱅킹 프로바이더의 모든 계좌 입출금내역
- [hometax.tax-invoices.sales.v1](https://api.h6s.ai/api/v1/schemas/hometax.tax-invoices.sales.v1): 매출 세금계산서 + 매출 계산서 통합 목록
- [hometax.tax-invoices.purchase.v1](https://api.h6s.ai/api/v1/schemas/hometax.tax-invoices.purchase.v1): 매입 세금계산서 + 매입 계산서 통합 목록
- [hometax.cash-receipts.sales.v1](https://api.h6s.ai/api/v1/schemas/hometax.cash-receipts.sales.v1): 매출 현금영수증 목록
- [hometax.cash-receipts.purchase.v1](https://api.h6s.ai/api/v1/schemas/hometax.cash-receipts.purchase.v1): 매입 현금영수증 목록
- [card.cards.corp.v1](https://api.h6s.ai/api/v1/schemas/card.cards.corp.v1): 자격증명 단위 카드 목록 스냅샷
- [card.approvals.corp.v1](https://api.h6s.ai/api/v1/schemas/card.approvals.corp.v1): 카드 단말 승인 시점 거래 (실시간 지출 모니터링)

## CLI

AI 에이전트가 직접 호출하기 좋은 한 줄 매크로. `npm i -g @h6s-ai/cli` 후:

- `h6s ai-guide --format markdown` — 본 가이드의 CLI 친화 요약(설치된 버전 기준).
- `h6s login` — Device Flow 자동 처리. 승인 후 `~/.h6s/config.json` 에 API key 저장.
- `h6s fetch <schema> --provider <code> --month YYYY-MM --output markdown` — 자격증명 매칭/생성 → data-job 실행 → 결과 회수까지 한 번에. `--output csv|jsonl|markdown|json|yaml` 지원, `--save <path>` 로 파일 저장.
- 같은 (credential, schema, params) 조합은 24h 캐시. 강제 새로 받기는 `--cache fresh`.

## Optional

- [전체 마크다운 합본](https://api.h6s.ai/llms-full.txt)
- [OpenAPI 스펙 — 공개 표면](https://api.h6s.ai/v3/api-docs/public)
- [OpenAPI 스펙 — 전체 (사내 도구 endpoint 포함)](https://api.h6s.ai/v3/api-docs/full)
- [Swagger UI](https://api.h6s.ai/swagger-ui.html)