From 694f558d7d4a0aa1b9e88180c61ba28bb16d0f71 Mon Sep 17 00:00:00 2001
From: spervuhina <spervuhina@team.amocrm.com>
Date: Tue, 30 Dec 2025 16:46:25 +0300
Subject: [PATCH] feat(notes): add pin and unpin notes methods and querying
 notes with is_pinned parameter

---
 src/AmoCRM/EntitiesServices/EntityNotes.php | 43 ++++++++++++++++++++-
 src/AmoCRM/Models/NoteModel.php             | 36 ++++++++++++++++-
 2 files changed, 77 insertions(+), 2 deletions(-)

diff --git a/src/AmoCRM/EntitiesServices/EntityNotes.php b/src/AmoCRM/EntitiesServices/EntityNotes.php
index 81bcadd0..07ed45fa 100644
--- a/src/AmoCRM/EntitiesServices/EntityNotes.php
+++ b/src/AmoCRM/EntitiesServices/EntityNotes.php
@@ -4,7 +4,11 @@
 
 use AmoCRM\EntitiesServices\Interfaces\HasParentEntity;
 use AmoCRM\EntitiesServices\Traits\WithParentEntityMethodsTrait;
+use AmoCRM\Exceptions\AmoCRMApiConnectExceptionException;
 use AmoCRM\Exceptions\AmoCRMApiException;
+use AmoCRM\Exceptions\AmoCRMApiHttpClientException;
+use AmoCRM\Exceptions\AmoCRMApiNoContentException;
+use AmoCRM\Exceptions\AmoCRMApiTooManyRedirectsException;
 use AmoCRM\Exceptions\AmoCRMoAuthApiException;
 use AmoCRM\Exceptions\InvalidArgumentException;
 use AmoCRM\Filters\BaseEntityFilter;
@@ -16,7 +20,6 @@
 use AmoCRM\EntitiesServices\Interfaces\HasPageMethodsInterface;
 use AmoCRM\EntitiesServices\Traits\PageMethodsTrait;
 use AmoCRM\Models\BaseApiModel;
-use AmoCRM\Models\CustomFields\CustomFieldModel;
 use AmoCRM\Models\NoteModel;
 
 /**
@@ -198,4 +201,42 @@ public function getOne($id, array $with = []): ?BaseApiModel
 
         return !empty($response) ? $collection->first() : null;
     }
+
+    /**
+     * Закрепляет примечание.
+     * @param NoteModel $model
+     *
+     * @return void
+     * @throws AmoCRMApiException
+     * @throws AmoCRMoAuthApiException
+     * @throws AmoCRMApiConnectExceptionException
+     * @throws AmoCRMApiHttpClientException
+     * @throws AmoCRMApiTooManyRedirectsException
+     */
+    public function pin(NoteModel $model): void
+    {
+        try {
+            $this->request->post(sprintf('%s/%d/pin', $this->getMethod(), $model->getId()));
+        } catch (AmoCRMApiNoContentException $exception) {
+        }
+    }
+
+    /**
+     * Открепляет примечание.
+     * @param NoteModel $model
+     *
+     * @return void
+     * @throws AmoCRMApiException
+     * @throws AmoCRMoAuthApiException
+     * @throws AmoCRMApiConnectExceptionException
+     * @throws AmoCRMApiHttpClientException
+     * @throws AmoCRMApiTooManyRedirectsException
+     */
+    public function unpin(NoteModel $model): void
+    {
+        try {
+            $this->request->post(sprintf('%s/%d/unpin', $this->getMethod(), $model->getId()));
+        } catch (AmoCRMApiNoContentException $exception) {
+        }
+    }
 }
diff --git a/src/AmoCRM/Models/NoteModel.php b/src/AmoCRM/Models/NoteModel.php
index 16609471..c8507015 100644
--- a/src/AmoCRM/Models/NoteModel.php
+++ b/src/AmoCRM/Models/NoteModel.php
@@ -16,6 +16,9 @@ class NoteModel extends BaseApiModel implements Arrayable, HasIdInterface
 {
     use RequestIdTrait;
 
+    /** @var string Закреплено ли примечание */
+    public const IS_PINNED = 'is_pinned';
+
     protected $modelClass = NoteModel::class;
 
     /**
@@ -63,6 +66,11 @@ class NoteModel extends BaseApiModel implements Arrayable, HasIdInterface
      */
     protected $accountId;
 
+    /**
+     * @var null|bool
+     */
+    protected $isPinned = null;
+
     /**
      * @var null|bool
      */
@@ -109,6 +117,10 @@ public function fromArray(array $note): self
             $model->setAccountId((int)$note['account_id']);
         }
 
+        if (isset($note['is_pinned'])) {
+            $model->setIsPinned((bool)$note['is_pinned']);
+        }
+
         if (!empty($note['is_need_to_trigger_digital_pipeline'])) {
             $model->setIsNeedToTriggerDigitalPipeline((bool)$note['is_need_to_trigger_digital_pipeline']);
         }
@@ -318,6 +330,26 @@ public function setAccountId(?int $accountId): NoteModel
         return $this;
     }
 
+    /**
+     * Возвращает закреплено ли примечание
+     * @return bool|null
+     */
+    public function getIsPinned(): ?bool
+    {
+        return $this->isPinned;
+    }
+
+    /**
+     * @param bool|null $isPinned
+     * @return NoteModel
+     */
+    public function setIsPinned(?bool $isPinned): NoteModel
+    {
+        $this->isPinned = $isPinned;
+
+        return $this;
+    }
+
     /**
      * @return bool|null
      */
@@ -393,6 +425,8 @@ public function toApi(?string $requestId = "0"): array
      */
     public static function getAvailableWith(): array
     {
-        return [];
+        return [
+            self::IS_PINNED,
+        ];
     }
 }