주요 콘텐츠로 이동

QR 코드 API: 한 번의 호출로 QR 코드 또는 SEPA 결제 QR 생성


HTTP 호출 한 번이면 포스터, 청구서 또는 사이트에 바로 붙여 넣을 수 있는 QR 코드 이미지를 받습니다. 텍스트, 링크, Wi-Fi, 또는 아예 고객이 은행 앱으로 스캔하기만 하면 되는 SEPA 송금도 가능합니다.

설치할 라이브러리도 없고, 코드 한가운데에 자기 로고를 붙이는 서비스에 계정을 만들 필요도 없습니다. API는 PNG 또는 SVG 파일을 바로 반환하며, 그게 전부입니다. 결과는 다음과 같습니다.

Digital3D API가 생성한 흑백 QR 코드 예시

무료 또는 PRO: 제공되는 것

두 요금제는 똑같은 형식과 똑같은 크기로 정확히 같은 일을 합니다. 워터마크도 없고 만료되는 QR도 없습니다. 유일한 차이는 하루 코드 수입니다. 초록색 막대는 하루에 생성할 수 있는 양을 보여줍니다.

무료 API

0 €, 계정 키만 있으면 됩니다

10하루
  • 하루 10개의 QR 코드
  • 일반 QR 및 SEPA 결제 QR
  • PNG 및 SVG, 모든 크기, 워터마크 없음
  • 포스터, 명함 또는 청구서 몇 장을 만들기에 충분한 양

PRO API

월 12 €, 내 모든 소프트웨어 포함

하루 1000개
  • 하루 1000개의 QR 코드
  • 관리 소프트웨어의 모든 청구서에 결제 QR을 하나씩 넣기에 충분한 양
  • 11일 동안의 완전한 TV 가이드와 내 소프트웨어까지 덤으로 제공
  • 같은 키로 다음 요청부터 바로 활성화

PRO로 전환

카운터는 UTC 자정에 다시 시작하므로, 프랑스에서는 계절에 따라 새벽 1시 또는 2시입니다. 서투른 사람들에게 좋은 소식도 있습니다: 잘못 구성된 요청(가짜 IBAN, 빈 텍스트)은 키를 확인하기도 전에 거부되므로 아무 비용도 들지 않습니다.

키 받기

1분이면 됩니다: 계정을 만들고, 이메일 주소를 확인한 다음, 계정에 표시된 키를 복사하세요. 다른 서비스에서도 사용하는 것과 같은 키입니다. 각 요청의 Authorization 헤더에 보내며, 아래 예시의 VotreCleApi 대신 넣으면 됩니다.

URL이나 JSON에 userId를 넣는 예전 버전을 사용하고 있었나요? 이제는 이 매개변수를 읽지 않으며, 키는 이제 헤더를 통해서만 전달됩니다. 결과적으로 브라우저 주소창에 주소를 그대로 붙여 넣을 수는 없습니다. 마우스로 테스트하려면 Swagger가 있고, 아래에서 다시 이야기하겠습니다.

일반 QR: 텍스트, 링크, Wi-Fi

이것은 NormalQr 호출로, 간단한 GET입니다. 텍스트를 보내면 이미지를 받습니다:

curl -H "Authorization: Bearer VotreCleApi" "https://qr.digital3d.com/api/QrCreator/NormalQr?text=https%3A%2F%2Fdigital3d.com&format=Png&size=6" -o qr.png
매개변수값하는 일
text필수인코딩할 내용입니다. URL용으로 인코딩해야 합니다(:, / 및 &는 이스케이프해야 합니다).
formatPng (기본값) 또는 Svg반환되는 이미지 유형입니다.
size1에서 20까지, 기본값은 4코드의 각 작은 사각형 크기로, PNG에서는 픽셀 단위입니다.

재미있어지는 지점은 텍스트가 링크일 필요가 없다는 거야. 전화기는 여러 형식을 해석할 수 있어. 집에서 가장 실용적인 건 손님을 위해 인쇄해서 냉장고에 붙여 둘 와이파이 QR이야. 인코딩할 텍스트는 이렇게 생겼어:

WIFI:T:WPA;S:NomDuReseau;P:MotDePasse;;

mailto:quelquun@example.com으로 이메일을 여는 것도 같은 원리야, 또는 vCard(연락처 카드 형식)를 사용해서 스캔하면 네 연락처 정보가 주소록에 추가되게 할 수도 있어.

SEPA 결제 QR

이건 정말 마음에 들어. 청구서에 QR을 넣고, 고객이 은행 앱으로 스캔하면, 이체 정보가 미리 채워져 있어: 수취인, IBAN, 금액, 송금 내용. 이제 아무도 IBAN을 잘못 옮겨 적지 않아. 이건 PaymentQr 호출이고, JSON 본문을 사용하는 POST야:

curl -X POST "https://qr.digital3d.com/api/QrCreator/PaymentQr" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "Content-Type: application/json" \
  -o paiement.svg \
  -d '{
    "beneficiaryName": "ACME SRL",
    "iban": "BE68539007547034",
    "bic": "GKCCBEBB",
    "amount": 12.34,
    "remittance": "Facture 2026-001",
    "outputFormat": "Svg",
    "size": 8
  }'
필드필수포함 내용
beneficiaryName예돈을 받는 사람의 이름, 최대 70자.
iban예그 사람의 계좌. IBAN을 확인하며, 유효하지 않은 번호는 거부됩니다.
bic아니요은행 코드, 대문자로 된 8자 또는 11자.
amount아니요, 하지만 권장됨유로 단위의 금액, 0.01부터 9,999,999.99까지.
remittance아니요거래 내역에 표시되는 자유 형식의 메시지, 최대 140자.
structuredReference아니요로 시작하는 구조화된 메시지 RF. 둘 중 하나입니다: remittance와 동시에 사용하면 요청이 거부됩니다.
purpose아니요지급 사유를 나타내는 4글자 코드, 예를 들어 임대료라면 RENT.
info아니요지급자에게 보내는 짧은 메시지, 최대 140자. 모든 은행이 이를 표시하는 것은 아닙니다.
outputFormat 및 size아니요일반 QR과 동일하게: Png 또는 Svg, 크기는 1부터 20까지.

한 가지 단서는 있습니다. 있어야 하니까요: 이 QR은 유럽 표준을 따르지만, 모든 은행 앱이 이걸 읽는 건 아닙니다. 벨기에, 네덜란드 또는 독일에서는 아주 널리 쓰입니다. 다른 곳에서는 오백 장을 인쇄하기 전에 자기 은행으로 먼저 시험해 보세요.

내부 구조

뒤에서 무슨 일이 일어나는지 알고 싶은 분들을 위해, 기술적인 선택을 소개하겠습니다.

결제 QR은 유럽 결제 위원회의 EPC069-12 표준을 따릅니다. 구체적으로 말하면, 몇 줄짜리 짧은 텍스트(버전, 수취인, IBAN, 금액, 전달 사항)를 정해진 순서로 배열한 다음, 일반 QR과 똑같이 인코딩합니다. API가 이 텍스트를 대신 만들고, 그 전에 필드를 확인합니다.

모든 코드는 오류 수정 수준 M으로 생성됩니다. QR에는 손상된 상태에서도 계속 읽을 수 있도록 데이터가 중복으로 들어갑니다: M 수준에서는 표면의 약 15%가 얼룩지거나, 접히거나, 가려져도 읽는 데 방해가 되지 않습니다. 결제 QR에 표준이 요구하는 수준도 바로 이것입니다.

형식으로는 이메일이나 웹 페이지에 쓸 때 PNG를 선택하고, 늘이지 않아도 되도록 size 값을 충분히 크게 잡으세요. 인쇄소로 보낼 것은 무엇이든 SVG를 선택하세요: 벡터 그림이라 현수막 크기까지 키워도 흐려지지 않습니다. 응답에는 올바른 형식인 image/png 또는 image/svg+xml이 들어가고, 본문은 JSON을 디코딩할 필요 없이 파일 자체입니다.

마지막 세부 사항입니다: 이건 정적 QR입니다. 누군가 코드를 스캔해도 아무것도 제 서버를 거치지 않고, 모든 내용이 이미지 안에 들어 있습니다. 그러니 제 서비스가 존재하든 아니든 십 년 뒤에도 계속 작동합니다.

할당량 확인하기

키가 승인되면 각 응답에는 헤더 세 개가 붙습니다: X-RateLimit-Limit(오늘의 한도), X-RateLimit-Remaining(남은 양) 및 X-RateLimit-Reset(초 단위 Unix 시간으로 표시된 초기화 시각).

오류 쪽에서는 네 가지를 예상해야 합니다:

  • 400 : 요청이 유효하지 않습니다(빈 텍스트, 허용 범위를 벗어난 크기, 잘못된 IBAN). 무료이며, 아무것도 차감되지 않습니다.
  • 401 : 키가 없거나, 잘못 입력했거나, 계정이 아직 승인되지 않았습니다. 이것도 무료입니다.
  • 429 : 오늘의 할당량을 다 썼습니다. Retry-After 헤더에 초기화 전에 기다려야 할 초 수가 나옵니다.
  • 503 : 서비스가 키를 확인하지 못했습니다. 30초 뒤에 다시 시도하면 됩니다.

코드 한 줄 쓰지 않고 테스트하기

모든 내용은 API의 Swagger에 문서화되어 있어(호출 목록을 보여주고 브라우저에서 실행할 수 있게 해주는 페이지). « Authorize »를 클릭하고, 네 키를 붙여넣은 다음, « Try it out » 버튼으로 각 호출을 시도해 봐. 이미지가 페이지에 표시돼. 그래도 주의해: 이 시도도 다른 요청과 마찬가지로 네 할당량에 포함돼.

왜 구독이 필요한가?

이 모든 게 내가 비용을 내는 서버에서 돌아가기 때문이야. 무료 플랜은 테스트와 가벼운 사용을 위해 계속 제공되고, 하루 10개의 코드는 개인 사용자의 필요를 충분히 충족해. API를 청구 소프트웨어나 사이트에 연결한다면, 월 12유로인 PRO 구독으로 하루 한도가 1000개 코드까지 올라가고, 전체 TV 가이드와 내 소프트웨어 전부가 포함되며, 이게 서비스를 계속 유지해 주는 거야. 구독 없이 상업적으로 사용하는 것은 허용되지 않아.

대화에 참여하세요

이 글에 댓글을 달려면 계정이 있어야 합니다. 계정 생성은 무료이며 1분도 걸리지 않습니다.

  • 매일 무료로 다운로드할 수 있는 XMLTV 파일
  • 기사에 댓글을 달고 다른 독자들에게 답변하기
  • 팔로우 중인 새 게시물에 대한 알림을 이메일로 받기

현재 댓글이 없습니다.

Une erreur s'est produite. Cette application peut ne plus répondre jusqu'à ce qu'elle soit rechargée.Veuillez contacter l'auteur. Reload 🗙