PDFVela — pdfvela.com
모든 PDF 도구

PDF를 Base64로 인코딩해 API로 보내는 방법

전자세금계산서, 전자서명, 배송 API가 문서를 JSON 필드로 받는다면, PDF를 알맞은 텍스트로 바꾸고 확인해서 요청 실패를 막는 방법을 알아보세요

작성자 · 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로 변환 열기

PDF를 Base64로 보낼 때 자주 묻는 질문

API는 왜 파일 대신 Base64를 요구하나요?

JSON에는 텍스트만 담을 수 있기 때문입니다. Base64는 PDF의 바이트를 영문자, 숫자, +, /로 적은 것이라, 문서 전체를 고객 번호나 청구서 발행일 같은 다른 데이터 옆의 문자열 필드 하나에 넣을 수 있습니다.

data:application/pdf;base64, 접두어도 같이 보내야 하나요?

보통은 보내지 않습니다. 대부분의 API는 JVBERi0으로 시작하는 코드만 받습니다. API 문서에 Data URI 형식이 나와 있거나, iframe처럼 브라우저가 URL을 필요로 할 때만 Data URI로 보내세요.

API가 Base64가 잘못됐다고 합니다. 가장 흔한 원인은 무엇인가요?

문자열에 줄바꿈이나 접두어가 들어 있거나, 붙여 넣는 과정에서 코드가 잘린 경우입니다. 접두어 없는 코드를 한 줄로 보내고, 문자열 끝까지 빠짐없이 전달됐는지 확인하세요.

PDF 용량은 어디까지 괜찮나요?

서비스마다 다르지만, Base64 텍스트는 원래 파일보다 약 3분의 1 커집니다. 3 MB PDF라면 JSON으로 약 4 MB가 됩니다. 몇 MB에서 막는 API가 많으니, 먼저 PDF를 압축하는 것이 가장 간단한 해결책입니다.

Base64는 암호화인가요?

아닙니다. 코드만 있으면 누구나 다시 문서로 되돌릴 수 있습니다. 반드시 HTTPS로만 보내고, 기밀 PDF는 파일을 서버로 업로드하는 웹사이트에 절대 붙여 넣지 마세요.