JiriUhlir
197 lines
5.1 KiB
Markdown
197 lines
5.1 KiB
Markdown
# SAP Business One Service Layer Connector
|
|
|
|
Produkční Node.js + TypeScript connector pro SAP Business One Service Layer REST/OData API. Používá pouze Service Layer (`/b1s/v1`), ne SAP DI API.
|
|
|
|
Součástí repozitáře je i malý AppFactory HTTP wrapper s endpointy:
|
|
|
|
- `GET /`
|
|
- `GET /health`
|
|
- `GET /docs`
|
|
- `GET /openapi.json`
|
|
- `POST /api/session/login`
|
|
- `POST /api/session/logout`
|
|
- `GET /api/<resource>`
|
|
- `GET /api/<resource>/all`
|
|
- `GET /api/<resource>/{id}`
|
|
- `POST /api/<resource>`
|
|
- `PATCH /api/<resource>/{id}`
|
|
- `DELETE /api/<resource>/{id}` pouze pro obecně mazatelné resource
|
|
|
|
## Instalace
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
npm test
|
|
```
|
|
|
|
## Konfigurace knihovny
|
|
|
|
Vytvoř `.env` podle `.env.example`:
|
|
|
|
```env
|
|
SAP_B1_BASE_URL=https://sap.example.local:50000
|
|
SAP_B1_COMPANY_DB=SBODEMOUS
|
|
SAP_B1_USERNAME=manager
|
|
SAP_B1_PASSWORD=change-me
|
|
SAP_B1_LANGUAGE=
|
|
SAP_B1_TIMEOUT_MS=30000
|
|
SAP_B1_REJECT_UNAUTHORIZED=true
|
|
SAP_B1_RETRY_COUNT=2
|
|
SAP_B1_RETRY_DELAY_MS=250
|
|
```
|
|
|
|
`SAP_B1_BASE_URL` může být buď root Service Layer hostu, nebo přímo URL končící `/b1s/v1`. Hesla ani session tokeny se nelogují.
|
|
|
|
Pro self-signed certifikáty lze v interním prostředí nastavit:
|
|
|
|
```env
|
|
SAP_B1_REJECT_UNAUTHORIZED=false
|
|
```
|
|
|
|
V produkci preferuj důvěryhodný certifikát a ponech `true`.
|
|
|
|
## HTTP API credentials
|
|
|
|
Podle AppFactory pravidel se SAP credentials pro HTTP API předávají v request headers, ne v JSON body:
|
|
|
|
```http
|
|
X-SAP-B1-BaseUrl: https://sap.example.local:50000
|
|
X-SAP-B1-CompanyDB: SBODEMOUS
|
|
X-SAP-B1-Username: manager
|
|
X-SAP-B1-Password: <secret>
|
|
X-SAP-B1-Language: 3
|
|
X-SAP-B1-Reject-Unauthorized: true
|
|
X-SAP-B1-Timeout-Ms: 30000
|
|
```
|
|
|
|
Povinné jsou `X-SAP-B1-BaseUrl`, `X-SAP-B1-CompanyDB`, `X-SAP-B1-Username` a `X-SAP-B1-Password`.
|
|
|
|
Heslo se nesmí zapisovat do README, logů ani běžných response. `/docs` obsahují interaktivní formulář, který tyto hodnoty posílá jako hlavičky.
|
|
|
|
## Použití
|
|
|
|
### Login a logout
|
|
|
|
```ts
|
|
import { SapBusinessOneServiceLayer, loadSapB1ConfigFromEnv } from "./src";
|
|
|
|
const sap = new SapBusinessOneServiceLayer(loadSapB1ConfigFromEnv());
|
|
|
|
await sap.login();
|
|
await sap.logout();
|
|
```
|
|
|
|
Login volá `POST /b1s/v1/Login`, uloží cookies `B1SESSION` a `ROUTEID` a posílá je v dalších requestech. Při expiraci session a odpovědi `401` connector jednou provede re-login a request zopakuje.
|
|
|
|
### Vypsání Business Partners
|
|
|
|
```ts
|
|
const partners = await sap.businessPartners.list({
|
|
select: ["CardCode", "CardName", "CardType"],
|
|
filter: "CardType eq 'cCustomer'",
|
|
top: 50,
|
|
orderby: "CardName asc"
|
|
});
|
|
|
|
console.log(partners.value);
|
|
```
|
|
|
|
### Načtení všech záznamů přes nextLink
|
|
|
|
```ts
|
|
const allItems = await sap.items.listAll({
|
|
select: ["ItemCode", "ItemName"],
|
|
top: 100
|
|
});
|
|
```
|
|
|
|
Connector podporuje starší `odata.nextLink` i novější `@odata.nextLink`.
|
|
|
|
### Vytvoření objednávky
|
|
|
|
```ts
|
|
const order = await sap.orders.create({
|
|
CardCode: "C001",
|
|
DocDueDate: "2026-07-15",
|
|
DocumentLines: [
|
|
{
|
|
ItemCode: "A00001",
|
|
Quantity: 2,
|
|
UnitPrice: 100
|
|
}
|
|
]
|
|
});
|
|
```
|
|
|
|
### Aktualizace položky
|
|
|
|
```ts
|
|
await sap.items.update("A00001", {
|
|
ItemName: "Updated item name"
|
|
});
|
|
```
|
|
|
|
## Resource moduly
|
|
|
|
Implementované resource moduly:
|
|
|
|
- `businessPartners`
|
|
- `items`
|
|
- `orders`
|
|
- `invoices`
|
|
- `purchaseOrders`
|
|
- `deliveryNotes`
|
|
- `stockTransfers`
|
|
|
|
Každý modul má:
|
|
|
|
- `list(query?)`
|
|
- `listAll(query?)`
|
|
- `get(id)`
|
|
- `create(data)`
|
|
- `update(id, data)`
|
|
- `delete(id)` pouze tam, kde je povolené mazání
|
|
|
|
U marketing dokumentů (`Orders`, `Invoices`, `PurchaseOrders`, `DeliveryNotes`) a skladových převodek je delete v connectoru záměrně blokovaný. SAP Business One obvykle řeší rušení dokumentů storno/cancel operacemi podle typu dokladu a nastavení firmy.
|
|
|
|
## Zpracování chyb
|
|
|
|
Connector převádí chyby na `SapB1Error`:
|
|
|
|
- `status` HTTP status
|
|
- `code` SAP error code, pokud jej Service Layer vrátí
|
|
- `message` bezpečná chybová zpráva
|
|
- `retryable` příznak pro dočasné chyby
|
|
|
|
Retry se používá pro `408`, `429` a `5xx`. Citlivé hodnoty jako heslo, cookies a session tokeny se při logování redigují.
|
|
|
|
## Testy
|
|
|
|
Testy používají mockované HTTP odpovědi přes axios adapter nebo fake klienty. Nevolají reálný SAP.
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Pokryté oblasti:
|
|
|
|
- autentizace a cookies
|
|
- logout
|
|
- automatický re-login po `401`
|
|
- OData query parametry
|
|
- resource URL builder
|
|
|
|
## AppFactory
|
|
|
|
Aplikace poslouchá na `0.0.0.0` a portu `PORT` s výchozí hodnotou `3000`. `ROOT_PATH` se používá pro dokumentaci a testovací requesty za reverse proxy, například `/apps/sap-bo`.
|
|
|
|
`/docs` a `/openapi.json` dokumentují všechny obecně implementované endpointy a obsahují povinné `X-SAP-B1-*` hlavičky.
|
|
|
|
## TODO ověřit v konkrétní instalaci SAP Business One
|
|
|
|
- Přesné enum hodnoty a povinná pole pro jednotlivé entity se mohou lišit podle lokalizace, add-onů a verze SAP Business One.
|
|
- U rušení dokladů ověř konkrétní Service Layer akce dostupné pro daný typ dokladu a firemní nastavení.
|
|
- U velkých datasetů ověř server-side limity stránkování a maximální povolené `$top`.
|
|
- Ověř, zda konkrétní instalace vrací OData metadata ve starším formátu `odata.*` nebo novějším `@odata.*`.
|