sap-bo/documentation/sap-business-one-service-layer.md

SAP Business One Service Layer Connector

Connector komunikuje výhradně přes SAP Business One Service Layer /b1s/v1.

Hlavní vlastnosti:

• login/logout přes Service Layer
• správa B1SESSION a ROUTEID
• automatický re-login po expiraci session
• HTTP API s credentials předávanými v X-SAP-B1-* hlavičkách podle AppFactory pravidel
• OData parametry $select, $filter, $top, $skip, $orderby
• stránkování přes odata.nextLink a @odata.nextLink
• retry pro dočasné chyby
• zod validace konfigurace a hlavních response tvarů

Bezpečnostní pravidla:

• při knihovním použití se konfigurace může číst z environment variables
• při HTTP API použití se SAP credentials posílají v request headers
• hesla, cookies a session tokeny se nelogují
• hesla a session tokeny se nevrací v běžných response
• 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

HTTP API hlavičky:

• X-SAP-B1-BaseUrl
• X-SAP-B1-CompanyDB
• X-SAP-B1-Username
• X-SAP-B1-Password
• X-SAP-B1-Language volitelně
• X-SAP-B1-Reject-Unauthorized volitelně
• X-SAP-B1-Timeout-Ms volitelně

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.
• 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