Headless BFF API

One endpoint. Every call is POST to /graphql with header Content-Type: application/json and a body { "query": "...", "variables": { ... } }. The Run buttons below hit the live staging Odoo - edit the body and re-run. Auth calls need Authorization: Bearer <token> - paste a token here after logging in:

Test customer: buyer@example.com / demo1234. Same call as a curl (note the full URL - that's the endpoint for every request):

curl -X POST https://poc.way4tech.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products { variant_id sku availability price_chf } }"}'

Products

products query

Catalog with live stock from Odoo. No parameters.

Request body

product query

One product with its variants.

Param	Type	Notes
`name` required	String	product template name

Request body

Products (Phase 2)

productCard query

Card shape: what the list, hover quick view and drawer preview need. Small, sparse. Has has_variants for the smart "+".

Param	Type	Notes
`slug` required	String	e.g. `hayabusa-t3-boxing-gloves`
`locale`	String	de / fr / it / en (default de)

Request body

productDetail query

Full PDP body: attribute_axes with display_type + html_color per value, all variants, precomputed variant_matrix (combo_key sorted alphabetically by attribute_slug), images, badges.

Param	Type	Notes
`slug` required	String	same as productCard
`locale`	String	de / fr / it / en

Request body

productList query

Cursor-paginated list of cards. next_cursor is opaque; pass it back as cursor for the next page; null on the last page.

Param	Type	Notes
`category_slug`	String	optional filter
`locale`	String	de / fr / it / en
`limit`	Int	default 24
`cursor`	String	from a previous response's `next_cursor`

Request body

Images (Phase 2b)

image pipeline how it works

One binary is stored once. The BFF mints one public URL per locale, each ending in the translated product name, so a FR crawler sees gants-de-boxe.webp and a DE crawler sees boxhandschuhe.webp for the same stored file. imgproxy only ever receives a key, a width and a format, never a language.

URL shape: /img/{base64url(s3_key)}/{width}x{dpr}/{localized-name}.{format}
Rendered pixels are width * dpr. The trailing name is decorative and exists for SEO: the key is authoritative, so renaming a product never breaks an indexed URL. Formats: webp, avif, jpg, png. Responses carry cache-control: immutable.

Field on Image	Type	Notes
`src`	String	resolved for the requested locale
`src_i18n`	I18n	one URL per locale, same binary
`srcset`	[ImageRendition]	1x / 2x / 3x, build `url 1x, url 2x, url 3x`
`alt` / `alt_i18n`	String / I18n	localized alt text
`width` / `height`	Int	intrinsic pixels, reserve the box so CLS stays 0
`is_primary`	Boolean	use this one for `og:image`
`variant_id`	Int	null = template level, else the variant it belongs to
`placeholder_url`	String	show while the rendition loads
`s3_key`	String	neutral key, no language in it

Live renditions of one binary (open in a new tab)

512 @1x, DE filename, webp
512 @2x, FR filename, webp
512 @3x, IT filename, webp
256 @1x, EN filename, avif

All four are the same stored binary. Only the transform and the filename differ.

productDetail images query

The image array on a product, with the localized URLs and the retina ladder. Needs Odoo up.

Request body

Cart

addToCart mutation

Adds a variant. First add (no cart_token) starts a guest cart = a draft sale.order in Odoo. Blocked if over stock.

Param	Type	Notes
`variant_id` required	Int	from `products`
`qty`	Float	default 1
`cart_token`	String	omit to start a new cart; pass to add to an existing one

Request body

cart query

Read a cart by its token.

Param	Type	Notes
`cart_token` required	String	from `addToCart`

Request body

Auth

login mutation

Portal (res.users) authentication. Returns a stateless JWT. Pass a guest cart token to merge it into the customer on login.

Param	Type	Notes
`email` required	String	portal login
`password` required	String	wrong password → `AUTH_INVALID_CREDENTIALS`
`guest_cart_token`	String	optional - merges that cart

Request body

checkEmail query

Fluid Auth step 1 - enter email first. If it exists, show the password field (Login); if new, expand Registration.

Param	Type	Notes
`email` required	String	returns `{ email, exists }` - one fast Odoo lookup

Request body

register mutation

Fluid Auth - new email path: creates the portal customer and logs them straight in (returns a Session, same shape as login).

Param	Type	Notes
`email` required	String	the new login
`password` required	String
`name` required	String	display name
`guest_cart_token`	String	optional - merges the guest cart into the new account

Request body

mergeGuestCart mutation needs token

Explicit guest → customer merge. Requires the JWT in the box at the top (auto-filled after Login).

Param	Type	Notes
`guest_cart_token` required	String	the guest cart to fold in

Request body

Types

Type	Fields
`Variant`	variant_id Int, sku String, name String, price_chf Float, free_qty Float, availability String (in_stock / low_stock / out_of_stock)
`Cart`	cart_token String, order_id Int, partner_id Int, state String (guest / active / merged / converted), currency String, lines [CartLine], subtotal_chf / tax_chf / total_chf Float
`CartLine`	line_id Int, variant_id Int, name String, qty Float, unit_price_chf Float, subtotal_chf Float
`Session`	token String (JWT), partner_id Int, display_name String, cart Cart

Errors

Failures return { "errors": [...] } with extensions.code from a fixed set and a translated extensions.user_message { de, fr, it, en }. Switch on code, never on the text.

code	when
`CART_STOCK_INSUFFICIENT`	ordering more than available stock
`CART_VARIANT_UNAVAILABLE`	variant archived / inactive
`AUTH_INVALID_CREDENTIALS`	wrong email or password
`ODOO_ACCESS_DENIED`	the integration user lacks rights on a model
`ODOO_UNAVAILABLE`	Odoo is down or unreachable. `retryable: true`, so show a retry rather than a hard error
`INTERNAL`	anything unmapped