전자세금계산서 전송 상태 결과조회 API

인증요청 5분 · 결과 재조회 24시간은 서로 다른 기한입니다. 5분(AUTH_WAITING 중 expiresAt)은 "사용자가 승인해야 하는 시간"이고, 24시간(resultExpiresAt)은 "받은 결과를 다시 꺼내볼 수 있는 시간"입니다. 5분 안에 승인하지 못하면 그 요청은 AUTH_EXPIRED 로 끝나고 결과 단가는 발생하지 않습니다. 인증요청 단가 20P 는 발송이 성공한 시점에 이미 발생하므로 승인 실패·거부와 무관하게 환불되지 않습니다. 결과 보관 만료는 errorCode=RESULT_EXPIRED로 구분합니다. 새 인증·조회에는 각 단계의 과금 조건이 다시 적용됩니다. 동일 APICK 계정·같은 상품의 진행 중 요청 또는 최근 30초 내 요청이 있으면 인증을 재발송하지 않고 기존 transactionId 를 그대로 반환합니다. 이때는 success=0, charged=false 로 돌아오며 과금되지 않습니다. 중복 판정은 조회 대상자의 이름·전화번호가 아닌 계정·상품 기준입니다. 다른 대상자의 인증을 동시에 요청하지 마세요.

인증 대기중(AUTH_WAITING)과 조회 중(COLLECTING)은 실패가 아닙니다. 개발 중에 이 응답을 오류로 처리해 사용자에게 "실패"라고 보여주는 경우가 많습니다. resultAvailable=false 는 "아직 준비 중"이라는 뜻이고, resultAvailable=true 일 때만 결과를 사용하세요. 같은 transactionId 를 다른 조회 항목의 엔드포인트로 조회하면 실패합니다. 인증요청에 사용한 /rest/req_<항목> 과 같은 항목의 /rest/get_<항목> 을 짝으로 사용하세요.

인증 승인은 사용자가 직접 해야 합니다. 승인 대행·자동 승인·인증 정보 저장은 지원하지 않으며, 사용자에게 승인 화면을 안내하는 흐름을 직접 만들어야 합니다. 승인 전 화면을 이탈한 사용자가 많다면 expiresAt 으로 남은 시간을 표시하고, 만료 후에는 재요청 버튼을 제공하세요. 만료된 transactionId 는 재사용할 수 없습니다.

API 요청

POST/rest/get_etax_status

Bearer 인증
multipart/form-data
JSON 응답

요청 예제

curl --fail-with-body --request POST 'https://apick.app/rest/get_etax_status' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'transactionId=9f2c4a7b1d8e35c60a4f7b2d1e9c803a'

curl --fail-with-body --request POST 'https://apick.app/rest/get_etax_status' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --form-string 'transactionId=9f2c4a7b1d8e35c60a4f7b2d1e9c803a'

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const form = new FormData();
form.append("transactionId", "9f2c4a7b1d8e35c60a4f7b2d1e9c803a");
const response = await fetch("https://apick.app/rest/get_etax_status", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const form = new FormData();
form.append("transactionId", "9f2c4a7b1d8e35c60a4f7b2d1e9c803a");
const response = await fetch("https://apick.app/rest/get_etax_status", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
parts = [
    ("transactionId", (None, "9f2c4a7b1d8e35c60a4f7b2d1e9c803a")),
]
response = requests.request("POST", "https://apick.app/rest/get_etax_status",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
parts = [
    ("transactionId", (None, "9f2c4a7b1d8e35c60a4f7b2d1e9c803a")),
]
response = requests.request("POST", "https://apick.app/rest/get_etax_status",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'transactionId' => '9f2c4a7b1d8e35c60a4f7b2d1e9c803a',
];
$curl = curl_init('https://apick.app/rest/get_etax_status');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'transactionId' => '9f2c4a7b1d8e35c60a4f7b2d1e9c803a',
];
$curl = curl_init('https://apick.app/rest/get_etax_status');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

{
  "data": {
    "schemaVersion": "1.0",
    "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
    "product": "etax_status",
    "status": "AUTH_WAITING",
    "resultAvailable": false,
    "charged": false,
    "sources": [],
    "message": "인증 대기중입니다.",
    "expiresAt": "2026-09-20T05:24:07+09:00",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 42,
    "pl_id": -1
  }
}

{
  "data": {
    "schemaVersion": "1.0",
    "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
    "product": "etax_status",
    "status": "COLLECTING",
    "resultAvailable": false,
    "charged": false,
    "sources": [],
    "progress": {
      "total": 1,
      "completed": 0
    },
    "message": "정보를 조회하고 있습니다.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 38,
    "pl_id": -1
  }
}

{
  "data": {
    "schemaVersion": "1.0",
    "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
    "product": "etax_status",
    "status": "SUCCESS",
    "resultAvailable": true,
    "charged": true,
    "sources": [
      {
        "source": "전자세금계산서 전송 상태 조회",
        "type": "ETAX_STATUS",
        "status": "SUCCESS"
      }
    ],
    "checkedAt": "2026-09-20T04:47:33+09:00",
    "resultExpiresAt": "2026-09-21T04:47:33+09:00",
    "result": {
      "etaxStatus": {
        "확인건수": 3,
        "확인시각": "2026-10-26T14:20:00.000Z",
        "상태": [
          {
            "승인번호": "20261026-41000001-12345678",
            "구분": "매출",
            "전송상태": "전송완료",
            "상태코드": ""
          }
        ],
        "장부에없는승인번호": []
      }
    },
    "message": "인증이 완료되었습니다.",
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 60,
    "ms": 318,
    "pl_id": 4903
  }
}

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

요청 파라미터 1개 · 필수 1

파라미터

설명

transactionIdstring필수

인증요청 단계에서 발급된 거래 ID입니다. 인증요청 응답의 transactionId를 그대로 넣어야 하며, 임의 값이나 만료된 ID는 거부됩니다.

예시: 9f2c4a7b1d8e35c60a4f7b2d1e9c803a

응답 필드 36개

응답 필드

설명

dataobject

요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

data.schemaVersionstring

응답 스키마의 버전입니다. 현재 "1.0"으로 고정되어 있으며, 필드 구조가 바뀌면 값이 올라갑니다. 클라이언트는 이 값을 저장해 두고 파싱 로직을 분기할 수 있습니다.

data.transactionIdstring

간편인증 요청에서 발급된 거래 ID입니다. 인증요청 응답의 transactionId와 같으며, 같은 거래의 결과를 조회하거나 문의할 때 사용합니다. 인증이 만료되면 새 거래를 만들어야 합니다.

data.productstring

조회한 상품 코드입니다. 인증요청 때 보낸 product와 같은 값이며, 응답의 result 구조를 해석할 때 기준이 됩니다.

data.statusstring

현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 9가지입니다. AUTH_REQUESTED = 인증 요청만 접수되어 사용자 승인을 기다리는 상태, AUTH_WAITING = 승인 전 대기, AUTH_COMPLETED = 승인은 끝났고 결과 준비 전, COLLECTING = 결과 준비 중, SUCCESS = 정상 완료되어 결과 사용 가능, PARTIAL_SUCCESS = 일부 자료만 준비되어 sources의 항목별 status 확인 필요, FAILED = 서버 처리 실패, AUTH_REJECTED = 사용자가 인증 거부, AUTH_EXPIRED = 승인 유효시간(300초) 만료입니다.

data.resultAvailableboolean

실제 결과 포함 여부. 과금 여부도 이 값으로 결정됩니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 결과를 지금 사용할 수 있는 경우, false = 아직 처리 중이거나 실패·만료되어 결과가 없는 경우입니다. false면 data.status를 확인하세요.

data.chargedboolean

이번 호출의 과금 발생 여부. 최초 결과 반환에서만 true 입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이번 조회에서 포인트가 실제로 차감된 경우(유료 결과를 처음 받은 때), false = 이미 차감된 결과를 다시 조회했거나 무료 응답인 경우입니다. api.cost가 0이면 false입니다.

data.sourcesarray

자료 항목별 처리 결과 목록입니다. 항목별 성공·실패를 구분하므로 일부만 성공한 응답을 판단할 때 사용합니다.

data.messagestring

안내 문구입니다. 오류 원인과 다음 행동을 설명합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

data.expiresAtstring

이 응답이나 인증 요청의 유효 만료 시각입니다. 한국시간(UTC+09:00) ISO 8601 형식이며, 이 시각을 넘기면 같은 요청을 다시 접수해야 합니다.

data.successinteger

업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

data.progressobject

결과 준비 진행 상태 묶음입니다. 전체 자료 수와 완료된 자료 수를 담습니다.

data.checkedAtstring

실제 정보를 확인한 시각. 한국시간(UTC+09:00) ISO 8601 이며 재조회 유효기간의 기준입니다.

data.resultExpiresAtstring

결과 재조회 만료 시각. 한국시간(UTC+09:00) ISO 8601 입니다.

data.resultobject

조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.

data.errorCodestring

오류 구분. RESULT_EXPIRED(재조회 기간 만료) / AUTH_EXPIRED / AUTH_REJECTED / COLLECT_FAILED / SERVICE_MAINTENANCE(기관이 서비스 점검·중지 중) 가능한 값은 5가지입니다. RESULT_EXPIRED = 결과 재조회 기간이 지난 경우(새로 인증해야 함), AUTH_EXPIRED = 승인 유효시간이 지난 경우, AUTH_REJECTED = 사용자가 인증을 거부한 경우, COLLECT_FAILED = 승인 뒤 결과 준비가 실패한 경우, SERVICE_MAINTENANCE = 기관이 서비스 점검(중지) 중이라 결과를 만들지 못한 경우입니다. SERVICE_MAINTENANCE 는 요청 오류가 아니므로 입력값을 고칠 필요가 없습니다. 오류가 없으면 null입니다.

data.maintenanceboolean

기관이 서비스 점검(중지) 중이라 결과를 만들지 못한 경우에만 true 입니다. 요청 오류가 아니므로 입력값을 고칠 필요가 없고, 점검 시간이 끝난 뒤 다시 요청하세요. 값이 없거나 false 면 점검 때문이 아닙니다. 이때는 message 에 같은 안내가 들어옵니다.

apiobject

API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

api.successboolean

API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

api.costinteger

이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

api.msinteger

서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

api.pl_idinteger

포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

하위 필드 14개 더 보기

응답 필드

설명

data.sources[].sourcestring

자료 항목의 표시 이름입니다. type과 함께 어떤 자료인지 구분할 때 사용합니다.

data.sources[].typestring

자료 유형 구분자입니다. 같은 상품 안에서 여러 종류의 자료를 묶어 받을 때 종류를 구분합니다.

data.sources[].statusstring

해당 자료 항목의 처리 상태입니다. SUCCESS는 정상, 그 외 값은 그 항목만 실패했거나 자료가 없음을 뜻합니다. 가능한 값은 2가지입니다. SUCCESS = 해당 자료 항목을 정상적으로 받은 경우, FAILED = 그 항목만 실패해 result에 그 자료가 빠진 경우입니다. 전체 status가 SUCCESS여도 항목별 FAILED가 있을 수 있습니다.

data.progress.totalinteger

이번 조회에서 준비할 전체 자료 항목 수입니다. 여러 자료를 묶은 상품에서 진행률 계산의 분모로 사용합니다.

data.progress.completedinteger

현재까지 준비를 마친 자료 항목 수입니다. total과 같아지면 모든 항목의 처리가 끝난 것입니다.

data.result.etaxStatusobject

이 조회 항목의 결과입니다. 항목은 결과 규격을 참고하세요. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

data.result.etaxStatus.확인건수integer

전송 상태를 확인한 건수 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.result.etaxStatus.확인시각string

확인한 시각(ISO 8601) 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

data.result.etaxStatus.상태object

승인번호별 전송 상태 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

data.result.etaxStatus.상태.승인번호string

전자세금계산서 승인번호 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

data.result.etaxStatus.상태.구분string

매출 또는 매입 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

data.result.etaxStatus.상태.전송상태string

전송 상태(전송완료·미전송) 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

data.result.etaxStatus.상태.상태코드string

확인된 상태 코드. 없으면 빈 문자열 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

data.result.etaxStatus.장부에없는승인번호array

요청했지만 내 장부에 없어 확인하지 않은 승인번호 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다. 항목 수와 순서를 함께 확인하세요.

{ "data": { "schemaVersion": "1.0", "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a", "product": "etax_status", "status": "AUTH_WAITING", "resultAvailable": false, "charged": false, "sources": [], "message": "인증 대기중입니다.", "expiresAt": "2026-09-20T05:24:07+09:00", "success": 0 }, "api": { "success": true, "cost": 0, "ms": 42, "pl_id": -1 } }

{ "data": { "schemaVersion": "1.0", "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a", "product": "etax_status", "status": "COLLECTING", "resultAvailable": false, "charged": false, "sources": [], "progress": { "total": 1, "completed": 0 }, "message": "정보를 조회하고 있습니다.", "success": 0 }, "api": { "success": true, "cost": 0, "ms": 38, "pl_id": -1 } }

{ "data": { "schemaVersion": "1.0", "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a", "product": "etax_status", "status": "SUCCESS", "resultAvailable": true, "charged": true, "sources": [ { "source": "전자세금계산서 전송 상태 조회","type": "ETAX_STATUS", "status": "SUCCESS" } ], "checkedAt": "2026-09-20T04:47:33+09:00", "resultExpiresAt": "2026-09-21T04:47:33+09:00", "result": { "etaxStatus": { "확인건수": 3, "확인시각": "2026-10-26T14:20:00.000Z", "상태": [ { "승인번호": "20261026-41000001-12345678", "구분": "매출", "전송상태": "전송완료", "상태코드": "" } ], "장부에없는승인번호": [] } }, "message": "인증이 완료되었습니다.", "success": 1 }, "api": { "success": true, "cost": 60, "ms": 318, "pl_id": 4903 } }

알아둘 점

한눈에 보는 진행 절차

모든 조회 상품에 공통인 계약

개발 체크리스트

연동 전에 확인하세요

요금과 포인트

예상 금액 계산 예시

호출 제한과 재시도

자주 묻는 질문

2단계 · 결과조회 엔드포인트

요청과 응답

API 요청

요청 파라미터 1개 · 필수 1

응답 필드 36개

입력 조건·전송 규칙

요청 본문 형식

요청 예시

응답 처리

처리 상태(status)

결과 규격

result.etaxStatus

Body

오류 코드

업무 실패 응답 data.error

서비스 코드·조건

공통 오류 응답

상태와 성공 판정

인증·포인트 오류 result.error 문구

폼 입력 오류 error.code

요금·이용 조건

연동 팁

인증 대기중 (무과금)

조회 중 (무과금)

조회 완료 (과금)