자버 발송 API (OpenAPI v1)

자버 발송 API는 자버 웹에서 미리 만들어 둔 빠른 발송 세트(서식, 입력값, 발송 채널, 메시지 템플릿)와 수신자 목록만 보내면 전자문서와 메시지를 일괄 발송하는 HTTP API입니다. 사내 시스템, CRM, 예약 시스템에서 이벤트가 생길 때 서버에서 호출하는 용도로 씁니다.

발송은 비동기로 처리됩니다. 요청이 유효하면 바로 접수 결과를 돌려주고 실제 발송은 백그라운드에서 진행되며, 결과는 문서 조회 API로 확인합니다.

연동 흐름

1. 세트 목록 조회: 발송에 쓸 세트의 id 를 얻습니다.
2. 발송 정보 조회: 세트의 발송 채널, 수신자 연락처 종류, 채워야 할 입력 항목과 선택지, 링크 필요 여부를 확인합니다.
3. 발송: 세트 id 와 수신자 목록(최대 100명)을 보냅니다.
4. 결과 확인: 문서 목록·상세 조회로 진행 상태를 확인합니다.

시작하기

처음이면

자버 계정이 없으면 먼저 자버에 가입합니다. 가입비는 없고 가입 보너스 500원이 들어옵니다. AI 도구(Claude, ChatGPT 등)에서 대화로 보내려면 AI 도구용 가입 안내로 가입하고 MCP 서버를 보세요. 가입한 뒤 아래 순서로 키를 발급하고 세트를 만듭니다.

1. API 키 발급

발송 API 에는 회사 API 키(jbr_co_ 로 시작)를 씁니다. 두 곳에서 발급할 수 있고, 콘솔에서 만든 문서 발송 키도 설정의 회사 API 키 목록에 함께 보입니다.

1. 위 화면 중 한 곳에서 키를 발급합니다. 이 문서의 API 를 쓰려면 문서 발송(openapi:document) 권한이 있어야 합니다.
2. 키는 발급 직후 한 번만 보입니다. 복사해 서버에만 보관하세요.
3. 다시 발급하면 같은 이름·권한의 새 키가 나오고 이전 키는 바로 쓸 수 없습니다.

API 키는 스페이스의 발송 권한을 위임받은 값입니다. 서버에서만 보관하고 브라우저나 앱 코드에 넣지 마세요. 노출이 의심되면 바로 재발급하세요.

• 문서 발송 권한으로 이 문서의 문서(/document)·서식(/frame) API 를 호출할 수 있습니다.
• 같은 회사 API 키에 AI 에이전트 권한을 더 주면 자유 발송 API에도 쓸 수 있습니다(그때는 Authorization: Bearer 헤더). 권한 종류와 줄 수 있는 사람은 키 발급에 있습니다.
• 개인 API 키(jbr_live_)와 OAuth 토큰은 발송 API 에 쓸 수 없습니다(400 J_40_01_1_2).
• 예전에 발급받은 키도 그대로 쓸 수 있습니다.
• 연락처·스페이스 생성·로그인 연동 OpenAPI 의 레퍼런스는 공개하지 않습니다. 필요하면 도입 문의로 요청하세요.

2. 빠른 발송 세트 만들기

자버 웹의 전자문서 빠른 발송에서 서식, 미리 채울 입력값, 발송 채널, 메시지 템플릿을 정해 세트로 저장합니다. API로 보낼 때는 이 세트의 설정을 그대로 쓰고, 요청마다 바꿀 값만 보냅니다.

3. 첫 호출

curl "https://api.jober.io/openapi/v1/document/preset/list?limit=20&offset=0" \
  -H "x-jober-openapi: YOUR_API_KEY"

인증과 기본 주소

모든 요청에 발급받은 키를 헤더로 보냅니다. 키가 스페이스를 정하므로 스페이스 ID 헤더는 따로 없습니다.

x-jober-openapi: YOUR_API_KEY

예전에 안내된 https://open-api.jober.io/v1 주소도 같은 API로 연결되지만, 이 주소로는 오류 응답의 data 필드(예: 정책 제한 표현 목록)가 전달되지 않습니다. 새 연동은 위 기본 주소를 쓰세요.

인증 오류

응답 형식

성공하면 HTTP 200과 함께 다음 형태로 응답합니다.

{ "message": "사람이 읽는 안내 문구", "data": { } }

실패하면 4xx·5xx 와 함께 다음 형태로 응답합니다.

{ "message": "error message", "errorCode": "J_44_42_1_2", "httpStatusCode": 400, "data": null }

• 성공·실패 판단과 재시도 여부는 실제 HTTP 상태 코드로 하세요. 본문의 httpStatusCode 는 실제 상태와 다를 수 있습니다(예: HTTP 403 응답의 본문에 400).
• 분기 처리는 errorCode 로 하세요. message 문구는 바뀔 수 있습니다.
• 없는 경로를 호출하면 JSON이 아닌 HTML 404 페이지가 옵니다.

API 목록

세트 목록 조회

GET /document/preset/list?limit=20&offset=0

API 발송용으로 저장한 세트만 최근 수정 순으로 돌려줍니다.

{
  "message": "API 발송 목록 조회에 성공하였습니다.",
  "data": {
    "presets": [
      {
        "id": 123,
        "title": "예약 확인 안내",
        "personId": "세트를 만든 매니저의 사용자 ID",
        "documentFrameId": 4567,
        "frameTitle": "예약 확인서",
        "isEmptyDocument": false,
        "notificationTemplateInfo": { "kakaoTemplateInfo": { "variables": [ { "key": "예약일", "value": "" } ] } },
        "updatedAt": "2026-10-30T09:00:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

• 위 예시는 주요 필드만 줄여 보인 것입니다. 실제로는 spaceId, type, description, inputValues, saveFolderId, documentFrame 등 세트 정보가 함께 옵니다.
• 발송 때 templateValues 로 바꿀 수 있는 메시지 변수의 키는 notificationTemplateInfo 안 템플릿의 variables[].key 입니다.

발송 정보 조회

GET /document/preset/{presetId}/send-context

{
  "message": "API 발송 정보 조회에 성공하였습니다.",
  "data": {
    "preset": { "id": 123, "title": "예약 확인 안내" },
    "documentFrame": {
      "inputs": [
        {
          "id": 1, "key": "visitType", "label": "방문 유형", "type": "radio",
          "options": [
            { "value": "first", "label": "첫 방문", "order": 1, "isDirectInput": false },
            { "value": null, "label": "기타(직접 입력)", "order": 2, "isDirectInput": true }
          ]
        }
      ]
    },
    "channel": { "type": "KAKAO" },
    "receiverContactField": "phone",
    "sendable": true,
    "messageType": "document",
    "link": { "supported": true, "required": false, "presetTargetUrl": null }
  }
}

입력 항목의 필수 여부와 세트에 미리 채운 값은 이 응답에 없습니다.

발송

POST /document/preset/{presetId}/send

요청 본문

수신자에게 가는 발송 알림은 위 알림 옵션과 상관없이 항상 나갑니다. 예약 발송, 수신자마다 다른 inputValues 는 지원하지 않습니다.

수신자

채널에 따라 쓰는 연락처가 다릅니다. 다른 채널용 연락처는 무시합니다.

수신자는 스페이스 연락처에 자동으로 등록되거나(없으면 생성) 기존 연락처와 연결됩니다.

링크 규칙

• 링크 우선순위는 receivers[].targetUrl > targetUrl > 세트에 저장된 링크입니다.
• 공통 targetUrl 은 메시지+링크 세트에만 적용합니다. 수신자별 targetUrl 은 카카오는 모든 세트, 이메일·메신저는 메시지+링크 세트에만 적용합니다.
• 메시지+전자문서 세트에 수신자별 targetUrl 을 넣으면 문서 보기 버튼이 그 링크로 바뀌어 수신자가 문서에 들어갈 수 없습니다.
• 링크는 http·https 주소만, 500자까지 받습니다. 아이디·비밀번호가 든 주소, localhost, 사설·내부 IP와 도메인(.local, .internal)은 받지 않습니다. 문자(SMS)·Viber 는 300바이트, Discord 는 900바이트까지입니다.
• 링크를 넣었는데 규칙에 맞지 않으면 다른 링크로 바꿔 보내지 않고 요청 전체를 거부합니다(J_44_42_1_14).

요청 예시

curl -X POST "https://api.jober.io/openapi/v1/document/preset/123/send" \
  -H "x-jober-openapi: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputValues": { "visitType": "first" },
    "templateValues": { "예약일": "11월 7일 14:00" },
    "notifyOnMassiveSent": false,
    "receivers": [
      { "name": "홍길동", "phone": "01012345678" },
      { "name": "김자버", "phone": "010-9876-5432" }
    ]
  }'

응답

{
  "message": "API 발송 요청이 접수되었습니다.",
  "data": {
    "requestId": "0f8c2a4e-5b1d-4c7a-9e2f-3a6b8d1c4e5f",
    "documentTaskDefinitionId": 4567,
    "totalTargets": 2,
    "skipped": [],
    "receiverInputRequired": false
  }
}

발송할 수 있는 수신자가 한 명도 없으면 HTTP 200에 "message": "API 발송할 유효한 수신자가 없습니다.", totalTargets: 0, documentTaskDefinitionId: null 을 돌려줍니다.

발송 전 검사

요청 전체를 검사해 하나라도 걸리면 아무것도 보내지 않습니다.

처리 순서

1. 수신자마다 연락처를 등록하거나 기존 연락처와 연결합니다.
2. 중복 수신자를 정리하고 발송 대상을 확정합니다.
3. 세트에 지정한 폴더(없으면 공유 폴더, 그것도 없으면 API 발송 폴더)에 문서를 만들고 발송 작업을 시작합니다.
4. 접수 결과를 바로 응답합니다. 이후 발송은 백그라운드에서 진행됩니다.

발송 API에는 결과 웹훅이 없습니다. 진행 상태는 문서 목록·문서 상세로 확인하세요.

문서 목록 조회

GET /document/list?status[]=IN_PROGRESS&status[]=ISSUED&current=1&pageSize=20

{
  "message": "전자문서 목록 조회에 성공하였습니다.",
  "data": {
    "list": [
      {
        "id": 98765, "frameId": 4567, "frameHistoryId": 8910, "frameTitle": "예약 확인서", "folderId": 12,
        "status": "ISSUED",
        "issueTargets": [ { "profileCardId": 555, "name": "홍길동", "email": null, "phone": "01012345678", "receiptDate": "2026-10-30T09:05:00.000Z", "useCertification": false } ],
        "files": [], "sentDate": "2026-10-30T09:00:00.000Z", "issuedDate": "2026-10-30T09:10:00.000Z",
        "createdAt": "2026-10-30T09:00:00.000Z", "updatedAt": "2026-10-30T09:10:00.000Z"
      }
    ],
    "total": 1, "current": 1, "pageSize": 20
  }
}

status 가 없거나 배열이 아니면 400 O_document_5_1_1, 허용하지 않는 값이면 400 O_document_5_2_1 입니다.

문서 상세 조회

GET /document/detail/{documentId}

data.documentDetail 에 목록 항목과 같은 필드와 함께 입력값 value({ "입력키": 값 })가 옵니다. 자동표 셀은 부모키_자식키_행 키로 옵니다. 문서가 없거나 삭제됐으면 400 O_document_4_3_2 입니다.

알림 재발송

POST /document/resend

{
  "actionPersonId": "재발송하는 매니저의 사용자 ID",
  "targetDocuments": [ { "id": 98765, "frameId": 4567, "contact": "01012345678" } ],
  "sendOptions": { "defaultLanguage": "ko", "useCertification": false, "memo": "확인 부탁드립니다." }
}

• actionPersonId 와 targetDocuments[].id·frameId·contact(이메일 또는 전화번호)는 필수입니다. 한 번에 같은 서식의 문서만 보낼 수 있습니다(O_document_3_2_2).
• 비동기로 처리되며 { "started": true } 를 바로 돌려줍니다.
• 사용자 ID 는 세트 목록 응답의 personId(세트를 만든 매니저)를 쓸 수 있습니다.
• 참여자 정보(targetDocuments[].participants[])를 함께 보내면 id 는 그 대상 문서의 참여자여야 합니다. 다른 문서의 참여자가 섞이면 요청 전체를 거부합니다(O_document_3_4_5). 참여자의 documentId 는 보내도 쓰지 않고 대상 문서 ID 로 고정합니다.

요청 전체를 검사해 하나라도 걸리면 아무것도 보내지 않습니다.

문서 요청 취소

POST /document/cancel

{ "documentIds": [98765], "actionPersonId": "취소하는 매니저의 사용자 ID", "memo": "일정이 변경되어 취소합니다." }

• documentIds(최대 25개)와 actionPersonId 는 필수입니다. memo 는 취소 알림에 함께 나갑니다.
• 다른 참여자에게 이메일이나 카카오로 취소 알림이 갑니다.
• 응답 data.canceledDocumentIds 에 실제로 취소된 문서만 담깁니다. 취소하지 못한 문서는 오류 없이 빠지므로 이 목록으로 확인하세요.

문서 파일

수신자 입력이 있는 문서는 수신자가 제출해 완료(ISSUED)된 뒤에 받으세요.

서식 조회

/frame/one 에 id 가 없으면 400 O_frame_1_1_1, 이 스페이스에서 쓸 수 없는 서식이면 400 O_frame_1_2_2 입니다.

한도와 정책

• 스팸·금지 표현 검사, 수신거부, 카카오 발송 한도, 선불 잔액 검사는 자버 웹 발송과 같게 적용됩니다.
• 메신저 채널 발송은 현재 무과금 시범 운영이라 선불 잔액 검사를 하지 않습니다.

자주 묻는 질문

API 키는 어디서 발급하나요?

설정 > AI 도구 연동의 회사 API 키에서 스페이스 관리자가 권한을 골라 발급합니다(스페이스당 활성 5개). 문서 발송 키 하나만 필요하면 왼쪽 메뉴의 전자문서 환경설정 > API 연동에서 열리는 빠른 발송 API 콘솔에서도 발급할 수 있습니다. 다시 발급하면 이전 키는 바로 쓸 수 없게 됩니다.

수신자가 100명보다 많으면 어떻게 하나요?

요청 하나에 최대 100명까지 보낼 수 있습니다. 100명씩 나눠 여러 번 호출하세요. 같은 요청 안의 중복 연락처는 한 번만 발송되지만, 요청을 나눌 때 같은 수신자를 두 요청에 넣으면 두 번 발송됩니다.

발송 결과는 어떻게 받나요?

발송 API는 결과 웹훅을 보내지 않습니다. 발송 응답의 totalTargets·skipped 로 접수 결과를 확인하고, 이후 상태는 문서 목록 조회(status[]=ISSUED 등)와 문서 상세 조회로 확인하세요.

문서가 바로 완료되지 않고 진행 중으로 남아요.

서식에 수신자가 채울 항목이 남아 있으면 문서가 진행 중(IN_PROGRESS)으로 발송되고, 수신자가 제출해야 완료(ISSUED)됩니다. 발송 응답의 receiverInputRequired 가 true 면 이 경우입니다. 발신자가 모든 값을 채워 보내려면 inputValues 로 값을 넣으세요.

AI 도구에서 대화로 보내고 싶어요.

Claude, ChatGPT 같은 AI 도구에서는 자버 MCP 서버를 연결하면 대화로 알림톡·이메일 캠페인을 만들고 보낼 수 있습니다.

세트 없이 문자 원문으로 보내고 싶어요.

자유 발송 API를 쓰세요. 문자 원문을 보내면 자버가 알림톡·이메일 캠페인으로 바꾸고, 버튼에 내 링크를 붙이고, 받는 사람을 확인해 발송·예약까지 합니다. AI 에이전트 권한을 준 회사 API 키(jbr_co_), 개인 API 키(jbr_live_) 또는 OAuth 토큰으로 호출하고, 카카오 채널을 연동하지 않았으면 자버 공용 채널로 한도 안에서 보냅니다.