MultiTEL
개발자

POST/v3/send_fax

팩스 보내기

문서를 업로드하고 발신 팩스를 대기열에 등록한 다음, 진행 상황을 확인할 수 있도록 작업 ID를 보관하세요.

이 페이지의 내용
  1. 보내기 전 확인 사항
  2. 문서 업로드
  3. 문서 및 제출 제한
  4. 작업 ID 보관
  5. 오류 및 잔액 확인

보내기 전 확인 사항

발신 번호로 표시할 권한이 있는 번호를 사용하고, 팩스 수신을 예상하고 있는 수신자에게 보내세요. 이 요청은 실제 전송을 생성하며 요금이 부과될 수 있습니다. 페이지 감지 결과를 최대한 안정적으로 얻으려면 미리 준비한 PDF 또는 TIFF 문서를 사용하세요. 대기열에 등록되었다는 응답은 요청이 접수되었음을 확인하는 것이며, 수신자에게 전달되었음을 확인하는 것은 아닙니다.

활성화된 MultiTEL API 계정을 사용하세요. 비밀번호 방식 계정에서는 HTTP Basic 인증 정보를, 토큰 방식 계정에서는 Bearer 토큰을 전송하세요. 계정 권한과 IP 제한은 계속 적용됩니다. 내부 워커의 인증 정보를 사용하지 마세요.

문서 업로드

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --form-string from_number=+12125550123 \
  --form-string to_number=+12125550124 \
  --form fax_file=@./document.pdf \
  https://api.multitel.net/v3/send_fax
요청 필드
필드필수 여부설명
from_number필수발신 번호로 사용할 권한이 있는 번호입니다. +와 국가 코드로 시작하는 국제 형식을 사용하세요.
to_number필수국제 형식으로 입력한 수신 팩스 번호입니다.
fax_file멀티파트 형식에서는 필수업로드할 문서입니다. 멀티파트 Content-Type과 경계 문자열은 curl이 설정하도록 하세요.
webhook_url선택선택적으로 지정하는 HTTP 또는 HTTPS 콜백 URL입니다. HTTPS 사용을 권장합니다. 콜백 페이로드와 전달 보장은 아직 검토 중입니다. 문서에 명시된 상태 확인 절차에 따라 fax_status를 주기적으로 조회하세요.

JSON 형식도 허용됩니다. 지정할 항목은 Content-Type: application/json과 동일한 번호 필드, 선택 항목인 webhook_url, 그리고 file_name 및 file_b64입니다. file_b64에는 data: 접두사 없이 엄격한 Base64 형식으로 인코딩한 문서 바이트를 넣습니다. 유효한 멀티파트 fax_file이 있으면 해당 값이 우선합니다. 이 API는 파일 URL에서 파일을 가져오는 기능을 제공하지 않습니다.

문서 및 제출 제한

애플리케이션은 디코딩된 문서 크기가 최대 15,728,640바이트(15 MiB)이며 확장자가 pdf, tif, tiff, jpg, jpeg, png, doc, docx 또는 txt인 문서를 허용합니다. 허용되는 확장자라고 해서 서비스에서 페이지 수를 세거나 페이지를 변환할 수 있다는 보장은 없습니다. 인프라의 요청 크기 제한은 이보다 낮을 수 있으며, Base64를 사용하면 요청 크기가 증가합니다.

현재 애플리케이션은 계정별로 동일한 수신처에 대해 대기 중이거나 전송 중인 작업을 한 건까지 허용합니다. 직전 한 시간 동안 동일한 수신처로 제출할 수 있는 요청은 최대 다섯 건이며, 직전 한 시간 동안의 전체 제출 요청은 최대 50건입니다. 요청 빈도 제한 응답에는 API 코드 429가 사용됩니다. 잠시 기다린 후 다시 시도하세요. 제한을 우회하려고 하지 마세요.

작업 ID 보관

HTTP 결과와 JSON의 status.code를 모두 확인하세요. JSON에서 실패를 나타내는 응답도 HTTP 200으로 반환될 수 있습니다. 성공한 JSON 응답에는 status와 response가 포함됩니다. 예시에는 가상의 데이터가 사용되었습니다.

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

주기적으로 조회할 대상은 fax_status입니다. 조회 시 response.job_id를 사용하세요. 전송 요청에 대한 응답을 받지 못했다면 다시 보내기 전에 포털의 보낼 편지함을 확인하세요. 요청을 반복하면 별도의 전송이 생성될 수 있습니다. 이 핸들러는 클라이언트가 지정할 수 있는 멱등성 매개변수를 제공하지 않습니다.

오류 및 잔액 확인

API 코드에는 필드 누락, 유효하지 않은 콜백 URL, 문서 거부 또는 페이지 감지 실패를 나타내는 400, 인증 누락을 나타내는 401, 예상 팩스 비용과 대기 중이거나 전송 중인 작업의 예상 비용을 합한 금액이 계정의 사용 가능한 잔액을 초과할 때 반환되는 402, 요청 빈도 제한을 나타내는 429, 전송 준비 처리 실패를 나타내는 500이 있습니다. 구체적인 이유는 status.msg를 확인하세요.

대기열에는 전송 전에 예상 비용이 기록됩니다. 요청 접수, 잔액 확인 또는 이 예상 비용을 과금 완료의 확인으로 해석하지 마세요. 최종 과금 및 콜백 세부 사항은 추가 검증이 필요합니다.