# 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/...` 를 호출합니다.

## 활용 형태

headless 로 받은 데이터가 어디로 흘러가는지에 따라 세 가지로 나뉩니다. 어느 쪽이든 아래 Open API 호출은 같습니다.

- **플랫폼 통합**은 받은 데이터를 내 서비스의 사용자·고객에게 다시 제공하는 형태입니다 (핀테크 임베드, 다중 고객 수집, 마켓플레이스 정산).
- **내부 시스템 적재**는 회사 내부 어드민·ERP·정산 시스템에 적재하는 형태입니다 (월말 정산, 대사, 부서 예산, 감사 추적).
- **로컬 대시보드**는 로컬에서 받아 대시보드·리포트로 쓰는 형태입니다 (캐시플로우, Slack·Notion 리포팅, 1인 사장 신고 자료).

## 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)
- [Swagger UI](https://api.h6s.ai/swagger-ui.html)