PortOne REST API - V2
API 결제, 결제 정보 조회, 결제 취소 등의 기능을 제공하는 REST API입니다.
V2 API hostname: api.portone.io
요청 및 응답 형식
요청과 응답의 본문은 JSON 형식입니다.
API 응답에 포함된 필드는 별도 안내 없이 추가될 수 있으니, 알지 못하는 필드가 있는 경우에는 무시하도록 개발해 주세요.
API 매개 변수 중 URL 경로에 들어가는 문자열 값이 있는 경우, URL 경로에 들어갈 수 없는 문자열은 이스케이프하여야 합니다. 자바스크립트의 encodeURIComponent 함수 등을 사용할 수 있습니다.
인증 방식
V2 API를 사용하기 위해서는 V2 API Secret이 필요하며, 포트원 콘솔 내 결제연동 탭에서 발급받을 수 있습니다.
인증 관련 API를 제외한 모든 API는 HTTP Authorization 헤더로 인증 정보를 전달해 주셔야 합니다. Authorization 헤더에 전달하는 형식은 두 가지 중 하나입니다.
- API Secret 직접 사용 (간편)
Authorization: PortOne MY_API_SECRET - 액세스 토큰 사용
Authorization: Bearer MY_ACCESS_TOKEN
GET 요청 시 Body 대신 Query 사용
GET 요청 시에 Body를 사용해야 하는 경우, Body 대신 Query를 사용할 수 있습니다.
이 경우, Body 객체를 requestBody Query 필드에 넣어주시면 됩니다.
인증 관련 API
인증과 관련된 API 기능을 제공합니다.
결제 관련 API
결제와 관련된 API 기능을 제공합니다.
목차
결제 정보 사전 등록
post/payments/{paymentId}/pre-register결제 단건 조회
get/payments/{paymentId}결제 다건 조회(페이지 기반)
get/payments결제 대용량 다건 조회(커서 기반)
get/payments-by-cursor결제 취소
post/payments/{paymentId}/cancel빌링키 결제
post/payments/{paymentId}/billing-key수기 결제
post/payments/{paymentId}/instant가상계좌 말소
post/payments/{paymentId}/virtual-account/close에스크로 배송 정보 등록
post/payments/{paymentId}/escrow/logistics에스크로 배송 정보 수정
patch/payments/{paymentId}/escrow/logistics에스크로 구매 확정
post/payments/{paymentId}/escrow/complete웹훅 재발송
post/payments/{paymentId}/resend-webhook영수증 내 하위 상점 거래 등록
post/payments/{paymentId}/register-store-receipt결제 예약 관련 API
빌링키 관련 API
현금 영수증 관련 API
본인인증 관련 API
B2B 서비스 API
B2B 관련 API 기능을 제공합니다. alpha 버전의 API 로서, 사용을 원하실 경우 관리자콘솔 및 홈페이지를 통해 문의해주세요.
목차
연동 사업자 조회
get/b2b-preview/member-companies/{brn}연동 사업자 정보 수정
patch/b2b-preview/member-companies/{brn}사업자 연동
post/b2b-preview/member-companies담당자 조회
get/b2b-preview/member-companies/{brn}/contacts/{contactId}담당자 정보 수정
patch/b2b-preview/member-companies/{brn}/contacts/{contactId}사업자 인증서 등록 URL 조회
get/b2b-preview/member-companies/{brn}/certificate/registration-url인증서 조회
get/b2b-preview/member-companies/{brn}/certificate담당자 ID 존재 여부 확인
get/b2b-preview/member-companies/contacts/id-existence예금주 조회
get/b2b-preview/bank-accounts/{bank}/{accountNumber}/holder사업자 상태 조회
get/b2b-preview/company/{brn}/state세금계산서 역발행 요청
post/b2b-preview/tax-invoices/request-reverse-issuance세금 계산서 조회
get/b2b-preview/tax-invoices/{documentKey}세금계산서 삭제
delete/b2b-preview/tax-invoices/{documentKey}세금계산서 발행
post/b2b-preview/tax-invoices/issue세금계산서 역발행 요청 취소
post/b2b-preview/tax-invoices/cancel-request세금계산서 역발행 취소
post/b2b-preview/tax-invoices/cancel-issuance세금계산서 역발행 요청 거부
post/b2b-preview/tax-invoices/refuse-request세금 계산서 다건조회
get/b2b-preview/tax-invoices세금 계산서 팝업 URL 조회
get/b2b-preview/tax-invoices/{documentKey}/popup-url세금 계산서 프린트 URL 조회
get/b2b-preview/tax-invoices/{documentKey}/print-url세금 계산서 PDF 다운로드 URL 조회
get/b2b-preview/tax-invoices/{documentKey}/pdf-download-url세금계산서 임시 저장
post/b2b-preview/tax-invoices/register세금계산서 역발행 요청
post/b2b-preview/tax-invoices/request세금계산서 파일 업로드 링크 생성
post/b2b-preview/tax-invoices/file-upload-link세금계산서 파일 첨부
post/b2b-preview/tax-invoices/attach-file세금계산서 첨부파일 목록 조회
get/b2b-preview/tax-invoices/{documentKey}/attachments세금계산서 첨부파일 삭제
delete/b2b-preview/tax-invoices/{documentKey}/attachments/{attachmentId}get/b2b-preview/member-companies/{brn}
연동 사업자 조회unstable
포트원 B2B 서비스에 연동된 사업자를 조회합니다.
Request
Path
brn: string
사업자등록번호
사업자등록번호
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
성공 응답으로 사업자 객체를 반환합니다.
brn: string
사업자등록번호
- 없이 숫자로만 구성됩니다.
name: string
회사명
ceoName: string
대표자 성명
address: string
회사 주소
businessType: string
업태
businessClass: string
업종
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bMemberCompanyNotFoundError: 연동 사업자가 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bMemberCompanyNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
patch/b2b-preview/member-companies/{brn}
연동 사업자 정보 수정unstable
연동 사업자 정보를 수정합니다.
Request
Path
brn: string
사업자등록번호
사업자등록번호
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Body
name?: string
회사명
(Optional)
ceoName?: string
대표자 성명
(Optional)
address?: string
회사 주소
(Optional)
businessType?: string
업태
(Optional)
businessClass?: string
업종
(Optional)
Response
200
성공 응답
B2bMemberCompany
brn: string
사업자등록번호
- 없이 숫자로만 구성됩니다.
name: string
회사명
ceoName: string
대표자 성명
address: string
회사 주소
businessType: string
업태
businessClass: string
업종
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bMemberCompanyNotFoundError: 연동 사업자가 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bMemberCompanyNotFoundError 입니다.
message?: string
(Optional)
try
Request
Request Sample
post/b2b-preview/member-companies
사업자 연동unstable
포트원 B2B 서비스에 사업자를 연동합니다.
Request
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Body
B2bMemberCompany
brn: string
사업자등록번호
- 없이 숫자로만 구성됩니다.
name: string
회사명
ceoName: string
대표자 성명
address: string
회사 주소
businessType: string
업태
businessClass: string
업종
B2bCompanyContactInput
id: string
담당자 ID
팝빌 로그인 계정으로 사용됩니다.
password: string
비밀번호
name: string
담당자 성명
phoneNumber: string
담당자 핸드폰 번호
email: string
담당자 이메일
Response
200
성공 응답
B2bMemberCompany
brn: string
사업자등록번호
- 없이 숫자로만 구성됩니다.
name: string
회사명
ceoName: string
대표자 성명
address: string
회사 주소
businessType: string
업태
businessClass: string
업종
B2bCompanyContact
id: string
담당자 ID
팝빌 로그인 계정으로 사용됩니다.
name: string
담당자 성명
phoneNumber: string
담당자 핸드폰 번호
email: string
담당자 이메일
등록 일시
isManager: boolean
관리자 여부
true일 경우 관리자, false일 경우 담당자입니다.
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
409
B2bIdAlreadyExistsError: ID가 이미 사용중인 경우B2bCompanyAlreadyRegisteredError: 사업자가 이미 연동되어 있는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bCompanyAlreadyRegisteredError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
get/b2b-preview/member-companies/{brn}/contacts/{contactId}
담당자 조회unstable
연동 사업자에 등록된 담당자를 조회합니다.
Request
Path
brn: string
사업자등록번호
사업자등록번호
contactId: string
담당자 ID
담당자 ID
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
성공 응답으로 담당자 객체를 반환합니다.
id: string
담당자 ID
팝빌 로그인 계정으로 사용됩니다.
name: string
담당자 성명
phoneNumber: string
담당자 핸드폰 번호
email: string
담당자 이메일
등록 일시
isManager: boolean
관리자 여부
true일 경우 관리자, false일 경우 담당자입니다.
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bMemberCompanyNotFoundError: 연동 사업자가 존재하지 않는 경우B2bContactNotFoundError: 담당자가 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bContactNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
patch/b2b-preview/member-companies/{brn}/contacts/{contactId}
담당자 정보 수정unstable
담당자 정보를 수정합니다.
Request
Path
brn: string
사업자등록번호
사업자등록번호
contactId: string
담당자 ID
담당자 ID
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Body
password?: string
비밀번호
(Optional)
name?: string
담당자 성명
(Optional)
phoneNumber?: string
담당자 핸드폰 번호
(Optional)
email?: string
담당자 이메일
(Optional)
Response
200
성공 응답
B2bCompanyContact
id: string
담당자 ID
팝빌 로그인 계정으로 사용됩니다.
name: string
담당자 성명
phoneNumber: string
담당자 핸드폰 번호
email: string
담당자 이메일
등록 일시
isManager: boolean
관리자 여부
true일 경우 관리자, false일 경우 담당자입니다.
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bContactNotFoundError: 담당자가 존재하지 않는 경우B2bMemberCompanyNotFoundError: 연동 사업자가 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bContactNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
get/b2b-preview/member-companies/{brn}/certificate/registration-url
사업자 인증서 등록 URL 조회unstable
연동 사업자의 인증서를 등록하기 위한 URL을 조회합니다.
Request
Path
brn: string
사업자등록번호
사업자등록번호
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
성공 응답으로 URL을 반환합니다.
url: string
인증서 등록 URL
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bMemberCompanyNotFoundError: 연동 사업자가 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bMemberCompanyNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
get/b2b-preview/member-companies/{brn}/certificate
인증서 조회unstable
연동 사업자의 인증서를 조회합니다.
Request
Path
brn: string
사업자등록번호
사업자등록번호
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
성공 응답으로 인증서 객체를 반환합니다.
등록일시
만료일시
issuerDn: string
발행자명
subjectDn: string
본인명
인증서 타입
인증서 타입
E_TAX전자세금용 공동인증서POP_BILL팝빌 특목용 공동인증서ETC기타oid: string
OID
registrantContactName: string
등록 담당자 성명
registrantContactId: string
등록 담당자 ID
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bMemberCompanyNotFoundError: 연동 사업자가 존재하지 않는 경우B2bCertificateUnregisteredError: 인증서가 등록되어 있지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bCertificateUnregisteredError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
get/b2b-preview/member-companies/contacts/id-existence
담당자 ID 존재 여부 확인unstable
담당자 ID가 이미 사용중인지 확인합니다.
Request
Query
contactId: string
담당자 ID
담당자 ID
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
성공 응답입니다.
exists: boolean
존재 여부
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
get/b2b-preview/bank-accounts/{bank}/{accountNumber}/holder
예금주 조회unstable
원하는 계좌의 예금주를 조회합니다.
Request
Path
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
성공 응답
accountHolder: string
예금주
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bBankAccountNotFoundError: 계좌가 존재하지 않는 경우B2bForeignExchangeAccountError: 계좌 정보 조회가 불가능한 외화 계좌인 경우B2bSuspendedAccountError: 정지 계좌인 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bBankAccountNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
503
B2bRegularMaintenanceTimeError: 금융기관 시스템이 정기 점검 중인 경우B2bFinancialSystemFailureError: 금융기관 장애B2bFinancialSystemUnderMaintenanceError: 금융기관 시스템이 점검 중인 경우B2bFinancialSystemCommunicationError: 금융기관과의 통신에 실패한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bFinancialSystemCommunicationError 입니다.
message?: string
(Optional)
try
Request
Request Sample
get/b2b-preview/company/{brn}/state
사업자 상태 조회unstable
원하는 사업자의 상태를 조회합니다. 포트원 B2B 서비스에 연동 및 등록되지 않은 사업자도 조회 가능합니다.
Request
Path
brn: string
사업자등록번호
사업자등록번호
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
성공 응답으로 사업자 상태 객체를 반환합니다.
사업자 과세 유형
사업자 과세 유형
SIMPLE간이 과세ASSIGNED_ID_NUMBER비영리법인 또는 국가기관, 고유번호가 부여된 단체TAX_FREE면세SIMPLE_TAX_INVOICE_ISSUER간이 과세 세금계산서 발급 사업자NORMAL일반 과세taxationTypeDate?: string
과세 유형 변경 일자
(Optional)
날짜를 나타내는 문자열로, yyyy-MM-dd 형식을 따릅니다.
영업 상태
영업 상태
IN_BUSINESS영업중CLOSED폐업SUSPENDED휴업closedSuspendedDate?: string
휴폐업 일자
(Optional)
날짜를 나타내는 문자열로, yyyy-MM-dd 형식을 따릅니다.
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bCompanyNotFoundError: 사업자가 존재하지 않는 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bCompanyNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
503
B2bHometaxUnderMaintenanceError: 홈택스가 점검중이거나 순단이 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bHometaxUnderMaintenanceError 입니다.
message?: string
(Optional)
try
Request
Request Sample
post/b2b-preview/tax-invoices/request-reverse-issuance
세금계산서 역발행 요청unstable
공급자에게 세금계산서 역발행을 요청합니다.
Request
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Body
세금계산서 생성 요청 정보
세금계산서 생성 요청 정보
과세 유형
과세 유형
serialNum?: string
일련번호
(Optional)
bookVolume?: integer (32 bit)
권
(Optional)
bookIssue?: integer (32 bit)
호
(Optional)
writeDate: string
작성일
날짜를 나타내는 문자열로, yyyy-MM-dd 형식을 따릅니다.
영수/청구
영수/청구
supplyCostTotalAmount: integer (64 bit)
공급가액 합계
taxTotalAmount: integer (64 bit)
세액 합계
totalAmount: integer (64 bit)
합계 금액
cashAmount?: integer (64 bit)
현금
(Optional)
checkAmount?: integer (64 bit)
수표
(Optional)
creditAmount?: integer (64 bit)
외상
(Optional)
noteAmount?: integer (64 bit)
수표
(Optional)
remarks?: string[]
비고
(Optional)
최대 3개
supplierDocumentKey?: string
공급자 문서번호
(Optional)
영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
B2bTaxInvoiceCompany
recipientDocumentKey?: string
공급받는자 문서번호
(Optional)
영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
B2bTaxInvoiceCompany
sendSms?: boolean
문자 전송 여부
(Optional)
공급자 담당자 휴대폰번호 {supplier.contact.mobile_phone_number} 값으로 문자 전송 전송시 포인트 차감되며, 실패시 환불 처리 기본값은 false
세금 계산서 수정
(Optional)
세금 계산서 수정
품목
(Optional)
최대 99개
추가 담당자
(Optional)
최대 3개
memo?: string
메모
(Optional)
Response
200
성공 응답으로 세금계산서를 반환합니다.
status: string (Union Tag)
세금계산서 상태
필드의 값이 일 때 타입은 B2bTaxInvoiceBeforeSending 입니다.
과세 유형
과세 유형
TAXABLE과세ZERO_RATED영세FREE면세serialNum?: string
일련번호
(Optional)
bookVolume?: integer (32 bit)
책번호 - 권
(Optional)
입력 범위(4자리) : 0 ~ 9999
bookIssue?: integer (32 bit)
책번호 - 호
(Optional)
입력 범위(4자리) : 0 ~ 9999
writeDate: string
작성일
날짜를 나타내는 문자열로, yyyy-MM-dd 형식을 따릅니다.
영수/청구
영수/청구
RECEIPTINVOICENONEsupplyCostTotalAmount: integer (64 bit)
공급가액 합계
taxTotalAmount: integer (64 bit)
세액 합계
totalAmount: integer (64 bit)
합계 금액
cashAmount?: integer (64 bit)
현금
(Optional)
checkAmount?: integer (64 bit)
수표
(Optional)
creditAmount?: integer (64 bit)
외상
(Optional)
noteAmount?: integer (64 bit)
수표
(Optional)
remarks: string[]
비고
최대 3개
supplierDocumentKey?: string
공급자 문서번호
(Optional)
B2bTaxInvoiceCompany
brn: string
사업자등록번호
-를 제외한 10자리
taxRegistrationId?: string
종사업자 식별 번호
(Optional)
4자리 고정
name?: string
상호명
(Optional)
최대 200자
ceoName?: string
대표자 성명
(Optional)
최대 100자
address?: string
주소
(Optional)
최대 300자
businessType?: string
업태
(Optional)
최대 100자
businessClass?: string
종목
(Optional)
최대 100자
세금계산서 담당자
(Optional)
세금계산서 담당자
recipientDocumentKey?: string
공급받는자 문서번호
(Optional)
B2bTaxInvoiceCompany
brn: string
사업자등록번호
-를 제외한 10자리
taxRegistrationId?: string
종사업자 식별 번호
(Optional)
4자리 고정
name?: string
상호명
(Optional)
최대 200자
ceoName?: string
대표자 성명
(Optional)
최대 100자
address?: string
주소
(Optional)
최대 300자
businessType?: string
업태
(Optional)
최대 100자
businessClass?: string
종목
(Optional)
최대 100자
세금계산서 담당자
(Optional)
세금계산서 담당자
sendSms: boolean
문자 전송 여부
세금 계산서 수정
(Optional)
세금 계산서 수정
수정 사유
수정 사유
originalNtsApproveNumber: string
수정 대상 원본 세금계산서 국세청 승인 번호
품목
최대 99개
purchaseDate?: string
결제일
(Optional)
날짜를 나타내는 문자열로, yyyy-MM-dd 형식을 따릅니다.
name?: string
품명
(Optional)
최대 100자
spec?: string
규격
(Optional)
최대 100자
quantity?: integer (64 bit)
수량
(Optional)
입력 범위 : -99999999.99 ~ 999999999.99, 10^-quantityScale 단위로 치환됨
quantityScale?: integer (32 bit)
수량 단위
(Optional)
입력 범위 : 0 ~ 2, 기본값: 0
unitCostAmount?: integer (64 bit)
단가
(Optional)
입력 범위 : -99999999999999.99 ~ 999999999999999.99
unitCostAmountScale?: integer (32 bit)
단가 단위
(Optional)
입력 범위 : 0 ~ 2, 기본값: 0
supplyCostAmount?: integer (64 bit)
공급가액
(Optional)
taxAmount?: integer (64 bit)
세액
(Optional)
remark?: string
비고
(Optional)
추가 담당자
최대 3개
name?: string
성명
(Optional)
최대 100자
email: string
이메일
상태 변경 일시
발행 일시
ntsApproveNumber: string
국세청 승인번호
세금계산서 발행(전자서명) 시점에 자동으로 부여
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bSupplierNotFoundError: 공급자가 존재하지 않은 경우B2bRecipientNotFoundError: 공급받는자가 존재하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bRecipientNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
get/b2b-preview/tax-invoices/{documentKey}
세금 계산서 조회unstable
등록된 세금 계산서를 공급자 혹은 공급받는자 문서번호로 조회합니다.
Request
Path
documentKey: string
세금계산서 문서 번호
세금계산서 문서 번호
Query
brn: string
사업자등록번호
사업자등록번호
문서 번호 유형
(Optional)
path 파라미터로 전달된 문서번호 유형. 기본 값은 RECIPIENT이며 SUPPLIER, RECIPIENT을 지원합니다.
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
성공 응답으로 세금계산서를 반환합니다.
status: string (Union Tag)
세금계산서 상태
필드의 값이 일 때 타입은 B2bTaxInvoiceBeforeSending 입니다.
과세 유형
과세 유형
TAXABLE과세ZERO_RATED영세FREE면세serialNum?: string
일련번호
(Optional)
bookVolume?: integer (32 bit)
책번호 - 권
(Optional)
입력 범위(4자리) : 0 ~ 9999
bookIssue?: integer (32 bit)
책번호 - 호
(Optional)
입력 범위(4자리) : 0 ~ 9999
writeDate: string
작성일
날짜를 나타내는 문자열로, yyyy-MM-dd 형식을 따릅니다.
영수/청구
영수/청구
RECEIPTINVOICENONEsupplyCostTotalAmount: integer (64 bit)
공급가액 합계
taxTotalAmount: integer (64 bit)
세액 합계
totalAmount: integer (64 bit)
합계 금액
cashAmount?: integer (64 bit)
현금
(Optional)
checkAmount?: integer (64 bit)
수표
(Optional)
creditAmount?: integer (64 bit)
외상
(Optional)
noteAmount?: integer (64 bit)
수표
(Optional)
remarks: string[]
비고
최대 3개
supplierDocumentKey?: string
공급자 문서번호
(Optional)
B2bTaxInvoiceCompany
brn: string
사업자등록번호
-를 제외한 10자리
taxRegistrationId?: string
종사업자 식별 번호
(Optional)
4자리 고정
name?: string
상호명
(Optional)
최대 200자
ceoName?: string
대표자 성명
(Optional)
최대 100자
address?: string
주소
(Optional)
최대 300자
businessType?: string
업태
(Optional)
최대 100자
businessClass?: string
종목
(Optional)
최대 100자
세금계산서 담당자
(Optional)
세금계산서 담당자
recipientDocumentKey?: string
공급받는자 문서번호
(Optional)
B2bTaxInvoiceCompany
brn: string
사업자등록번호
-를 제외한 10자리
taxRegistrationId?: string
종사업자 식별 번호
(Optional)
4자리 고정
name?: string
상호명
(Optional)
최대 200자
ceoName?: string
대표자 성명
(Optional)
최대 100자
address?: string
주소
(Optional)
최대 300자
businessType?: string
업태
(Optional)
최대 100자
businessClass?: string
종목
(Optional)
최대 100자
세금계산서 담당자
(Optional)
세금계산서 담당자
sendSms: boolean
문자 전송 여부
세금 계산서 수정
(Optional)
세금 계산서 수정
수정 사유
수정 사유
originalNtsApproveNumber: string
수정 대상 원본 세금계산서 국세청 승인 번호
품목
최대 99개
purchaseDate?: string
결제일
(Optional)
날짜를 나타내는 문자열로, yyyy-MM-dd 형식을 따릅니다.
name?: string
품명
(Optional)
최대 100자
spec?: string
규격
(Optional)
최대 100자
quantity?: integer (64 bit)
수량
(Optional)
입력 범위 : -99999999.99 ~ 999999999.99, 10^-quantityScale 단위로 치환됨
quantityScale?: integer (32 bit)
수량 단위
(Optional)
입력 범위 : 0 ~ 2, 기본값: 0
unitCostAmount?: integer (64 bit)
단가
(Optional)
입력 범위 : -99999999999999.99 ~ 999999999999999.99
unitCostAmountScale?: integer (32 bit)
단가 단위
(Optional)
입력 범위 : 0 ~ 2, 기본값: 0
supplyCostAmount?: integer (64 bit)
공급가액
(Optional)
taxAmount?: integer (64 bit)
세액
(Optional)
remark?: string
비고
(Optional)
추가 담당자
최대 3개
name?: string
성명
(Optional)
최대 100자
email: string
이메일
상태 변경 일시
발행 일시
ntsApproveNumber: string
국세청 승인번호
세금계산서 발행(전자서명) 시점에 자동으로 부여
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 InvalidRequestError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bTaxInvoiceNotFoundError: 세금계산서가 존재하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bTaxInvoiceNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
delete/b2b-preview/tax-invoices/{documentKey}
세금계산서 삭제unstable
세금계산서를 삭제합니다.
Request
Path
documentKey: string
세금계산서 문서 번호
세금계산서 문서 번호
Query
brn: string
사업자등록번호
사업자등록번호
문서 번호 유형
(Optional)
path 파라미터로 전달된 문서번호 유형. 기본 값은 RECIPIENT이며 SUPPLIER, RECIPIENT을 지원합니다.
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Response
200
400
InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우B2bTaxInvoiceNonDeletableStatusError: 세금계산서가 삭제 가능한 상태가 아닌 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bTaxInvoiceNonDeletableStatusError 입니다.
message?: string
(Optional)
401
UnauthorizedError: 인증 정보가 올바르지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 UnauthorizedError 입니다.
message?: string
(Optional)
403
B2bNotEnabledError: B2B 기능이 활성화되지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bNotEnabledError 입니다.
message?: string
(Optional)
404
B2bTaxInvoiceNotFoundError: 세금계산서가 존재하지 않은 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bTaxInvoiceNotFoundError 입니다.
message?: string
(Optional)
502
B2bExternalServiceError: 외부 서비스에서 에러가 발생한 경우
type: string (Union Tag)
필드의 값이 일 때 타입은 B2bExternalServiceError 입니다.
message: string
try
Request
Request Sample
post/b2b-preview/tax-invoices/issue
세금계산서 발행unstable
역발행의 경우 역발행요청(REQUESTED) 상태, 정발행의 경우 임시저장(REGISTERED) 상태의 세금계산서를 발행합니다.
Request
Query
test?: boolean
테스트 모드 여부
(Optional)
true 이면 테스트 모드로 실행되며, false 이거나 주어지지 않은 경우 테스트 모드를 사용하지 않습니다.
Body
brn: string
사업자등록번호
documentKey: string
세금계산서 문서 번호
문서번호 유형
(Optional)
문서번호 유형
SUPPLIER공급자RECIPIENT공급받는자memo?: string
메모
(Optional)
emailSubject?: string
이메일 제목
(Optional)
Response
200
성공 응답으로 세금계산서를 반환합니다.
status: string (Union Tag)
세금계산서 상태
필드의 값이 일 때 타입은 B2bTaxInvoiceBeforeSending 입니다.
과세 유형
과세 유형
TAXABLE과세ZERO_RATED영세FREE면세serialNum?: string
일련번호
(Optional)
bookVolume?: integer (32 bit)
책번호 - 권
(Optional)
입력 범위(4자리) : 0 ~ 9999
bookIssue?: integer (32 bit)
책번호 - 호
(Optional)
입력 범위(4자리) : 0 ~ 9999
writeDate: string
작성일
날짜를 나타내는 문자열로, yyyy-MM-dd 형식을 따릅니다.
영수/청구
영수/청구
RECEIPTINVOICENONEsupplyCostTotalAmount: integer (64 bit)
공급가액 합계
taxTotalAmount: integer (64 bit)
세액 합계
totalAmount: integer (64 bit)
합계 금액
cashAmount?: integer (64 bit)
현금
(Optional)
checkAmount?: integer (64 bit)
수표
(Optional)
creditAmount?: integer (64 bit)
외상
(Optional)
noteAmount?: integer (64 bit)
수표
(Optional)
remarks: string[]
비고
최대 3개
supplierDocumentKey?: string
공급자 문서번호
(Optional)
B2bTaxInvoiceCompany
brn: string
사업자등록번호
-를 제외한 10자리
taxRegistrationId?: string
종사업자 식별 번호
(Optional)
4자리 고정
name?: string
상호명
(Optional)
최대 200자
ceoName?: string
대표자 성명
(Optional)
최대 100자