first
This commit is contained in:
JiriUhlir
@@ -0,0 +1,44 @@
|
||||
# Specifika instalace POLSTRIN DESIGN s.r.o.
|
||||
|
||||
Zjištěno z `GET /api/system/info` (10. 7. 2026, testovací databáze).
|
||||
|
||||
## Základní údaje
|
||||
|
||||
- Service Layer: `https://ws.polstrin.cz:50000/b1s/v1`
|
||||
- Verze SAP Business One: `1000310` (SAP B1 10.0), session timeout 30 minut
|
||||
- Firma: POLSTRIN DESIGN s.r.o., Hradec Králové, DIČ `CZ49283120`
|
||||
- Firemní měna `CZK`, systémová měna `EUR`, účtová osnova šablona `U`
|
||||
- Průběžné vedení skladu metodou **Moving Average**, výchozí sklad `01.100`
|
||||
- Výchozí kódy DPH: prodej `UP21`, nákup `PP21`
|
||||
- **Pozor:** dodaný výpis pochází z databáze pojmenované „TEST 10.7.2026 POLSTRIN DESIGN, s.r.o.“ — před produkčním nasazením ověř, že secret `SAP_B1_COMPANY_DB` míří na správnou (produkční) databázi.
|
||||
|
||||
## Nainstalované addony a jejich prefixy
|
||||
|
||||
Instalace obsahuje rozsáhlé customizace. UDO tabulky jsou v Service Layeru dostupné jako entity sety `U_<prefix>_*` (přes `/api/entities/...`), UDF se stejnými prefixy jsou přidané na standardních objektech (artikly `OITM`, obchodní partneři `OCRD`, všechny marketingové doklady, montážní zakázky `OWOR`, kusovníky `OITT` atd.) a vrací se v běžných odpovědích — stačí je uvést v `$select`.
|
||||
|
||||
| Prefix | Oblast |
|
||||
|---|---|
|
||||
| `ADN_` / `U_ADN_*` | Evidence majetku (karty majetku, odpisy daňové/účetní, pohyby, inventury, ceniny, pronájmy) |
|
||||
| `DFX_` / `U_DFX_*` | Intrastat a evidence majetku CZ (hlášení, nomenklatury, číselníky, verze addonu) |
|
||||
| `PVT_` / `U_PVT_*` | Intrastat (KN8 kódy, kurzy, statistické kódy, tisková data) |
|
||||
| `VCZ_` / `U_VCZ_*` | Versino CZ – lokalizace a výroba: EET, elektronická banka, platební příkazy (KS/SS/VS), QR platba, kontrolní/souhrnné hlášení DPH, kalkulace, plánování výroby (`MPK*`), pracoviště (`MWPL*`), trasování výroby (`MTTRC`), pick listy, tiskové reporty |
|
||||
| `B1SYS_` | Systémová CZ lokalizace (EET pole PKP/BKP na dokladech) |
|
||||
| `BOE*`, `BOO*`, `BOQUOT`, `BOSETTINGS` | Outlook/Office integrace (sync kalendáře, kontaktů, šablony Word/Excel) |
|
||||
| `VYROBNI_PLAN`, `VYROBNI_DAVKA` | Vlastní UDO pro výrobní plánování |
|
||||
|
||||
Často užitečná pole na dokladech: `VCZ_5030` (číslo dokladu), `VCZ_7042` (variabilní symbol), `VCZ_6502`/`VCZ_7141` (KS/SS), `VCZ_9522`/`VCZ_9192` (vazba na zakázku odběratele a její řádek), `VCZ_5EE*` (EET), `DFX_*`/`PVT_*` (Intrastat), na artiklu `VCZ_5315/5316/5317` (popisy CZ/EN/RU) a `PVT_KINT` (kód Intrastat).
|
||||
|
||||
## Oprávnění SAP uživatele
|
||||
|
||||
Aktuální SAP uživatel **nemá oprávnění** číst `UserTablesMD` a `UserObjectsMD` (v `/api/system/info` se vrací `{ "error": "The logged-on user does not have permission..." }`). Data UDO tabulek jsou přesto dostupná přes jejich `U_*` entity sety; pro čtení metadat UDT/UDO je potřeba uživateli doplnit oprávnění v SAP (General → User-Defined Objects/Tables).
|
||||
|
||||
## Práce s customizacemi přes API
|
||||
|
||||
```http
|
||||
GET /api/entities # seznam všech entity setů
|
||||
GET /api/entities/U_VCZ_MKONF?$top=10 # konfigurátor výroby
|
||||
GET /api/entities/U_ADN_MEM/all # všechny karty majetku
|
||||
GET /api/entities/VYROBNI_PLAN/'001' # klíč Code (string, default)
|
||||
GET /api/entities/ProductionOrders/123?idType=number
|
||||
GET /api/items/A00001 # UDF pole jsou součástí odpovědi
|
||||
```
|
||||
@@ -0,0 +1,70 @@
|
||||
# SAP Business One Service Layer Connector (POLSTRIN)
|
||||
|
||||
Connector komunikuje výhradně přes SAP Business One Service Layer `/b1s/v1` instalace POLSTRIN
|
||||
(`https://ws.polstrin.cz:50000`). Specifika instalace jsou v [polstrin-specifika.md](polstrin-specifika.md).
|
||||
|
||||
Hlavní vlastnosti:
|
||||
|
||||
- login/logout přes Service Layer
|
||||
- správa `B1SESSION` a `ROUTEID`, jedna sdílená session mezi requesty
|
||||
- automatický re-login po expiraci session
|
||||
- SAP credentials výhradně z environment variables (AppFactory secrets), ne z requestů
|
||||
- volitelná ochrana `/api` rout hlavičkou `X-Api-Key` (secret `API_KEY`)
|
||||
- OData parametry `$select`, `$filter`, `$top`, `$skip`, `$orderby`
|
||||
- stránkování přes `odata.nextLink` a `@odata.nextLink`
|
||||
- generický přístup k libovolnému entity setu přes `/api/entities/...` (POLSTRIN UDO tabulky `U_*`)
|
||||
- retry pro dočasné chyby
|
||||
- zod validace konfigurace a hlavních response tvarů
|
||||
|
||||
Bezpečnostní pravidla:
|
||||
|
||||
- konfigurace se čte výhradně z environment variables (`SAP_B1_*`, `API_KEY`)
|
||||
- SAP credentials se nikdy nepřijímají v requestech, nelogují a nevrací v response
|
||||
- hesla, cookies a session tokeny se nelogují
|
||||
- testy nepoužívají reálný SAP přístup
|
||||
- pro self-signed certifikáty je dostupné `rejectUnauthorized`, ale produkčně se doporučuje důvěryhodný certifikát
|
||||
|
||||
## Detaily komunikace se Service Layer
|
||||
|
||||
- **Login** – `POST /b1s/v1/Login` s `{ CompanyDB, UserName, Password, Language? }`.
|
||||
`Language` se posílá jako celé číslo (Service Layer očekává `Edm.Int32`); nenumerická
|
||||
hodnota se vynechá. Z odpovědi se čtou cookies `B1SESSION` a `ROUTEID` (s fallbackem na
|
||||
`SessionId` v body) a `SessionTimeout` (minuty) pro výpočet expirace.
|
||||
- **Autentizované requesty** – posílají `Cookie: B1SESSION=…; ROUTEID=…`. Při `401`
|
||||
connector jednou provede re-login a request zopakuje; re-login nesnižuje retry budget,
|
||||
takže funguje i při `SAP_B1_RETRY_COUNT=0`.
|
||||
- **Logout** – `POST /b1s/v1/Logout` se posílá **s aktivní session cookie**, jinak by
|
||||
Service Layer nevěděl, kterou session ukončit, a nechal by ji běžet až do timeoutu.
|
||||
- **Verze a system info** – login response obsahuje `Version` (např. `1000230` = SAP B1
|
||||
10.0 PL 23) a `SessionTimeout`; connector si je ukládá (`client.loginInfo`, přežije
|
||||
logout) a HTTP endpoint `POST /api/session/login` je vrací v odpovědi.
|
||||
`GET /api/system/info` navíc vrátí přehled instalace: service document (`GET /b1s/v1/`
|
||||
→ dostupné entity sety), `UserFieldsMD` (UDF), `UserTablesMD` (UDT), `UserObjectsMD`
|
||||
(UDO) a `CompanyService_GetAdminInfo`. Sekce, na kterou SAP uživatel nemá práva, se
|
||||
vrátí jako `{ "error": "…" }`, aby jedno chybějící oprávnění neshodilo celý přehled
|
||||
(chyba je v odpovědi vidět, nejde o tiché selhání).
|
||||
- **Stránkování** – následuje `odata.nextLink` i `@odata.nextLink`. U absolutních
|
||||
nextLinků se zachová i query string (`$skip` apod.), takže `listAll` nezacyklí.
|
||||
|
||||
## Reverse proxy a Swagger
|
||||
|
||||
Aplikace běží za AppFactory proxy na `/apps/<app-id>` (Caddy `handle_path` prefix před
|
||||
předáním do containeru odstraní, takže container vidí routy bez prefixu a z requestu
|
||||
veřejnou cestu nelze odvodit). Stejný přístup jako sousední služba `google-service`:
|
||||
|
||||
- `/docs` se servíruje **přímo jako HTML** (`GET /docs`), bez `swagger-ui-express` a bez
|
||||
statického middleware – proto **nevzniká žádný redirect `/docs` → `/docs/`**, který by za
|
||||
proxy zahodil prefix `/apps/<app-id>` (to byla příčina bílé stránky).
|
||||
- Swagger UI assety se načítají z CDN (`unpkg.com/swagger-ui-dist@5`).
|
||||
- Spec URL je `ROOT_PATH + /openapi.json`, takže odkazuje na veřejné
|
||||
`/apps/<app-id>/openapi.json`.
|
||||
- `servers[0].url` se nastaví z `ROOT_PATH` (jinak `/`), takže Swagger `Try it out` volá
|
||||
`…/apps/<app-id>/api/<resource>`.
|
||||
|
||||
| Kontrola | Lokálně (bez ROOT_PATH) | S `ROOT_PATH=/apps/sap-bo` |
|
||||
|---|---|---|
|
||||
| `GET /health` | 200 | 200 |
|
||||
| `GET /docs` (Swagger UI) | 200, žádný redirect | 200, žádný redirect |
|
||||
| `GET /openapi.json` | 200 | 200 |
|
||||
| spec URL v `/docs` | `/openapi.json` | `/apps/sap-bo/openapi.json` |
|
||||
| `servers[0].url` v OpenAPI | `/` | `/apps/sap-bo` |
|
||||
Reference in New Issue
Block a user