팩스 발송

파일을 팩스로 수신자에게 전송하는 팩스 메시지 API입니다.

사전에 Storage API를 통해 업로드한 팩스 전용 파일을 수신자에게 팩스로 발송합니다. 여러 파일을 한 번에 발송할 수 있으며, 파일 수에 따라 과금이 이루어집니다.

발송 방법

팩스 메시지는 별도의 전용 API가 아닌, 기존 그룹 메시지 API를 통해 발송합니다. 메시지의 type을 FAX로 지정하면 팩스 메시지로 처리됩니다.

발송 흐름은 다른 메시지 타입과 동일합니다.

1. 그룹 생성 — POST /messages/v4/groups

2. 메시지 추가 — PUT /messages/v4/groups/:groupId/messages (type: FAX)

3. 발송 요청 — POST /messages/v4/groups/:groupId/send

그룹 메시지 API의 전체 사용법은 그룹 메시지 API 문서를 참조하세요.

메시지 구조

팩스 메시지를 그룹에 추가할 때 사용하는 메시지 객체 구조입니다.

{
  "messages": [
    {
      "to": "0312345678",
      "from": "029302266",
      "type": "FAX",
      "faxOptions": {
        "fileIds": ["ST01FZ230828021656148zSe0iXE93v9"]
      }
    }
  ]
}

필수 필드

선택 필드

주의: 발신 번호(from)는 사전에 팩스 전용으로 등록된 번호여야 합니다.

faxOptions 상세

팩스 발송에 필요한 파일 정보를 지정하는 옵션입니다.

{
  "faxOptions": {
    "fileIds": [
      "ST01FZ230828021656148zSe0iXE93v9",
      "ST01FZ230828021656148zSe0iXE9310"
    ]
  }
}

필드 설명

과금 기준

팩스 메시지의 과금은 fileIds에 포함된 파일 수를 기준으로 산정됩니다. 예를 들어, fileIds에 파일 3개를 지정하면 3건으로 과금됩니다.

파일 업로드

팩스 발송 전에 반드시 Storage API를 통해 파일을 업로드해야 합니다.

업로드 요건

• Storage API의 파일 업로드 엔드포인트를 사용합니다.

• 업로드 시 파일 타입을 FAX 전용으로 지정해야 합니다.

• 업로드 완료 후 반환되는 fileId를 faxOptions.fileIds에 사용합니다.

주의사항

• 일반 이미지(MMS용 등)로 업로드된 파일은 팩스에 사용할 수 없습니다.

• 반드시 팩스 전용(FAX 타입)으로 업로드된 파일만 사용 가능합니다.

• 존재하지 않거나 FAX 전용이 아닌 fileId를 사용하면 에러가 발생합니다.

유효성 검증 규칙

팩스 메시지 추가 시 아래 규칙에 따라 유효성 검증이 수행됩니다. 검증에 실패하면 해당 메시지는 추가되지 않습니다.

발송 예시

단일 파일 팩스 발송

{
  "messages": [
    {
      "to": "0312345678",
      "from": "029302266",
      "type": "FAX",
      "faxOptions": {
        "fileIds": ["ST01FZ230828021656148zSe0iXE93v9"]
      }
    }
  ]
}

다중 파일 팩스 발송

{
  "messages": [
    {
      "to": "0312345678",
      "from": "029302266",
      "type": "FAX",
      "faxOptions": {
        "fileIds": [
          "ST01FZ230828021656148zSe0iXE93v9",
          "ST01FZ230828021656148zSe0iXE9310"
        ]
      }
    }
  ]
}

다수 수신자에게 팩스 발송

{
  "messages": [
    {
      "to": "0312345678",
      "from": "029302266",
      "type": "FAX",
      "faxOptions": {
        "fileIds": ["ST01FZ230828021656148zSe0iXE93v9"]
      }
    },
    {
      "to": "0212345678",
      "from": "029302266",
      "type": "FAX",
      "faxOptions": {
        "fileIds": ["ST01FZ230828021656148zSe0iXE93v9"]
      }
    }
  ]
}

간편 발송

{
  "message": {
    "to": "0312345678",
    "from": "029302266",
    "type": "FAX",
    "faxOptions": {
      "fileIds": ["ST01FZ230828021656148zSe0iXE93v9"]
    }
  }
}