> For the complete documentation index, see [llms.txt](https://docs.salesmap.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.salesmap.kr/developers/api-reference/crm/file/upload.md).

# 파일 업로드 · 첨부

## 파일 업로드 · 첨부

`POST` `/v2/file`

파일을 업로드합니다. `objectType`과 `objectId`를 함께 보내면 해당 레코드에 파일이 첨부됩니다.

`objectType`과 `objectId` 없이 업로드하면 파일만 업로드됩니다. 이때 응답의 `id`를 이메일 발송 API(`POST /v2/email`)의 `attachmentIdList`에 넣어 이메일 첨부에 사용할 수 있습니다.

### 언제 사용하나요?

세일즈맵 화면에서 딜, 리드, 고객 등 레코드 상세의 **첨부파일** 탭에 파일을 올리는 것과 같은 작업을 API로 처리할 때 사용합니다.

예를 들어 특정 딜에 계약서 PDF를 첨부하려면 `objectType`에 `deal`, `objectId`에 해당 딜의 ID를 입력합니다.

### Headers

| Name          | Value                 |
| ------------- | --------------------- |
| Content-Type  | `multipart/form-data` |
| Authorization | `Bearer <token>`      |

요청 본문은 JSON이 아니라 `multipart/form-data`입니다. JSON으로 보내면 400 에러가 발생합니다.

### Body parameters (form-data)

| Name         | Type   | Description                         |
| ------------ | ------ | ----------------------------------- |
| `file`       | binary | 업로드할 파일 Required. 요청당 1개            |
| `objectType` | string | 첨부할 대상의 종류. `objectId`와 함께 사용       |
| `objectId`   | string | 첨부할 대상 레코드의 ID. `objectType`과 함께 사용 |

`objectType`에는 파일을 어느 대상에 첨부할지 입력합니다.

| 화면에서의 대상 | API에 입력하는 값    |
| -------- | -------------- |
| 딜        | `deal`         |
| 리드       | `lead`         |
| 고객       | `people`       |
| 회사       | `organization` |
| 상품       | `product`      |
| 견적서      | `quote`        |
| 커스텀 오브젝트 | `customObject` |
| 노트       | `memo`         |

커스텀 오브젝트에 첨부할 때 `objectId`에는 커스텀 오브젝트 **레코드**의 ID를 입력합니다. 정의(definition) ID가 아닙니다.

화면에서 첨부할 때와 동일하게, 딜·리드에 첨부하면 연결된 고객·회사의 첨부파일 탭에도, 고객에 첨부하면 연결된 회사의 첨부파일 탭에도 파일이 함께 표시됩니다.

### 업로드 제약

* 파일 크기는 1개당 25MB 이하여야 합니다.
* 허용된 MIME 타입만 업로드할 수 있습니다: `image/jpeg` `image/png` `image/gif` `image/webp` `application/pdf` `application/zip` doc/docx/xls/xlsx/ppt/pptx `text/plain` `text/csv`
* 파일 확장자와 MIME 타입이 일치해야 합니다.
* 빈 파일(0 byte)은 업로드할 수 없습니다.
* `objectType`과 `objectId`는 반드시 함께 보내야 합니다. 한쪽만 보내면 400 에러가 발생합니다.
* 존재하지 않거나 다른 워크스페이스에 속한 레코드에는 첨부할 수 없습니다.

### Request

#### 파일만 업로드하기 (이메일 첨부용)

응답의 `id`를 이메일 발송 API의 `attachmentIdList`에 사용합니다.

```bash
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/contract.pdf" \
  "https://salesmap.kr/api/v2/file"
```

#### 딜에 파일 첨부하기

업로드와 동시에 특정 딜의 첨부파일 탭에 파일이 첨부됩니다.

```bash
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/contract.pdf" \
  -F "objectType=deal" \
  -F "objectId=<dealId>" \
  "https://salesmap.kr/api/v2/file"
```

### Response

#### 201

```json
{
  "success": true,
  "data": {
    "id": "<fileId>",
    "name": "contract.pdf"
  }
}
```

| Name   | Type   | Description                        |
| ------ | ------ | ---------------------------------- |
| `id`   | string | 업로드된 파일의 ID. 이메일 첨부, 파일 삭제에 사용합니다. |
| `name` | string | 원본 파일명                             |

응답 형태는 `objectType` 유무와 관계없이 동일합니다.

#### 40x

```json
{
  "success": false,
  "message": "에러 메세지"
}
```

### 주요 에러

| Status | 상황                                                                                   |
| ------ | ------------------------------------------------------------------------------------ |
| 400    | `file` 필드 누락, JSON 본문 전송, 허용되지 않는 MIME 타입, 25MB 초과, `objectType`·`objectId` 중 한쪽만 전달 |
| 401    | 인증에 실패했습니다.                                                                          |
| 404    | 첨부할 대상 레코드를 찾을 수 없습니다.                                                               |
| 429    | 요청 횟수 제한을 초과했습니다.                                                                    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.salesmap.kr/developers/api-reference/crm/file/upload.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.