Piitel API

Base URL: https://api.ronniri.com

Piitel catalog and product details, normal guest carts, account login/readers and selected bundle cart operations are live verified. Search uses search=raspberry, page=1 and per_page=100 (maximum 100). Read all pages for all matching results. Catalog price strings are minor currency units; use currency_minor_unit to scale them. Product details include images, descriptions, stock and options. Null stock means unknown. For bundles use component variants and quote the selected total, then use a classic cart.

Authentication and credential choices

RonNiri API: authentication and accounts

The Copy to agent button at /docs copies the complete Markdown reference: shared guidance and every service section. On /docs/:service, it copies that service's reference and its shared authentication guidance only. The full export is also available at /docs/index.md; individual exports use /docs/:service.md.

Base URL: https://api.ronniri.com. Local default: http://localhost:3000.

Two ways to supply service credentials

Every service request needs gateway authorization: X-API-Key: rni_... or Authorization: Bearer rni_.... A browser signed in to the console can also call APIs with its HttpOnly session cookie and CSRF token for writes. Registration alone cannot access the service. Keys belong to approved users, including the admin. An optional deployment-wide API_KEY enables direct requests without creating a user account; treat it as a root secret. It cannot access any user's saved credentials or management endpoints.

1. Inline credentials: send provider credentials in a JSON POST body over HTTPS. They are used for the upstream operation and are not saved in MongoDB. Never put passwords or keys in query strings. No extra client-side encoding replaces HTTPS. Configure proxies and clients not to log request bodies or authorization headers.
2. Saved credentials: sign in, save credentials in the console, then send useSavedCredentials: true with a user API key. The server decrypts only the caller's service credentials. Passwords are never returned by the credential-list endpoint. Credentials are encrypted with AES-256-GCM, bound to the user and service. Back up the encryption key separately from the database.

Inline PADI request

POST /padi/certifications
X-API-Key: YOUR_GATEWAY_KEY
Content-Type: application/json

{"email":"[email protected]","password":"YOUR_PADI_PASSWORD","raw":false}

PADI uses email as the username field. Stateless calls clear their in-memory provider client after the response. To reuse login, POST the same email/password to /padi/sessions, then use its sessionId in X-Session-Id on GET /padi/certifications, GET /padi/credentials, GET /padi/session, POST /padi/sessions/refresh, and DELETE /padi/sessions.

Saved PADI request

Save {"email":"[email protected]","password":"..."} with PUT /auth/credentials/padi, then:

POST /padi/certifications
X-API-Key: YOUR_USER_KEY
Content-Type: application/json

{"useSavedCredentials":true,"raw":false}

The same flag works on POST /padi/sessions, POST /padi/credentials, POST /lifesavingSociety/lookup and POST /piitel/login. Do not mix saved and inline credential fields. Piitel login requires an existing Piitel X-Session-Id; create it with POST /piitel/sessions first.

One-request wrapper

POST /:service/request accepts method (default GET), path (service-relative, no query string), query object, body object, and either credentials or useSavedCredentials:true. It dispatches only an existing service endpoint and enforces that endpoint's key permission. It cannot invoke account/admin routes or session/login routes. Query values follow the target endpoint's rules. Responses are wrapped in { "data": ... }.

{
  "method": "GET",
  "path": "/orders",
  "useSavedCredentials": true
}

Send this to /piitel/request with a key containing piitel:account:login and piitel:orders:read. For inline Piitel login replace the flag with "credentials":{"username":"[email protected]","password":"..."}. For PADI, POST /padi/request with method:"POST", path:"/certifications", credentials {email,password}, and optional body:{raw:true}. Lifesaving credentials are {identifier}; AliExpress buyer credentials are {accessToken}. KSP/Amazon account login is unsupported.

Provider sessions created by the wrapper are discarded after the operation by default. Set keepSession:true to return sessionId and expiresAt for follow-up cart/session operations; this additionally requires that service's sessions:manage permission. Set sessionId instead of credentials to reuse a session. Piitel supports cartMode:"classic" for bundles. Discarding a local session does not undo an upstream action: a Piitel account cart change persists at the store. Check state before retrying an uncertain mutation.

Account lifecycle

On the first successful database initialization, the server creates admin username admin, generates a random password and prints it once to server logs. Sign in and change it before using APIs or creating keys. This is an ordinary user account with an additional admin role; its saved provider credentials are private to it. Startup does not reset an existing admin or reprint its password.

POST /auth/register with {username,password} creates a pending registration request, not an active user. Passwords must be 8–256 characters. Usernames are normalized to lowercase, 3–64 characters, using letters, digits, dots, dashes and underscores. The admin approves/rejects requests in the console. Pending and rejected applicants cannot sign in, save credentials, or create keys. There is no automatic approval. Admin can disable approved users; disabling invalidates access immediately. Re-enabling requires new login and keys.

POST /auth/login accepts {username,password} and sets an 8-hour HttpOnly, SameSite=Strict cookie (Secure in production). Response includes user and csrfToken. GET /auth/me returns the current user and CSRF token. All authenticated browser writes require X-CSRF-Token. Account management accepts browser sessions only; even a root API key cannot approve users or manage accounts.

PATCH /auth/profile accepts currentPassword, optional username and optional password. Changing profile requires the current password and invalidates existing browser sessions and API keys. Initial admin login requires a new password. POST /auth/logout invalidates the current browser session.

API keys and permissions

POST /auth/keys: {name,scopes,expiresAt?} creates a key and returns the plaintext key exactly once. MongoDB stores only its SHA-256 hash and display prefix. GET /auth/keys lists metadata; DELETE /auth/keys/:id revokes one. Optional expiresAt is an ISO future timestamp. Maximum 50 unrevoked keys per user. Revocation, user disablement and password/profile changes are checked on every request.

GET /auth/permissions lists the current service permissions. Scope syntax is service:resource:action, for example piitel:catalog:read, piitel:cart:write, padi:certifications:read. A key may include several services and permissions. root grants all current and future service API permissions, not administrator account-management access. No scopes are granted by omission. A write permission does not imply read; select both if needed. Session creation/refresh/deletion requires sessions:manage. Checkout submission has its own checkout:submit permission. The wrapper checks its target and any login/session permission it needs. Each service documentation page lists the exact permission for every registered route.

GET /capabilities reports adapter support and verification state. Provider session IDs are random, scoped by service and owned by the authenticated user (or the legacy direct key). They cannot be reused across users. Users may use their own session across their own keys only if each key has the requested permission. Local provider sessions expire after 30 minutes idle and are lost on restart. Account data, keys and saved credentials persist in MongoDB.

Saved credential management

GET /auth/credentials returns configured services and update timestamps, never plaintext secrets. PUT /auth/credentials/:service replaces credentials; DELETE removes them. Supported schemas:

Administrator endpoints

All require an admin browser session, completed initial password change, and CSRF on writes.

Request security and errors

Production requires HTTPS, a configured PUBLIC_URL and the trusted Coolify reverse proxy. Do not expose the Node port directly to the internet. The app never logs request bodies, keys or saved provider passwords. The initial admin password is intentionally printed once as requested; rotate it immediately and restrict log access. Account passwords use salted scrypt (N=131072,r=8,p=1). Login/registration attempts are rate-limited, and concurrent password hashing is bounded.

Common errors: 400 INVALID_INPUT/JSON_REQUIRED, 401 UNAUTHORIZED/SESSION_EXPIRED, 403 FORBIDDEN/ADMIN_REQUIRED/CSRF_REQUIRED/SESSION_FORBIDDEN/PASSWORD_CHANGE_REQUIRED, 409 USERNAME_UNAVAILABLE/SESSION_BUSY, 429 RATE_LIMITED, 503 BUSY. Errors have {code,error,details?}. Provider errors preserve their existing codes. Keys and credentials belong in headers/JSON bodies, not URL query parameters. No live payment validation has been performed.

Every registered endpoint

Piitel

curl 'https://api.ronniri.com/piitel/products?search=raspberry&per_page=10' \
  -H 'X-API-Key: YOUR_KEY'

curl 'https://api.ronniri.com/piitel/sessions' -X POST \
  -H 'X-API-Key: YOUR_KEY' -H 'Content-Type: application/json' -d '{}'

# Copy sessionId from the previous response; id is the product or variation ID.
curl 'https://api.ronniri.com/piitel/cart/items' -X POST \
  -H 'X-API-Key: YOUR_KEY' -H 'X-Session-Id: YOUR_SESSION_ID' \
  -H 'Content-Type: application/json' -d '{"id":102128,"quantity":1}'

Product list responses are {items,total,totalPages}. Price strings are minor currency units, with the scale provided by currency_minor_unit: "6000" with scale 2 means ₪60.00. Raw issuer fields are retained. stock.inStock is current upstream availability; exact warehouse counts are not necessarily public.

Filters are validated per resource against the site's registered schema. Reviews accept product_id, category_id, page, per_page, offset, order, orderby; the attributes list accepts no filters. Arrays such as include, exclude, parent, stock_status and rating accept comma-separated values or JSON arrays. Structured attributes filters accept a JSON array, for example [{"attribute":"pa_color","slug":["black"],"operator":"in"}]; the server encodes the upstream PHP bracket parameters. Product queries also support category/brand/tag operators, date bounds and parent exclusions. calculate_attribute_counts accepts [{"taxonomy":"pa_color","query_type":"or"}]. Unknown filters and invalid enums return 400 instead of being silently ignored.

For variants, request /piitel/products/:id/variations or /piitel/products?type=variation&parent=<productId>. Add the variation ID and, when required, its attribute/value pairs. YITH product details now include component options, discounted prices, images, descriptions and stock under bundle. Configured bundle add/read/update/remove and price quotes are covered in the bundle guide. Arbitrary third-party add-ons and nested bundles remain unsupported.

Live verified: search, product detail/by-slug, stock filters, category detail, attribute terms, product review filtering, collection price/stock/rating counts, variation listing and addition, guest-cart create/read/add/update/remove, two-cart isolation, shipping-rate selection, invalid-coupon rejection, and isolated guest wishlist read/add/remove. Account login, authenticated cart read, dashboard, order list/detail, saved-address reading, authenticated wishlist reading and local session deletion were also verified through the shared HTTP API using the authorized account. Wishlist changes fetch fresh YITH action nonces and verify the resulting list; cookies and wishlist tokens remain private. Account wishlist pagination, valid coupon redemption, address changes and checkout drafts still require live validation. Invalid coupon/stock/address responses remain upstream errors.

Opening https://piitel.co.il/checkout/ does not transfer this API cart. For Store API carts, a live same-cookie classic checkout request redirected to the empty cart: Cart-Token context is required. Use the Store API checkout routes described in checkout integration. Native configured-bundle carts support add/read/update/remove, but their checkout is unfinished and explicitly rejected. Prepare/update/submit routes have deterministic contract tests, but no real order/payment has been attempted. The gocredit_payment fields and any interactive payment handoff still need live merchant/test-environment validation. Treat an uncertain submission as potentially accepted; inspect orders before retrying.

Piitel product options and bundles

Product details preserve gallery/preview image URLs, HTML descriptions, prices and normalized stock. For normal variable products, get priced variation records using GET /piitel/products/:id/variations?page=1&per_page=100, then add the chosen variation's product ID.

YITH bundles need extra page data and a native cart context: Piitel's Store API cart returns a server error for bundles. The implementation uses ordinary HTTP forms and cookies, with no browser process.

Read options

GET /piitel/products/78436 returns normal product fields plus bundle:

• items: component itemId, product ID, name, description HTML, image, quantity limits and optional flag.
• items[].attributes: dropdown labels/options and values; absent matching variations are explicit, not labelled definitely out of stock.
• items[].variants: variation IDs, attribute combinations, discounted/regular prices, images, descriptions, stock and purchasability, plus raw upstream fields.
• defaultSelections: IDs matching the page's selected defaults, when available.
• complete: false for deferred variation loading or unsupported nested configuration.

Price strings are minor currency units: "129270" with scale 2 means ₪1,292.70. The parent catalog price is a base value and can differ from a selected total. Components may have their own descriptions when the bundle parent description is empty.

Quote and add selected options

Use IDs from fresh product details. For example, this checked configuration selects 16GB RAM, Red/White case, white power supply and white 1m HDMI cable; the fixed microSD component is included automatically:

{
  "1": { "variationId": 88877 },
  "2": { "variationId": 77925 },
  "3": { "variationId": 77932 },
  "5": { "variationId": 23516 }
}

Send that map as selections to POST /piitel/products/78436/quote. This calls the page's read-only pricing action with fresh session-bound nonce data; it does not add to cart. The response has the selected price, currency/scale and price HTML. Each selection may also specify a component quantity within its limits or included for optional components.

Create a cart with POST /piitel/sessions:

{"cartMode":"classic"}

Then POST /piitel/cart/items with the returned X-Session-Id:

{
  "id": 78436,
  "quantity": 1,
  "bundleSelections": {
    "1": { "variationId": 88877 },
    "2": { "variationId": 77925 },
    "3": { "variationId": 77932 },
    "5": { "variationId": 23516 }
  }
}

All requests require X-API-Key. JSON POST/PATCH bodies require Content-Type: application/json.

The adapter validates that variations belong to their components, derives matching form attributes, submits the native form and confirms the cart increase. Missing selections, unavailable variations and unknown IDs are rejected before submission. A bundle without bundleSelections is rejected before reaching the broken Store API add path.

GET /piitel/cart, PATCH /piitel/cart/items/:key and DELETE /piitel/cart/items/:key work in native mode. Responses include cartMode: "classic", item keys/quantities, images, minor-unit totals and submitted bundleConfiguration metadata. That metadata is labelled submitted-product-form; Piitel does not echo every selected ID in its cart HTML. Existing native cart lines may lack structured component IDs.

An empty default Store API cart can switch to native mode when adding a configured bundle. A nonempty Store API cart is never silently moved/replaced: start with an explicit classic session for a cart that will contain bundles. Native mode can also add simple products or selected variation IDs; use a variation ID instead of a parent variable ID.

Limitation: Store API coupon/shipping/customer operations and checkout cannot process native bundle carts. They return context errors. Native bundle checkout/payment, arbitrary third-party add-ons and nested bundle configuration remain unfinished. A separate browser does not automatically inherit the server's cookies.

Verification

Live verified on 2026-10-20: the starter kit returned five components with option prices/images/stock and component descriptions. A 16GB configuration quoted ₪1,488, matched the cart unit price, was updated to quantity 2 and removed. An HTTP API test then added two configurations differing only in case colour, confirmed separate cart keys, read both and removed them. No order/payment was submitted; authenticated customer data was not used for these mutation tests.

Piitel checkout

These routes use the same private Cart-Token and X-Session-Id as the cart APIs. They implement the site's registered Store API contract. Checkout submission and payment have not been validated against a real order or test merchant environment.

Update accepts billing_address, shipping_address, payment_method, customer_note, order_notes, additional_fields, extensions and create_account. Submit accepts the same fields except order_notes, plus payment_data and customer_password. Submit requires a billing-address object and payment-method identifier; the upstream applies store-specific required fields, stock checks and gateway validation.

Address fields are first_name, last_name, company, address_1, address_2, city, state, postcode, country, phone; billing also accepts email. All address values are strings. Country codes use uppercase ISO alpha-2. Get the offered payment identifiers and shipping rates from /piitel/cart, and select shipping through /piitel/cart/shipping before submitting.

Example draft update:

{
  "customer_note": "Pickup preferred",
  "payment_method": "gocredit_payment"
}

payment_data is an array of { "key": "gateway-specific-name", "value": "gateway-specific-value" }; values may also be booleans. The correct GoCredit fields/tokenization flow are still unverified. Do not assume another gateway's token fields apply. Optional customer_password is preserved verbatim when account creation is requested.

Responses preserve the upstream order ID, order status, addresses and payment_result. A payment status of pending/failed is retained; an HTTP 200 alone does not prove successful payment. payment_result.redirect_url may point to an interactive gateway; the server returns it without following it. A browser opened at the store's normal checkout URL does not inherit this cart.

Mutations are never automatically retried. On timeout or an invalid submission response, an order may already exist. Inspect your account orders before retrying; don't repeatedly submit the same payment. An upstream response still marked checkout-draft produces PIITEL_CHECKOUT_INCOMPLETE rather than claiming submission succeeded.

Evidence: Piitel's registered route index exposes checkout GET, POST and PUT/PATCH contracts. WooCommerce's Checkout API documentation distinguishes draft reads, PUT updates and POST order/payment processing. Gateway-specific payment data requires separate validation. The newer expected_total field in WooCommerce documentation was absent from Piitel's inspected route schema and is not advertised by this adapter.

Complete catalog filter reference

For URL requests, encode structured arrays as JSON strings. The request wrapper also accepts JSON arrays/objects directly. Unknown fields are rejected.

products

terms

categories

brands

tags

attributes

reviews

collection