Referência da API

Campo	Tipo	Descrição
idObrigatório	string	Product id.
titleObrigatório	string	Title.
handleObrigatório	string	URL slug (set on creation, never changes).
statusObrigatório	string	active (on sale), draft or archived. Valores:`activedraftarchived`
descriptionObrigatório	string	Plain-text description (line breaks kept; HTML is not rendered).
category_idObrigatório	string \| null	Primary category id.
brandObrigatório	string \| null	Brand.
tagsObrigatório	string[]	Tags.
fiscalObrigatório	object
ncmObrigatório	string \| null	NCM, 8 digits, or null when not informed (optional; required only when the store issues the NF-e itself). `^\d{8}$`
cestObrigatório	string \| null	CEST, 7 digits.
originObrigatório	integer	Origem da mercadoria (0–8). 0 a 8
weight_gramsObrigatório	integer	Shipping weight in grams. ≥ 0
dimensions_cmObrigatório	object	Package dimensions in cm.
lengthObrigatório	number
widthObrigatório	number
heightObrigatório	number
imagesObrigatório	object[]	Gallery, first = main image. Images sent by apps are copied into the store's media library shortly after the write, so the URLs change to the store's own.
urlObrigatório	string	Absolute image URL.
altObrigatório	string \| null	Alt text.
wholesaleObrigatório	→ Wholesale \| null	Wholesale pricing, or null when the product has none.
packagingsObrigatório	→ Packaging[]	Sales packages (up to 4); empty when sold by the piece only.
packaging_onlyObrigatório	boolean	True when the product is sold only in packages (no loose pieces).
variantsObrigatório	→ Variant[]	Variants (at least one).
created_atObrigatório	string (date-time)	Creation time.
updated_atObrigatório	string (date-time)	Last change of product data (not stock).

Exemplo

json

{
  "id": "p_gan_65w",
  "title": "Carregador GaN 65W 3 Portas",
  "handle": "carregador-gan-65w-3-portas",
  "status": "active",
  "description": "Tecnologia GaN, 2 portas USB-C + 1 USB-A.",
  "category_id": "cat_chargers",
  "brand": "Volt",
  "tags": [
    "gan",
    "notebook",
    "anatel"
  ],
  "fiscal": {
    "ncm": "85044010",
    "cest": null,
    "origin": 2
  },
  "weight_grams": 140,
  "dimensions_cm": {
    "length": 9,
    "width": 6,
    "height": 4
  },
  "images": [],
  "variants": [
    {
      "id": "p_gan_65w_v1",
      "product_id": "p_gan_65w",
      "sku": "VLT-GAN65W",
      "title": "Padrão",
      "options": {},
      "price": 17990,
      "compare_at_price": 21990,
      "gtin": "7891035631000",
      "inventory": {
        "on_hand": 42,
        "reserved": 1,
        "available": 41
      }
    }
  ],
  "wholesale": {
    "enabled": true,
    "tiers": [
      {
        "min_qty": 12,
        "unit_price": 15990
      },
      {
        "min_qty": 48,
        "unit_price": 14990
      }
    ],
    "min_qty": null,
    "multiple": null,
    "packs": []
  },
  "packagings": [
    {
      "id": "pkg_caixa12",
      "unit": "caixa",
      "label": null,
      "name": "Caixa c/ 12",
      "pieces": 12,
      "unit_price": 15490,
      "tiers": [],
      "fill": "single",
      "axis": null,
      "wholesale_only": false
    }
  ],
  "packaging_only": false,
  "created_at": "2026-09-13T15:00:00.000Z",
  "updated_at": "2026-10-18T15:00:00.000Z"
}

curl · getProduct

curl "https://api.tfshop.cloud/v1/products/p_gan_65w" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

POST/products

Create a product

products:writeAceita Idempotency-KeycreateProduct

SKUs must be unique in the store. NCM is optional, but must have 8 digits when sent. Send an Idempotency-Key header to retry safely (only 2xx responses are stored; after fixing an error, retry with the same key).

Pode publicarproduct.created inventory.updated

Corpo da requisição

Campo	Tipo	Descrição
titleObrigatório	string	Title. máx. 150
description	string	Plain-text description (line breaks kept; HTML tags are stripped). máx. 10000
status	string	Default draft. Valores:`activedraftarchived`
category_id	string \| null	Category id of the store.
brand	string \| null	Brand.
tags	string[]	Tags.
fiscal	object
ncm	string \| null	NCM, 8 digits (optional). `^\d{8}$`
cest	string \| null	CEST, 7 digits.
origin	integer	Origem (0–8). 0 a 8
weight_grams	integer	Weight in grams. ≥ 0
dimensions_cm	object
length	number
width	number
height	number
images	object[]	Gallery.
urlObrigatório	string (uri)	HTTPS image URL.
alt	string \| null	Alt text.
wholesale	object \| null	Replaces the whole wholesale configuration when sent; null removes it.
enabled	boolean	Default true when tiers are sent.
tiers	object[]	Up to 5 tiers: min_qty ascending, unit_price descending. máx. 5
min_qtyObrigatório	integer	Pieces (2 or more). ≥ 2
unit_priceObrigatório	integer	Per-piece price in centavos (> 0). ≥ 1
min_qty	integer \| null	MOQ in pieces, or null. ≥ 1
multiple	integer \| null	Sold in multiples of this many pieces, or null. ≥ 2
packs	object[]	Fixed size packs; omit to keep the current ones.
id	string	Keep an existing pack by sending its id.
name	string	Name.
axisObrigatório	string	Option name of the product ("Tamanho").
compositionObrigatório	map<integer>	Pieces per option value.
packagings	object[]	Replaces the whole package list when sent (up to 4); [] removes every package. Packages the app does not send are removed, so send the current ones (with their ids) along with new ones. máx. 4
id	string	Keep an existing package by sending its id (order lines reference it); omit for a new one.
unitObrigatório	string	Kind of package. Valores:`duziameia_duziacaixapacotefardodisplaykitoutro`
label	string \| null	Own name; required for unit "outro". máx. 60
piecesObrigatório	integer	Pieces per package (dúzia = 12, meia dúzia = 6). 2 a 10000
unit_price	integer \| null	Per-piece price in centavos, or null for the product's usual price. ≥ 1
tiers	object[]	Up to 3 tiers (need unit_price): min_packages ascending, unit_price descending. máx. 3
min_packagesObrigatório	integer	Packages (2 or more). ≥ 2
unit_priceObrigatório	integer	Per-piece price in centavos. ≥ 1
fill	string	single (default), mix or assorted. Valores:`singlemixassorted`
axis	string \| null	mix / assorted: option name whose values are mixed; null = all variants.
wholesale_only	boolean	Only for buyers with wholesale prices (default false).
packaging_only	boolean	Sell only in packages (needs at least one package).
variantsObrigatório	object[]	Variants (1–100). máx. 100
skuObrigatório	string	SKU, unique in the store. máx. 60
title	string	Variant title; defaults to the option values joined by " / ".
options	map<string>	Option values ({"Cor": "Preto"}).
priceObrigatório	integer	Retail price in centavos (> 0). ≥ 1
compare_at_price	integer \| null	"De" price in centavos, above price. ≥ 1
gtin	string \| null	GTIN/EAN (8, 12, 13 or 14 digits).
image_url	string \| null (uri)	Photo of this variant: public HTTPS URL (added to the gallery when missing).
on_hand	integer	Initial stock (on update: sets the stock when sent, otherwise kept). ≥ 0

Resposta 201

Campo	Tipo	Descrição
idObrigatório	string	Product id.
titleObrigatório	string	Title.
handleObrigatório	string	URL slug (set on creation, never changes).
statusObrigatório	string	active (on sale), draft or archived. Valores:`activedraftarchived`
descriptionObrigatório	string	Plain-text description (line breaks kept; HTML is not rendered).
category_idObrigatório	string \| null	Primary category id.
brandObrigatório	string \| null	Brand.
tagsObrigatório	string[]	Tags.
fiscalObrigatório	object
ncmObrigatório	string \| null	NCM, 8 digits, or null when not informed (optional; required only when the store issues the NF-e itself). `^\d{8}$`
cestObrigatório	string \| null	CEST, 7 digits.
originObrigatório	integer	Origem da mercadoria (0–8). 0 a 8
weight_gramsObrigatório	integer	Shipping weight in grams. ≥ 0
dimensions_cmObrigatório	object	Package dimensions in cm.
lengthObrigatório	number
widthObrigatório	number
heightObrigatório	number
imagesObrigatório	object[]	Gallery, first = main image. Images sent by apps are copied into the store's media library shortly after the write, so the URLs change to the store's own.
urlObrigatório	string	Absolute image URL.
altObrigatório	string \| null	Alt text.
wholesaleObrigatório	→ Wholesale \| null	Wholesale pricing, or null when the product has none.
packagingsObrigatório	→ Packaging[]	Sales packages (up to 4); empty when sold by the piece only.
packaging_onlyObrigatório	boolean	True when the product is sold only in packages (no loose pieces).
variantsObrigatório	→ Variant[]	Variants (at least one).
created_atObrigatório	string (date-time)	Creation time.
updated_atObrigatório	string (date-time)	Last change of product data (not stock).

Exemplo

json

{
  "id": "p_gan_65w",
  "title": "Carregador GaN 65W 3 Portas",
  "handle": "carregador-gan-65w-3-portas",
  "status": "active",
  "description": "Tecnologia GaN, 2 portas USB-C + 1 USB-A.",
  "category_id": "cat_chargers",
  "brand": "Volt",
  "tags": [
    "gan",
    "notebook",
    "anatel"
  ],
  "fiscal": {
    "ncm": "85044010",
    "cest": null,
    "origin": 2
  },
  "weight_grams": 140,
  "dimensions_cm": {
    "length": 9,
    "width": 6,
    "height": 4
  },
  "images": [],
  "variants": [
    {
      "id": "p_gan_65w_v1",
      "product_id": "p_gan_65w",
      "sku": "VLT-GAN65W",
      "title": "Padrão",
      "options": {},
      "price": 17990,
      "compare_at_price": 21990,
      "gtin": "7891035631000",
      "inventory": {
        "on_hand": 42,
        "reserved": 1,
        "available": 41
      }
    }
  ],
  "wholesale": {
    "enabled": true,
    "tiers": [
      {
        "min_qty": 12,
        "unit_price": 15990
      },
      {
        "min_qty": 48,
        "unit_price": 14990
      }
    ],
    "min_qty": null,
    "multiple": null,
    "packs": []
  },
  "packagings": [
    {
      "id": "pkg_caixa12",
      "unit": "caixa",
      "label": null,
      "name": "Caixa c/ 12",
      "pieces": 12,
      "unit_price": 15490,
      "tiers": [],
      "fill": "single",
      "axis": null,
      "wholesale_only": false
    }
  ],
  "packaging_only": false,
  "created_at": "2026-09-13T15:00:00.000Z",
  "updated_at": "2026-10-18T15:00:00.000Z"
}

curl · createProduct

curl -X POST "https://api.tfshop.cloud/v1/products" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "title": "Cabo USB-C 240W 2 m",
    "description": "Cabo de nylon trançado, 240 W, 40 Gbps.",
    "status": "draft",
    "brand": "Volt",
    "fiscal": {
      "ncm": "85444200",
      "origin": 2
    },
    "weight_grams": 60,
    "dimensions_cm": {
      "length": 12,
      "width": 8,
      "height": 2
    },
    "variants": [
      {
        "sku": "VLT-C240-2M",
        "price": 8990,
        "gtin": "7891000123457",
        "on_hand": 30
      }
    ]
  }'

PATCH/products/{product_id}

Update a product (fields, images and, when sent, the variant set)

products:writeupdateProduct

Variants are matched by SKU: existing ones keep their id and reserved units; new SKUs are created; SKUs left out of a sent variants array are removed. on_hand changes stock only when sent.

Pode publicarproduct.updated inventory.updated

Parâmetros

Campo	Tipo	Descrição
product_idcaminhoObrigatório	string	Product id.

Corpo da requisição

Campo	Tipo	Descrição
title	string	Title. máx. 150
description	string	Plain-text description (line breaks kept; HTML tags are stripped). máx. 10000
status	string	Default draft. Valores:`activedraftarchived`
category_id	string \| null	Category id of the store.
brand	string \| null	Brand.
tags	string[]	Tags.
fiscal	object
ncm	string \| null	NCM, 8 digits (optional). `^\d{8}$`
cest	string \| null	CEST, 7 digits.
origin	integer	Origem (0–8). 0 a 8
weight_grams	integer	Weight in grams. ≥ 0
dimensions_cm	object
length	number
width	number
height	number
images	object[]	Gallery.
urlObrigatório	string (uri)	HTTPS image URL.
alt	string \| null	Alt text.
wholesale	object \| null	Replaces the whole wholesale configuration when sent; null removes it.
enabled	boolean	Default true when tiers are sent.
tiers	object[]	Up to 5 tiers: min_qty ascending, unit_price descending. máx. 5
min_qtyObrigatório	integer	Pieces (2 or more). ≥ 2
unit_priceObrigatório	integer	Per-piece price in centavos (> 0). ≥ 1
min_qty	integer \| null	MOQ in pieces, or null. ≥ 1
multiple	integer \| null	Sold in multiples of this many pieces, or null. ≥ 2
packs	object[]	Fixed size packs; omit to keep the current ones.
id	string	Keep an existing pack by sending its id.
name	string	Name.
axisObrigatório	string	Option name of the product ("Tamanho").
compositionObrigatório	map<integer>	Pieces per option value.
packagings	object[]	Replaces the whole package list when sent (up to 4); [] removes every package. Packages the app does not send are removed, so send the current ones (with their ids) along with new ones. máx. 4
id	string	Keep an existing package by sending its id (order lines reference it); omit for a new one.
unitObrigatório	string	Kind of package. Valores:`duziameia_duziacaixapacotefardodisplaykitoutro`
label	string \| null	Own name; required for unit "outro". máx. 60
piecesObrigatório	integer	Pieces per package (dúzia = 12, meia dúzia = 6). 2 a 10000
unit_price	integer \| null	Per-piece price in centavos, or null for the product's usual price. ≥ 1
tiers	object[]	Up to 3 tiers (need unit_price): min_packages ascending, unit_price descending. máx. 3
min_packagesObrigatório	integer	Packages (2 or more). ≥ 2
unit_priceObrigatório	integer	Per-piece price in centavos. ≥ 1
fill	string	single (default), mix or assorted. Valores:`singlemixassorted`
axis	string \| null	mix / assorted: option name whose values are mixed; null = all variants.
wholesale_only	boolean	Only for buyers with wholesale prices (default false).
packaging_only	boolean	Sell only in packages (needs at least one package).
variants	object[]	When sent, the full variant set: matched by SKU, existing variants keep their id and reserved units, new SKUs are added, SKUs left out are removed. máx. 100
skuObrigatório	string	SKU, unique in the store. máx. 60
title	string	Variant title; defaults to the option values joined by " / ".
options	map<string>	Option values ({"Cor": "Preto"}).
priceObrigatório	integer	Retail price in centavos (> 0). ≥ 1
compare_at_price	integer \| null	"De" price in centavos, above price. ≥ 1
gtin	string \| null	GTIN/EAN (8, 12, 13 or 14 digits).
image_url	string \| null (uri)	Photo of this variant: public HTTPS URL (added to the gallery when missing).
on_hand	integer	Initial stock (on update: sets the stock when sent, otherwise kept). ≥ 0

Resposta 200

Campo	Tipo	Descrição
idObrigatório	string	Product id.
titleObrigatório	string	Title.
handleObrigatório	string	URL slug (set on creation, never changes).
statusObrigatório	string	active (on sale), draft or archived. Valores:`activedraftarchived`
descriptionObrigatório	string	Plain-text description (line breaks kept; HTML is not rendered).
category_idObrigatório	string \| null	Primary category id.
brandObrigatório	string \| null	Brand.
tagsObrigatório	string[]	Tags.
fiscalObrigatório	object
ncmObrigatório	string \| null	NCM, 8 digits, or null when not informed (optional; required only when the store issues the NF-e itself). `^\d{8}$`
cestObrigatório	string \| null	CEST, 7 digits.
originObrigatório	integer	Origem da mercadoria (0–8). 0 a 8
weight_gramsObrigatório	integer	Shipping weight in grams. ≥ 0
dimensions_cmObrigatório	object	Package dimensions in cm.
lengthObrigatório	number
widthObrigatório	number
heightObrigatório	number
imagesObrigatório	object[]	Gallery, first = main image. Images sent by apps are copied into the store's media library shortly after the write, so the URLs change to the store's own.
urlObrigatório	string	Absolute image URL.
altObrigatório	string \| null	Alt text.
wholesaleObrigatório	→ Wholesale \| null	Wholesale pricing, or null when the product has none.
packagingsObrigatório	→ Packaging[]	Sales packages (up to 4); empty when sold by the piece only.
packaging_onlyObrigatório	boolean	True when the product is sold only in packages (no loose pieces).
variantsObrigatório	→ Variant[]	Variants (at least one).
created_atObrigatório	string (date-time)	Creation time.
updated_atObrigatório	string (date-time)	Last change of product data (not stock).

Exemplo

json

{
  "id": "p_gan_65w",
  "title": "Carregador GaN 65W 3 Portas",
  "handle": "carregador-gan-65w-3-portas",
  "status": "active",
  "description": "Tecnologia GaN, 2 portas USB-C + 1 USB-A.",
  "category_id": "cat_chargers",
  "brand": "Volt",
  "tags": [
    "gan",
    "notebook",
    "anatel"
  ],
  "fiscal": {
    "ncm": "85044010",
    "cest": null,
    "origin": 2
  },
  "weight_grams": 140,
  "dimensions_cm": {
    "length": 9,
    "width": 6,
    "height": 4
  },
  "images": [],
  "variants": [
    {
      "id": "p_gan_65w_v1",
      "product_id": "p_gan_65w",
      "sku": "VLT-GAN65W",
      "title": "Padrão",
      "options": {},
      "price": 17990,
      "compare_at_price": 21990,
      "gtin": "7891035631000",
      "inventory": {
        "on_hand": 42,
        "reserved": 1,
        "available": 41
      }
    }
  ],
  "wholesale": {
    "enabled": true,
    "tiers": [
      {
        "min_qty": 12,
        "unit_price": 15990
      },
      {
        "min_qty": 48,
        "unit_price": 14990
      }
    ],
    "min_qty": null,
    "multiple": null,
    "packs": []
  },
  "packagings": [
    {
      "id": "pkg_caixa12",
      "unit": "caixa",
      "label": null,
      "name": "Caixa c/ 12",
      "pieces": 12,
      "unit_price": 15490,
      "tiers": [],
      "fill": "single",
      "axis": null,
      "wholesale_only": false
    }
  ],
  "packaging_only": false,
  "created_at": "2026-09-13T15:00:00.000Z",
  "updated_at": "2026-10-18T15:00:00.000Z"
}

curl · updateProduct

curl -X PATCH "https://api.tfshop.cloud/v1/products/p_gan_65w" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fiscal": {
      "ncm": "85044010",
      "cest": "2106400"
    },
    "weight_grams": 150,
    "variants": [
      {
        "sku": "VLT-C240-2M",
        "price": 8490,
        "compare_at_price": 9990,
        "options": {
          "Cor": "Preto"
        }
      }
    ]
  }'

DELETE/products/{product_id}

Archive a product

products:writedeleteProduct

Products are archived, never erased: past orders keep pointing at them.

Pode publicarproduct.deleted

Parâmetros

Campo	Tipo	Descrição
product_idcaminhoObrigatório	string	Product id.

Resposta 200

Campo	Tipo	Descrição
idObrigatório	string	Product id.
titleObrigatório	string	Title.
handleObrigatório	string	URL slug (set on creation, never changes).
statusObrigatório	string	active (on sale), draft or archived. Valores:`activedraftarchived`
descriptionObrigatório	string	Plain-text description (line breaks kept; HTML is not rendered).
category_idObrigatório	string \| null	Primary category id.
brandObrigatório	string \| null	Brand.
tagsObrigatório	string[]	Tags.
fiscalObrigatório	object
ncmObrigatório	string \| null	NCM, 8 digits, or null when not informed (optional; required only when the store issues the NF-e itself). `^\d{8}$`
cestObrigatório	string \| null	CEST, 7 digits.
originObrigatório	integer	Origem da mercadoria (0–8). 0 a 8
weight_gramsObrigatório	integer	Shipping weight in grams. ≥ 0
dimensions_cmObrigatório	object	Package dimensions in cm.
lengthObrigatório	number
widthObrigatório	number
heightObrigatório	number
imagesObrigatório	object[]	Gallery, first = main image. Images sent by apps are copied into the store's media library shortly after the write, so the URLs change to the store's own.
urlObrigatório	string	Absolute image URL.
altObrigatório	string \| null	Alt text.
wholesaleObrigatório	→ Wholesale \| null	Wholesale pricing, or null when the product has none.
packagingsObrigatório	→ Packaging[]	Sales packages (up to 4); empty when sold by the piece only.
packaging_onlyObrigatório	boolean	True when the product is sold only in packages (no loose pieces).
variantsObrigatório	→ Variant[]	Variants (at least one).
created_atObrigatório	string (date-time)	Creation time.
updated_atObrigatório	string (date-time)	Last change of product data (not stock).

Exemplo

json

{
  "id": "p_gan_65w",
  "title": "Carregador GaN 65W 3 Portas",
  "handle": "carregador-gan-65w-3-portas",
  "status": "active",
  "description": "Tecnologia GaN, 2 portas USB-C + 1 USB-A.",
  "category_id": "cat_chargers",
  "brand": "Volt",
  "tags": [
    "gan",
    "notebook",
    "anatel"
  ],
  "fiscal": {
    "ncm": "85044010",
    "cest": null,
    "origin": 2
  },
  "weight_grams": 140,
  "dimensions_cm": {
    "length": 9,
    "width": 6,
    "height": 4
  },
  "images": [],
  "variants": [
    {
      "id": "p_gan_65w_v1",
      "product_id": "p_gan_65w",
      "sku": "VLT-GAN65W",
      "title": "Padrão",
      "options": {},
      "price": 17990,
      "compare_at_price": 21990,
      "gtin": "7891035631000",
      "inventory": {
        "on_hand": 42,
        "reserved": 1,
        "available": 41
      }
    }
  ],
  "wholesale": {
    "enabled": true,
    "tiers": [
      {
        "min_qty": 12,
        "unit_price": 15990
      },
      {
        "min_qty": 48,
        "unit_price": 14990
      }
    ],
    "min_qty": null,
    "multiple": null,
    "packs": []
  },
  "packagings": [
    {
      "id": "pkg_caixa12",
      "unit": "caixa",
      "label": null,
      "name": "Caixa c/ 12",
      "pieces": 12,
      "unit_price": 15490,
      "tiers": [],
      "fill": "single",
      "axis": null,
      "wholesale_only": false
    }
  ],
  "packaging_only": false,
  "created_at": "2026-09-13T15:00:00.000Z",
  "updated_at": "2026-10-18T15:00:00.000Z"
}

curl · deleteProduct

curl -X DELETE "https://api.tfshop.cloud/v1/products/p_gan_65w" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

GET/variants

Look variants up by SKU

products:readlistVariants

Parâmetros

Campo	Tipo	Descrição
skuconsulta	string	One or more SKUs, comma-separated (max 100).
limitconsulta	integer	Page size, 1–100 (default 50).
cursorconsulta	string	Opaque cursor from `next_cursor`.

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ Variant[]	Page of Variant objects.
next_cursorObrigatório	string \| null	Cursor of the next page; null on the last page.

Exemplo

json

{
  "data": [
    {
      "id": "string",
      "product_id": "string",
      "sku": "string",
      "title": "string",
      "options": {},
      "price": 0,
      "compare_at_price": 0,
      "gtin": "string",
      "image_url": "string",
      "inventory": {
        "on_hand": 0,
        "reserved": 0,
        "available": 0
      }
    }
  ],
  "next_cursor": "string"
}

curl · listVariants

curl "https://api.tfshop.cloud/v1/variants?sku=VLT-GAN65W,VLT-CHARGER20&limit=50" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

POST/prices/batch

Set retail and compare-at prices by SKU (up to 100)

products:writeAceita Idempotency-KeyupdateVariantPrices

Coupons, Pix discount and promotions stay in the store. Send an Idempotency-Key header to retry safely (only 2xx responses are stored; after fixing an error, retry with the same key).

Pode publicarproduct.updated

Corpo da requisição

Campo	Tipo	Descrição
itemsObrigatório	object[]	Up to 100 SKUs. The batch is applied all or nothing. máx. 100
skuObrigatório	string	SKU.
priceObrigatório	integer	Retail price in centavos (> 0). ≥ 1
compare_at_price	integer \| null	"De" price, or null to remove it. ≥ 1

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ Variant[]	Updated Variant objects, in request order.

Exemplo

json

{
  "data": [
    {
      "id": "string",
      "product_id": "string",
      "sku": "string",
      "title": "string",
      "options": {},
      "price": 0,
      "compare_at_price": 0,
      "gtin": "string",
      "image_url": "string",
      "inventory": {
        "on_hand": 0,
        "reserved": 0,
        "available": 0
      }
    }
  ]
}

curl · updateVariantPrices

curl -X POST "https://api.tfshop.cloud/v1/prices/batch" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "items": [
      {
        "sku": "VLT-GAN65W",
        "price": 16990,
        "compare_at_price": 21990
      },
      {
        "sku": "VLT-CHARGER20",
        "price": 6490
      }
    ]
  }'

Estoque

3 endpoints

GET/inventory_levels
POST/inventory_levels/set
POST/inventory_levels/adjust

GET/inventory_levels

List stock levels (on hand, reserved, available) by SKU

inventory:readlistInventoryLevels

Parâmetros

Campo	Tipo	Descrição
skuconsulta	string	SKUs, comma-separated (max 100).
updated_sinceconsulta	string (date-time)	Only objects changed at or after this instant (ISO 8601).
limitconsulta	integer	Page size, 1–100 (default 50).
cursorconsulta	string	Opaque cursor from `next_cursor`.

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ InventoryLevel[]	Page of InventoryLevel objects.
next_cursorObrigatório	string \| null	Cursor of the next page; null on the last page.

Exemplo

json

{
  "data": [
    {
      "sku": "VLT-GAN65W",
      "variant_id": "p_gan_65w_v1",
      "product_id": "p_gan_65w",
      "on_hand": 42,
      "reserved": 1,
      "available": 41,
      "updated_at": "2026-10-28T13:05:12.000Z"
    }
  ],
  "next_cursor": "string"
}

curl · listInventoryLevels

curl "https://api.tfshop.cloud/v1/inventory_levels?sku=VLT-GAN65W,VLT-CHARGER20&limit=50" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

POST/inventory_levels/set

Set absolute on-hand quantities by SKU (up to 100, e.g. after a stock count)

inventory:writeAceita Idempotency-KeysetInventoryLevels

Units reserved by unpaid orders are kept: available = on_hand − reserved. Send an Idempotency-Key header to retry safely (only 2xx responses are stored; after fixing an error, retry with the same key).

Pode publicarinventory.updated

Corpo da requisição

Campo	Tipo	Descrição
itemsObrigatório	object[]	Up to 100 SKUs, all or nothing. máx. 100
skuObrigatório	string	SKU.
on_handObrigatório	integer	Absolute units in stock. ≥ 0

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ InventoryLevel[]	Updated InventoryLevel objects, in request order.

Exemplo

json

{
  "data": [
    {
      "sku": "VLT-GAN65W",
      "variant_id": "p_gan_65w_v1",
      "product_id": "p_gan_65w",
      "on_hand": 42,
      "reserved": 1,
      "available": 41,
      "updated_at": "2026-10-28T13:05:12.000Z"
    }
  ]
}

curl · setInventoryLevels

curl -X POST "https://api.tfshop.cloud/v1/inventory_levels/set" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "items": [
      {
        "sku": "VLT-GAN65W",
        "on_hand": 40
      }
    ]
  }'

POST/inventory_levels/adjust

Add or remove units by SKU with a reason (up to 100)

inventory:writeAceita Idempotency-KeyadjustInventory

Send an Idempotency-Key header to retry safely (only 2xx responses are stored; after fixing an error, retry with the same key).

Pode publicarinventory.updated

Corpo da requisição

Campo	Tipo	Descrição
itemsObrigatório	object[]	Up to 100 SKUs, all or nothing. máx. 100
skuObrigatório	string	SKU.
deltaObrigatório	integer	Units to add (positive) or remove (negative); on_hand never goes below 0.
reasonObrigatório	string	Why ("recebimento NF 1234", "avaria", "inventário"). máx. 120

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ InventoryLevel[]	Updated InventoryLevel objects, in request order.

Exemplo

json

{
  "data": [
    {
      "sku": "VLT-GAN65W",
      "variant_id": "p_gan_65w_v1",
      "product_id": "p_gan_65w",
      "on_hand": 42,
      "reserved": 1,
      "available": 41,
      "updated_at": "2026-10-28T13:05:12.000Z"
    }
  ]
}

curl · adjustInventory

curl -X POST "https://api.tfshop.cloud/v1/inventory_levels/adjust" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "items": [
      {
        "sku": "VLT-GAN65W",
        "delta": 24,
        "reason": "Recebimento NF 88213"
      }
    ]
  }'

Webhooks

3 endpoints

GET/webhook_endpoints
POST/webhook_endpoints
DELETE/webhook_endpoints/{endpoint_id}

GET/webhook_endpoints

List webhook endpoints of this app or token

webhooks:managelistWebhookEndpoints

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ WebhookEndpoint[]	Page of WebhookEndpoint objects.
next_cursorObrigatório	string \| null	Cursor of the next page; null on the last page.

Exemplo

json

{
  "data": [
    {
      "id": "string",
      "url": "https://erp.exemplo.com.br/recurso",
      "description": "string",
      "events": [
        "order.created"
      ],
      "status": "enabled",
      "created_at": "2026-10-29T13:05:12.000Z",
      "secret": "string"
    }
  ],
  "next_cursor": "string"
}

curl · listWebhookEndpoints

curl "https://api.tfshop.cloud/v1/webhook_endpoints" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

POST/webhook_endpoints

Subscribe a URL to events (returns the signing secret once)

webhooks:manageAceita Idempotency-KeycreateWebhookEndpoint

Each event type needs the read scope of its object (orders:read, products:read, inventory:read). Deliveries are signed with Standard Webhooks headers and retried for about a day (5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h).

Corpo da requisição

Campo	Tipo	Descrição
urlObrigatório	string (uri)	HTTPS URL.
eventsObrigatório	string[]	Event types.
description	string	Free text. máx. 120

Resposta 201

→ WebhookEndpoint

Campo	Tipo	Descrição
idObrigatório	string	Endpoint id (we_…).
urlObrigatório	string (uri)	HTTPS URL that receives the events.
descriptionObrigatório	string \| null	Free text.
eventsObrigatório	string[]	Subscribed event types.
statusObrigatório	string	enabled or disabled. Valores:`enableddisabled`
created_atObrigatório	string (date-time)	Creation time.
secret	string	Signing secret (whsec_…). Returned only by the create call: store it.

Exemplo

json

{
  "id": "string",
  "url": "https://erp.exemplo.com.br/recurso",
  "description": "string",
  "events": [
    "order.created"
  ],
  "status": "enabled",
  "created_at": "2026-10-29T13:05:12.000Z",
  "secret": "string"
}

Erros:idempotency_key_reuse

curl · createWebhookEndpoint

curl -X POST "https://api.tfshop.cloud/v1/webhook_endpoints" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "url": "https://erp.exemplo.com.br/webhooks/tfshop",
    "events": [
      "order.paid",
      "order.cancelled"
    ],
    "description": "ERP produção"
  }'

DELETE/webhook_endpoints/{endpoint_id}

Delete a webhook endpoint

webhooks:managedeleteWebhookEndpoint

Parâmetros

Campo	Tipo	Descrição
endpoint_idcaminhoObrigatório	string	we_…

Resposta 204

204 No Content

curl · deleteWebhookEndpoint

curl -X DELETE "https://api.tfshop.cloud/v1/webhook_endpoints/we_3Jx8Lq2Vn5Rk0p" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

Eventos

1 endpoints

GET/events

GET/events

List events of the last 30 days (catch up after downtime)

orders:readlistEvents

Oldest first. Only event types your scopes can read are listed.

Parâmetros

Campo	Tipo	Descrição
typeconsulta	string	Event type filter (comma-separated).
created_sinceconsulta	string (date-time)	ISO 8601.
limitconsulta	integer	Page size, 1–100 (default 50).
cursorconsulta	string	Opaque cursor from `next_cursor`.

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ Event[]	Page of Event objects.
next_cursorObrigatório	string \| null	Cursor of the next page; null on the last page.

Exemplo

json

{
  "data": [
    {
      "id": "evt_8bQ2kT9mWx1Lp4",
      "type": "order.paid",
      "timestamp": "2026-10-28T13:05:12.000Z",
      "api_version": "v1",
      "store_id": "st_volt",
      "actor": {
        "type": "system",
        "app_id": null
      },
      "data": {
        "object": "order",
        "id": "o_1017",
        "reference": "1017",
        "status": "paid",
        "test": false
      }
    }
  ],
  "next_cursor": "string"
}

curl · listEvents

curl "https://api.tfshop.cloud/v1/events?type=order.paid&limit=50" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

Design da loja

12 endpoints

GET/theme
PATCH/theme
POST/theme/sections
PATCH/theme/sections/{section_id}
DELETE/theme/sections/{section_id}
GET/theme/versions
POST/theme/versions/{version_id}/restore
GET/menus
PUT/menus
GET/pages
POST/pages
PATCH/pages/{page_id}

GET/theme

Get the storefront theme

store:readgetTheme

Preset, tokens, home page sections in display order, header / footer / product options, the storefront URL and how many versions can be restored.

Resposta 200

Campo	Tipo	Descrição
preset_idObrigatório	string	Base preset. Valores:`voltcleanmodaatacadocasabeleza`
tokensObrigatório	→ ThemeTokens
sectionsObrigatório	→ ThemeSection[]	Home page sections in display order. The announcement bar (one at most) renders in the header and always comes first.
headerObrigatório	object
show_searchObrigatório	boolean	Search box in the header.
menu_category_idsObrigatório	any	"all", or category ids: the automatic header menu while the store has no custom menus.
footerObrigatório	object
about_textObrigatório	string	Short text about the store in the footer.
show_payment_iconsObrigatório	boolean	Pix / card / boleto icons in the footer.
productObrigatório	object
show_pix_priceObrigatório	boolean	Pix price with discount on product pages.
show_installmentsObrigatório	boolean	Instalment line on product pages.
show_shipping_calculatorObrigatório	boolean	CEP shipping calculator on product pages.
show_whatsapp_buttonObrigatório	boolean	WhatsApp button on product pages.
identity	object
logo_max_height	integer	Max logo height in the header, px (24–96).
storefront_urlObrigatório	string	Public URL of the storefront — open it to see the result.
versionsObrigatório	integer	Previous versions available to restore (up to 10).

Exemplo

json

{
  "preset_id": "volt",
  "tokens": {
    "primary": "string",
    "primary_text": "string",
    "accent": "string",
    "background": "string",
    "surface": "string",
    "text": "string",
    "muted_text": "string",
    "header_background": "string",
    "header_text": "string",
    "radius": "none",
    "heading_font": "inter",
    "body_font": "inter"
  },
  "sections": [
    {
      "id": "string",
      "type": "announcement",
      "enabled": false,
      "settings": {}
    }
  ],
  "header": {
    "show_search": false,
    "menu_category_ids": null
  },
  "footer": {
    "about_text": "string",
    "show_payment_icons": false
  },
  "product": {
    "show_pix_price": false,
    "show_installments": false,
    "show_shipping_calculator": false,
    "show_whatsapp_button": false
  },
  "identity": {
    "logo_max_height": 0
  },
  "storefront_url": "string",
  "versions": 0
}

curl · getTheme

curl "https://api.tfshop.cloud/v1/theme" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

PATCH/theme

Change tokens, preset or options of the theme

store:writeupdateTheme

Partial: only the sent fields change. preset_id replaces every token with the preset's and keeps the sections. The previous theme is kept as a version.

Corpo da requisição

Campo	Tipo	Descrição
preset_id	string	Apply a preset: replaces every token with the preset's and keeps the sections. Valores:`voltcleanmodaatacadocasabeleza`
tokens	object	Only the sent tokens change.
primary	string	Hex colour.
primary_text	string	Hex colour.
accent	string	Hex colour.
background	string	Hex colour.
surface	string	Hex colour.
text	string	Hex colour.
muted_text	string	Hex colour.
header_background	string	Hex colour.
header_text	string	Hex colour.
radius	string	Corner radius. Valores:`nonesmmdlg`
heading_font	string	Heading font. Valores:`interjakartagrotesk`
body_font	string	Body font. Valores:`interjakartagrotesk`
header	object
show_search	boolean	Search box in the header.
menu_category_ids	any	"all", or category ids: the automatic header menu while the store has no custom menus.
footer	object
about_text	string	Short text about the store (≤ 400 characters).
show_payment_icons	boolean	Pix / card / boleto icons.
product	object
show_pix_price	boolean	Pix price with discount.
show_installments	boolean	Instalment line.
show_shipping_calculator	boolean	CEP shipping calculator.
show_whatsapp_button	boolean	WhatsApp button.
identity	object
logo_max_height	integer	Max logo height in the header, px (24–96).

Resposta 200

Campo	Tipo	Descrição
preset_idObrigatório	string	Base preset. Valores:`voltcleanmodaatacadocasabeleza`
tokensObrigatório	→ ThemeTokens
sectionsObrigatório	→ ThemeSection[]	Home page sections in display order. The announcement bar (one at most) renders in the header and always comes first.
headerObrigatório	object
show_searchObrigatório	boolean	Search box in the header.
menu_category_idsObrigatório	any	"all", or category ids: the automatic header menu while the store has no custom menus.
footerObrigatório	object
about_textObrigatório	string	Short text about the store in the footer.
show_payment_iconsObrigatório	boolean	Pix / card / boleto icons in the footer.
productObrigatório	object
show_pix_priceObrigatório	boolean	Pix price with discount on product pages.
show_installmentsObrigatório	boolean	Instalment line on product pages.
show_shipping_calculatorObrigatório	boolean	CEP shipping calculator on product pages.
show_whatsapp_buttonObrigatório	boolean	WhatsApp button on product pages.
identity	object
logo_max_height	integer	Max logo height in the header, px (24–96).
storefront_urlObrigatório	string	Public URL of the storefront — open it to see the result.
versionsObrigatório	integer	Previous versions available to restore (up to 10).

Exemplo

json

{
  "preset_id": "volt",
  "tokens": {
    "primary": "string",
    "primary_text": "string",
    "accent": "string",
    "background": "string",
    "surface": "string",
    "text": "string",
    "muted_text": "string",
    "header_background": "string",
    "header_text": "string",
    "radius": "none",
    "heading_font": "inter",
    "body_font": "inter"
  },
  "sections": [
    {
      "id": "string",
      "type": "announcement",
      "enabled": false,
      "settings": {}
    }
  ],
  "header": {
    "show_search": false,
    "menu_category_ids": null
  },
  "footer": {
    "about_text": "string",
    "show_payment_icons": false
  },
  "product": {
    "show_pix_price": false,
    "show_installments": false,
    "show_shipping_calculator": false,
    "show_whatsapp_button": false
  },
  "identity": {
    "logo_max_height": 0
  },
  "storefront_url": "string",
  "versions": 0
}

curl · updateTheme

curl -X PATCH "https://api.tfshop.cloud/v1/theme" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": {
      "primary": "#0f766e",
      "accent": "#f59e0b"
    },
    "footer": {
      "about_text": "Loja oficial da marca — nota fiscal em todos os pedidos e envio para todo o Brasil."
    }
  }'

POST/theme/sections

Add a home page section

store:writeAceita Idempotency-KeyaddSection

Types: announcement (one at most, always first), hero, benefits, category_grid, product_grid, promo_banner, testimonials, faq, newsletter, rich_text. Categories and collections referenced by the settings must exist. Returns the theme plus section_id. Send an Idempotency-Key header to retry safely (only 2xx responses are stored; after fixing an error, retry with the same key).

Corpo da requisição

Campo	Tipo	Descrição
typeObrigatório	string	Section type. Valores:`announcementherobenefitscategory_gridproduct_gridpromo_bannertestimonialsfaqnewsletterrich_text`
settings	object	Settings of the section type, snake_case. The design guide (tfshop://design-guide on MCP, /developers/mcp) lists each type's fields: announcement{text,link}; hero{eyebrow,title,subtitle,cta_label,cta_href,layout,art,image}; benefits{items[{icon,title,text}]}; category_grid{title,category_ids,layout}; product_grid{title,source,category_id,collection_id,limit,layout}; promo_banner{title,text,cta_label,cta_href,tone,image}; testimonials{title,items[{name,city,text,rating}]}; faq{title,items[{question,answer}]}; newsletter{title,text}; rich_text{title,body,style}. Omitted fields take the Brazilian Portuguese defaults; lists (items, category_ids) are sent whole.
enabled	boolean	Default true.
after_section_id	string \| null	Insert after this section; null = first page section. Omitted = at the end. The announcement bar is always first.
index	integer	Position among the page sections (0 = first after the announcement bar); ignored when after_section_id is sent.

Resposta 201

Campo	Tipo	Descrição
preset_idObrigatório	string	Base preset. Valores:`voltcleanmodaatacadocasabeleza`
tokensObrigatório	→ ThemeTokens
sectionsObrigatório	→ ThemeSection[]	Home page sections in display order. The announcement bar (one at most) renders in the header and always comes first.
headerObrigatório	object
show_searchObrigatório	boolean	Search box in the header.
menu_category_idsObrigatório	any	"all", or category ids: the automatic header menu while the store has no custom menus.
footerObrigatório	object
about_textObrigatório	string	Short text about the store in the footer.
show_payment_iconsObrigatório	boolean	Pix / card / boleto icons in the footer.
productObrigatório	object
show_pix_priceObrigatório	boolean	Pix price with discount on product pages.
show_installmentsObrigatório	boolean	Instalment line on product pages.
show_shipping_calculatorObrigatório	boolean	CEP shipping calculator on product pages.
show_whatsapp_buttonObrigatório	boolean	WhatsApp button on product pages.
identity	object
logo_max_height	integer	Max logo height in the header, px (24–96).
storefront_urlObrigatório	string	Public URL of the storefront — open it to see the result.
versionsObrigatório	integer	Previous versions available to restore (up to 10).

Exemplo

json

{
  "preset_id": "volt",
  "tokens": {
    "primary": "string",
    "primary_text": "string",
    "accent": "string",
    "background": "string",
    "surface": "string",
    "text": "string",
    "muted_text": "string",
    "header_background": "string",
    "header_text": "string",
    "radius": "none",
    "heading_font": "inter",
    "body_font": "inter"
  },
  "sections": [
    {
      "id": "string",
      "type": "announcement",
      "enabled": false,
      "settings": {}
    }
  ],
  "header": {
    "show_search": false,
    "menu_category_ids": null
  },
  "footer": {
    "about_text": "string",
    "show_payment_icons": false
  },
  "product": {
    "show_pix_price": false,
    "show_installments": false,
    "show_shipping_calculator": false,
    "show_whatsapp_button": false
  },
  "identity": {
    "logo_max_height": 0
  },
  "storefront_url": "string",
  "versions": 0
}

curl · addSection

curl -X POST "https://api.tfshop.cloud/v1/theme/sections" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "type": "faq",
    "settings": {
      "title": "Dúvidas frequentes",
      "items": [
        {
          "question": "Qual o prazo de entrega?",
          "answer": "Até 5 dias úteis para capitais; informe o CEP no carrinho para ver o prazo exato."
        }
      ]
    }
  }'

PATCH/theme/sections/{section_id}

Edit, enable / disable or move a section

store:writeupdateSection

Parâmetros

Campo	Tipo	Descrição
section_idcaminhoObrigatório	string	Section id (sec_…) from the theme.

Corpo da requisição

Campo	Tipo	Descrição
settings	object	Fields to change: they merge into the current settings; lists (items, category_ids) replace whole.
enabled	boolean	Show or hide the section.
after_section_id	string \| null	Move after this section; null = first page section.
index	integer	Move to this position among the page sections.

Resposta 200

Campo	Tipo	Descrição
preset_idObrigatório	string	Base preset. Valores:`voltcleanmodaatacadocasabeleza`
tokensObrigatório	→ ThemeTokens
sectionsObrigatório	→ ThemeSection[]	Home page sections in display order. The announcement bar (one at most) renders in the header and always comes first.
headerObrigatório	object
show_searchObrigatório	boolean	Search box in the header.
menu_category_idsObrigatório	any	"all", or category ids: the automatic header menu while the store has no custom menus.
footerObrigatório	object
about_textObrigatório	string	Short text about the store in the footer.
show_payment_iconsObrigatório	boolean	Pix / card / boleto icons in the footer.
productObrigatório	object
show_pix_priceObrigatório	boolean	Pix price with discount on product pages.
show_installmentsObrigatório	boolean	Instalment line on product pages.
show_shipping_calculatorObrigatório	boolean	CEP shipping calculator on product pages.
show_whatsapp_buttonObrigatório	boolean	WhatsApp button on product pages.
identity	object
logo_max_height	integer	Max logo height in the header, px (24–96).
storefront_urlObrigatório	string	Public URL of the storefront — open it to see the result.
versionsObrigatório	integer	Previous versions available to restore (up to 10).

Exemplo

json

{
  "preset_id": "volt",
  "tokens": {
    "primary": "string",
    "primary_text": "string",
    "accent": "string",
    "background": "string",
    "surface": "string",
    "text": "string",
    "muted_text": "string",
    "header_background": "string",
    "header_text": "string",
    "radius": "none",
    "heading_font": "inter",
    "body_font": "inter"
  },
  "sections": [
    {
      "id": "string",
      "type": "announcement",
      "enabled": false,
      "settings": {}
    }
  ],
  "header": {
    "show_search": false,
    "menu_category_ids": null
  },
  "footer": {
    "about_text": "string",
    "show_payment_icons": false
  },
  "product": {
    "show_pix_price": false,
    "show_installments": false,
    "show_shipping_calculator": false,
    "show_whatsapp_button": false
  },
  "identity": {
    "logo_max_height": 0
  },
  "storefront_url": "string",
  "versions": 0
}

curl · updateSection

curl -X PATCH "https://api.tfshop.cloud/v1/theme/sections/{section_id}" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "title": "Perguntas frequentes"
    },
    "index": 0
  }'

DELETE/theme/sections/{section_id}

Remove a section

store:writedeleteSection

The previous theme stays restorable as a version.

Parâmetros

Campo	Tipo	Descrição
section_idcaminhoObrigatório	string	Section id (sec_…) from the theme.

Resposta 200

Campo	Tipo	Descrição
preset_idObrigatório	string	Base preset. Valores:`voltcleanmodaatacadocasabeleza`
tokensObrigatório	→ ThemeTokens
sectionsObrigatório	→ ThemeSection[]	Home page sections in display order. The announcement bar (one at most) renders in the header and always comes first.
headerObrigatório	object
show_searchObrigatório	boolean	Search box in the header.
menu_category_idsObrigatório	any	"all", or category ids: the automatic header menu while the store has no custom menus.
footerObrigatório	object
about_textObrigatório	string	Short text about the store in the footer.
show_payment_iconsObrigatório	boolean	Pix / card / boleto icons in the footer.
productObrigatório	object
show_pix_priceObrigatório	boolean	Pix price with discount on product pages.
show_installmentsObrigatório	boolean	Instalment line on product pages.
show_shipping_calculatorObrigatório	boolean	CEP shipping calculator on product pages.
show_whatsapp_buttonObrigatório	boolean	WhatsApp button on product pages.
identity	object
logo_max_height	integer	Max logo height in the header, px (24–96).
storefront_urlObrigatório	string	Public URL of the storefront — open it to see the result.
versionsObrigatório	integer	Previous versions available to restore (up to 10).

Exemplo

json

{
  "preset_id": "volt",
  "tokens": {
    "primary": "string",
    "primary_text": "string",
    "accent": "string",
    "background": "string",
    "surface": "string",
    "text": "string",
    "muted_text": "string",
    "header_background": "string",
    "header_text": "string",
    "radius": "none",
    "heading_font": "inter",
    "body_font": "inter"
  },
  "sections": [
    {
      "id": "string",
      "type": "announcement",
      "enabled": false,
      "settings": {}
    }
  ],
  "header": {
    "show_search": false,
    "menu_category_ids": null
  },
  "footer": {
    "about_text": "string",
    "show_payment_icons": false
  },
  "product": {
    "show_pix_price": false,
    "show_installments": false,
    "show_shipping_calculator": false,
    "show_whatsapp_button": false
  },
  "identity": {
    "logo_max_height": 0
  },
  "storefront_url": "string",
  "versions": 0
}

curl · deleteSection

curl -X DELETE "https://api.tfshop.cloud/v1/theme/sections/{section_id}" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

GET/theme/versions

List previous theme versions (newest first)

store:readlistThemeVersions

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ ThemeVersion[]	Up to 10 versions, newest first.

Exemplo

json

{
  "data": [
    {
      "id": "string",
      "saved_at": "2026-10-29T13:05:12.000Z",
      "saved_by": "string",
      "source": "admin",
      "preset_id": "string",
      "section_count": 0,
      "sections": [
        {
          "id": null,
          "type": null,
          "enabled": null,
          "summary": null
        }
      ]
    }
  ]
}

curl · listThemeVersions

curl "https://api.tfshop.cloud/v1/theme/versions" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

POST/theme/versions/{version_id}/restore

Restore a previous theme version

store:writerestoreThemeVersion

The current theme is kept as a new version first.

Parâmetros

Campo	Tipo	Descrição
version_idcaminhoObrigatório	string	Theme version id (thv_…).

Resposta 200

Campo	Tipo	Descrição
preset_idObrigatório	string	Base preset. Valores:`voltcleanmodaatacadocasabeleza`
tokensObrigatório	→ ThemeTokens
sectionsObrigatório	→ ThemeSection[]	Home page sections in display order. The announcement bar (one at most) renders in the header and always comes first.
headerObrigatório	object
show_searchObrigatório	boolean	Search box in the header.
menu_category_idsObrigatório	any	"all", or category ids: the automatic header menu while the store has no custom menus.
footerObrigatório	object
about_textObrigatório	string	Short text about the store in the footer.
show_payment_iconsObrigatório	boolean	Pix / card / boleto icons in the footer.
productObrigatório	object
show_pix_priceObrigatório	boolean	Pix price with discount on product pages.
show_installmentsObrigatório	boolean	Instalment line on product pages.
show_shipping_calculatorObrigatório	boolean	CEP shipping calculator on product pages.
show_whatsapp_buttonObrigatório	boolean	WhatsApp button on product pages.
identity	object
logo_max_height	integer	Max logo height in the header, px (24–96).
storefront_urlObrigatório	string	Public URL of the storefront — open it to see the result.
versionsObrigatório	integer	Previous versions available to restore (up to 10).

Exemplo

json

{
  "preset_id": "volt",
  "tokens": {
    "primary": "string",
    "primary_text": "string",
    "accent": "string",
    "background": "string",
    "surface": "string",
    "text": "string",
    "muted_text": "string",
    "header_background": "string",
    "header_text": "string",
    "radius": "none",
    "heading_font": "inter",
    "body_font": "inter"
  },
  "sections": [
    {
      "id": "string",
      "type": "announcement",
      "enabled": false,
      "settings": {}
    }
  ],
  "header": {
    "show_search": false,
    "menu_category_ids": null
  },
  "footer": {
    "about_text": "string",
    "show_payment_icons": false
  },
  "product": {
    "show_pix_price": false,
    "show_installments": false,
    "show_shipping_calculator": false,
    "show_whatsapp_button": false
  },
  "identity": {
    "logo_max_height": 0
  },
  "storefront_url": "string",
  "versions": 0
}

curl · restoreThemeVersion

curl -X POST "https://api.tfshop.cloud/v1/theme/versions/{version_id}/restore" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

GET/menus

Get the header and footer menus

store:readgetMenus

automatic = true while the store has no custom menus: they then derive from categories, collections, pages and policies.

Resposta 200

→ Menus

Campo	Tipo	Descrição
headerObrigatório	→ MenuItem[]	Header menu (up to 12 items with up to 20 children each).
footerObrigatório	→ MenuItem[]	Footer columns (up to 5 headings with up to 12 links each).
automaticObrigatório	boolean	true while the store has no custom menus: header and footer are derived from categories, collections, pages and policies.

Exemplo

json

{
  "header": [
    {
      "id": "string",
      "label": "string",
      "target": null,
      "children": []
    }
  ],
  "footer": [
    {
      "id": "string",
      "label": "string",
      "target": null,
      "children": []
    }
  ],
  "automatic": false
}

curl · getMenus

curl "https://api.tfshop.cloud/v1/menus" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

PUT/menus

Replace the header and/or footer menus

store:writeupdateMenus

Targets must exist in the store (category, collection and page ids; policy slugs). A part left out keeps the current menu.

Corpo da requisição

Campo	Tipo	Descrição
header	object[]	Header menu (≤ 12 items). Omitted = unchanged.
id	string	Keep an existing item's id to preserve it; omitted = new id.
labelObrigatório	string	Label (≤ 40 characters).
targetObrigatório	→ MenuTarget
children	object[]	Sub-items (header) or the links of a footer column.
id	string	Existing id or omitted.
labelObrigatório	string	Label (≤ 40 characters).
targetObrigatório	→ MenuTarget
footer	object[]	Footer columns (≤ 5). Omitted = unchanged.
id	string	Keep an existing item's id to preserve it; omitted = new id.
labelObrigatório	string	Label (≤ 40 characters).
targetObrigatório	→ MenuTarget
children	object[]	Sub-items (header) or the links of a footer column.
id	string	Existing id or omitted.
labelObrigatório	string	Label (≤ 40 characters).
targetObrigatório	→ MenuTarget

Resposta 200

→ Menus

Campo	Tipo	Descrição
headerObrigatório	→ MenuItem[]	Header menu (up to 12 items with up to 20 children each).
footerObrigatório	→ MenuItem[]	Footer columns (up to 5 headings with up to 12 links each).
automaticObrigatório	boolean	true while the store has no custom menus: header and footer are derived from categories, collections, pages and policies.

Exemplo

json

{
  "header": [
    {
      "id": "string",
      "label": "string",
      "target": null,
      "children": []
    }
  ],
  "footer": [
    {
      "id": "string",
      "label": "string",
      "target": null,
      "children": []
    }
  ],
  "automatic": false
}

curl · updateMenus

curl -X PUT "https://api.tfshop.cloud/v1/menus" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "header": [
      {
        "label": "Início",
        "target": {
          "type": "home"
        }
      },
      {
        "label": "Fones",
        "target": {
          "type": "category",
          "id": "cat_audio"
        }
      },
      {
        "label": "Atacado",
        "target": {
          "type": "wholesale"
        }
      }
    ]
  }'

GET/pages

List institutional pages

store:readlistPages

Parâmetros

Campo	Tipo	Descrição
limitconsulta	integer	Page size, 1–100 (default 50).
cursorconsulta	string	Opaque cursor from `next_cursor`.

Resposta 200

Campo	Tipo	Descrição
dataObrigatório	→ Page[]	Page of Page objects.
next_cursorObrigatório	string \| null	Cursor of the next page; null on the last page.

Exemplo

json

{
  "data": [
    {
      "id": "string",
      "slug": "string",
      "title": "string",
      "body": "string",
      "published": false,
      "url": "string",
      "first_published_at": "2026-10-29T13:05:12.000Z",
      "updated_at": "2026-10-29T13:05:12.000Z"
    }
  ],
  "next_cursor": "string"
}

curl · listPages

curl "https://api.tfshop.cloud/v1/pages?limit=50" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

POST/pages

Create an institutional page

store:writeAceita Idempotency-KeycreatePage

Unpublished unless published is true. Send an Idempotency-Key header to retry safely (only 2xx responses are stored; after fixing an error, retry with the same key).

Corpo da requisição

Campo	Tipo	Descrição
titleObrigatório	string	Title (≤ 80 characters).
bodyObrigatório	string	Rich text (≤ 20 000 characters): blank-line paragraphs, '## ' headings, '- ' lists, bold, text.
published	boolean	Default false.
slug	string	Optional; generated from the title when omitted. `^[a-z0-9]+(?:-[a-z0-9]+)*$`

Resposta 201

→ Page

Campo	Tipo	Descrição
idObrigatório	string	Page id.
slugObrigatório	string	URL slug, frozen after the first publish.
titleObrigatório	string	Title (≤ 80 characters).
bodyObrigatório	string	Rich text: blank-line paragraphs, '## ' headings, '- ' lists, bold, text. No HTML.
publishedObrigatório	boolean	Visible in the storefront.
urlObrigatório	string	Public URL (/pagina/{slug}).
first_published_atObrigatório	string \| null (date-time)	First publish; null while never published.
updated_atObrigatório	string (date-time)	Last change.

Exemplo

json

{
  "id": "string",
  "slug": "string",
  "title": "string",
  "body": "string",
  "published": false,
  "url": "string",
  "first_published_at": "2026-10-29T13:05:12.000Z",
  "updated_at": "2026-10-29T13:05:12.000Z"
}

curl · createPage

curl -X POST "https://api.tfshop.cloud/v1/pages" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "title": "Sobre nós",
    "body": "## Quem somos\n\nSomos uma loja de Campinas, SP, com entrega para todo o Brasil.",
    "published": true
  }'

PATCH/pages/{page_id}

Edit a page

store:writeupdatePage

The slug is frozen after the first publish. Pages are not deleted through the API: unpublish them.

Parâmetros

Campo	Tipo	Descrição
page_idcaminhoObrigatório	string	Page id.

Corpo da requisição

Campo	Tipo	Descrição
title	string	Title (≤ 80 characters).
body	string	Rich text (≤ 20 000 characters).
published	boolean	Publish or unpublish.
slug	string	Only while the page was never published.

Resposta 200

→ Page

Campo	Tipo	Descrição
idObrigatório	string	Page id.
slugObrigatório	string	URL slug, frozen after the first publish.
titleObrigatório	string	Title (≤ 80 characters).
bodyObrigatório	string	Rich text: blank-line paragraphs, '## ' headings, '- ' lists, bold, text. No HTML.
publishedObrigatório	boolean	Visible in the storefront.
urlObrigatório	string	Public URL (/pagina/{slug}).
first_published_atObrigatório	string \| null (date-time)	First publish; null while never published.
updated_atObrigatório	string (date-time)	Last change.

Exemplo

json

{
  "id": "string",
  "slug": "string",
  "title": "string",
  "body": "string",
  "published": false,
  "url": "string",
  "first_published_at": "2026-10-29T13:05:12.000Z",
  "updated_at": "2026-10-29T13:05:12.000Z"
}