제품 및 API 안내

대기열을 통한 생성

대기열을 사용해야 하는 경우

직접 생성 엔드포인트는 문서가 준비되면 응답하므로 호출자가 기다릴 수 있을 때 가장 간단합니다. 문서가 길거나 한 번에 많이 생성하거나 오래 열어 둘 수 없는 웹 요청에서 호출한다면 대기열을 사용하세요. queueId가 포함된 응답이 즉시 반환되고 뒤에서 작업이 계속됩니다.

긴 문서와 일괄 작업은 요청을 대기열에 넣으세요. 응답은 즉시 반환되며 statusUrl에서 작업을 추적할 수 있습니다.

대기열 순서

대기열 우선순위는 요금제에 따라 정해지며 별도 대기열을 사용하는 것은 아닙니다. 작업은 우선순위에 비례하여 더 일찍 도착한 것으로 처리됩니다. 따라서 우선순위가 높은 작업은 동시에 등록된 작업보다 먼저 처리되며, 대기 중인 작업이 무한히 기다리지는 않습니다. 최악의 대기 시간은 계산할 수 있으며 현재 설정에서는 Free 작업은 최대 54분을 기다리고 Max 작업은 기다리지 않습니다.

요청

curl -X POST https://api.pdfgine.com/api/v1/documents/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateCode": "invoice", "format": "pdf", "data": { } }'

응답

{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "queued",
  "statusUrl": "/api/v1/async-jobs/queue_ea464b42...",
  "documentId": null,
  "createdAt": "2026-08-28T13:23:45+00:00"
}

대기열을 통한 생성

curl https://api.pdfgine.com/api/v1/async-jobs/queue_ea464b42... \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

요청에 webhookUrl을 추가하면 작업 완료 시 서명된 알림이 전달되므로 폴링할 필요가 없습니다.

완료된 작업의 모습

statusUrl에서 작업을 확인하세요. 실행 중에는 status가 queued 또는 running이며 완료되면 documentId와 result가 채워집니다.

응답

{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "succeeded",
  "attemptCount": 1,
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "result": {
    "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
    "pageCount": 12
  },
  "failureCode": null,
  "createdAt": "2026-08-28T13:23:45+00:00",
  "completedAt": "2026-08-28T13:23:52+00:00"
}

실패한 작업은 status가 failed이며 이유를 나타내는 failureCode를 반환합니다. 같은 코드 목록이 오류 페이지에 있습니다.

자주 발생하는 문제

대기열은 문서 없이 queueId가 포함된 202를 반환합니다. 작업이 완료될 때까지 documentId는 null입니다. 바로 읽고 null을 실패로 처리하는 것이 가장 흔한 실수입니다.
매초 폴링하면 요청 속도 한도를 낭비합니다. 몇 초 간격으로 폴링하거나 webhookUrl을 보내 폴링하지 마세요.
status가 failed인 작업은 대기 중이 아니라 종료된 작업입니다. failureCode를 읽고 입력을 수정하세요. 작업이 자동으로 다시 시작되지는 않습니다.
웹훅 알림에는 서명이 있습니다. 신뢰하기 전에 웹훅 페이지의 방법으로 서명을 검증하세요. 2xx로 응답하지 않으면 다시 전달됩니다.
대기열 문서는 직접 생성 문서와 같은 페이지를 사용합니다. 대기열은 처리 시점만 바꾸며 비용은 바꾸지 않습니다.