Повезивање на СЕФ API: кључ није довољан док статус не постане активан

За повезивање ERP система са Системом електронских фактура (СЕФ) потребни су регистрован налог субјекта, генерисан API кључ и укључен статус „Активно“. Званично кратко упутство наводи генерисање кључа и активирање статуса као засебне радње у одељку „API management“. Сам приказан кључ зато није довољна провера да је приступ спреман.

Редослед за фирму и ERP програмера је да овлашћено лице региструје субјекта, припреми кључ и активира API статус, а програмер провери приступ позивом који не шаље фактуру. Тек после успешног позива следе припрема XML-а и пробно слање. Такав редослед помаже да се проблем са приступом одвоји од грешке у садржају фактуре.

Регистрација субјекта је први услов

Ако субјект још није регистрован на СЕФ-у, поступак започиње законски заступник. Он се пријављује преко портала за електронску идентификацију, уз квалификовани електронски сертификат или параметре за двофакторску аутентикацију. По повратку на СЕФ бира субјект који заступа и довршава регистрацију његовог налога. Програмер не може да надомести тај пословни корак самим подешавањем ERP-а.

Пре рада са кључем утврдите који је субјект изабран у СЕФ-у и ко у фирми управља његовим подешавањима. Ово је нарочито важно ако законски заступник има приступ налозима више фирми: кључ треба преузети са налога чије фактуре ERP заиста обрађује. Лична еИД пријава служи човеку за улазак у систем, док се API кључ користи за идентификацију софтвера при позиву метода. Провајдеру зато предајте само приступне податке који су му потребни за интеграцију, без лозинке или параметара за личну пријаву.

Кључ и статус подешавају се одвојено

На налогу одговарајућег субјекта отворите „Подешавања“, затим „API management“. Изаберите „Генериши кључ“, па засебно укључите клизач за API статус „Активно“. Пре него што кључ доставите програмеру, у истом одељку проверите обе ставке: да је кључ генерисан и да је статус укључен. Овим се избегава ситуација у којој је тајна унета у ERP, а приступ још није активиран на налогу.

Ако први позив не успе, проверу почните од налога, статуса и кључа који интеграција шаље. Утврдите и да ли ERP позива окружење за које сте припремили приступ. Поновно генерисање кључа није замена за ту дијагностику: прво забележите HTTP статус и поруку одговора, али из записа и тикета изоставите вредност кључа. Тако програмер добија податке потребне за отклањање грешке без откривања тајне.

Када кључ заиста треба заменити, договорите тренутак промене са особом која одржава ERP интеграцију. Нова вредност мора стићи у њену конфигурацију, после чега поновите пробни позив пре редовног слања фактура. Ово је организациона мера за контролисану замену приступних података; немојте претпоставити да је интеграција подешена само зато што је нови кључ видљив у СЕФ-у.

Swagger и први позив без фактуре

Линк ка Swagger документацији доступан је у одељку „API management“. Она служи за преглед метода и параметара које програмер уноси у интеграцију. Страница техничке спецификације упућује и на посебну API документацију која се одржава у складу са имплементираном верзијом система. Зато назив методе, путању и параметре узмите из документације за окружење са којим се повезујете.

За проверу приступа погодан је GET /api/publicApi/get-unit-measures. API документација за ту методу прописује HTTP заглавље ApiKey и описује одговор са листом јединица мере. Методом се не шаље фактура, па омогућава да најпре проверите кључ и приступ. Условни приказ заглавља је „ApiKey: [ТЕСТ_КЉУЧ]“; текст у заградама није стварна тајна и у захтеву се замењује кључем одговарајућег налога.

Покрените позив у Swagger-у, па из ERP-а према истом окружењу. Ако успе само у Swagger-у, упоредите адресу, путању, тачан назив заглавља и вредност коју ERP заиста шаље. Ако не успе ни тамо, вратите се на налог субјекта и његов API статус. Успешан одговор на овај позив показује да интеграција може да приступи методи; још не показује да ће XML фактура бити прихваћена.

XML проверите пре пробног слања

За пробну фактуру припремите UBL XML са подацима прикладним за окружење у којем тестирате. Упутство за XML валидацију упућује на сервис у којем се за фактуру бира скуп правила „UBL Invoice 2.1“. Ако користите тај спољни сервис, податке за тест припремите у складу са правилима фирме о њиховом дељењу. Пролаз на валидатору је провера документа, а не потврда да је фактура послата кроз СЕФ.

После валидације изаберите у API документацији методу за слање која одговара начину на који ERP доставља UBL: као датотеку или као XML садржај захтева. Параметри и тип садржаја нису исти за те поступке. Програмер треба да сачува одговор СЕФ-а и идентификатор фактуре који добије, како би исход пробног слања могао да повеже са конкретним захтевом. Ако слање не успе, порука одговора је полазиште за исправку XML-а или параметара позива.

За сваку нову фактуру задајте нов requestId. Ако је веза прекинута и исход истог слања је нејасан, поновите тај захтев са истим идентификатором, уместо да одмах направите други. Одговори СЕФ-а о API позивима објашњавају да поновна употреба идентификатора већ обрађене фактуре враћа њен постојећи идентификатор, без креирања нове фактуре. Тако се разликују ново слање и поновљени покушај после нејасног одговора.

Предаја кључа ERP провајдеру

Када интеграцију одржава спољни провајдер, пошаљите му кључ договореним заштићеним каналом и наведите субјект и окружење на које се односи. Кључ чувајте у заштићеној конфигурацији интеграције, доступној само људима и сервисима којима је потребна. Не уносите га у изворни код, јавни репозиторијум, снимак екрана или обичан прилог преписке. Исто правило важи за примере захтева и логове које размењујете током отклањања грешке.

Унапред одредите ко у фирми може да замени кључ и ко код провајдера ажурира конфигурацију. При промени забележите када је ERP прешао на нову вредност и поновите позив за јединице мере пре наредног слања. За завршну проверу интеграције потребна су три различита резултата: активан статус на налогу субјекта, успешан позив без фактуре и успешно обрађена пробна фактура у предвиђеном окружењу.

Прочитајте и:

• Ollama или LM Studio: бржи одговор није и већа пропусност