# Водяной знак

Источник: https://dev.smartpdf.ru/docs/operations/watermark

Наносит водяной знак — текст или логотип. Нужен ровно один из параметров text и image_file_id.

- Запрос: `POST https://api.smartpdf.ru/v1/pdf/watermark`, тело — JSON, ключ — заголовок `X-API-Key`

- Инструмент MCP: `watermark_pdf` (вместо file_id — публичная ссылка file_url)

- Вход: PDF; логотип — PNG, JPG или WEBP через POST /v1/upload

- Результат: PDF

- Единица цены: 10 МБ

## Параметры

| Параметр | Тип | Описание |
|---|---|---|
| `file_id` (обязательный) | `string` | file_id загруженного файла (POST /v1/upload); действует час. |
| `text` | `string` | Текст знака (кириллица поддерживается). |
| `image_file_id` | `string` | file_id загруженного логотипа вместо текста. Прозрачность PNG сохраняется. |
| `font_size` | `integer` | Размер шрифта текста: от 8 до 200. По умолчанию: `48`. |
| `color` | `string` | Цвет текста — hex, например #0F766E. По умолчанию: `"#FF0000"`. |
| `opacity` | `number` | Непрозрачность: от 0 до 1. По умолчанию: `0.3`. |
| `angle` | `number` | Угол наклона в градусах: от −180 до 180. По умолчанию: `45`. |
| `position` | `string` | center — в центре; tile — плиткой по всей странице; углы — в выбранном углу. Значения: `"center"`, `"tile"`, `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`. По умолчанию: `"center"`. |
| `pages` | `integer[] \| "all"` | Номера страниц с 1 или "all". По умолчанию: `"all"`. |
| `scale` | `number` | Ширина логотипа — доля ширины страницы: от 0,1 до 2; высота — по пропорциям. По умолчанию: `0.3`. |
| `webhook_url` | `string` | https-адрес: по завершении SmartPDF отправит на него POST с результатом и подписью — вместо опроса статуса (раздел «Вебхуки»). |

## Запрос

Шаг 2 полного цикла: файл уже загружен, статус и скачивание — как в быстром старте (https://dev.smartpdf.ru/docs/quickstart.md).

### cURL

```bash
BODY=$(jq -n --arg file_id "$FILE_ID" '{file_id: $file_id, text: "КОПИЯ", opacity: 0.2, position: "tile"}')
curl -sS --fail-with-body -H "X-API-Key: $SMARTPDF_API_KEY" -H "Content-Type: application/json" \
  -d "$BODY" https://api.smartpdf.ru/v1/pdf/watermark
```

### Python

```python
task_id = call("POST", "/pdf/watermark", json={"file_id": file_id, "text": "КОПИЯ", "opacity": 0.2, "position": "tile"})["task_id"]
```

### Node.js

```javascript
const { task_id } = await call("/pdf/watermark", { method: "POST", json: { file_id: fileId, text: "КОПИЯ", opacity: 0.2, position: "tile" } });
```

### PHP

```php
$taskId = call('POST', '/pdf/watermark', ['file_id' => $fileId, 'text' => 'КОПИЯ', 'opacity' => 0.2, 'position' => 'tile'])['task_id'];
```

### Go

```go
payload, _ := json.Marshal(map[string]any{"file_id": fileID, "text": "КОПИЯ", "opacity": 0.2, "position": "tile"})
call("POST", "/pdf/watermark", bytes.NewReader(payload), "application/json", &task)
```

### Java

```java
String body = JSON.writeValueAsString(Map.of("file_id", fileId, "text", "КОПИЯ", "opacity", 0.2, "position", "tile"));
String taskId = call(HttpRequest.newBuilder(URI.create(API + "/pdf/watermark"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))).get("task_id").asText();
```

### C#

```csharp
var task = await Read(await http.PostAsJsonAsync($"{Api}/pdf/watermark", new { file_id = fileId, text = "КОПИЯ", opacity = 0.2, position = "tile" }));
```

## Ответ

`202 Accepted` — операция оплачена и поставлена в очередь:

```json
{
  "task_id": "3f2c5b0e-8a41-4d7e-9c1f-5d0b8f2e7a64"
}
```

Дальше — GET /v1/tasks/{task_id} (https://dev.smartpdf.ru/docs/tasks.md) или вебхук (https://dev.smartpdf.ru/docs/webhooks.md).