Ръководства

Фактури

Агентът може да прочете издадена фактура от свързания Fakturoid или ABRA Flexi и да я използва като основа за напомнящо обаждане - никога не издава фактура и не я отбелязва като платена.

Какво може и какво не може

• Търси издадени фактури по номер или име на фирма (list_invoices).
• Зарежда актуалното състояние на една фактура директно от доставчика (get_invoice).
• Създава напомняща Задача (taskType: "invoice"), която препраща към фактурата.

Не може

• Не издава, не редактира и не изтрива никаква фактура.
• Не отбелязва фактура като платена - това могат само Fakturoid или ABRA сами.
• Не свързва Fakturoid с данни за вход - възможно е само през OAuth в браузъра.

Свързване на профил

Двете фактуриращи услуги се управляват на същото място като календарите, в портала в раздела Данни и интеграции (/propojeni). list_integrations и GET /v1/integrations са само за четене: връщат състоянието на връзката и евентуален connectUrl, но сами нищо не свързват. Подробната процедура за агента (list_integrations -> connectUrl -> стъпка в браузъра) е на страницата Връзки.

Fakturoid

Свързва се единствено чрез OAuth вход в браузъра - POST /v1/integrations с provider: "fakturoid" REST отхвърля с грешка integration_unsupported, данни за вход тук не могат да се изпращат. Когато профилът има повече фирми с фактуриране, след входа браузърът се връща на страницата Данни и интеграции във volai (/propojeni) и там едва се показва изборът на фирма - записът в integrations възниква чак след този избор. ready за fakturoid в GET /v1/integrations съобщава само, че volai има настроени OAuth данни за вход към Fakturoid (FAKTUROID_CLIENT_ID и др.) - НЕ че конкретен профил вече е свързан. Дали връзката е готова, агентът познава по това, че се появява в полето integrations.

ABRA Flexi

Свързва се с данни за вход, както Apple Calendar: POST /v1/integrations с {provider: "abra-flexi", baseUrl, company, username, password}. Адресът на сървъра (baseUrl) трябва да съвпада с точния адрес, предварително разрешен от оператора (ABRA_FLEXI_ALLOWED_HOSTS) - друг връща грешка.

Четене на фактури

Процедура в две стъпки: първо търсене, после актуален детайл на онази една фактура, която Ви интересува.

• list_invoices({integrationId, search?}) - search (до 100 знака) търси при доставчика по номер на документ или име на фирма; връща първите 40 реда при Fakturoid или 50 при ABRA, без странициране. Когато резултатите са много, уточнете search.
• get_invoice({integrationId, invoiceId}) - invoiceId е повторената стойност externalId от list_invoices. Връща най-актуалното състояние директно от доставчика, а не това, което помни volai.

REST еквиваленти: GET /v1/integrations/{id}/invoices?search=... и GET /v1/integrations/{id}/invoices/{invoiceId}.

status е paid, unpaid, overdue или unknown; amountDueMinor е цяло число в най-малките единици на ВАЛУТАТА НА ДОКУМЕНТА (не непременно CZK), а null означава неустановен остатък. Детайлът допълнително носи provider, fetchedAt и evidence: "provider_response".

Напомняне през Задачи

Масовите напомнящи обаждания за неплатени фактури минават през Задачи.

Задача от тип taskType: "invoice" се създава със source: "integration" и всеки получател (или цялата задача, когато фактурата е една и съща за всички) носи externalRefs.invoice = {connectionId, externalId, provider?} - connectionId е id на връзката от list_integrations, externalId е id на фактурата от list_invoices. Без тази референция create_task/POST /v1/tasks пропада с грешка validation със съобщение recipients.externalRefs и не записва никаква задача. Ако задължителната референция липсва при вече съществуващ запис, get_task/GET /v1/tasks/{id} я посочва в issues, а start_task отказва да стартира задачата със същата грешка при валидиране.

Всеки получател освен това носи поле paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - само за четене, системата го извежда от последното четене на фактурата при доставчика непосредствено преди набирането. Без референция към фактура е not_applicable, след създаване или когато състоянието или сумата не могат да бъдат потвърдени е unknown, иначе според отговора на Fakturoid/ABRA - платена фактура задачата пропуска (skipped) и задава paid. Стойността disputed днес системата сама не задава, портала само може да я показва - тя е част от публичното изброяване (TaskItem в /openapi.json) за бъдещо ръчно отбелязване на спорна фактура.

Грешки

• integration_not_found - Връзка с този integrationId не съществува или не принадлежи на този профил.
• integration_unsupported - Връзката не е фактурираща (например календар) или е направен опит Fakturoid да бъде свързан с данни за вход вместо чрез OAuth.
• integration_unauthorized - Fakturoid или ABRA са оттеглили достъпа - връзката трябва да се направи наново в портала.
• integration_provider_error - Доставчикът в момента не отговаря или върна грешка - опитайте по-късно, а състоянието на фактурата междувременно приемайте за неизвестно.
• integration_invalid_query - ABRA отхвърли search с обратни наклонени черти или смесени кавички - опростете заявката.

Пълната таблица с всички кодове ще намерите в раздела фактури в REST API справочника и в грешките на MCP.

Сигурност

Токени за достъп и пароли към Fakturoid и ABRA Flexi нито REST API, нито MCP връщат някога, а ние ги съхраняваме криптирани. Прекъсване на интеграция е възможно само в портала или през REST (DELETE /v1/integrations/{id}) - MCP няма инструмент за това нарочно, защото е необратимо.