xaxumessageAPI
Методы API

Файлы

Загрузка исходящих файлов и скачивание входящих. Лимит — 100 МБ на файл.

Загрузить файл (multipart)

POST/v1/attachments
API-ключ клиентаУспех: 201

Загрузите файл, затем отправьте его сообщением типа file с attachmentId. Один загруженный файл можно отправлять сколько угодно раз.

Тело запроса

fileфайлобязательно
поле формы multipart/form-data
captionstring
подпись по умолчанию

Ошибки

400bad_requestнет поля file или запрос не multipart
413too_largeфайл больше 100 МБ
Запрос
curl -X POST https://msg.xaxu.am/v1/attachments \
  -H "Authorization: Bearer $XM_API_KEY" \
  -F file=@scan.pdf -F caption="Договор"
Ответ 201
{
  "id": "f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
  "messageId": null,
  "direction": "out",
  "kind": "document",
  "fileName": "scan.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 184213,
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "caption": "Договор",
  "status": "stored",
  "error": null,
  "createdAt": "2026-10-10T09:28:11.000Z",
  "storedAt": "2026-10-10T09:28:12.000Z",
  "contentUrl": "/v1/attachments/f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b/content"
}

Загрузить файл (байты в теле)

PUT/v1/attachments
API-ключ клиентаУспех: 201

То же, но файл передаётся «как есть» телом запроса — удобно для потоков и больших файлов.

Параметры запроса

fileNamestring ≤ 255обязательно
имя файла
mimeTypestring
тип; если не указан — берётся из Content-Type (кроме application/octet-stream)
captionstring
подпись

Ошибки

413too_largeфайл больше 100 МБ
Запрос
curl -X PUT "https://msg.xaxu.am/v1/attachments?fileName=photo.jpg&mimeType=image/jpeg" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @photo.jpg
Ответ 201
{
  "id": "f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
  "messageId": null,
  "direction": "out",
  "kind": "image",
  "fileName": "photo.jpg",
  "mimeType": "image/jpeg",
  "sizeBytes": 184213,
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "caption": null,
  "status": "stored",
  "error": null,
  "createdAt": "2026-10-10T09:28:11.000Z",
  "storedAt": "2026-10-10T09:28:12.000Z",
  "contentUrl": "/v1/attachments/f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b/content"
}

Сведения о файле

GET/v1/attachments/:id
API-ключ клиентаУспех: 200

Входящие файлы шлюз скачивает сам: сначала status: pending, затем stored (можно скачивать) или failed / expired. Об этом приходят события attachment.stored / attachment.failed.

Параметры пути

iduuidобязательно
id файла

Ошибки

404not_foundфайла нет или он принадлежит другому клиенту
Запрос
curl "https://msg.xaxu.am/v1/attachments/{id}" \
  -H "Authorization: Bearer $XM_API_KEY"
Ответ 200
{
  "id": "f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
  "messageId": "0b8e4d2a-6c1f-4a3e-9b7d-5e2f1c0a9d8b",
  "direction": "in",
  "kind": "image",
  "fileName": "photo.jpg",
  "mimeType": "image/jpeg",
  "sizeBytes": 184213,
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "caption": "Вот так выглядит номер",
  "status": "stored",
  "error": null,
  "createdAt": "2026-10-10T09:28:11.000Z",
  "storedAt": "2026-10-10T09:28:12.000Z",
  "contentUrl": "/v1/attachments/f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b/content"
}

Скачать файл

GET/v1/attachments/:id/content
API-ключ клиентаУспех: 200

Отдаёт сами байты с Content-Type файла. Ссылка на этот адрес — поле contentUrl файла.

Параметры пути

iduuidобязательно
id файла

Параметры запроса

inlineboolean
true — открыть в браузере, а не скачать (Content-Disposition: inline)

Ошибки

409attachment_not_readyфайл ещё скачивается или не сохранился
404not_foundфайла нет или он принадлежит другому клиенту
Запрос
curl -OJ https://msg.xaxu.am/v1/attachments/f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b/content \
  -H "Authorization: Bearer $XM_API_KEY"