Flow Procurement · Dokumentacja API

Przegląd

Flow Procurement REST API — JSON over HTTPS, JWT-auth, multi-tenant. Wszystkie endpointy pod /api/v1/ (z paroma wyjątkami: /auth/*, /admin/*, /superadmin/* bez prefiksu).

Base URL

https://flow-procurement.up.railway.app

http://localhost:8000

Format danych

• Request: Content-Type: application/json
• Response: application/json (z wyjątkiem /audit/export-html i /health/*)
• Daty: ISO-8601 UTC (np. 2026-04-26T19:32:00Z)
• Waluty: PLN domyślnie, multi-currency (EUR/USD/GBP/CHF/CZK/JPY) per pole currency
• NIP: 10 cyfr bez separatorów (np. "5260250274")
• UNSPSC: 8 cyfr (np. "25101500" = Hamulce i układy)

Wersjonowanie

Tesla-style YYYY.WW.BUILD.PATCH (np. 2026.17.86.0) — bumpowane automatycznie przy każdym push do main. Wersja widoczna w GET /health/ready response field version. Breaking changes sygnalizujemy przed deploymentem przez Slack/email + 30-dniowy deprecation window.

Uwierzytelnianie

JWT Bearer token. Każdy request (poza /auth/login, /health, /docs) wymaga headera Authorization: Bearer <token>.

1. Login

curl -X POST https://flow-procurement.up.railway.app/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"buyer","password":"buyer123"}'

# Response:
# {
#   "access_token": "eyJhbGc...",
#   "token_type": "bearer",
#   "expires_in": 86400,
#   "user": {"username":"buyer","role":"buyer","tenant_id":"demo","must_change_password":false}
# }

import requests

BASE = "https://flow-procurement.up.railway.app"

resp = requests.post(f"{BASE}/auth/login", json={
    "username": "buyer",
    "password": "buyer123"
})
data = resp.json()
TOKEN = data["access_token"]
print("Logged in as", data["user"]["username"], "role:", data["user"]["role"])

# Use the token for all subsequent requests:
headers = {"Authorization": f"Bearer {TOKEN}"}
me = requests.get(f"{BASE}/auth/me", headers=headers).json()
print(me)

const BASE = "https://flow-procurement.up.railway.app";

const login = await fetch(`${BASE}/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "buyer", password: "buyer123" })
});
const { access_token, user } = await login.json();
console.log("Logged in as", user.username, "role:", user.role);

// Use the token for all subsequent requests:
const me = await fetch(`${BASE}/auth/me`, {
  headers: { Authorization: `Bearer ${access_token}` }
}).then(r => r.json());
console.log(me);

2. Token lifetime

Tenant context

Flow Procurement jest multi-tenant — każda firma ma własny tenant. tenant_id jest:

1. Wpisany w JWT przy login (user.tenant_id)
2. Czytany przez TenantContextMiddleware z X-Tenant-ID headera (tylko super_admin może go przesłonić)
3. Filtruje wszystkie zapytania DB (suppliers, orders, catalog) tenant-isolated

Cross-tenant reads zwracają 404 Not Found (nie 403 Forbidden) — celowo, żeby nie wyjawiać czy zasób istnieje w innym tenant.

Błędy + rate limity

Wszystkie błędy mają jednolite body: {"detail": "<message>"} (FastAPI default).

Buyer · Koszyk + intake

POST /api/v1/copilot/conversational-intake

Polski natural language → lista pozycji + UNSPSC + dostawca. AI parsuje zdanie i auto-resolves brand/qty/budget/deadline.

curl -X POST $BASE/api/v1/copilot/conversational-intake \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"100 filtrów oleju Castrol, budżet 5 tys, do końca tygodnia"}'

# Response:
# {
#   "items": [{"name":"Filtr oleju Castrol","qty":100,"price_estimate":50,"unspsc":"25101504"}],
#   "urgency": "med",
#   "deadline": "2026-05-02",
#   "category": "Oleje i filtry",
#   "reply": "Dodałem do koszyka 100 sztuk filtrów Castrol..."
# }

Buyer · Optymalizacja

POST /api/v1/buying/optimize

HiGHS LP solver — multi-criteria allocation z Pareto + Monte Carlo + shadow prices.

resp = requests.post(f"{BASE}/api/v1/buying/optimize", headers=headers, json={
    "items": [{"id": "BRK-PAD-0041", "qty": 100, "name": "Klocki TRW"}],
    "weights": {"w_cost": 0.4, "w_time": 0.3, "w_compliance": 0.15, "w_esg": 0.15},
    "constraints": {
        "preferred_share_min": 0.6,   # C15: min 60% wolumenu od preferred
        "single_source_max": 0.8,     # C8: max 80% u jednego dostawcy
        "esg_min_score": 65,          # C13: ESG floor
    }
})
sol = resp.json()
print("Total cost:", sol["total_cost"], "savings:", sol["savings_pln"])
for alloc in sol["allocations"]:
    print(f"  {alloc['supplier_name']}: {alloc['allocated_qty']}× @ {alloc['unit_cost']} PLN")

Constraints (C1–C15b)

Buyer · Zamówienia + PO

Buyer/Manager · Zatwierdzanie

Approval thresholds skonfigurowane per tenant (tab Reguły w admin):

curl -X POST $BASE/api/v1/buying/orders/$ORDER_ID/approve \
  -H "Authorization: Bearer $MANAGER_TOKEN"

Supplier · Moje zamówienia

Supplier · Mój katalog (publishing)

Każdy dostawca może publikować swoje produkty bezpośrednio do wspólnego katalogu, widocznego dla wszystkich kupujących.

# Publikacja nowego produktu
new_item = requests.post(f"{BASE}/portal/catalog", headers=headers, json={
    "sku": "TRW-GDB1550",
    "name": "Klocki hamulcowe TRW GDB1550 (przód, VW Golf VII)",
    "price": 189.50,
    "currency": "PLN",
    "unit": "szt",
    "category": "Hamulce",
    "unspsc_code": "25101500",
    "manufacturer": "TRW",
    "ean": "5901234567890",
    "delivery_days": 2,
    "min_order_qty": 1,
    "status": "published"
}).json()
print("Created item id:", new_item["item"]["id"])

# Bulk import z CSV
csv_text = """sku,name,price,unit,unspsc,category
TRW-001,Klocki przód,189.50,szt,25101500,Hamulce
TRW-002,Klocki tył,159.90,szt,25101500,Hamulce"""
result = requests.post(f"{BASE}/portal/catalog/import", headers=headers, json={
    "csv": csv_text
}).json()
print(f"Created: {result['created']}, updated: {result['updated']}, errors: {len(result['errors'])}")

Supplier · Confirm/Reject PO

POST /portal/orders/{order_id}/po/{po_id}/confirm

Potwierdzenie z opcjonalnym scope per linia (partial confirm). confirmed_qty <= quantity.

curl -X POST $BASE/portal/orders/ORD-123/po/PO-001/confirm \
  -H "Authorization: Bearer $TRW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirmed_lines":[{"line_id":"L1","confirmed_qty":50},{"line_id":"L2","confirmed_qty":0}]}'

POST /portal/orders/{order_id}/po/{po_id}/reject

Odrzucenie z opcjonalną kontr-ofertą:

curl -X POST $BASE/portal/orders/ORD-123/po/PO-001/reject \
  -H "Authorization: Bearer $TRW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Brak stanu",
    "counter_offer": {
      "alt_unit_cost": 195.00,
      "alt_qty": 80,
      "alt_delivery_date": "2026-05-15"
    }
  }'

Compliance PL · KSeF (e-faktury 2026)

ksef = requests.post(f"{BASE}/api/v1/buying/ksef/send-invoice",
    headers=headers, json={"invoice_id": 42}).json()
print("KSeF ref:", ksef["ksef_ref"], "status:", ksef["status"])

# Po chwili sprawdź UPO:
import time; time.sleep(2)
status = requests.get(f"{BASE}/api/v1/buying/ksef/status/{ksef['ksef_ref']}",
    headers=headers).json()
if status["status"] == "upo_received":
    print("UPO ID:", status["upo_id"])

FLOW_KSEF_BACKEND

Compliance PL · Biała Lista VAT

Codzienny check przeciwko wl-api.mf.gov.pl. Auto-block PO generation gdy supplier traci VAT czynny.

Compliance PL · Audit + JPK_FA export

Compliance · DECLARE rules

LTL temporal rules nad event log (P2P process). 4 typy:

• existence — aktywność musi się zdarzyć (np. "PO musi mieć confirmation")
• absence — aktywność NIE może się zdarzyć (np. "Brak płatności przed GR")
• response — A → B (np. "PO sent → confirmation w 7 dni")
• precedence — B tylko po A (np. "GR tylko po PO_confirmed")

curl -X POST $BASE/api/v1/compliance/rules \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "rule_id": "PO-CONFIRM-7D",
    "type": "response",
    "activity_a": "PO_sent",
    "activity_b": "PO_confirmed",
    "max_delay_hours": 168
  }'

Admin · 1-click supplier onboarding

POST /admin/onboard-supplier?nip=<10digits>

Pełen profil dostawcy w <30s: VIES + KRS (osint_engine) + Biała Lista VAT + CPI risk score.

curl -X POST "$BASE/admin/onboard-supplier?nip=5260250274" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Response (in <30s):
# {
#   "success": true,
#   "supplier_id": "VND-5260-274",
#   "name": "Inter Cars S.A.",
#   "address": "...",
#   "vat_status": "active",
#   "krs_active": true,
#   "cpi_risk_score": 23,
#   "vat_check_source": "live"
# }

Admin · Catalog import (master)

Master catalog (admin-managed) — distinct od supplier-published catalog. Import z CSV: sku,name,price,category,unit,unspsc,description. Akceptuje ; i , jako delimitery.

Admin · User management

Webhooks (planned 2026 Q3)

ERP push (SAP / Oracle / Workday)

Adaptery z env switch (analogicznie do KSeF):

FLOW_ERP_BACKEND=sap_s4hana            # | oracle_fusion | workday | mock
FLOW_ERP_BASE_URL=https://erp.client.com
FLOW_ERP_OAUTH_CLIENT_ID=...
FLOW_ERP_OAUTH_SECRET=...

Po approval, PO jest pushowany do ERP klienta przez REST. Sync orders → ERP, sync invoices ← ERP.

SDK / klienty

Pomoc i kontakt

📧 [email protected] · 💬 GitHub Issues · 📚 Swagger UI z live tryout