{"_id":"@01republic/easycodef-node","_rev":"4-ebc0579793420eed4a70e2dac4cfb881","name":"@01republic/easycodef-node","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.5":{"name":"@01republic/easycodef-node","version":"1.0.5","keywords":["CODEF","easyCodef","easyCodef-node"],"author":{"url":"https://codef.io/","name":"CODEF corp.","email":"tech@codef.io"},"license":"MIT","_id":"@01republic/easycodef-node@1.0.5","maintainers":[{"name":"freddy-kim","email":"yhkks1038@gmail.com"},{"name":"kimsoo0119","email":"0119kimsoo@gmail.com"}],"homepage":"https://developer.codef.io/","bugs":{"url":"https://github.com/01Republic/easycodef-node/issues"},"dist":{"shasum":"77049f59a3352b3f3ad84857112392b157bbe248","tarball":"https://registry.npmjs.org/@01republic/easycodef-node/-/easycodef-node-1.0.5.tgz","fileCount":19,"integrity":"sha512-Rsp35iQri6j3tgrJ/wig3oJRtabxSGIKVC6tNmiqsjxYfZq8BkC1KO5Cu7mS3UqtzIkuHo/Vej4w3C5Wd/KWGQ==","signatures":[{"sig":"MEUCIQCqhPAdIYbAopbvo6EYZU66xAIoi6Ydq8tytmycjXLa5wIgcQjsprxbCxxsc0EeSUOaruJ66luEfDbjUjX0T9lfd9k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":57827},"main":"dist/index.js","husky":{"hooks":{"pre-commit":"npm run test && npm run cleanup"}},"types":"dist/index.d.ts","gitHead":"829490531088e73d17cb4d7924121a6314ed3c51","scripts":{"test":"mocha --timeout 10000 test/**/*.ts -r ts-node/register","build":"tsc","cleanup":"prettier --config ./prettier.config.js --write ./**/*.ts","prepare":"npm run build","prepublishOnly":"npm test"},"_npmUser":{"name":"freddy-kim","email":"yhkks1038@gmail.com"},"repository":{"url":"git+https://github.com/01Republic/easycodef-node.git","type":"git"},"_npmVersion":"11.1.0","description":"CODEF easyCodef-node","directories":{},"_nodeVersion":"22.14.0","dependencies":{"https":"^1.0.0","mocha":"^8.1.1","crypto":"^1.0.1","hashmap":"^2.4.0","request":"^2.88.2","url-parse":"^1.4.7","urlencode":"^1.1.0"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^4.2.5","ts-node":"^8.10.2","prettier":"2.0.5","typescript":"^4.9.5","@types/node":"^20.19.11","@types/debug":"^4.1.5","@types/mocha":"^8.0.3","@types/request":"^2.48.5"},"_npmOperationalInternal":{"tmp":"tmp/easycodef-node_1.0.5_1756260898370_0.05896412705268261","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-08-27T02:14:58.271Z","modified":"2025-10-26T15:08:24.100Z","1.0.5":"2025-08-27T02:14:58.557Z"},"bugs":{"url":"https://github.com/01Republic/easycodef-node/issues"},"author":{"url":"https://codef.io/","name":"CODEF corp.","email":"tech@codef.io"},"license":"MIT","homepage":"https://developer.codef.io/","keywords":["CODEF","easyCodef","easyCodef-node"],"repository":{"url":"git+https://github.com/01Republic/easycodef-node.git","type":"git"},"description":"CODEF easyCodef-node","maintainers":[{"email":"im.ymiju@gmail.com","name":"yoonmiju"},{"email":"yhkks1038@gmail.com","name":"freddy-kim"},{"email":"yanghw0911@gmail.com","name":"hwyang"}],"readme":"\n\n# Overview\n\nCODEF는 온라인에 흩어진 데이터를 클라이언트 엔진과 웹 API 등을 활용해 쉽고 빠르게 사용할 수 있도록 돕습니다. 아이디어가 구현되기 위한 복잡한 과정을 간결하게 바꾸고, 수고로움을 줄이고자 노력합니다. \n\n[홈페이지](https://codef.io/)  \n[개발가이드](https://developer.codef.io/)  \n[블로그](https://blog.hectodata.co.kr/)  \n\n\n\n`easycodef-node`는 CODEF API 연동 개발을 돕는 라이브러리 유틸입니다.  \n사용을 위해서는 [홈페이지](https://codef.io/) 가입 후 데모/정식 서비스 신청을 통해 자격 증명을 위한 클라이언트 정보 등을 발급받아야 하며 사용 가능한 모든 API의 엔드포인트(은행, 카드, 보험, 증권, 공공, 기타)와 요청/응답 항목은 모두 [개발가이드](https://developer.codef.io/)를 통해 확인할 수 있습니다.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/codef-io/easycodef-node/blob/master/LICENSE)\n![Node version](https://img.shields.io/badge/node-%3E%3D%20v7.6.0-brightgreen)\n\n# Get it!\n  \nUsing npm:\n\n```bash\n$ npm i easycodef-node\n```\n\n\n# Use it!\n\n## Quik Start\n아래 가이드는 [easycodef-node-exam](https://github.com/codef-io/easycodef-node-exam)을 기반으로 작성되었으며 샌드박스 서버를 대상으로 즉시 테스트가 가능합니다.\n\n> **샌드박스에서는 필수 요청 파라미터 여부를 체크한 뒤 요청 상품에 따른 예정되어 있는 고정 응답 값을 반환합니다.**  \n> **사용자는 샌드박스를 통해 코드에프 연동에 대한 개발 연습과 상품 별 응답 자료 구조 등을 확인 할 수 있습니다.**\n\n## 1. 토큰 요청\n\nCODEF API 서비스를 이용하기 위해서는 서비스 이용에 대한 자격 증명을 통해 토큰을 발급받아야 합니다. 토큰은 모든 요청시 헤더 값에 포함되어야 하며 한번 발급 받은 토큰은 일주일간 재사용이 가능합니다. \n\n> **easycodef-node 라이브러리는 토큰의 발급과 재사용을 자동으로 처리합니다.**  \n> **재사용 중인 토큰의 유효기간이 만료되는 경우 재발급 또한 자동으로 처리됩니다.**\n\n사용자는 단순히 자격증명을 위한 **클라이언트 정보** 설정 만을 진행하면 됩니다.  아래의 예제는 사용자가 직접 토큰을 발급받는 과정을 설명합니다. 계정 관리나 상품 요청시 토큰은 라이브러리 내에서 자동 발급받아 사용하기 때문에 특별한 경우가 아니라면 사용자가 직접 토큰을 요청할 필요는 없습니다.\n\n```node\n//코드에프 가입을 통해 발급 받은 클라이언트 정보 - 데모\nconst DEMO_CLIENT_ID = '';\nconst DEMO_CLIENT_SECRET = '';\n\n// 코드에프 가입을 통해 발급 받은 클라이언트 정보- 정식\nconst CLIENT_ID = '';\nconst CLIENT_SECRET = '';\n\n//\t코드에프 가입을 통해 발급 받은 RSA 공개키 정보\nconst PUBLIC_KEY = '';\n\n/*\n *#1.쉬운 코드에프 객체 생성\n */\nconst codef = new EasyCodef();\n\n/*\n *#2.RSA암호화를 위한 퍼블릭키 설정\n * - 데모/정식 서비스 가입 후 코드에프 홈페이지에 확인 가능(https://codef.io/#/account/keys)\n * - 암호화가 필요한 필드에 사용 - encryptValue(String plainText);\n */\ncodef.setPublicKey(PUBLIC_KEY);\n\n/*\n *#3.데모 클라이언트 정보 설정\n * - 데모 서비스 가입 후 코드에프 홈페이지에 확인 가능(https://codef.io/#/account/keys)\n * - 데모 서비스로 상품 조회 요청시 필수 입력 항목\n */\ncodef.setClientInfoForDemo(DEMO_CLIENT_ID, DEMO_CLIENT_SECRET);\n\n/*\n * #4.정식 클라이언트 정보 설정\n * - 정식 서비스 가입 후 코드에프 홈페이지에 확인 가능(https://codef.io/#/account/keys)\n * - 정식 서비스로 상품 조회 요청시 필수 입력 항목\n */\ncodef.setClientInfo(CLIENT_ID, CLIENT_SECRET);\n\n/*#5.요청\n *  - 샌드박스 : EasyCodefConstant.SERVICE_TYPE_SANDBOX\n *  - 데모 : EasyCodefConstant.SERVICE_TYPE_DEMO\n *  - 운영 : EasyCodefConstant.SERVICE_TYPE_API\n */\ncodef\n  .requestToken(EasyCodefConstant.SERVICE_TYPE_SANDBOX)\n  .then(function (response) {\n    /*\n     * #6. 토큰 발급 결과\n     */\n    console.log(response);\n  });\n```\n\n\n## 2. 계정 관리\n\nCODEF API 서비스의 여러 상품들 중 요청 파라미터에 Connected ID가 필요한 경우가 있습니다. 인증이 필요한 CODEF API를 사용하기 위해서는 엔드 유저(End User) 계정 정보(대상기관의 인증수단)등록이 필요하며, 이를 통해 사용자마다 다른 Connected ID를 발급받을 수 있습니다. (Connected ID는 [개발가이드 인증방식](https://developer.codef.io/common-guide/connected-id/cid)에서 자세한 내용을 확인하세요.) \n\nConnected ID 발급 이후에는 직접적인 계정 정보 전송 없이 대상기관의 데이터를 요청할 수 있습니다. Connected ID는 계정 등록 요청 시 발급되며 이후 계정 추가/계정 수정/계정 삭제 요청으로 관리할 수 있습니다. 동일한 기관의 동일한 계정 정보는 중복해서 등록할 수 없으며 개인 고객/기업 고객 각각 1개씩 등록이 가능합니다.\n\n모든 상품의 파라미터에 Connected ID가 필요한 것은 아닙니다. 상품별 파라미터는 [개발가이드 상품안내](https://developer.codef.io/products/bank/overview)에서 확인할 수 있습니다.\n\n> **Connected ID를 사용하지 않는 API를 사용하는 경우 계정 관리는 생략하세요.**\n\n```node\nconst {\n  EasyCodef,\n  EasyCodefConstant,\n  EasyCodefUtil,\n} = require('easycodef-node');\nconst path = require('path');\n\n// 쉬운 코드에프 객체 생성 및 클라이언트 정보, 퍼블릭키 설정에 관한 #1~#4 단계는 생략.\n\n/*\n * #5.요청 파라미터 설정\n * - 계정관리 파라미터를 설정(https://developer.codef.io/cert/account/cid-overview)\n */\nconst accountList = []; // 계정 등록 리스트\n\n//+[인증서]\nconst accountCert = {\n  countryCode: 'KR',\n  businessType: 'BK',\n  clientType: 'P',\n  organization: '0004',\n  loginType: '0',\n  certType: '1',\n  keyFile: EasyCodefUtil.encodeToFileString(\n    path.join(__dirname, 'signPri.key')\n  ),\n  derFile: EasyCodefUtil.encodeToFileString(\n    path.join(__dirname, 'signCert.der')\n  ),\n  password: EasyCodefUtil.encryptRSA(PUBLIC_KEY, 'user_password')\n};\naccountList.push(accountCert);\n\n//+ [아이디]\nconst accountIDPWD = {\n  countryCode: 'KR',\n  businessType: 'BK',\n  clientType: 'P',\n  organization: '0081',\n  loginType: '1',\n  id: 'user_id',\n  password: EasyCodefUtil.encryptRSA(PUBLIC_KEY, 'user_password')\n};\naccountList.push(accountIDPWD);\n\nconst param = {\n  accountList: accountList,\n};\n\n/*\t#6.요청\n *  [서비스 타입 설정]\n *      - 샌드박스 : EasyCodefConstant.SERVICE_TYPE_SANDBOX\n *      - 데모 : EasyCodefConstant.SERVICE_TYPE_DEMO\n *      - 운영 : EasyCodefConstant.SERVICE_TYPE_API\n */\ncodef\n  .createAccount(EasyCodefConstant.SERVICE_TYPE_SANDBOX, param)\n  .then(function (response) {\n    /*\n     *  #7. 응답 결과\n     */\n    console.log(response);\n  });\n\n\n```\n계정 등록 요청은 등록하려는 여러 기관의 계정을 목록 파라미터로 설정해 한번에 요청이 가능하며 응답 결과는 아래와 같습니다. 사용자는 발급받은 Connected ID를 계정 등록에 성공한 기관(successList) 상품 조회 요청시 사용을 할 수 있습니다.\n\n> 예) 우리카드(0309)으로 등록한 Connected ID를 KB카드(0301) 상품 조회시 사용할 수 없음\n\n```json\n{\n  \"result\" : {\n    \"code\" : \"CF-00000\",\n    \"extraMessage\" : \"\",\n    \"message\" : \"정상\",\n    \"transactionId\":\"786e01e459af491888e1f782d1902e40\"\n  },\n  \"data\" : {\n    \"successList\" : [ {\n      \"code\" : \"CF-00000\",    \n      \"message\" : \"정상\",\n      \"extraMessage\" : \"\",            \n      \"countryCode\" : \"KR\",      \n      \"businessType\" : \"CD\",      \n      \"clientType\" : \"P\",\n      \"loginType\" : \"1\",\n      \"organization\" : \"0309\"\n    }],\n    \"errorList\" : [ ],\n    \"connectedId\" : \"byi1wYwD40k8hEIiXl6bRF\"\n  }\n}\n```\n계정 등록 이외의 계정 추가, 수정, 삭제 등의 계정 관리 기능과 계정 목록 조회, Connected ID 목록 조회 등 조회 기능은 `easycodef-node-exam`에서 확인 할 수 있습니다. \n\n인증서로 계정을 등록하는 경우에는 cert파일, key파일 세트 혹은 pfx파일 2가지 모두를 지원합니다. [개발가이드 계정등록](https://developer.codef.io/common-guide/connected-id/register)에서 자세한 내용을 확인하세요. 인증서 내보내기/가져오기 등 인증서 릴레이 서버 기능이 필요한 경우 <support@codef.io>로 문의해주시기 바랍니다. 코드에프에서는 계정 관리를 위한 인증서 팝업과 전송 서버를 서비스 하고 있습니다.\n\n![코드에프 인증서 릴레이 서비스](https://download.codef.io/codef/github/codef-relay-server01.png)\n\n\n## 3. 상품 요청\n\n엔드 유저의 계정 등록 과정을 거쳐 상품 사용 준비가 끝났다면 이제 발급받은 Connected ID와 필요한 파라미터 정보 설정 등을 통해 코드에프 API 상품 요청을 할 수 있습니다.  Connected ID를 사용하는 상품과 Connected ID를 사용하지 않는 상품 요청 예제를 아래 코드를 통해 \n확인하겠습니다.\n\n> **한번 더 강조하자면 모든 상품의 파라미터에 Connected ID가 필요한 것은 아닙니다.**  \n> **상품별 파라미터는 [개발가이드 상품안내](https://developer.codef.io/products/bank/overview)에서 확인할 수 있습니다.** \n\n#### - 일반 상품\n```node\n// 개인 보유카드 조회(Connected ID 사용)\n\n//#1 ~ #4 쉬운 코드에프 객체 생성\nconst codef = new EasyCodef();\ncodef.setPublicKey(PUBLIC_KEY);\ncodef.setClientInfoForDemo(DEMO_CLIENT_ID, DEMO_CLIENT_SECRET);\ncodef.setClientInfo(CLIENT_ID, CLIENT_SECRET);\n\n/* #5.요청 파라미터 설정 - 각 상품별 파라미터를 설정(https://developer.codef.io/products) */\nlet param = {\n  connectedId: '9GNB80TmkzNaX-E7zG....',\n  organization: '0309',\n  birthDate : '',\n  inquiryType: '0'\n};\n\n/* #6.코드에프 정보 조회 요청 - 서비스타입(API:정식, DEMO:데모, SANDBOX:샌드박스) */\nconst productUrl = '/v1/kr/card/p/account/card-list'; // (예시)개인 보유카드 조회 URL\ncodef\n  .requestProduct(productUrl, EasyCodefConstant.SERVICE_TYPE_SANDBOX, param)\n  .then(function (response) {\n    // #7. 응답 결과\n    console.log(response);\n  });\n```\n\n쉬운 코드에프 객체 생성 후 클라이언트 정보 등을 설정한 다음 개인 보유카드 조회를 위한 파라미터를 설정해서 상품 요청을 합니다. 라이브러리 사용자는 토큰 발급이나 토큰 관리, 요청 파라미터의 인코딩, 응답 바디의 디코딩 등 API이용을 위한 부수적인 작업을 직접 할 필요가 없습니다. 상품 요청에 필요한 파라미터를 설정하고 requestProduct 메서드 호출만으로 Connected ID로 등록된 계정의 기관(0309 우리카드)의 보유카드 목록을 아래와 같이 응답받게 됩니다.\n\n```json\n{\n  \"result\" : {\n    \"code\" : \"CF-00000\",\n    \"extraMessage\" : \"\",\n    \"message\" : \"성공\",\n    \"transactionId\" : \"5069429e367745baba92f5c12c4343de\"\n  },\n  \"data\" : [ {\n    \"resCardType\" : \"체크/본인\",\n    \"resValidPeriod\" : \"\",\n    \"resCardName\" : \"OO체크카드-국제ATM\",\n    \"resTrafficYN\" : \"불가능\",\n    \"resIssueDate\" : \"\",\n    \"resUserNm\" : \"***\",\n    \"resSleepYN\" : \"\",\n    \"resCardNo\" : \"6056********0000\"\n  }, {\n    \"resCardType\" : \"신용/본인\",\n    \"resValidPeriod\" : \"\",\n    \"resCardName\" : \"할인카드\",\n    \"resTrafficYN\" : \"불가능\",\n    \"resIssueDate\" : \"\",\n    \"resUserNm\" : \"***\",\n    \"resSleepYN\" : \"\",\n    \"resCardNo\" : \"6253********0000\"\n  }, {\n    \"resCardType\" : \"체크/본인\",\n    \"resValidPeriod\" : \"\",\n    \"resCardName\" : \"OO체크카드\",\n    \"resTrafficYN\" : \"불가능\",\n    \"resIssueDate\" : \"\",\n    \"resUserNm\" : \"***\",\n    \"resSleepYN\" : \"\",\n    \"resCardNo\" : \"4214********0000\"\n  } ]\n}\n```\n\n이번에는 사업자 휴폐업 상태 정보를 조회하는 상품의 예제입니다.\n\n```node\n// 사업자등록상태(휴폐업조회)(Connected ID 미사용)\n\n//#1 ~ #4 쉬운 코드에프 객체 생성\nconst codef = new EasyCodef();\ncodef.setPublicKey(PUBLIC_KEY);\ncodef.setClientInfoForDemo(DEMO_CLIENT_ID, DEMO_CLIENT_SECRET);\ncodef.setClientInfo(CLIENT_ID, CLIENT_SECRET);\n\n/* #5.요청 파라미터 설정 - 각 상품별 파라미터를 설정(https://developer.codef.io/products) */\n\nconst reqIdentityList = [];\n\nconst identity1 = {\n  reqIdentity: '3333344444',\n};\nreqIdentityList.push(identity1);\n\nconst identity2 = {\n  reqIdentity: '1234567890',\n};\nreqIdentityList.push(identity2);\n\n/*\n * #5.요청 파라미터 설정\n */\nlet param = {\n  organization: '0004',\n  reqIdentityList: reqIdentityList,\n};\n\nconst productUrl = '/v1/kr/public/nt/business/status'; // (예시)사업자등록상태(휴폐업조회) URL\n\n/*\t#6.요청\n *  [서비스 타입 설정]\n *      - 샌드박스 : EasyCodefConstant.SERVICE_TYPE_SANDBOX\n *      - 데모 : EasyCodefConstant.SERVICE_TYPE_DEMO\n *      - 운영 : EasyCodefConstant.SERVICE_TYPE_API\n */\ncodef\n  .requestProduct(productUrl, EasyCodefConstant.SERVICE_TYPE_SANDBOX, param)\n  .then(function (response) {\n    /*\n     *  #7. 응답 결과\n     */\n    console.log(response);\n  });\n\n```\n\n2개의 상폼 요청 예시를 비교해 코드의 내용을 살펴보면 개인 보유카드 조회와 사업자등록상태 조회의 차이는 **요청주소(URL)와 파라미터 설정**에만 있는 것을 확인할 수 있습니다.  사용자는 라이브러리 사용을 통해 일관된 형태의 코드를 작성하여 개발할 수 있고 다른 사람이 작성한 상품 요청 코드를 쉽게 이해할 수 있습니다.\n\n```json\n{\n  \"result\" : {\n    \"code\" : \"CF-00000\",\n    \"extraMessage\" : \"\",\n    \"message\" : \"성공\",\n    \"transactionId\" : \"786e01e459af491888e1f782d1902e40\"\n  },\n  \"data\" : [ {\n    \"resBusinessStatus\" : \"사업을하지않고있습니다.\",\n    \"resCompanyIdentityNo\" : \"3333344444\",\n    \"code\" : \"CF-00000\",\n    \"resTaxationTypeCode\" : \"98\",\n    \"extraMessage\" : null,\n    \"resClosingDate\" : \"\",\n    \"resTransferTaxTypeDate\" : \"\",\n    \"message\" : \"성공\"\n  }, {\n    \"resBusinessStatus\" : \"부가가치세일반과세자입니다.\\n*과세유형전환된날짜는2011년07월01일입니다.\",\n    \"resCompanyIdentityNo\" : \"1234567890\",\n    \"code\" : \"CF-00000\",\n    \"resTaxationTypeCode\" : \"1\",\n    \"extraMessage\" : null,\n    \"resClosingDate\" : \"\",\n    \"resTransferTaxTypeDate\" : \"20110701\",\n    \"message\" : \"성공\"\n  } ]\n}\n```\n\n#### - 추가 인증 상품\n\n추가 인증 상품이란 API호출 한번으로 요청 결과를 받을 수 있는 일반 상품과는 달리 첫 요청 이후 대상기관이 요구하는 추가 인증(이메일, SMS,  보안문자 입력 등)을 수행해야 요청 결과를 받을 수 있는 상품을 의미합니다. \n\n예를 들어 아래 그림과 같이 로그인을 하는 경우 아이디와 비밀번호 외에 대상기관에서 추가적으로 요구하는 보안문자 입력이 진행되어야 합니다. 고정 값인 아이디, 비밀번호와 다르게 보안문자 이미지는 랜덤하게 반환되기 때문에 엔드 유저의 추가적인 정보 입력이 필요합니다. \n\n![보안문자입력 예시](https://download.codef.io/codef/github/recaptcha.png)\n\n대상기관이 요구하는 인증방식에 따라 N차 추가인증이 요구 될 수 있으며, 추가 인증 정보 입력이 진행되어야 정상적으로 CODEF API 요청도 완료됩니다.  1차 입력부[기본파라미터] -> n차 추가 인증[기본 파라미터 + 추가 인증 파라미터] 요청으로 이루어집니다. **추가 인증은 사용자 인증을 위한 정보가 대부분**이며 추가 인증 요청시에도 Endpoint URL은 동일합니다. \n\n> **샌드박스 서버를 통해 추가인증 상품에 대한 테스트를 진행 할 수는 없습니다.**\n\n추가 인증에 필요한 파라미터 설명은 개발 가이드의 각 상품  페이지에서 확인할 수 있으며 자세한 내용은 [개발가이드 추가인증](https://developer.codef.io/common-guide/add-auth)을 통해 확인하세요.\n\n# Ask us\n\neasycodef-node 라이브러리 사용에 대한 문의사항과 개발 과정에서의 오류 등에 대한 문의를 [홈페이지 문의게시판](https://codef.io/#/cs/inquiry)에 올려주시면 운영팀이 답변을 드립니다. 문의게시판의 작성 양식에 맞춰 문의 글을 남겨주세요. 가능한 빠르게 응답을 드리겠습니다.\n","readmeFilename":"README.md"}