apick-api 4.8.2 → 4.12.1

package/src/index.d.ts

@@ -246,6 +246,188 @@ export interface LinkedinCompany {
 	readonly updates: readonly { readonly title: string; readonly link: string; readonly date: string; readonly text: string }[];
 }
 
+export interface CourtAuctionItem {
+	readonly itemNo: number | null;
+	readonly address: string;
+	readonly propertyKind: string;
+	readonly appraisedPrice: number | null;
+	readonly minimumPrice: number | null;
+	readonly failedCount: number;
+	readonly saleDate: string;
+	readonly saleTime: string;
+	readonly depositRate: number | null;
+}
+
+export interface CourtAuction {
+	readonly result: number;
+	readonly msg: string;
+	readonly success: number;
+	readonly case: {
+		readonly caseNo: string;
+		readonly court: string;
+		readonly caseName: string;
+		readonly receivedAt: string;
+		readonly claimAmount: number | null;
+		readonly judgeDept: string;
+		readonly judgeDeptTel: string;
+		readonly executorTel: string;
+		readonly auctionStatus: string;
+		readonly completedAt: string;
+		readonly suspended: boolean;
+		readonly suspensionReason: string;
+	};
+	readonly items: readonly CourtAuctionItem[];
+	readonly saleSchedule: readonly {
+		readonly saleDate: string;
+		readonly saleTime: string;
+		readonly items: readonly { readonly itemNo: number | null; readonly minimumPrice: number | null }[];
+	}[];
+	readonly claimDeadline: string;
+	readonly relatedCases: readonly { readonly caseNo: string; readonly court: string; readonly kind: string }[];
+	readonly count: number;
+}
+
+export interface RegistryDocVerify {
+	readonly verified: boolean;
+	readonly status: 'confirmed' | 'not_found' | 'count_exhausted' | 'invalid_format' | 'not_opened' | 'unknown';
+	readonly message: string;
+	readonly kind: 'realestate' | 'corporate' | 'movable';
+	readonly document: string | null;
+	readonly issued_date: string | null;
+	readonly registry_office: string | null;
+}
+
+export interface BidQueryOptions {
+	readonly bizType?: '물품' | '공사' | '용역' | '외자';
+	readonly startDate?: string;
+	readonly endDate?: string;
+	readonly bidNtceNo?: string;
+	readonly indstrytyCd?: string;
+	readonly pageNo?: number;
+	readonly numOfRows?: number;
+}
+
+export interface RtmsQueryOptions {
+	readonly propertyType?: 'apt' | 'rh' | 'sh' | 'offi';
+	readonly pageNo?: number;
+	readonly numOfRows?: number;
+}
+
+export interface DistributionEntry {
+	readonly name?: string;
+	readonly band?: string;
+	readonly count: number;
+	readonly share_pct: number;
+}
+
+export interface BidSummary {
+	readonly total: number;
+	readonly agency_count: number;
+	readonly industry_count: number;
+	readonly budget_total: number | null;
+	readonly budget_median: number | null;
+	readonly closing_within_3d: number;
+	readonly closed: number;
+	readonly first_close_at: string | null;
+	readonly last_close_at: string | null;
+}
+
+export interface BidPosting {
+	readonly bid_no: string;
+	readonly bid_name: string;
+	readonly agency: string;
+	readonly notice_at: string | null;
+	readonly close_at: string | null;
+	readonly days_left: number | null;
+	readonly urgency: string;
+	readonly budget: number | null;
+	readonly budget_band: string;
+	readonly industry: string;
+	readonly method: string;
+}
+
+export interface BidNotice {
+	readonly summary: BidSummary;
+	readonly distribution: {
+		readonly by_agency: readonly DistributionEntry[];
+		readonly by_industry: readonly DistributionEntry[];
+		readonly by_method: readonly DistributionEntry[];
+		readonly by_budget_band: readonly DistributionEntry[];
+		readonly by_urgency: readonly DistributionEntry[];
+	};
+	readonly deadlines: readonly BidPosting[];
+	readonly largest: readonly BidPosting[];
+	readonly insights: readonly string[];
+}
+
+export interface BidAward {
+	readonly summary: {
+		readonly total: number;
+		readonly winner_count: number;
+		readonly avg_success_rate: number | null;
+		readonly median_success_rate: number | null;
+		readonly success_rate_stdev: number | null;
+		readonly avg_participants: number | null;
+		readonly rate_sample: number;
+		readonly winner_concentration_hhi: number | null;
+		readonly success_amount_total: number | null;
+	};
+	readonly distribution: {
+		readonly by_winner: readonly DistributionEntry[];
+		readonly by_agency: readonly DistributionEntry[];
+		readonly by_rate_band: readonly DistributionEntry[];
+	};
+	readonly competitors: readonly { readonly name: string; readonly wins: number; readonly share_pct: number; readonly amount_total: number | null }[];
+	readonly low_rate: readonly BidPosting[];
+	readonly insights: readonly string[];
+}
+
+export interface RtmsTrade {
+	readonly summary: {
+		readonly total: number;
+		readonly complex_count: number;
+		readonly median_amount: number | null;
+		readonly median_price_per_sqm: number | null;
+		readonly avg_price_per_sqm: number | null;
+		readonly direct_deal_share_pct: number | null;
+		readonly canceled_count: number;
+		readonly median_area: number | null;
+		readonly median_build_year: number | null;
+	};
+	readonly distribution: {
+		readonly by_complex: readonly DistributionEntry[];
+		readonly by_area_band: readonly DistributionEntry[];
+		readonly by_amount_band: readonly DistributionEntry[];
+		readonly by_floor: readonly DistributionEntry[];
+	};
+	readonly complexes: readonly Readonly<Record<string, unknown>>[];
+	readonly anomalies: readonly Readonly<Record<string, unknown>>[];
+	readonly insights: readonly string[];
+}
+
+export interface RtmsRent {
+	readonly summary: {
+		readonly total: number;
+		readonly complex_count: number;
+		readonly jeonse_count: number;
+		readonly jeonse_share_pct: number | null;
+		readonly median_deposit: number | null;
+		readonly median_monthly_rent: number | null;
+		readonly median_deposit_per_sqm: number | null;
+		readonly avg_annual_rent_to_deposit_pct: number | null;
+		readonly renewal_share_pct: number | null;
+	};
+	readonly distribution: {
+		readonly by_complex: readonly DistributionEntry[];
+		readonly by_deposit_band: readonly DistributionEntry[];
+		readonly by_monthly_band: readonly DistributionEntry[];
+		readonly by_contract_type: readonly DistributionEntry[];
+	};
+	readonly complexes: readonly Readonly<Record<string, unknown>>[];
+	readonly jeonse_ratio: Readonly<Record<string, unknown>> | null;
+	readonly insights: readonly string[];
+}
+
 export interface LinkedinJob {
 	readonly job_posting_id: string;
 	readonly title: string;
@@ -359,6 +541,12 @@ export interface MaskResidentNumberOptions extends OcrOptions {
 export const AUTH_PROVIDERS: readonly [
 	'kakao', 'naver', 'toss', 'pass', 'samsung', 'kb', 'shinhan', 'hana', 'woori', 'ibk', 'nh', 'kakaobank', 'banksalad'
 ];
+/** 정부24 통합 조회에서 고를 수 있는 상품 키. */
+export const GOV24_BUNDLE_PRODUCTS: readonly [
+	'resident_registration', 'resident_registration_cho', 'driving_license', 'health_checkup',
+	'police_penalty', 'parking_fine_target', 'mortgage_loan', 'housing_refund_balance',
+	'housing_pension_balance', 'housing_loan_stage', 'mortgage_application', 'confirm_verify', 'power_bill'
+];
 export type AuthProvider = typeof AUTH_PROVIDERS[number];
 
 /** 간편인증 기반 조회 상품(재직·소득·연금·면허·건강검진 등)의 공통 입력. */
@@ -377,6 +565,109 @@ export interface RequestDrivingLicenseInput extends DataRequestInput {}
 export interface RequestHealthCheckupInput extends DataRequestInput {}
 export interface RequestCashReceiptDeductionInput extends DataRequestInput { incomeYears?: number; }
 export interface RequestTaxReturnHistoryInput extends DataRequestInput { years?: number; }
+/** 주민등록표 발급 공통 입력. `sido`·`sigungu` 는 주민등록 주소지다. */
+export interface ResidentRegistrationOptions {
+	sido: string;
+	sigungu: string;
+	purposeCd?: string;
+	submitTarget?: string;
+	includeAddressHistory?: 'Y' | 'N';
+	includeHousehold?: 'Y' | 'N';
+}
+export interface RequestResidentRegistrationInput extends DataRequestInput, ResidentRegistrationOptions {}
+export interface RequestResidentRegistrationChoInput extends DataRequestInput, ResidentRegistrationOptions {}
+/**
+ * 정부24 통합 조회 입력. `products` 로 조회할 상품 키를 고른다.
+ * 등본·초본을 고르면 `sido`·`sigungu` 가 필요하다.
+ */
+export interface RequestGov24BundleInput extends DataRequestInput {
+	products: string[] | string;
+	sido?: string;
+	sigungu?: string;
+	purposeCd?: string;
+	submitTarget?: string;
+	includeAddressHistory?: 'Y' | 'N';
+	includeHousehold?: 'Y' | 'N';
+}
+
+/**
+ * 홈택스 민원증명 발급 조건. 신청인 본인명의 발급이고 발급 1건 60P 정액이다.
+ * `format` 은 응답 형식이고, `json`·`both` 이면 발급된 PDF를 파싱한 `PDF데이터` 가 함께 온다.
+ * 코드 값(`use_purpose`·`submit_to`·`itrf_cd`)은 정부 공통코드다.
+ */
+export interface HometaxCertificateOptions extends DataRequestInput {
+	year?: string;
+	use_purpose?: string;
+	submit_to?: string;
+	delivery?: '06' | '10' | '04' | '12';
+	format?: 'pdf' | 'json' | 'both';
+	engl_yn?: 'Y' | 'N';
+	quantity?: number;
+	email?: string;
+	fax_no?: string;
+	wallet_address?: string;
+}
+export interface RequestIncomeAmountCertInput extends HometaxCertificateOptions {}
+export interface RequestPensionCreditCertInput extends HometaxCertificateOptions {
+	address_open_yn?: 'Y' | 'N';
+	resno_open_yn?: 'Y' | 'N';
+}
+export interface RequestFactCertInput extends HometaxCertificateOptions {
+	start_month?: string;
+	end_month?: string;
+	itrf_cd?: string;
+	issuance?: '1' | '2';
+}
+/** 소득 증빙서류 통합발급 입력. `year`·`use_purpose`·`submit_to`·`delivery` 가 필수다. */
+export interface RequestIncomeCertBundleInput extends HometaxCertificateOptions {
+	year: string;
+	use_purpose: string;
+	submit_to: string;
+	delivery: '06' | '10' | '04' | '12';
+	amount_open_yn?: 'Y' | 'N';
+	income_source_open_yn?: 'Y' | 'N';
+	withholding_all_print_yn?: 'Y' | 'N';
+	address_open_yn?: 'Y' | 'N';
+	resno_open_yn?: 'Y' | 'N';
+}
+/**
+ * 사업자 증빙서류 통합발급 입력. `business_no` 와 발급 입력이 필수이고,
+ * `bind_id` 가 없으면 대표자 본인 확인 동의 `agreed: true` 가 있어야 접수된다.
+ */
+export interface RequestBusinessCertBundleInput extends HometaxCertificateOptions {
+	business_no: string;
+	year: string;
+	use_purpose: string;
+	submit_to: string;
+	delivery: '06' | '10' | '04' | '12';
+	period?: '1' | '2' | 'all';
+	agreed?: boolean;
+	bind_id?: string;
+}
+export interface RequestTaxClearanceCertInput extends RequestFactCertInput {
+	cert_type?: 'B0006' | 'B0010';
+}
+/** 발급 PDF를 열어 글자를 뽑고 라벨 기준으로 만든 값. 필드는 비어 있을 수 있다. */
+export interface HometaxPdfData {
+	사용가능: boolean;
+	페이지수: number;
+	필드: Record<string, string | number>;
+	텍스트: string;
+	사유?: string;
+}
+/** 홈택스 민원증명 결과. `format` 이 json·both 이면 `발급문서`(base64)와 `PDF데이터` 가 함께 온다. */
+export interface HometaxCertificateResultPayload {
+	문서확인번호: string;
+	귀속연도?: string;
+	소득금액?: string;
+	응답형식?: 'pdf' | 'json' | 'both';
+	발급문서?: string;
+	문서파일명?: string;
+	문서해시?: string;
+	문서크기?: number;
+	PDF데이터?: HometaxPdfData;
+	[key: string]: unknown;
+}
 
 export type DataRequestStatus =
 	| 'AUTH_REQUESTED' | 'AUTH_WAITING' | 'AUTH_COMPLETED' | 'AUTH_REJECTED' | 'AUTH_EXPIRED'
@@ -522,6 +813,36 @@ export interface TaxReturnHistoryInfo {
 }
 export interface TaxReturnHistoryResultPayload { taxReturnHistory: TaxReturnHistoryInfo; }
 
+/** 주민등록표 등본·초본 발급 결과. `발급문서` 는 PDF 원본의 base64 다. */
+export interface ResidentRegistrationInfo {
+	문서확인번호: string;
+	발급일자: string;
+	성명: string;
+	발급문서: string;
+	문서파일명: string;
+	문서해시?: string;
+	문서크기?: number;
+	조회결과?: string;
+}
+export interface ResidentRegistrationResultPayload { residentRegistration: ResidentRegistrationInfo; }
+export interface ResidentRegistrationChoResultPayload { residentRegistrationCho: ResidentRegistrationInfo; }
+/** 통합 조회는 고른 상품의 섹션만 담는다. 섹션 키는 상품 키의 camelCase 다. */
+/** 소득 증빙서류 통합발급 결과. 증명마다 섹션이 따로 오며 일부만 발급되면 status 가 PARTIAL_SUCCESS 다. */
+export type IncomeCertBundleResultPayload = Record<string, unknown> & {
+	incomeAmountCert?: HometaxCertificateResultPayload;
+	pensionCreditCert?: HometaxCertificateResultPayload;
+};
+/** 사업자 증빙서류 통합발급 결과. 성공 응답에 다음 조회에 쓸 `bind_id` 가 함께 올 수 있다. */
+export type BusinessCertBundleResultPayload = Record<string, unknown> & {
+	businessRegistrationCert?: HometaxCertificateResultPayload;
+	vatTaxBaseCert?: HometaxCertificateResultPayload;
+	financialStatementCert?: HometaxCertificateResultPayload;
+};
+export type Gov24BundleResultPayload = Record<string, unknown> & {
+	residentRegistration?: ResidentRegistrationInfo;
+	residentRegistrationCho?: ResidentRegistrationInfo;
+};
+
 export interface YoutubeThumbnail { url: string; width: number; height: number; }
 export interface YoutubeChapter { title: string; start_time: number | null; end_time: number | null; }
 export interface YoutubeMetadata {
@@ -696,6 +1017,12 @@ export class ApickClient {
 	linkedinProfile(url: string): Promise<ApickResult<LinkedinProfile>>;
 	linkedinCompany(url: string): Promise<ApickResult<LinkedinCompany>>;
 	linkedinJob(url: string): Promise<ApickResult<LinkedinJob>>;
+	courtAuction(caseNo: string, court: string): Promise<ApickResult<CourtAuction>>;
+	registryDocVerify(issueNo: string, options?: { readonly kind?: 'realestate' | 'corporate' | 'movable' }): Promise<ApickResult<RegistryDocVerify>>;
+	bidNotice(options: BidQueryOptions): Promise<ApickResult<BidNotice>>;
+	bidAward(options: BidQueryOptions): Promise<ApickResult<BidAward>>;
+	rtmsTrade(lawdCd: string, dealYmd: string, options?: RtmsQueryOptions): Promise<ApickResult<RtmsTrade>>;
+	rtmsRent(lawdCd: string, dealYmd: string, options?: RtmsQueryOptions): Promise<ApickResult<RtmsRent>>;
 	screenshot(url: string): Promise<ApickBinaryResult>;
 	youtubeMetadata(url: string): Promise<ApickResult<YoutubeMetadata>>;
 	youtubeThumbnail(url: string): Promise<ApickBinaryResult>;
@@ -752,6 +1079,24 @@ export class ApickClient {
 	getCashReceiptDeduction(transactionId: string): Promise<ApickResult<DataRequestResult<CashReceiptDeductionResultPayload>>>;
 	requestTaxReturnHistory(input: RequestTaxReturnHistoryInput): Promise<ApickResult<DataRequestAcceptedData>>;
 	getTaxReturnHistory(transactionId: string): Promise<ApickResult<DataRequestResult<TaxReturnHistoryResultPayload>>>;
+	requestIncomeAmountCert(input: RequestIncomeAmountCertInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getIncomeAmountCert(transactionId: string): Promise<ApickResult<DataRequestResult<HometaxCertificateResultPayload>>>;
+	requestPensionCreditCert(input: RequestPensionCreditCertInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getPensionCreditCert(transactionId: string): Promise<ApickResult<DataRequestResult<HometaxCertificateResultPayload>>>;
+	requestFactCert(input: RequestFactCertInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getFactCert(transactionId: string): Promise<ApickResult<DataRequestResult<HometaxCertificateResultPayload>>>;
+	requestTaxClearanceCert(input: RequestTaxClearanceCertInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getTaxClearanceCert(transactionId: string): Promise<ApickResult<DataRequestResult<HometaxCertificateResultPayload>>>;
+	requestIncomeCertBundle(input: RequestIncomeCertBundleInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getIncomeCertBundle(transactionId: string): Promise<ApickResult<DataRequestResult<IncomeCertBundleResultPayload>>>;
+	requestBusinessCertBundle(input: RequestBusinessCertBundleInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getBusinessCertBundle(transactionId: string): Promise<ApickResult<DataRequestResult<BusinessCertBundleResultPayload>>>;
+	requestResidentRegistration(input: RequestResidentRegistrationInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getResidentRegistration(transactionId: string): Promise<ApickResult<DataRequestResult<ResidentRegistrationResultPayload>>>;
+	requestResidentRegistrationCho(input: RequestResidentRegistrationChoInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getResidentRegistrationCho(transactionId: string): Promise<ApickResult<DataRequestResult<ResidentRegistrationChoResultPayload>>>;
+	requestGov24Bundle(input: RequestGov24BundleInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getGov24Bundle(transactionId: string): Promise<ApickResult<DataRequestResult<Gov24BundleResultPayload>>>;
 	searchSkills(options?: SkillSearchOptions): Promise<ApickResult<SkillPage<SkillSummary>>>;
 	/** Public measured results and methods; model scores are not accuracy guarantees. */
 	getSkillPerformance(): Promise<ApickResult<SkillPerformanceReport>>;
@@ -864,7 +1209,7 @@ export interface SkillSummary {
 export interface SkillDetail extends SkillSummary {
 	description: string; billing_rule: 'validated_result' | 'subagent_usage'; limits: SkillLimits | null;
 	delivery?: 'installed_agent'; installation?: {package:string;command:string;api_key_env:string;guide:string;usage:string};
-	billing?: {markup_percent:number;installation_points:number;base_points:number;complete_cache_points:number;quota:null};
+	billing?: {installation_points:number;base_points:number;complete_cache_points:number;quota:null};
 	input_schema: Record<string, unknown>; output_schema: Record<string, unknown>;
 	examples: unknown[]; stats: Record<string, unknown> | null; published_at: string | null;
 }