Referência da API

Todos os endpoints da v1, gerados do mesmo catálogo que alimenta a API e o documento OpenAPI 3.1.

URL base: https://api.tfshop.cloud/v1
Autenticação: Authorization: Bearer …

Baixar OpenAPIOpenAPI 3.1

Resumos e descrições dos endpoints ficam em inglês, como no documento OpenAPI.

Loja

1 endpoints

GET/store

GET/store

Get the connected store

store:readgetStore

Name, domains, legal entity (CNPJ/CPF), plan limits, NF-e issuer, payment methods and shipping origin of the store the token belongs to. The tenant always comes from the token: there is no store id parameter.

Resposta 200

→ Store

Campo	Tipo	Descrição
idObrigatório	string	Store id (st_…). The token belongs to exactly one store.
nameObrigatório	string	Store name shown to shoppers.
slugObrigatório	string	Store slug ({slug}.tfshop.cloud and /s/{slug}).
urlObrigatório	string (uri)	Public storefront URL (primary domain).
statusObrigatório	string	draft (not public yet), published or paused. Valores:`draftpublishedpaused`
domainsObrigatório	object[]	Domains of the storefront.
hostnameObrigatório	string	Hostname.
typeObrigatório	string	subdomain (free) or custom. Valores:`subdomaincustom`
statusObrigatório	string	DNS / certificate status. Valores:`pending_dnsverifyingactiveerror`
primaryObrigatório	boolean	The canonical storefront address.
legalObrigatório	object
nameObrigatório	string	Legal name (razão social).
documentObrigatório	string	CNPJ (14 characters) or CPF (11 digits) of the seller, without punctuation. NF-e issuer (emit) when the store issues through TF Fiscal.
document_typeObrigatório	string	cnpj or cpf. Valores:`cnpjcpf`
state_registrationObrigatório	string \| null	Inscrição estadual (IE), digits only, or null.
addressObrigatório	object	Seller address (shown in the storefront footer, Decreto 7.962/2013).
zipObrigatório	string	CEP, 8 digits. `^\d{8}$`
streetObrigatório	string	Logradouro.
numberObrigatório	string	Número.
complementObrigatório	string \| null	Complemento.
districtObrigatório	string	Bairro.
cityObrigatório	string	Município.
stateObrigatório	string	UF. `^[A-Z]{2}$`
countryObrigatório	string	ISO 3166-1 alpha-2. Valores:`BR`
ibge_codeObrigatório	string \| null	7-digit IBGE municipality code, or null when unknown.
emailObrigatório	string	Customer-service e-mail.
phoneObrigatório	string	Phone in E.164 (+55…), or empty.
currencyObrigatório	string	Always BRL. Valores:`BRL`
timezoneObrigatório	string	Always America/Sao_Paulo. Valores:`America/Sao_Paulo`
localeObrigatório	string	Always pt-BR. Valores:`pt-BR`
invoice_issuerObrigatório	string	Who issues the NF-e: tf_fiscal (the store) or erp (apps post it with POST /orders/{order_id}/invoices). Valores:`tf_fiscalerp`
planObrigatório	object
idObrigatório	string	Plan id. Valores:`startbusinessadvancedenterprise`
nameObrigatório	string	Plan name.
limitsObrigatório	object
productsObrigatório	integer \| null	Max products; null = unlimited.
staffObrigatório	integer \| null	Max staff users; null = unlimited.
storesObrigatório	integer	Stores included.
orders_per_monthObrigatório	integer \| null	Max orders per month; null = unlimited.
storage_gbObrigatório	integer	Media storage in GB.
payment_methodsObrigatório	object	Methods the store's C6 account accepts at checkout.
pixObrigatório	boolean	Pix enabled.
credit_cardObrigatório	boolean	Credit card enabled.
boletoObrigatório	boolean	Boleto enabled.
shipping_origin_cepObrigatório	string \| null	CEP the parcels ship from (8 digits), or null when not configured.
created_atObrigatório	string (date-time)	Creation time.
published_atObrigatório	string \| null (date-time)	When the store went live, or null.

Exemplo

json

{
  "id": "st_volt",
  "name": "VoltShop",
  "slug": "voltshop",
  "url": "https://www.voltshop.com.br",
  "status": "published",
  "domains": [
    {
      "hostname": "voltshop.tfshop.cloud",
      "type": "subdomain",
      "status": "active",
      "primary": false
    },
    {
      "hostname": "www.voltshop.com.br",
      "type": "custom",
      "status": "active",
      "primary": true
    }
  ],
  "legal": {
    "name": "Volt Comércio de Eletrônicos Ltda",
    "document": "11222333000181",
    "document_type": "cnpj",
    "state_registration": "123456789110",
    "address": {
      "zip": "03016000",
      "street": "Rua Oriente",
      "number": "320",
      "complement": "Loja 4",
      "district": "Brás",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "ibge_code": "3550308"
    },
    "email": "atendimento@voltshop.com.br",
    "phone": "+551133112200"
  },
  "currency": "BRL",
  "timezone": "America/Sao_Paulo",
  "locale": "pt-BR",
  "invoice_issuer": "tf_fiscal",
  "plan": {
    "id": "business",
    "name": "Business",
    "limits": {
      "products": null,
      "staff": 5,
      "stores": 1,
      "orders_per_month": null,
      "storage_gb": 20
    }
  },
  "payment_methods": {
    "pix": true,
    "credit_card": true,
    "boleto": true
  },
  "shipping_origin_cep": "03016000",
  "created_at": "2026-09-13T15:00:00.000Z",
  "published_at": "2026-09-20T12:00:00.000Z"
}

curl · getStore

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

Pedidos

4 endpoints

GET/orders
GET/orders/{order_id}
POST/orders/{order_id}/acknowledge
POST/orders/{order_id}/cancel

GET/orders

List orders

orders:readlistOrders

Incremental sync: pass updated_since and follow next_cursor (sorted by updated_at, then id). export_status=pending returns paid orders this app has not acknowledged yet. Test orders are left out unless include_test=true; sandbox tokens (tfs_test_) only see test orders.

Parâmetros

Campo	Tipo	Descrição
updated_sinceconsulta	string (date-time)	Only objects changed at or after this instant (ISO 8601).
statusconsulta	string	Order status (comma-separated for several).
export_statusconsulta	string	pending \| acknowledged (per app).`pendingacknowledged`
include_testconsulta	boolean	Include test orders (default false).
limitconsulta	integer	Page size, 1–100 (default 50).
cursorconsulta	string	Opaque cursor from `next_cursor`.

Resposta 200

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

Exemplo

json

{
  "data": [
    {
      "id": "o_1011",
      "number": 1011,
      "created_at": "2026-10-26T12:00:00.000Z",
      "updated_at": "2026-10-26T12:00:00.000Z",
      "status": "paid",
      "payment_status": "confirmed",
      "fulfillment_status": "unfulfilled",
      "invoice_status": "pending",
      "test": false,
      "channel": "online_store",
      "currency": "BRL",
      "subtotal": 19990,
      "discount": 0,
      "shipping_total": 0,
      "total": 19990,
      "refunded": 0,
      "buyer": {
        "type": "PF",
        "name": "Juliana Martins",
        "document": "12345678909",
        "document_type": "cpf",
        "email": "juliana@exemplo.com.br",
        "phone": "+5519981234567",
        "state_registration": null,
        "ie_indicator": 9,
        "masked": false
      },
      "shipping_address": {
        "zip": "13010111",
        "street": "Rua Barão de Jaguara",
        "number": "100",
        "complement": null,
        "district": "Centro",
        "city": "Campinas",
        "state": "SP",
        "country": "BR",
        "ibge_code": "3509502"
      },
      "billing_address": {
        "zip": "13010111",
        "street": "Rua Barão de Jaguara",
        "number": "100",
        "complement": null,
        "district": "Centro",
        "city": "Campinas",
        "state": "SP",
        "country": "BR",
        "ibge_code": "3509502"
      },
      "lines": [
        {
          "line_id": "o_1011:1",
          "product_id": "p_pb_20k",
          "variant_id": "p_pb_20k_v1",
          "sku": "VLT-PB20K",
          "title": "Power Bank 20.000 mAh 22,5W",
          "variant_title": "Padrão",
          "quantity": 1,
          "unit_price": 19990,
          "list_price": 19990,
          "discount_allocated": 0,
          "freight_allocated": 0,
          "total": 19990,
          "ncm": "85076000",
          "cest": null,
          "origin": 2,
          "gtin": "7891000079190"
        }
      ],
      "shipping": {
        "carrier": "Correios",
        "service": "SEDEX",
        "price": 0,
        "business_days": 2,
        "tracking_code": null,
        "tracking_url": null
      },
      "payment": {
        "method": "credit_card",
        "status": "confirmed",
        "paid_at": "2026-10-26T12:00:00.000Z",
        "installments": 2,
        "nfe_payment_code": "03",
        "card_brand": "visa",
        "nfe_card_brand": "01",
        "card_last4": "8407",
        "acquirer_cnpj": "31872495000172",
        "authorization_code": "482913",
        "pix_end_to_end_id": null,
        "provider": "c6",
        "provider_payment_id": "c6_card_1011"
      },
      "fiscal_hints": {
        "ind_pres": 2,
        "ind_intermed": 0,
        "ind_final": 1
      },
      "invoice": null,
      "export": {
        "acknowledged_at": "2026-10-26T12:05:00.000Z",
        "external_id": "11011"
      }
    }
  ],
  "next_cursor": "string"
}

curl · listOrders

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

GET/orders/{order_id}

Get an order (NF-e-ready payload)

orders:readgetOrder

Buyer personal data requires orders.pii:read; without it, name, document, e-mail, phone and address are masked.

Parâmetros

Campo	Tipo	Descrição
order_idcaminhoObrigatório	string	Order id (o_…).

Resposta 200

→ Order

Campo	Tipo	Descrição
idObrigatório	string	Order id (immutable). Use it as the unique key in your system.
numberObrigatório	integer	Order number shown to the buyer and the merchant (#1011).
created_atObrigatório	string (date-time)	Creation time.
updated_atObrigatório	string (date-time)	Last change (latest timeline entry). Use with `updated_since`.
statusObrigatório	string	Order status. Valores:`pending_paymentpaidfulfillingfulfilledcancelledexpiredreturn_requestedrefundedpartially_refunded`
payment_statusObrigatório	string	Payment status (see Payment.status).
fulfillment_statusObrigatório	string	Fulfillment status. Valores:`unfulfilledlabel_purchasedshippeddeliveredreturned`
invoice_statusObrigatório	string	NF-e status. Valores:`not_requiredpendingauthorizederrorcancelled`
testObrigatório	boolean	Test order placed by the merchant: never issue an NF-e for it.
channelObrigatório	string	Sales channel. Valores:`online_storewhatsappmanualvendedormercado_livreshopeetiktok_shop`
currencyObrigatório	string	Always BRL. Valores:`BRL`
subtotalObrigatório	integer	Sum of the lines (unit_price × quantity). In centavos. ≥ 0
discountObrigatório	integer	Coupon + Pix discount. In centavos. ≥ 0
shipping_totalObrigatório	integer	Freight charged (same as shipping.price). In centavos. ≥ 0
totalObrigatório	integer	subtotal − discount + shipping_total. In centavos. ≥ 0
refundedObrigatório	integer	Refunded so far. In centavos. ≥ 0
buyerObrigatório	→ Buyer	NF-e recipient (dest).
shipping_addressObrigatório	→ Address	Brazilian address. Without `orders.pii:read`, street, number, complement and district are masked and the CEP keeps only its first 5 digits.
billing_addressObrigatório	→ Address	Same as the shipping address in v1 (the checkout has a single address).
linesObrigatório	→ OrderLine[]	Order lines.
shippingObrigatório	→ OrderShipping
paymentObrigatório	→ Payment	Money goes straight to the merchant's own C6 account; refunds are made by the store.
fiscal_hintsObrigatório	→ FiscalHints
invoiceObrigatório	→ Invoice \| null	Current NF-e, or null.
exportObrigatório	→ OrderExportStatus \| null	This app's acknowledgement, or null when not yet imported.

Exemplo

json

{
  "id": "o_1011",
  "number": 1011,
  "created_at": "2026-10-26T12:00:00.000Z",
  "updated_at": "2026-10-26T12:00:00.000Z",
  "status": "paid",
  "payment_status": "confirmed",
  "fulfillment_status": "unfulfilled",
  "invoice_status": "pending",
  "test": false,
  "channel": "online_store",
  "currency": "BRL",
  "subtotal": 19990,
  "discount": 0,
  "shipping_total": 0,
  "total": 19990,
  "refunded": 0,
  "buyer": {
    "type": "PF",
    "name": "Juliana Martins",
    "document": "12345678909",
    "document_type": "cpf",
    "email": "juliana@exemplo.com.br",
    "phone": "+5519981234567",
    "state_registration": null,
    "ie_indicator": 9,
    "masked": false
  },
  "shipping_address": {
    "zip": "13010111",
    "street": "Rua Barão de Jaguara",
    "number": "100",
    "complement": null,
    "district": "Centro",
    "city": "Campinas",
    "state": "SP",
    "country": "BR",
    "ibge_code": "3509502"
  },
  "billing_address": {
    "zip": "13010111",
    "street": "Rua Barão de Jaguara",
    "number": "100",
    "complement": null,
    "district": "Centro",
    "city": "Campinas",
    "state": "SP",
    "country": "BR",
    "ibge_code": "3509502"
  },
  "lines": [
    {
      "line_id": "o_1011:1",
      "product_id": "p_pb_20k",
      "variant_id": "p_pb_20k_v1",
      "sku": "VLT-PB20K",
      "title": "Power Bank 20.000 mAh 22,5W",
      "variant_title": "Padrão",
      "quantity": 1,
      "unit_price": 19990,
      "list_price": 19990,
      "discount_allocated": 0,
      "freight_allocated": 0,
      "total": 19990,
      "ncm": "85076000",
      "cest": null,
      "origin": 2,
      "gtin": "7891000079190"
    }
  ],
  "shipping": {
    "carrier": "Correios",
    "service": "SEDEX",
    "price": 0,
    "business_days": 2,
    "tracking_code": null,
    "tracking_url": null
  },
  "payment": {
    "method": "credit_card",
    "status": "confirmed",
    "paid_at": "2026-10-26T12:00:00.000Z",
    "installments": 2,
    "nfe_payment_code": "03",
    "card_brand": "visa",
    "nfe_card_brand": "01",
    "card_last4": "8407",
    "acquirer_cnpj": "31872495000172",
    "authorization_code": "482913",
    "pix_end_to_end_id": null,
    "provider": "c6",
    "provider_payment_id": "c6_card_1011"
  },
  "fiscal_hints": {
    "ind_pres": 2,
    "ind_intermed": 0,
    "ind_final": 1
  },
  "invoice": null,
  "export": {
    "acknowledged_at": "2026-10-26T12:05:00.000Z",
    "external_id": "11011"
  }
}

curl · getOrder

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

POST/orders/{order_id}/acknowledge

Mark the order as imported by this app

orders:writeAceita Idempotency-KeyacknowledgeOrder

Idempotent per app: acknowledging again returns the first acknowledgement (and updates external_id when sent). Optionally stores the order id in your system for support.

Parâmetros

Campo	Tipo	Descrição
order_idcaminhoObrigatório	string	Order id (o_…).

Corpo da requisição

Campo	Tipo	Descrição
external_id	string	Order id in your system ("Bling pedido 10293"). máx. 64

Resposta 200

Campo	Tipo	Descrição
order_idObrigatório	string	Order id.
acknowledged_atObrigatório	string (date-time)	First acknowledgement.
external_idObrigatório	string \| null	Id in your system.

Exemplo

json

{
  "order_id": "string",
  "acknowledged_at": "2026-10-29T13:05:12.000Z",
  "external_id": "string"
}

Erros:idempotency_key_reuse

curl · acknowledgeOrder

curl -X POST "https://api.tfshop.cloud/v1/orders/o_1011/acknowledge" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "external_id": "10293"
  }'

POST/orders/{order_id}/cancel

Cancel an unpaid order, or request cancellation of a paid one

orders:writecancelOrder

An unpaid order is cancelled at once (200, status cancelled). A paid order gets a cancellation request the merchant decides (202, status cancellation_requested): refunds always happen in the store (C6).

Pode publicarorder.cancelled order.updated

Parâmetros

Campo	Tipo	Descrição
order_idcaminhoObrigatório	string	Order id (o_…).

Corpo da requisição

Campo	Tipo	Descrição
reason	string	Why (out of stock, fraud review…). máx. 200

Resposta 200

Campo	Tipo	Descrição
order_idObrigatório	string	Order id.
statusObrigatório	string	cancelled or cancellation_requested. Valores:`cancelledcancellation_requested`

Exemplo

json

{
  "order_id": "string",
  "status": "cancelled"
}

Erros:invalid_state

curl · cancelOrder

curl -X POST "https://api.tfshop.cloud/v1/orders/o_1011/cancel" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Sem estoque no depósito"
  }'

NF-e

2 endpoints

POST/orders/{order_id}/invoices
POST/orders/{order_id}/invoices/{access_key}/cancel

POST/orders/{order_id}/invoices

Post the NF-e issued by the ERP

invoices:writeAceita Idempotency-KeycreateInvoice

Validates the 44-digit access key (check digit, model 55, issuer = store's CNPJ). Idempotent by access key. Rejected with 409 when the store issues its own NF-e (TF Fiscal) or the order is a test order. The order must be paid and not shipped yet.

Pode publicarinvoice.authorized

Parâmetros

Campo	Tipo	Descrição
order_idcaminhoObrigatório	string	Order id (o_…).

Corpo da requisição

Campo	Tipo	Descrição
access_keyObrigatório	string	44-digit access key. `^\d{6}[0-9A-Z]{14}\d{24}$`
number	integer	nNF (checked against the key when sent).
series	integer	Series (checked against the key when sent).
issued_at	string (date-time)	Issue date (ISO 8601).
xml_url	string (uri)	HTTPS URL of the authorised XML.
danfe_url	string (uri)	HTTPS URL of the DANFE.

Resposta 201

→ Invoice

Campo	Tipo	Descrição
order_idObrigatório	string	Order id.
numberObrigatório	integer	NF-e number (nNF).
seriesObrigatório	integer	NF-e series.
access_keyObrigatório	string	44-digit access key (chave de acesso). `^\d{6}[0-9A-Z]{14}\d{24}$`
issued_atObrigatório	string (date-time)	Issue date.
sourceObrigatório	string	tf_fiscal (issued by the store) or erp (posted by an app). Valores:`tf_fiscalerp`
statusObrigatório	string	authorized or cancelled. Valores:`authorizedcancelled`
xml_urlObrigatório	string \| null	Authorised XML.
danfe_urlObrigatório	string \| null	DANFE PDF.

Exemplo

json

{
  "order_id": "o_2005",
  "number": 1501,
  "series": 1,
  "access_key": "35261011222333000181550010000150011000150019",
  "issued_at": "2026-10-28T14:10:00.000Z",
  "source": "erp",
  "status": "authorized",
  "xml_url": "https://erp.exemplo.com.br/nfe/35261011222333000181550010000150011000150019.xml",
  "danfe_url": null
}

Erros:invoice_issuer_mismatch test_order invalid_state idempotency_key_reuse

curl · createInvoice

curl -X POST "https://api.tfshop.cloud/v1/orders/o_1011/invoices" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "access_key": "35261011222333000181550010000150011000150019",
    "issued_at": "2026-10-28T14:10:00.000Z",
    "xml_url": "https://erp.exemplo.com.br/nfe/35261011222333000181550010000150011000150019.xml"
  }'

POST/orders/{order_id}/invoices/{access_key}/cancel

Report that the NF-e was cancelled at SEFAZ

invoices:writecancelInvoice

Pode publicarinvoice.cancelled

Parâmetros

Campo	Tipo	Descrição
order_idcaminhoObrigatório	string	Order id (o_…).
access_keycaminhoObrigatório	string	44-digit access key.

Corpo da requisição

Campo	Tipo	Descrição
reason	string	Justificativa sent to SEFAZ. máx. 255

Resposta 200

→ Invoice

Campo	Tipo	Descrição
order_idObrigatório	string	Order id.
numberObrigatório	integer	NF-e number (nNF).
seriesObrigatório	integer	NF-e series.
access_keyObrigatório	string	44-digit access key (chave de acesso). `^\d{6}[0-9A-Z]{14}\d{24}$`
issued_atObrigatório	string (date-time)	Issue date.
sourceObrigatório	string	tf_fiscal (issued by the store) or erp (posted by an app). Valores:`tf_fiscalerp`
statusObrigatório	string	authorized or cancelled. Valores:`authorizedcancelled`
xml_urlObrigatório	string \| null	Authorised XML.
danfe_urlObrigatório	string \| null	DANFE PDF.

Exemplo

json

{
  "order_id": "o_2005",
  "number": 1501,
  "series": 1,
  "access_key": "35261011222333000181550010000150011000150019",
  "issued_at": "2026-10-28T14:10:00.000Z",
  "source": "erp",
  "status": "authorized",
  "xml_url": "https://erp.exemplo.com.br/nfe/35261011222333000181550010000150011000150019.xml",
  "danfe_url": null
}

Erros:invoice_issuer_mismatch

curl · cancelInvoice

curl -X POST "https://api.tfshop.cloud/v1/orders/o_1011/invoices/35261011222333000181550010000010421304812756/cancel" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "string"
  }'

Envios

2 endpoints

POST/orders/{order_id}/fulfillments
POST/orders/{order_id}/fulfillments/delivered

POST/orders/{order_id}/fulfillments

Mark the order as shipped with carrier and tracking code

fulfillments:writeAceita Idempotency-KeycreateFulfillment

Requires an authorised NF-e or DC-e (the parcel cannot travel without a fiscal document). Correios codes are checked in S10 format with the check digit. Idempotent by tracking code; the buyer gets the shipped e-mail with the tracking link.

Pode publicarfulfillment.shipped

Parâmetros

Campo	Tipo	Descrição
order_idcaminhoObrigatório	string	Order id (o_…).

Corpo da requisição

Campo	Tipo	Descrição
carrierObrigatório	string	Carrier name (Correios, Jadlog, Loggi, J&T Express, Total Express or another).
service	string	Service (PAC, SEDEX…).
tracking_codeObrigatório	string	Tracking code. máx. 30
tracking_url	string (uri)	Carrier tracking URL, if any.

Resposta 201

→ Fulfillment

Campo	Tipo	Descrição
idObrigatório	string	Fulfillment id (`{order_id}:f1`).
order_idObrigatório	string	Order id.
statusObrigatório	string	shipped or delivered. Valores:`shippeddelivered`
carrierObrigatório	string	Carrier.
serviceObrigatório	string	Service.
tracking_codeObrigatório	string	Tracking code (Correios: S10 with a valid check digit).
tracking_urlObrigatório	string \| null	Public tracking page.
shipped_atObrigatório	string \| null (date-time)	When the order was marked as shipped.
delivered_atObrigatório	string \| null (date-time)	When it was delivered.

Exemplo

json

{
  "id": "o_1011:f1",
  "order_id": "o_1011",
  "status": "shipped",
  "carrier": "Correios",
  "service": "SEDEX",
  "tracking_code": "SS123456785BR",
  "tracking_url": "https://www.voltshop.com.br/rastreio/SS123456785BR",
  "shipped_at": "2026-10-28T16:00:00.000Z",
  "delivered_at": null
}

Erros:fiscal_document_required invalid_state idempotency_key_reuse

curl · createFulfillment

curl -X POST "https://api.tfshop.cloud/v1/orders/o_1011/fulfillments" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0b7c1e-8d2a-4c55-9a7e-1b2c3d4e5f60" \
  -d '{
    "carrier": "Correios",
    "service": "SEDEX",
    "tracking_code": "SS123456785BR"
  }'

POST/orders/{order_id}/fulfillments/delivered

Mark the order as delivered

fulfillments:writemarkDelivered

Pode publicarfulfillment.delivered

Parâmetros

Campo	Tipo	Descrição
order_idcaminhoObrigatório	string	Order id (o_…).

Corpo da requisição

Campo	Tipo	Descrição
delivered_at	string (date-time)	When it was delivered (ISO 8601); default now.

Resposta 200

→ Fulfillment

Campo	Tipo	Descrição
idObrigatório	string	Fulfillment id (`{order_id}:f1`).
order_idObrigatório	string	Order id.
statusObrigatório	string	shipped or delivered. Valores:`shippeddelivered`
carrierObrigatório	string	Carrier.
serviceObrigatório	string	Service.
tracking_codeObrigatório	string	Tracking code (Correios: S10 with a valid check digit).
tracking_urlObrigatório	string \| null	Public tracking page.
shipped_atObrigatório	string \| null (date-time)	When the order was marked as shipped.
delivered_atObrigatório	string \| null (date-time)	When it was delivered.

Exemplo

json

{
  "id": "o_1011:f1",
  "order_id": "o_1011",
  "status": "shipped",
  "carrier": "Correios",
  "service": "SEDEX",
  "tracking_code": "SS123456785BR",
  "tracking_url": "https://www.voltshop.com.br/rastreio/SS123456785BR",
  "shipped_at": "2026-10-28T16:00:00.000Z",
  "delivered_at": null
}

Erros:invalid_state

curl · markDelivered

curl -X POST "https://api.tfshop.cloud/v1/orders/o_1011/fulfillments/delivered" \
  -H "Authorization: Bearer $TFSHOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delivered_at": "2026-10-29T13:05:12.000Z"
  }'

Produtos

7 endpoints

GET/products
GET/products/{product_id}
POST/products
PATCH/products/{product_id}
DELETE/products/{product_id}
GET/variants
POST/prices/batch

GET/products

List products

products:readlistProducts

Sorted by updated_at, then id. Archived products are included (filter with status).

Parâmetros

Campo	Tipo	Descrição
updated_sinceconsulta	string (date-time)	Only objects changed at or after this instant (ISO 8601).
statusconsulta	string	active \| draft \| archived`activedraftarchived`
limitconsulta	integer	Page size, 1–100 (default 50).
cursorconsulta	string	Opaque cursor from `next_cursor`.

Resposta 200

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

Exemplo

json

{
  "data": [
    {
      "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
          }
        }
      ],
      "created_at": "2026-09-13T15:00:00.000Z",
      "updated_at": "2026-10-18T15:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

curl · listProducts

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

GET/products/{product_id}

Get a product with its variants

products:readgetProduct

Parâmetros

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

Resposta 200

→ Product

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.
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.
urlObrigatório	string	Public image URL.
altObrigatório	string \| null	Alt text.
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
      }
    }
  ],
  "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.
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.
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).
on_hand	integer	Initial stock. ≥ 0

Resposta 201

→ Product

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.
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.
urlObrigatório	string	Public image URL.
altObrigatório	string \| null	Alt text.
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
      }
    }
  ],
  "created_at": "2026-09-13T15:00:00.000Z",
  "updated_at": "2026-10-18T15:00:00.000Z"
}

Erros:sandbox_read_only idempotency_key_reuse

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 (title, description, status, fiscal data, dimensions)

products:writeupdateProduct

Pode publicarproduct.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.
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.

Resposta 200

→ Product

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.
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.
urlObrigatório	string	Public image URL.
altObrigatório	string \| null	Alt text.
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
      }
    }
  ],
  "created_at": "2026-09-13T15:00:00.000Z",
  "updated_at": "2026-10-18T15:00:00.000Z"
}

Erros:sandbox_read_only

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
  }'

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

→ Product

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.
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.
urlObrigatório	string	Public image URL.
altObrigatório	string \| null	Alt text.
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
      }
    }
  ],
  "created_at": "2026-09-13T15:00:00.000Z",
  "updated_at": "2026-10-18T15:00:00.000Z"
}

Erros:sandbox_read_only

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",
      "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",
      "inventory": {
        "on_hand": 0,
        "reserved": 0,
        "available": 0
      }
    }
  ]
}

Erros:sandbox_read_only idempotency_key_reuse

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"
    }
  ]
}

Erros:sandbox_read_only idempotency_key_reuse

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"
    }
  ]
}

Erros:sandbox_read_only idempotency_key_reuse

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"

Esquemas compartilhados

Objetos usados em várias respostas. Os campos marcados com → apontam para outro esquema.

Store

The store a token belongs to. Read it first: the NF-e issuer and the legal entity decide which operations apply.

Campo	Tipo	Descrição
idObrigatório	string	Store id (st_…). The token belongs to exactly one store.
nameObrigatório	string	Store name shown to shoppers.
slugObrigatório	string	Store slug ({slug}.tfshop.cloud and /s/{slug}).
urlObrigatório	string (uri)	Public storefront URL (primary domain).
statusObrigatório	string	draft (not public yet), published or paused. Valores:`draftpublishedpaused`
domainsObrigatório	object[]	Domains of the storefront.
hostnameObrigatório	string	Hostname.
typeObrigatório	string	subdomain (free) or custom. Valores:`subdomaincustom`
statusObrigatório	string	DNS / certificate status. Valores:`pending_dnsverifyingactiveerror`
primaryObrigatório	boolean	The canonical storefront address.
legalObrigatório	object
nameObrigatório	string	Legal name (razão social).
documentObrigatório	string	CNPJ (14 characters) or CPF (11 digits) of the seller, without punctuation. NF-e issuer (emit) when the store issues through TF Fiscal.
document_typeObrigatório	string	cnpj or cpf. Valores:`cnpjcpf`
state_registrationObrigatório	string \| null	Inscrição estadual (IE), digits only, or null.
addressObrigatório	object	Seller address (shown in the storefront footer, Decreto 7.962/2013).
zipObrigatório	string	CEP, 8 digits. `^\d{8}$`
streetObrigatório	string	Logradouro.
numberObrigatório	string	Número.
complementObrigatório	string \| null	Complemento.
districtObrigatório	string	Bairro.
cityObrigatório	string	Município.
stateObrigatório	string	UF. `^[A-Z]{2}$`
countryObrigatório	string	ISO 3166-1 alpha-2. Valores:`BR`
ibge_codeObrigatório	string \| null	7-digit IBGE municipality code, or null when unknown.
emailObrigatório	string	Customer-service e-mail.
phoneObrigatório	string	Phone in E.164 (+55…), or empty.
currencyObrigatório	string	Always BRL. Valores:`BRL`
timezoneObrigatório	string	Always America/Sao_Paulo. Valores:`America/Sao_Paulo`
localeObrigatório	string	Always pt-BR. Valores:`pt-BR`
invoice_issuerObrigatório	string	Who issues the NF-e: tf_fiscal (the store) or erp (apps post it with POST /orders/{order_id}/invoices). Valores:`tf_fiscalerp`
planObrigatório	object
idObrigatório	string	Plan id. Valores:`startbusinessadvancedenterprise`
nameObrigatório	string	Plan name.
limitsObrigatório	object
productsObrigatório	integer \| null	Max products; null = unlimited.
staffObrigatório	integer \| null	Max staff users; null = unlimited.
storesObrigatório	integer	Stores included.
orders_per_monthObrigatório	integer \| null	Max orders per month; null = unlimited.
storage_gbObrigatório	integer	Media storage in GB.
payment_methodsObrigatório	object	Methods the store's C6 account accepts at checkout.
pixObrigatório	boolean	Pix enabled.
credit_cardObrigatório	boolean	Credit card enabled.
boletoObrigatório	boolean	Boleto enabled.
shipping_origin_cepObrigatório	string \| null	CEP the parcels ship from (8 digits), or null when not configured.
created_atObrigatório	string (date-time)	Creation time.
published_atObrigatório	string \| null (date-time)	When the store went live, or null.

Exemplo

json

{
  "id": "st_volt",
  "name": "VoltShop",
  "slug": "voltshop",
  "url": "https://www.voltshop.com.br",
  "status": "published",
  "domains": [
    {
      "hostname": "voltshop.tfshop.cloud",
      "type": "subdomain",
      "status": "active",
      "primary": false
    },
    {
      "hostname": "www.voltshop.com.br",
      "type": "custom",
      "status": "active",
      "primary": true
    }
  ],
  "legal": {
    "name": "Volt Comércio de Eletrônicos Ltda",
    "document": "11222333000181",
    "document_type": "cnpj",
    "state_registration": "123456789110",
    "address": {
      "zip": "03016000",
      "street": "Rua Oriente",
      "number": "320",
      "complement": "Loja 4",
      "district": "Brás",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "ibge_code": "3550308"
    },
    "email": "atendimento@voltshop.com.br",
    "phone": "+551133112200"
  },
  "currency": "BRL",
  "timezone": "America/Sao_Paulo",
  "locale": "pt-BR",
  "invoice_issuer": "tf_fiscal",
  "plan": {
    "id": "business",
    "name": "Business",
    "limits": {
      "products": null,
      "staff": 5,
      "stores": 1,
      "orders_per_month": null,
      "storage_gb": 20
    }
  },
  "payment_methods": {
    "pix": true,
    "credit_card": true,
    "boleto": true
  },
  "shipping_origin_cep": "03016000",
  "created_at": "2026-09-13T15:00:00.000Z",
  "published_at": "2026-09-20T12:00:00.000Z"
}

Problem

RFC 9457 problem details, served as application/problem+json.

Campo	Tipo	Descrição
typeObrigatório	string (uri)	URL of the problem type (https://developers.tfshop.cloud/errors/<slug>).
titleObrigatório	string	Short summary of the problem type.
statusObrigatório	integer	HTTP status.
detail	string	What went wrong with this request.
instance	string	Request id (req_…), also in the X-Request-Id header.
errors	object[]	Field errors (validation_failed).
fieldObrigatório	string	JSON path of the field (items[2].sku).
messageObrigatório	string	Why it is invalid.

Exemplo

json

{
  "type": "https://developers.tfshop.cloud/errors/insufficient_scope",
  "title": "The token lacks the scope this operation requires",
  "status": 403,
  "detail": "This operation requires the invoices:write scope.",
  "instance": "req_Xk2mP9qL0aZt3w"
}

Address

Brazilian address. Without orders.pii:read, street, number, complement and district are masked and the CEP keeps only its first 5 digits.

Campo	Tipo	Descrição
zipObrigatório	string	CEP, 8 digits. `^\d{8}$`
streetObrigatório	string	Logradouro.
numberObrigatório	string	Número (may be "S/N").
complement	string \| null	Complemento.
districtObrigatório	string	Bairro.
cityObrigatório	string	Município.
stateObrigatório	string	UF. `^[A-Z]{2}$`
countryObrigatório	string	ISO 3166-1 alpha-2. Valores:`BR`
ibge_code	string \| null	7-digit IBGE municipality code (NF-e cMun); null when unknown. `^\d{7}$`

Buyer

NF-e recipient (dest).

Campo	Tipo	Descrição
typeObrigatório	string	PF (person) or PJ (company). Valores:`PFPJ`
nameObrigatório	string	Name or company name.
documentObrigatório	string	CPF (11 digits) or CNPJ (14 characters, may be alphanumeric), without punctuation.
document_typeObrigatório	string	cpf or cnpj. Valores:`cpfcnpj`
emailObrigatório	string	E-mail.
phoneObrigatório	string	Phone in E.164 (+55…).
state_registrationObrigatório	string \| null	Inscrição estadual (IE), when informed.
ie_indicatorObrigatório	integer	NF-e indIEDest: 1 contribuinte, 2 isento, 9 não contribuinte (always 9 for PF). Valores:`129`
maskedObrigatório	boolean	True when the token lacks orders.pii:read: name, document, e-mail and phone are masked.

OrderLine

Campo	Tipo	Descrição
line_idObrigatório	string	Stable line id (`{order_id}:{n}`), referenced by partial invoices, fulfillments and refunds.
product_idObrigatório	string	Product id.
variant_idObrigatório	string	Variant id.
skuObrigatório	string	SKU (the mapping key between the store and the ERP).
titleObrigatório	string	Product title at the time of the order.
variant_titleObrigatório	string	Variant title ("Preto / 2 m").
quantityObrigatório	integer	Quantity. ≥ 1
unit_priceObrigatório	integer	Unit price charged (wholesale / member price when applicable). In centavos. ≥ 0
list_priceObrigatório	integer	Retail unit price before wholesale / member pricing. In centavos. ≥ 0
discount_allocatedObrigatório	integer	Order discount allocated to the line (coupon + Pix), pro rata; the lines add up to the order discount. NF-e vDesc. In centavos. ≥ 0
freight_allocatedObrigatório	integer	Order freight allocated to the line, pro rata; the lines add up to the order freight. NF-e vFrete. In centavos. ≥ 0
totalObrigatório	integer	unit_price × quantity − discount_allocated + freight_allocated. In centavos. ≥ 0
ncmObrigatório	string \| null	NCM from the store's product data, as a hint (8 digits). Optional: the ERP's fiscal data prevails. `^\d{8}$`
cestObrigatório	string \| null	CEST hint (7 digits).
originObrigatório	integer	Origem da mercadoria (0–8) hint. 0 a 8
gtinObrigatório	string \| null	GTIN/EAN of the variant.

OrderShipping

Campo	Tipo	Descrição
carrierObrigatório	string	Carrier (Correios, Jadlog, Loggi…).
serviceObrigatório	string	Service (PAC, SEDEX, .Package…).
priceObrigatório	integer	Freight charged to the buyer. In centavos. ≥ 0
business_daysObrigatório	integer	Quoted transit time in business days.
tracking_codeObrigatório	string \| null	Tracking code once a label exists.
tracking_urlObrigatório	string \| null	Public tracking page.

Payment

Money goes straight to the merchant's own C6 account; refunds are made by the store.

Campo	Tipo	Descrição
methodObrigatório	string	Payment method. Valores:`pixcredit_cardboleto`
statusObrigatório	string	Payment status. Valores:`createdpendingconfirmedfailedexpiredcancelledrefund_pendingrefundedpartially_refunded`
paid_atObrigatório	string \| null (date-time)	When the payment was confirmed.
installmentsObrigatório	integer	Number of installments (1 for Pix and boleto). ≥ 1
nfe_payment_codeObrigatório	string	NF-e tPag: 17 Pix dinâmico, 03 cartão de crédito, 15 boleto. Valores:`170315`
card_brand	string \| null	Card brand (visa, mastercard, elo, amex, hipercard).
nfe_card_brand	string \| null	NF-e tBand (01 Visa, 02 Mastercard, 03 Amex, 06 Elo, 07 Hipercard, 99 other).
card_last4	string \| null	Last 4 digits of the card.
acquirer_cnpj	string \| null	CNPJ of the payment institution (NF-e card group CNPJ). Card and Pix only.
authorization_code	string \| null	Card authorisation code (NF-e cAut).
pix_end_to_end_id	string \| null	Pix end-to-end id (E + ISPB + timestamp + sequence).
providerObrigatório	string	Payment provider: c6, or manual when the merchant marked it as paid. Valores:`c6manual`
provider_payment_id	string \| null	Payment id at the provider.

FiscalHints

Campo	Tipo	Descrição
ind_presObrigatório	integer	NF-e indPres: 2 = internet. Valores:`2`
ind_intermedObrigatório	integer	NF-e indIntermed: 0 = own website (no marketplace intermediary). Valores:`01`
ind_finalObrigatório	integer	NF-e indFinal: 1 consumidor final, 0 resale (wholesale buyer buying to resell). Valores:`01`

Invoice

Campo	Tipo	Descrição
order_idObrigatório	string	Order id.
numberObrigatório	integer	NF-e number (nNF).
seriesObrigatório	integer	NF-e series.
access_keyObrigatório	string	44-digit access key (chave de acesso). `^\d{6}[0-9A-Z]{14}\d{24}$`
issued_atObrigatório	string (date-time)	Issue date.
sourceObrigatório	string	tf_fiscal (issued by the store) or erp (posted by an app). Valores:`tf_fiscalerp`
statusObrigatório	string	authorized or cancelled. Valores:`authorizedcancelled`
xml_urlObrigatório	string \| null	Authorised XML.
danfe_urlObrigatório	string \| null	DANFE PDF.

Exemplo

json

{
  "order_id": "o_2005",
  "number": 1501,
  "series": 1,
  "access_key": "35261011222333000181550010000150011000150019",
  "issued_at": "2026-10-28T14:10:00.000Z",
  "source": "erp",
  "status": "authorized",
  "xml_url": "https://erp.exemplo.com.br/nfe/35261011222333000181550010000150011000150019.xml",
  "danfe_url": null
}

OrderExportStatus

This app's export acknowledgement (each app has its own).

Campo	Tipo	Descrição
acknowledged_atObrigatório	string (date-time)	When this app acknowledged the order.
external_idObrigatório	string \| null	Order id in the app's system.

Order

NF-e-ready order payload.

Campo	Tipo	Descrição
idObrigatório	string	Order id (immutable). Use it as the unique key in your system.
numberObrigatório	integer	Order number shown to the buyer and the merchant (#1011).
created_atObrigatório	string (date-time)	Creation time.
updated_atObrigatório	string (date-time)	Last change (latest timeline entry). Use with `updated_since`.
statusObrigatório	string	Order status. Valores:`pending_paymentpaidfulfillingfulfilledcancelledexpiredreturn_requestedrefundedpartially_refunded`
payment_statusObrigatório	string	Payment status (see Payment.status).
fulfillment_statusObrigatório	string	Fulfillment status. Valores:`unfulfilledlabel_purchasedshippeddeliveredreturned`
invoice_statusObrigatório	string	NF-e status. Valores:`not_requiredpendingauthorizederrorcancelled`
testObrigatório	boolean	Test order placed by the merchant: never issue an NF-e for it.
channelObrigatório	string	Sales channel. Valores:`online_storewhatsappmanualvendedormercado_livreshopeetiktok_shop`
currencyObrigatório	string	Always BRL. Valores:`BRL`
subtotalObrigatório	integer	Sum of the lines (unit_price × quantity). In centavos. ≥ 0
discountObrigatório	integer	Coupon + Pix discount. In centavos. ≥ 0
shipping_totalObrigatório	integer	Freight charged (same as shipping.price). In centavos. ≥ 0
totalObrigatório	integer	subtotal − discount + shipping_total. In centavos. ≥ 0
refundedObrigatório	integer	Refunded so far. In centavos. ≥ 0
buyerObrigatório	→ Buyer	NF-e recipient (dest).
shipping_addressObrigatório	→ Address	Brazilian address. Without `orders.pii:read`, street, number, complement and district are masked and the CEP keeps only its first 5 digits.
billing_addressObrigatório	→ Address	Same as the shipping address in v1 (the checkout has a single address).
linesObrigatório	→ OrderLine[]	Order lines.
shippingObrigatório	→ OrderShipping
paymentObrigatório	→ Payment	Money goes straight to the merchant's own C6 account; refunds are made by the store.
fiscal_hintsObrigatório	→ FiscalHints
invoiceObrigatório	→ Invoice \| null	Current NF-e, or null.
exportObrigatório	→ OrderExportStatus \| null	This app's acknowledgement, or null when not yet imported.

Exemplo

json

{
  "id": "o_1011",
  "number": 1011,
  "created_at": "2026-10-26T12:00:00.000Z",
  "updated_at": "2026-10-26T12:00:00.000Z",
  "status": "paid",
  "payment_status": "confirmed",
  "fulfillment_status": "unfulfilled",
  "invoice_status": "pending",
  "test": false,
  "channel": "online_store",
  "currency": "BRL",
  "subtotal": 19990,
  "discount": 0,
  "shipping_total": 0,
  "total": 19990,
  "refunded": 0,
  "buyer": {
    "type": "PF",
    "name": "Juliana Martins",
    "document": "12345678909",
    "document_type": "cpf",
    "email": "juliana@exemplo.com.br",
    "phone": "+5519981234567",
    "state_registration": null,
    "ie_indicator": 9,
    "masked": false
  },
  "shipping_address": {
    "zip": "13010111",
    "street": "Rua Barão de Jaguara",
    "number": "100",
    "complement": null,
    "district": "Centro",
    "city": "Campinas",
    "state": "SP",
    "country": "BR",
    "ibge_code": "3509502"
  },
  "billing_address": {
    "zip": "13010111",
    "street": "Rua Barão de Jaguara",
    "number": "100",
    "complement": null,
    "district": "Centro",
    "city": "Campinas",
    "state": "SP",
    "country": "BR",
    "ibge_code": "3509502"
  },
  "lines": [
    {
      "line_id": "o_1011:1",
      "product_id": "p_pb_20k",
      "variant_id": "p_pb_20k_v1",
      "sku": "VLT-PB20K",
      "title": "Power Bank 20.000 mAh 22,5W",
      "variant_title": "Padrão",
      "quantity": 1,
      "unit_price": 19990,
      "list_price": 19990,
      "discount_allocated": 0,
      "freight_allocated": 0,
      "total": 19990,
      "ncm": "85076000",
      "cest": null,
      "origin": 2,
      "gtin": "7891000079190"
    }
  ],
  "shipping": {
    "carrier": "Correios",
    "service": "SEDEX",
    "price": 0,
    "business_days": 2,
    "tracking_code": null,
    "tracking_url": null
  },
  "payment": {
    "method": "credit_card",
    "status": "confirmed",
    "paid_at": "2026-10-26T12:00:00.000Z",
    "installments": 2,
    "nfe_payment_code": "03",
    "card_brand": "visa",
    "nfe_card_brand": "01",
    "card_last4": "8407",
    "acquirer_cnpj": "31872495000172",
    "authorization_code": "482913",
    "pix_end_to_end_id": null,
    "provider": "c6",
    "provider_payment_id": "c6_card_1011"
  },
  "fiscal_hints": {
    "ind_pres": 2,
    "ind_intermed": 0,
    "ind_final": 1
  },
  "invoice": null,
  "export": {
    "acknowledged_at": "2026-10-26T12:05:00.000Z",
    "external_id": "11011"
  }
}

InventoryLevel

Campo	Tipo	Descrição
skuObrigatório	string	SKU.
variant_idObrigatório	string	Variant id.
product_idObrigatório	string	Product id.
on_handObrigatório	integer	Units in stock. ≥ 0
reservedObrigatório	integer	Units held by unpaid Pix / boleto orders. ≥ 0
availableObrigatório	integer	on_hand − reserved (never below 0): what the storefront sells. ≥ 0
updated_atObrigatório	string (date-time)	Last stock change.

Exemplo

json

{
  "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"
}

Variant

Campo	Tipo	Descrição
idObrigatório	string	Variant id.
product_idObrigatório	string	Product id.
skuObrigatório	string	SKU, unique in the store.
titleObrigatório	string	"Preto / 2 m" ("Padrão" for products without options).
optionsObrigatório	map<string>	Option values by option name ({"Cor": "Preto"}).
priceObrigatório	integer	Retail price. In centavos. ≥ 0
compare_at_priceObrigatório	integer \| null	"De" price shown struck through (centavos), or null. ≥ 0
gtinObrigatório	string \| null	GTIN/EAN.
inventoryObrigatório	object
on_handObrigatório	integer	Units in stock.
reservedObrigatório	integer	Units held by unpaid orders.
availableObrigatório	integer	on_hand − reserved.

Product

The store is the source of truth for products, prices and stock.

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.
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.
urlObrigatório	string	Public image URL.
altObrigatório	string \| null	Alt text.
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
      }
    }
  ],
  "created_at": "2026-09-13T15:00:00.000Z",
  "updated_at": "2026-10-18T15:00:00.000Z"
}

Fulfillment

Campo	Tipo	Descrição
idObrigatório	string	Fulfillment id (`{order_id}:f1`).
order_idObrigatório	string	Order id.
statusObrigatório	string	shipped or delivered. Valores:`shippeddelivered`
carrierObrigatório	string	Carrier.
serviceObrigatório	string	Service.
tracking_codeObrigatório	string	Tracking code (Correios: S10 with a valid check digit).
tracking_urlObrigatório	string \| null	Public tracking page.
shipped_atObrigatório	string \| null (date-time)	When the order was marked as shipped.
delivered_atObrigatório	string \| null (date-time)	When it was delivered.

Exemplo

json

{
  "id": "o_1011:f1",
  "order_id": "o_1011",
  "status": "shipped",
  "carrier": "Correios",
  "service": "SEDEX",
  "tracking_code": "SS123456785BR",
  "tracking_url": "https://www.voltshop.com.br/rastreio/SS123456785BR",
  "shipped_at": "2026-10-28T16:00:00.000Z",
  "delivered_at": null
}

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.

Event

Thin payload: fetch the object with GET to read its current state (access checked against your scopes).

Campo	Tipo	Descrição
idObrigatório	string	Event id (evt_…), also the webhook-id header: deduplicate with it.
typeObrigatório	string	Event type. Valores:`order.createdorder.paidorder.updatedorder.cancelledrefund.completedinvoice.authorizedinvoice.cancelledfulfillment.shippedfulfillment.deliveredproduct.createdproduct.updatedproduct.deletedinventory.updatedapp.uninstalled`
timestampObrigatório	string (date-time)	When the change happened.
api_versionObrigatório	string	API version of the payload. Valores:`v1`
store_idObrigatório	string	Store id.
actorObrigatório	object
typeObrigatório	string	Who caused the change. Valores:`storebuyerappsystem`
app_idObrigatório	string \| null	App that caused it: ignore your own echoes.
dataObrigatório	object
objectObrigatório	string	Object type. Valores:`orderproductinventory_levelinvoicefulfillmentapp`
idObrigatório	string	Object id (order id, product id, variant id, NF-e access key, fulfillment id, installation id).
reference	string \| null	Human reference: order number, SKU, product handle or tracking code. Never personal data.
status	string \| null	Object status after the change.
test	boolean	Test order: skip it unless you are testing.
order_id	string \| null	Parent order of invoice and fulfillment events.

Exemplo

json

{
  "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
  }
}