개발자 BOOK
업무 단축을 위한 편리하고 신속한 개발 가이드를 제공합니다.
since now
업무 단축을 위한 편리하고 신속한 개발 가이드를 제공합니다.
개발 업무의 단축을 위한 개발 가이드 페이지, 개발자 BOOK을 소개합니다.
나이스디앤알의 전자세금계산서 서비스 나이스빌(NICE BILL)은
SOAP기반의 Web Service API를 통해 연동합니다.
테스트를 희망할 시 개발계에 동일한 스펙의 환경을 제공 드리며,
실제 서비스와 같은 조건으로 연동 개발이 가능하도록 지원 합니다.
개발 테스트를 시작하기에 앞서 회원가입 전 필수로 진행하셔야 하는 부분을 확인 바랍니다.
API 신규 연동 업체의 사용 유형에 따른 표준업무 신청
1) 계산서 사용 후 차감 방식 (선발행 후 정산, 포인트 차감 등)
2) 발행 후 안내 메시지 발송 여부 및 차감 방식 (알림톡, LMS 등)
3) 나이스빌 웹 서비스 접속 및 사용 여부
4) 부가서비스 사용 여부 (메시지, 거래명세서, FAX, 예금주 성명 조회 등)
API 신규 연동 업체에서 사용할 링크코드 (Link Code)
대문자 영문 3자리로 구성 (OOO_ID 생성), 중복일 시 미리 알려드립니다.
위/수탁 전자(세금)계산서 사용 여부
나이스빌은 SOAP기반의 웹서비스 API를 통해 연동합니다.
도입 문의 시 WSDL(Web Service Description Language)을 제공하며, 이를 통해 Webservice client를 생성하시면 됩니다
일반적인 플로우는 위의 전자(세금)계산서 프로세스와 같으며, 매 단계마다 기능을 부르는 호출이 있습니다.
각 과정에서 필요한 함수를 가이드 해드릴 예정이며 전체적인 순서는 아래와 같습니다.
테스트 서버에서 전자(세금)계산서 발행 후 담당자에게 연락 주시면 전송 상태를 변경해 드립니다.
이 후에 상태 변경 내역에 대한 요청 및 응답을 진행하시면 됩니다.
테스트가 완료되면 필요한 세팅 후 웹서비스 주소를 알려드리며, 운영서버로 전환하여 이용하시면 됩니다.
나이스빌에서 발행된 전자(세금)계산서는 2가지 유형의 전송 방식을 제공합니다.
1시간 이내 국세청으로 전송되는 ‘즉시 전송’과 지정 시간 이후 전송이 가능한 ‘지연(예약) 전송’이 있습니다.
전자서명이 완료된 세금계산서를 매 시 일정 시간에 국세청으로 전송합니다. 이때 발행 취소는 불가합니다.
나이스빌에서 일정 시간에 일괄 전송 후 국세청으로 전송이 완료되기까지 약 15~30분 정도 소요가 됩니다.
그리고 정각 전 결과값에 따라 업데이트된 상태 값을 나이스빌에서 조회할 수 있습니다.
작성 및 전자서명(발행) 기준 시점으로 최대 18시간 이후까지 지연(예약) 발송이 가능합니다.
국세청 전송 시작 전까지 ‘발행 취소’가 가능하며, 취소한 계산서는 전송에서 신고(전송) 제외 처리됩니다.
예약 발송 시 기존 발행일에서 익일로 넘어갈 수 있으며(D+1), 서버 환경이나 예기치 못한 문제에 따라 수신 값을 늦게 받을 수 있습니다.
이러한 경우 자칫 국세청이 지정한 ‘지연 전송’의 사유로 과태료가 부과될 수 있으니 마감까지 충분한 여유시간을 두고 해당 기능을 이용하는 것이 좋습니다.
개발을 위한 개발계 주소를 원하시면 를 통하여 언제든 말씀하세요!
전자(세금)계산서 발행을 위해 NICE디앤알에 회원 정보를 등록합니다.
계산서를 발행하는 회원은 최초 1회의 회원가입 절차가 필수입니다.
회원가입 이 후 공동(공인)인증서를 등록 합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
membJoin | Request | String linkCd (*) | 연계코드 | 3 |
String linkId | 연계사가 사용중인 ID | - | ||
String bizNo | 사업자번호 | 10 | ||
String custName | 회사명 | 100 | ||
String ownerName | 대표자 | 100 | ||
String bizCond | 업태 | 150 | ||
String bizItem | 종목 | 150 | ||
String rsbmName | 담당자명 | 100 | ||
String email | 이메일 | 100 | ||
String telNo | 전화번호 | 30 | ||
String hpNo | 휴대폰번호 | 30 | ||
String zipCode | 우편번호 | 10 | ||
String addr1 | 주소 | 200 | ||
String addr2 | 주소2 (상세주소) | 200 | ||
Response | String retVal | 결과코드 (**) | - | |
String errMsg | 오류메시지 | - | ||
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자 ID | 50 | ||
String passwd | 사용자 PW | 70 |
(*) 상단에서부터 아래로 짙은 글자(Bold 처리)는 필수 항목으로 분류됩니다.
(**) 별도 코드표를 제공하니 참조하시면 됩니다.
※ 회원가입 시 제3자 정보제공 동의 필수입니다.
NICE디앤알에 등록된 공인인증서로 전자(세금)계산서를 발행합니다.
정상 발행된 계산서의 승인번호는 총 24자리입니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
makeAndPublishSign | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String certPw | 암호화된 공인인증서 PW | 70 | ||
String DTIXml | 계산서 XML(DTIXml_sample.xml 파일 참조) | - | ||
String sendMailYn | 메일발송여부(Y/N) | 1 | ||
String sendSmsYn | 메시지 발송여부(Y/N) | 1 | ||
String erpBillNo | 연계사 DB 계산서 ID (unique) | 36 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String billNo | 승인번호 | 24 | ||
String retErpBillNo | 연계사 DB 계산서 ID (unique) | 36 | ||
String gnlPoint | 일반 포인트 | - | ||
String bnsPoint | 보너스 포인트 | - | ||
String totPoint | 통합 포인트 | - |
※ 나이스빌에 등록된 인증서로 서명까지 처리하는 단계입니다.
전자(세금)계산서를 발행 할 때에는 미리 기입한 공급받는자의 이메일로 메일이 발송됩니다.
기존 발송되었던 메일에 한하여 메일을 재전송 할 수 있습니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
sendMultiMail2 | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String billNos | 재전송 할 승인번호 | - | ||
String emails | 이메일 | - | ||
Response | String retVal | 결과코드 | - | |
String errMsg | 오류메시지 | - |
등록되어있는 회원의 정보를 수정 합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
updateMembInfo | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자 ID | 50 | ||
String passwd | 사용자 PW | 70 | ||
String custName | 회사명 | 100 | ||
String ownerName | 대표자명 | 100 | ||
String bizCond | 업태 | 150 | ||
String bizItem | 종목 | 150 | ||
String rsbmName | 담당자명 | 100 | ||
String email | 이메일 | 100 | ||
String telNo | 전화번호 | 30 | ||
String hpNo | 휴대폰번호 | 30 | ||
String zipCode | 우편번호 | 10 | ||
String addr1 | 주소1 | 200 | ||
String addr2 | 주소2(상세주소) | 200 | ||
Response | String retVal | 결과코드 | - | |
String errMsg | 오류메시지 | - |
등록되어 있는 회원의 정보를 조회합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
selectMembInfo | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자 ID | 50 | ||
String passwd | 사용자 PW | 70 | ||
Response | String retVal | 결과코드 | - | |
String errMsg | 오류메시지 | - | ||
String bizNo | 사업자번호 | 10 | ||
String custName | 회사명 | 100 | ||
String ownerName | 대표자명 | 100 | ||
String bizCond | 업태 | 150 | ||
String bizItem | 종목 | 150 | ||
String rsbmName | 담당자명 | 100 | ||
String email | 이메일 | 100 | ||
String telNo | 전화번호 | 30 | ||
String hpNo | 휴대폰번호 | 30 | ||
String zipCode | 우편번호 | 10 | ||
String addr1 | 주소1 | 200 | ||
String addr2 | 주소2(상세주소) | 200 |
사업자 번호를 기준으로 특정 조회 기간(30일, 3,000건 이내)에 문서 상태 또는 전송 상태가 변경된 데이터를 요청합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
changedStatusReq | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String startYYYYMMDD | 조회시작일 (검색일은 30일이내) | 8 | ||
String endYYYYMMDD | 조회종료일 (검색일은 30일이내) | 8 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String statusMsg | 상태가 변경된 데이터(하기 샘플 참조) | - |
[statusMsg Sample]
[202201104100004000000001,2,C,SUC001; 로 리턴값을 받았다면 콤마(,) 차례대로
상기의 형식을 한 건으로 여기며 세미콜론(;)을 표기하여 구분, 다수의 건을 리턴합니다.
사용자 ID를 기준으로 특정 조회 기간(30일, 3,000건 이내)에 문서 상태 또는 전송 상태가 변경된 데이터를 요청합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
changedStatusReqById | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String startYYYYMMDD | 조회시작일 (검색일은 30일이내) | 8 | ||
String endYYYYMMDD | 조회종료일 (검색일은 30일이내) | 8 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String statusMsg | 상태가 변경된 데이터(하기 샘플 참조) | - |
[statusMsg Sample]
[202201104100004000000001,2,C,SUC001; 로 리턴값을 받았다면 콤마(,) 차례대로
상기의 형식을 한 건으로 여기며 세미콜론(;)을 표기하여 구분, 다수의 건을 리턴합니다.
‘상태 변경내역 요청(chagedStatusReq)’ 에서 받은 데이터의 응답을 확인 처리합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
changedStatusRes | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String statusMsg | 상태변경내역 요청 API에서 받은 statusMsg | - | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - |
이 단계는 상태 변경내역 요청 단계(API 6,7)와 같이 수행되어야 하는 웹서비스입니다.
연계코드를 기준으로 특정 일자(3,000건 이내)에 문서 상태 또는 전송상태가 변경된 데이터를 요청합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
changedStatusReqByLinkCd | Request | String linkCd | 연계코드 | 3 |
String YYYYMMDD | 조회일 | 8 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String statusMsg | 상태가 변경된 데이터(하기 샘플 참조) | - |
이 단계는 주기적인 호출로 상태 값을 업데이트하는 것을 권장합니다.
[statusMsg Sample]
[202201104100004000000001,2,C,SUC001; 로 리턴값을 받았다면 콤마(,) 차례대로
상기의 형식을 한 건으로 여기며 세미콜론(;)을 표기하여 구분, 다수의 건을 리턴합니다.
‘상태 변경내역 요청(chagedStatusReqByLinkCd)’ 에서 받은 데이터의 응답을 확인 처리합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
changedStatusResByLinkCd | Request | String linkCd | 연계코드 | 3 |
String statusMsg | 상태변경내역 요청 API에서 받은 statusMsg | - | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - |
이 단계는 상태 변경내역 요청 단계(API 9)와 같이 수행되어야 하는 웹서비스입니다.
해당 고객의 인증서 등록 여부(Y/N)와 등록된 인증서의 만료 일자를 조회합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
selectExpireDt | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String regYn | 등록여부(Y/N) | - | ||
String expireDt | 만료일자(YYYYMMDD) | - |
인증서 등록 여부에 따라 값이 구분됩니다.
인증서가 등록되어 있는 경우 | 인증서가 등록되지 않은 경우 |
---|
regYn = Y, expireDt = YYYYMMDD 날짜 (ex: 20240808) | regYn = N |
나이스빌에서 포인트를 관리하는 연계 업체의 경우, 해당 고객의 잔여 포인트(일반/보너스 등 구분)를 조회합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
selectPoint | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String gnlPoint | 일반 포인트 | - | ||
String bnsPoint | 보너스 포인트 | - | ||
String totPoint | 통합 포인트 | - |
회원 가입 시 생성된 고객 정보를 조회합니다. (고객번호, ID, PW)
Function Name | Parameters | Size | ||
---|---|---|---|---|
getMembJoinInf | Request | String linkCd | 연계코드 | 3 |
String linkId | 연계사가 사용중인 ID | - | ||
String bizNo | 사업자번호 | 10 | ||
String rsbmName | 담당자명 | 100 | ||
String email | 이메일 주소 | 30 | ||
String hpNo | 휴대폰 번호 | 30 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String frnNo | 고객사코드 | 10 | ||
String userId | 사용자 ID | 50 | ||
String passwd | 사용자 PW | 70 |
나이스빌에 등록된 공인인증서로 전자(세금)계산서 발행 시 설정된 시간 이후에 국세청으로 전송합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
makeAndPublishSignDelay | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String certPw | 암호화된 공인인증서 PW | 70 | ||
String DTIXml | 계산서 XML(DTIXml_sample.xml 파일 참조) | - | ||
String sendMailYn | 메일발송여부(Y/N) | 1 | ||
String sendSmsYn | 메시지 발송여부(Y/N) | 1 | ||
String delayHour | 지연 시간 | 2 | ||
String erpBillNo | 연계사 DB 계산서 ID (unique) | 36 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String billNo | 승인번호 | 24 | ||
String retErpBillNo | 연계사 DB 계산서 ID (unique) | 36 | ||
String gnlPoint | 일반 포인트 | - | ||
String bnsPoint | 보너스 포인트 | - | ||
String totPoint | 통합 포인트 | - | ||
※ 국세청 서버 환경 및 서비스 장애에 따라 추가적인 지연 전송 및 가산세 발생 시 나이스빌은 책임지지 않습니다.
국세청으로 전송되기 전인 전자(세금)계산서를 강제로 전송 중지 시킵니다.
이러한 경우 해당 계산서는 국세청으로 신고(전송) 처리되지 않으며 재발행 하여야 합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
updateEtaxStatusToZ | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String apprNo | 승인번호 | 24 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - |
erp Bill No가 포함된 연계코드 기준으로 특정 조회 기간(3,000건 이내)에 전송 상태가 변경된 데이터를 요청합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
reqStatusWithErpBillNo | Request | String linkCd | 연계코드 | 3 |
String YYYYMMDD | 조회일 | 8 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String statusMsg | 상태가 변경된 데이터(하기 샘플 참조) | - |
이 단계는 주기적인 호출로 상태 값을 업데이트하는 것을 권장합니다.
[statusMsg Sample]
[202201104100004000000001,abcdefg1234567,C,SUC001; 로 리턴값을 받았다면 콤마(,) 차례대로
상기의 형식을 한 건으로 여기며 세미콜론(;)을 표기하여 구분, 다수의 건을 리턴합니다.
‘상태 변경내역 요청(reqStatusWithErpBillNo)’ 에서 받은 데이터의 응답을 확인 요청합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
resStatusWithErpBillNo | Request | String linkCd | 연계코드 | 3 |
String statusMsg | 상태변경내역 요청 API에서 받은 statusMsg | - | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - |
이 단계는 상태 변경내역 요청 단계(API 16)와 같이 수행되어야 하는 웹서비스입니다.
승인번호(appr No)를 이용하여 해당 계산서 의 전송 상태를 조회합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
getResultStatus | Request | String linkCd | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String apprNo | 승인번호 | 24 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String status | 신고상태(코드표3 참조) | - | ||
String resultCode | 국세청 응답코드(코드표 4참조) | - |
승인번호(appr No)를 이용하여 해당 계산서의 메일 발송 조회, 입력한 수신메일 주소의 읽음 여부를 조회합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
getMailSendResult | Request | String linkCd | 연계코드 | 3 |
String apprNo | 승인번호 | 10 | ||
String receiveMail | 수신 메일주소 | - | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String sendYn | 발송 여부 | - | ||
String sendDttm | 발송 일시(yyyymmddhh24mi) | - | ||
String readYn | 읽음 여부(수신 메일주소가 있는 경우) | - | ||
String readDttm | 읽음 일시(yyyymmddhh24mi) | - |
※ sendYn, sendDttm의 경우 수신 메일 주소와 무관합니다.
※ readYn, readDttm의 경우 수신메일 주소가 존재하는 경우에만 리턴합니다. 하지만 해당 데이터는 100% 신뢰할 수 없습니다.
승인번호(appr No) 혹은 erp Bill No를 이용하여 해당 계산서의 정보를 조회합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
getEtaxInfo | Request | String linkCd | 연계코드 | 3 |
String typeCode | 조회 유형(01 : 승인번호 / 02 : erpBillNo) | 2 | ||
String billNo | 조회 번호 | - | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String apprNo | 승인번호 | 24 | ||
String erpBillNo | 연계사 DB 계산서 ID (unique) | 36 | ||
String splrBizNo | 공급자 사업자번호 | 10 | ||
String rplrBizNo | 공급받는자 사업자번호 | 10 | ||
String supAmt | 공급가액 | - | ||
String issueDttm | 발행 일시(yyyymmddhh24miss) | 14 |
전자(세금)계산서 발행을 요청합니다.
발행 요청이 정상적으로 완료되면 해당 계산서의 승인번호 총 24자리를 리턴합니다.
만약 포인트를 사용하는 고객사라면, 잔여 포인트도 같이 리턴합니다.
Function Name | Parameters | Size | ||
---|---|---|---|---|
makeAndPublishSignReverse | Request | String linkCd` | 연계코드 | 3 |
String frnNo | 고객사코드 | 10 | ||
String userid | 사용자ID | 50 | ||
String passwd | 사용자PW | 70 | ||
String DTIXml | 계산서 XML(DTIXml_sample.xml 파일 참조) | - | ||
String sendMailYn | 메일발송여부(Y/N) | 1 | ||
String sendSmsYn | SMS발송여부(Y/N) | 1 | ||
String erpBillNo | 연계사 DB 계산서 ID (unique) | 36 | ||
Response | String retVal | 결과코드(코드표1 참조) | - | |
String errMsg | 오류메시지 | - | ||
String billNo | 승인번호 | 24 | ||
String retErpBillNo | 연계사 DB 계산서 ID (unique) | 36 | ||
String gnlPoint | 일반 포인트 | - | ||
String bnsPoint | 보너스 포인트 | - | ||
String totPoint | 통합 포인트 | - |