PDF를 Base64로 인코딩해 API로 보내는 방법
전자세금계산서, 전자서명, 배송 API가 문서를 JSON 필드로 받는다면, PDF를 알맞은 텍스트로 바꾸고 확인해서 요청 실패를 막는 방법을 알아보세요
작성자 Metin Ersoy · 2026년 11월 10일 업데이트
API가 보통 요구하는 형식
문서를 다루는 API는 대부분 content, file, data, document 같은 이름의 필드가 있는 JSON 본문을 요구합니다. 값은 PDF의 Base64 코드이고, 파일 이름과 형식이 함께 들어가는 경우가 많습니다.
{
"fileName": "invoice-1024.pdf",
"mimeType": "application/pdf",
"content": "JVBERi0xLjcKJ..."
}
코드를 작성하기 전에 API 문서에서 세 가지를 확인하세요. 필드 이름, data: 접두어가 필요한지(보통은 필요 없음), 그리고 용량 제한입니다.
1. PDF를 Base64로 변환하기
테스트용 값을 가장 빨리 얻는 방법은 PDF를 Base64로 변환입니다. PDF를 선택하고 Base64 코드만(JVBERi0으로 시작) 형식을 고른 뒤 결과를 복사하세요. 요청 본문 전체를 바로 쓰고 싶다면 대신 파일 이름, 형식, 내용이 담긴 JSON을 고르세요. 파일 이름과 형식을 자동으로 넣어 줍니다. PDF는 브라우저에서 인코딩되고 업로드되지 않습니다. 테스트 문서가 실제 청구서라면 특히 중요한 점입니다.
결과를 확인하세요. JVBERi0으로 시작하고, 공백이 없어야 하며, 끝에 붙는 = 기호 한두 개를 빼면 영문자, 숫자, +, /만 들어 있어야 합니다.
2. 코드에서 보내기
자주 쓰는 세 가지 언어로 같은 작업을 하는 예제입니다. 모두 파일을 읽어 인코딩한 뒤 JSON으로 전송합니다.
# curl (Linux / macOS): base64 -w 0 keeps it on one line
curl -X POST https://api.example.com/documents \
-H "Content-Type: application/json" \
-d "{\"fileName\":\"invoice.pdf\",\"content\":\"$(base64 -w 0 invoice.pdf)\"}"
// Node.js 18+
import { readFile } from 'node:fs/promises';
const content = (await readFile('invoice.pdf')).toString('base64');
await fetch('https://api.example.com/documents', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ fileName: 'invoice.pdf', content }),
});
# Python 3 with requests
import base64, requests
with open("invoice.pdf", "rb") as f:
content = base64.b64encode(f.read()).decode("ascii")
requests.post("https://api.example.com/documents",
json={"fileName": "invoice.pdf", "content": content})
macOS에서는 curl 줄의 -w 0 대신 base64 -i invoice.pdf를 쓰세요. 주소와 필드 이름은 예시이므로, 사용하는 서비스의 API 문서에 나온 값으로 바꾸세요.
3. 왕복 확인하기
서비스가 문서나 저장된 사본을 Base64로 돌려준다면, 그 응답을 Base64를 PDF로 변환에 붙여 넣으세요. 첫 페이지와 페이지 수가 제대로 보이는지 확인하는 것이 전송 중에 빠진 데이터가 없는지 가장 빨리 알아보는 방법입니다. 반대 방향의 자세한 방법은 Base64 문자열을 PDF 파일로 저장하는 방법에 있습니다.
자주 하는 실수
| 증상 | 예상 원인 | 해결 방법 |
|---|---|---|
| "Invalid Base64" | 줄바꿈(76자씩 나뉜 줄) 또는 data: 접두어 | 접두어 없는 코드를 한 줄로 보내기 |
| "Payload too large"(413) | 인코딩 후 PDF가 너무 큼 | PDF 압축으로 용량 줄이기 |
| PDF가 빈 화면이거나 깨져서 열림 | 문자열이 중간에 잘림 | 다시 인코딩해서 값 전체를 보내기 |
| 한글이나 악센트 문자가 든 파일 이름이 깨짐 | 파일 이름을 잘못된 인코딩으로 전송 | JSON 본문을 UTF-8로 유지하기 |
직접 사용해 보시겠어요? 무료이며 파일은 내 기기에만 머뭅니다.
PDF를 Base64로 변환 열기