@kynode/sdk

Official JavaScript/TypeScript SDK for the Kynode Korean Business Verification API.

Verify Korean business registration numbers against NTS (National Tax Service) data with optional DART-verified English company names.

Requirements

• Node.js 18+ (native fetch)

Installation

npm install @kynode/sdk

yarn add @kynode/sdk

pnpm add @kynode/sdk

Quick start

import { Kynode } from '@kynode/sdk';

const kynode = new Kynode({
  apiKey: process.env.KYNODE_API_KEY!,
});

const result = await kynode.verify({
  business_number: '8090903407',
  startDate: '20260513',
  ownerName: '강민구',
  company_name: '노드메트릭스',
  language: 'en',
});

console.log(result.isValid, result.businessInfo?.companyName);

Client options

| Option | Type | Default | Description | | --------- | -------- | -------------------------------------------- | ------------------------ | | apiKey | string | required | Your Kynode API key | | baseUrl | string | https://kynode-api.kynode.workers.dev | API base URL | | timeout | number | 30000 | Request timeout (ms) |

Single verification

const result = await kynode.verify({
  business_number: '1234567890',
  startDate: '20240101',
  ownerName: '홍길동',
  language: 'en', // optional: 'en' | 'ko' | 'both' | 'code' (default: 'en')
});

Calls POST /v1/verify with Bearer authentication.

Language options

| Value | Description | | ------ | ------------------------------------------------ | | en | English output with DART-verified names | | ko | Korean output (original NTS data) | | both | Korean and English in one response | | code | Minimal response with status codes only |

Batch verification

const batch = await kynode.batchVerify([
  { business_number: '1234567890', startDate: '20240101', ownerName: '홍길동' },
  { business_number: '9876543210', startDate: '20240101', ownerName: '김철수' },
]);

console.log(batch.total, batch.success, batch.failed);
for (const row of batch.results) {
  if (row.success) {
    console.log(row.business_number, row.data?.businessInfo?.companyName);
  } else {
    console.error(row.business_number, row.error);
  }
}

• If every item shares the same startDate, ownerName, language, and company_name, the SDK calls POST /v1/batch/verify (Pro tier and above).
• If fields differ per row (e.g. different ownerName), the SDK runs parallel single verify calls and returns a batch-shaped response.

Error handling

The SDK throws typed errors for failed HTTP responses:

import {
  Kynode,
  KynodeAuthError,
  KynodeQuotaError,
  KynodeValidationError,
  KynodeNotFoundError,
  KynodeError,
} from '@kynode/sdk';

try {
  await kynode.verify({ ... });
} catch (error) {
  if (error instanceof KynodeAuthError) {
    // 401 — invalid or missing API key
  } else if (error instanceof KynodeQuotaError) {
    // 429 — monthly quota exceeded
  } else if (error instanceof KynodeValidationError) {
    // 400 — invalid request
  } else if (error instanceof KynodeNotFoundError) {
    // 404 — endpoint or resource not found
  } else if (error instanceof KynodeError) {
    console.error(error.statusCode, error.code, error.message, error.details);
  }
}

| Class | HTTP status | Typical cause | | ----------------------- | ----------- | -------------------------------- | | KynodeAuthError | 401 | Invalid API key | | KynodeValidationError | 400 | Missing or invalid parameters | | KynodeNotFoundError | 404 | Unknown endpoint | | KynodeQuotaError | 429 | Monthly quota exceeded | | KynodeError | other | Server errors, timeouts, etc. |

Timeouts throw KynodeError with code: 'timeout' and status 408.

CommonJS

const { Kynode } = require('@kynode/sdk');

const kynode = new Kynode({ apiKey: 'sk_live_...' });

API reference

• Kynode API docs
• Get an API key

License

MIT