{"openapi":"3.1.0","info":{"title":"TF Shop Cloud API","version":"1.0.0","summary":"Orders, products, stock, NF-e and webhooks of a TF Shop Cloud store.","description":"One public REST API for every integration: external ERPs, TF's own Bling and Tiny connectors and TF ERP use the same endpoints, scopes, limits and webhooks.\n\n- **Authentication**: `Authorization: Bearer <token>`. Tokens are bound to one store; `tfs_live_…` tokens act on real data, `tfs_test_…` (sandbox) tokens only see test orders and cannot change products, prices or stock.\n- **Scopes**: each operation lists its scope in `x-required-scope`. Without `orders.pii:read`, buyer name, document, e-mail, phone and address are masked.\n- **Format**: JSON in snake_case; money in integer centavos (BRL); dates in ISO 8601 (UTC).\n- **Pagination**: lists return `{ \"data\": [...], \"next_cursor\": \"…\" | null }`; pass `cursor` to get the next page, `limit` 1–100 (default 50).\n- **Errors**: RFC 9457 `application/problem+json` with `type` = https://developers.tfshop.cloud/errors/<slug>.\n- **Idempotency**: operations marked idempotent accept an `Idempotency-Key` header (kept 24 h). The same key with the same request returns the stored response with `Idempotent-Replayed: true`; with a different request, 422 `idempotency_key_reuse`.\n- **Rate limit**: token bucket per token, 5 requests per second sustained, bursts of 50. Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`; 429 responses carry `Retry-After`.\n- **Webhooks**: Standard Webhooks signatures (`webhook-id`, `webhook-timestamp`, `webhook-signature` = `v1,<base64 HMAC-SHA256 of \"{id}.{timestamp}.{body}\">` keyed with the base64-decoded secret after `whsec_`). At least once, unordered: deduplicate by `webhook-id`, ignore events whose `actor.app_id` is your own app, and GET the object for its current state. Retries after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h.\n- **NF-e**: one issuer per store. When the store issues with TF Fiscal, `POST /orders/{order_id}/invoices` answers 409 `invoice_issuer_mismatch`.","contact":{"name":"TF Shop Cloud — desenvolvedores","url":"https://developers.tfshop.cloud","email":"integracoes@tfsoftware.com.br"},"license":{"name":"Proprietary — TF Shop Cloud API terms","url":"https://developers.tfshop.cloud/termos"}},"servers":[{"url":"https://api.tfshop.cloud/v1","description":"Production. Sandbox: the same URL with a tfs_test_ token (test orders only, read-only catalog)."}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Store","description":"The store the token belongs to: legal entity, NF-e issuer, plan limits, payment methods."},{"name":"Products","description":"Products, variants and prices. The store is the source of truth; writes are attributed to the calling app."},{"name":"Inventory","description":"Stock levels by SKU: on hand, reserved by unpaid orders, available."},{"name":"Orders","description":"Orders with an NF-e-ready payload, incremental sync and per-app export acknowledgement."},{"name":"Invoices","description":"NF-e posted back by the ERP (only when the store's NF-e issuer is the ERP)."},{"name":"Fulfillments","description":"Carrier and tracking code, delivery."},{"name":"Webhooks","description":"Webhook endpoints of the calling app or token."},{"name":"Events","description":"30-day event list to catch up after downtime."}],"paths":{"/store":{"get":{"operationId":"getStore","tags":["Store"],"summary":"Get the connected store","description":"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.\n\nRequired scope: `store:read`.","x-required-scope":"store:read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/products":{"get":{"operationId":"listProducts","tags":["Products"],"summary":"List products","description":"Sorted by `updated_at`, then id. Archived products are included (filter with `status`).\n\nRequired scope: `products:read`.","x-required-scope":"products:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"updated_since","in":"query","required":false,"description":"Only objects changed at or after this instant (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","required":false,"description":"active | draft | archived","schema":{"type":"string","enum":["active","draft","archived"]}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100 (default 50).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `next_cursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"description":"Page of Product objects."},"next_cursor":{"type":["string","null"],"description":"Cursor of the next page; null on the last page."}},"required":["data","next_cursor"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}},"post":{"operationId":"createProduct","tags":["Products"],"summary":"Create a product","description":"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).\n\nRequired scope: `products:write`.","x-required-scope":"products:write","x-emits-events":["product.created","inventory.updated"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Title.","minLength":1,"maxLength":150},"description":{"type":"string","description":"Plain-text description."},"status":{"type":"string","description":"Default draft.","enum":["active","draft","archived"]},"category_id":{"type":["string","null"],"description":"Category id of the store."},"brand":{"type":["string","null"],"description":"Brand."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags."},"fiscal":{"type":"object","properties":{"ncm":{"type":["string","null"],"description":"NCM, 8 digits (optional).","pattern":"^\\d{8}$"},"cest":{"type":["string","null"],"description":"CEST, 7 digits."},"origin":{"type":"integer","description":"Origem (0–8).","minimum":0,"maximum":8}}},"weight_grams":{"type":"integer","description":"Weight in grams.","minimum":0},"dimensions_cm":{"type":"object","properties":{"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}}},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS image URL.","format":"uri"},"alt":{"type":["string","null"],"description":"Alt text."}},"required":["url"]},"description":"Gallery."},"variants":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","description":"SKU, unique in the store.","minLength":1,"maxLength":60},"title":{"type":"string","description":"Variant title; defaults to the option values joined by \" / \"."},"options":{"type":"object","additionalProperties":{"type":"string"},"description":"Option values ({\"Cor\": \"Preto\"})."},"price":{"type":"integer","description":"Retail price in centavos (> 0).","minimum":1},"compare_at_price":{"type":["integer","null"],"description":"\"De\" price in centavos, above price.","minimum":1},"gtin":{"type":["string","null"],"description":"GTIN/EAN (8, 12, 13 or 14 digits)."},"on_hand":{"type":"integer","description":"Initial stock.","minimum":0}},"required":["sku","price"]},"description":"Variants (1–100).","minItems":1,"maxItems":100}},"required":["title","variants"],"example":{"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}]}},"example":{"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}]}}}},"responses":{"201":{"description":"Success. A replayed idempotent request has the header Idempotent-Replayed: true.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `sandbox_read_only`: Sandbox tokens cannot change products, prices or stock. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`idempotency_key_reuse`: Idempotency-Key reused with a different request. `validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/idempotency_key_reuse","title":"Idempotency-Key reused with a different request","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/products/{product_id}":{"get":{"operationId":"getProduct","tags":["Products"],"summary":"Get a product with its variants","description":"Required scope: `products:read`.","x-required-scope":"products:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"product_id","in":"path","required":true,"description":"Product id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}},"patch":{"operationId":"updateProduct","tags":["Products"],"summary":"Update a product (title, description, status, fiscal data, dimensions)","description":"Required scope: `products:write`.","x-required-scope":"products:write","x-emits-events":["product.updated"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"product_id","in":"path","required":true,"description":"Product id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Title.","minLength":1,"maxLength":150},"description":{"type":"string","description":"Plain-text description."},"status":{"type":"string","description":"Default draft.","enum":["active","draft","archived"]},"category_id":{"type":["string","null"],"description":"Category id of the store."},"brand":{"type":["string","null"],"description":"Brand."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags."},"fiscal":{"type":"object","properties":{"ncm":{"type":["string","null"],"description":"NCM, 8 digits (optional).","pattern":"^\\d{8}$"},"cest":{"type":["string","null"],"description":"CEST, 7 digits."},"origin":{"type":"integer","description":"Origem (0–8).","minimum":0,"maximum":8}}},"weight_grams":{"type":"integer","description":"Weight in grams.","minimum":0},"dimensions_cm":{"type":"object","properties":{"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}}},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS image URL.","format":"uri"},"alt":{"type":["string","null"],"description":"Alt text."}},"required":["url"]},"description":"Gallery."}},"description":"Only the fields sent are changed. Prices and stock have their own endpoints.","example":{"fiscal":{"ncm":"85044010","cest":"2106400"},"weight_grams":150}},"example":{"fiscal":{"ncm":"85044010","cest":"2106400"},"weight_grams":150}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `sandbox_read_only`: Sandbox tokens cannot change products, prices or stock. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}},"delete":{"operationId":"deleteProduct","tags":["Products"],"summary":"Archive a product","description":"Products are archived, never erased: past orders keep pointing at them.\n\nRequired scope: `products:write`.","x-required-scope":"products:write","x-emits-events":["product.deleted"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"product_id","in":"path","required":true,"description":"Product id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `sandbox_read_only`: Sandbox tokens cannot change products, prices or stock. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/variants":{"get":{"operationId":"listVariants","tags":["Products"],"summary":"Look variants up by SKU","description":"Required scope: `products:read`.","x-required-scope":"products:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"sku","in":"query","required":false,"description":"One or more SKUs, comma-separated (max 100).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100 (default 50).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `next_cursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Variant"},"description":"Page of Variant objects."},"next_cursor":{"type":["string","null"],"description":"Cursor of the next page; null on the last page."}},"required":["data","next_cursor"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/prices/batch":{"post":{"operationId":"updateVariantPrices","tags":["Products"],"summary":"Set retail and compare-at prices by SKU (up to 100)","description":"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).\n\nRequired scope: `products:write`.","x-required-scope":"products:write","x-emits-events":["product.updated"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","description":"SKU."},"price":{"type":"integer","description":"Retail price in centavos (> 0).","minimum":1},"compare_at_price":{"type":["integer","null"],"description":"\"De\" price, or null to remove it.","minimum":1}},"required":["sku","price"]},"description":"Up to 100 SKUs. The batch is applied all or nothing.","minItems":1,"maxItems":100}},"required":["items"],"example":{"items":[{"sku":"VLT-GAN65W","price":16990,"compare_at_price":21990},{"sku":"VLT-CHARGER20","price":6490}]}},"example":{"items":[{"sku":"VLT-GAN65W","price":16990,"compare_at_price":21990},{"sku":"VLT-CHARGER20","price":6490}]}}}},"responses":{"200":{"description":"Success. A replayed idempotent request has the header Idempotent-Replayed: true.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Variant"},"description":"Updated Variant objects, in request order."}},"required":["data"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `sandbox_read_only`: Sandbox tokens cannot change products, prices or stock. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`idempotency_key_reuse`: Idempotency-Key reused with a different request. `validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/idempotency_key_reuse","title":"Idempotency-Key reused with a different request","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/inventory_levels":{"get":{"operationId":"listInventoryLevels","tags":["Inventory"],"summary":"List stock levels (on hand, reserved, available) by SKU","description":"Required scope: `inventory:read`.","x-required-scope":"inventory:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"sku","in":"query","required":false,"description":"SKUs, comma-separated (max 100).","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"Only objects changed at or after this instant (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100 (default 50).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `next_cursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLevel"},"description":"Page of InventoryLevel objects."},"next_cursor":{"type":["string","null"],"description":"Cursor of the next page; null on the last page."}},"required":["data","next_cursor"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/inventory_levels/set":{"post":{"operationId":"setInventoryLevels","tags":["Inventory"],"summary":"Set absolute on-hand quantities by SKU (up to 100, e.g. after a stock count)","description":"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).\n\nRequired scope: `inventory:write`.","x-required-scope":"inventory:write","x-emits-events":["inventory.updated"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","description":"SKU."},"on_hand":{"type":"integer","description":"Absolute units in stock.","minimum":0}},"required":["sku","on_hand"]},"description":"Up to 100 SKUs, all or nothing.","minItems":1,"maxItems":100}},"required":["items"],"example":{"items":[{"sku":"VLT-GAN65W","on_hand":40}]}},"example":{"items":[{"sku":"VLT-GAN65W","on_hand":40}]}}}},"responses":{"200":{"description":"Success. A replayed idempotent request has the header Idempotent-Replayed: true.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLevel"},"description":"Updated InventoryLevel objects, in request order."}},"required":["data"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `sandbox_read_only`: Sandbox tokens cannot change products, prices or stock. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`idempotency_key_reuse`: Idempotency-Key reused with a different request. `validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/idempotency_key_reuse","title":"Idempotency-Key reused with a different request","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/inventory_levels/adjust":{"post":{"operationId":"adjustInventory","tags":["Inventory"],"summary":"Add or remove units by SKU with a reason (up to 100)","description":"Send an Idempotency-Key header to retry safely (only 2xx responses are stored; after fixing an error, retry with the same key).\n\nRequired scope: `inventory:write`.","x-required-scope":"inventory:write","x-emits-events":["inventory.updated"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","description":"SKU."},"delta":{"type":"integer","description":"Units to add (positive) or remove (negative); on_hand never goes below 0."},"reason":{"type":"string","description":"Why (\"recebimento NF 1234\", \"avaria\", \"inventário\").","minLength":1,"maxLength":120}},"required":["sku","delta","reason"]},"description":"Up to 100 SKUs, all or nothing.","minItems":1,"maxItems":100}},"required":["items"],"example":{"items":[{"sku":"VLT-GAN65W","delta":24,"reason":"Recebimento NF 88213"}]}},"example":{"items":[{"sku":"VLT-GAN65W","delta":24,"reason":"Recebimento NF 88213"}]}}}},"responses":{"200":{"description":"Success. A replayed idempotent request has the header Idempotent-Replayed: true.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLevel"},"description":"Updated InventoryLevel objects, in request order."}},"required":["data"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `sandbox_read_only`: Sandbox tokens cannot change products, prices or stock. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`idempotency_key_reuse`: Idempotency-Key reused with a different request. `validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/idempotency_key_reuse","title":"Idempotency-Key reused with a different request","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/orders":{"get":{"operationId":"listOrders","tags":["Orders"],"summary":"List orders","description":"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.\n\nRequired scope: `orders:read`.","x-required-scope":"orders:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"updated_since","in":"query","required":false,"description":"Only objects changed at or after this instant (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","required":false,"description":"Order status (comma-separated for several).","schema":{"type":"string"}},{"name":"export_status","in":"query","required":false,"description":"pending | acknowledged (per app).","schema":{"type":"string","enum":["pending","acknowledged"]}},{"name":"include_test","in":"query","required":false,"description":"Include test orders (default false).","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100 (default 50).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `next_cursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"},"description":"Page of Order objects."},"next_cursor":{"type":["string","null"],"description":"Cursor of the next page; null on the last page."}},"required":["data","next_cursor"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/orders/{order_id}":{"get":{"operationId":"getOrder","tags":["Orders"],"summary":"Get an order (NF-e-ready payload)","description":"Buyer personal data requires `orders.pii:read`; without it, name, document, e-mail, phone and address are masked.\n\nRequired scope: `orders:read`.","x-required-scope":"orders:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"description":"Order id (o_…).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/orders/{order_id}/acknowledge":{"post":{"operationId":"acknowledgeOrder","tags":["Orders"],"summary":"Mark the order as imported by this app","description":"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.\n\nRequired scope: `orders:write`.","x-required-scope":"orders:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"description":"Order id (o_…).","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string","description":"Order id in your system (\"Bling pedido 10293\").","maxLength":64}},"example":{"external_id":"10293"}},"example":{"external_id":"10293"}}}},"responses":{"200":{"description":"Success. A replayed idempotent request has the header Idempotent-Replayed: true.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","description":"Order id."},"acknowledged_at":{"type":"string","format":"date-time","description":"First acknowledgement."},"external_id":{"type":["string","null"],"description":"Id in your system."}},"required":["order_id","acknowledged_at","external_id"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`idempotency_key_reuse`: Idempotency-Key reused with a different request. `validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/idempotency_key_reuse","title":"Idempotency-Key reused with a different request","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/orders/{order_id}/cancel":{"post":{"operationId":"cancelOrder","tags":["Orders"],"summary":"Cancel an unpaid order, or request cancellation of a paid one","description":"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).\n\nRequired scope: `orders:write`.","x-required-scope":"orders:write","x-emits-events":["order.cancelled","order.updated"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"description":"Order id (o_…).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Why (out of stock, fraud review…).","maxLength":200}},"example":{"reason":"Sem estoque no depósito"}},"example":{"reason":"Sem estoque no depósito"}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","description":"Order id."},"status":{"type":"string","description":"cancelled or cancellation_requested.","enum":["cancelled","cancellation_requested"]}},"required":["order_id","status"]}}}},"202":{"description":"Paid order: cancellation requested (the merchant decides and refunds in the store).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","description":"Order id."},"status":{"type":"string","description":"cancelled or cancellation_requested.","enum":["cancelled","cancellation_requested"]}},"required":["order_id","status"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"409":{"description":"`invalid_state`: The resource is not in a state that allows this operation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/invalid_state","title":"The resource is not in a state that allows this operation","status":409,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/orders/{order_id}/invoices":{"post":{"operationId":"createInvoice","tags":["Invoices"],"summary":"Post the NF-e issued by the ERP","description":"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.\n\nRequired scope: `invoices:write`.","x-required-scope":"invoices:write","x-emits-events":["invoice.authorized"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"description":"Order id (o_…).","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"access_key":{"type":"string","description":"44-digit access key.","pattern":"^\\d{6}[0-9A-Z]{14}\\d{24}$"},"number":{"type":"integer","description":"nNF (checked against the key when sent)."},"series":{"type":"integer","description":"Series (checked against the key when sent)."},"issued_at":{"type":"string","description":"Issue date (ISO 8601).","format":"date-time"},"xml_url":{"type":"string","description":"HTTPS URL of the authorised XML.","format":"uri"},"danfe_url":{"type":"string","description":"HTTPS URL of the DANFE.","format":"uri"}},"required":["access_key"],"example":{"access_key":"35261011222333000181550010000150011000150019","issued_at":"2026-10-28T14:10:00.000Z","xml_url":"https://erp.exemplo.com.br/nfe/35261011222333000181550010000150011000150019.xml"}},"example":{"access_key":"35261011222333000181550010000150011000150019","issued_at":"2026-10-28T14:10:00.000Z","xml_url":"https://erp.exemplo.com.br/nfe/35261011222333000181550010000150011000150019.xml"}}}},"responses":{"200":{"description":"Already registered with the same access key / tracking code (idempotent).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"201":{"description":"Success. A replayed idempotent request has the header Idempotent-Replayed: true.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"409":{"description":"`invoice_issuer_mismatch`: The store does not accept NF-e from apps. `test_order`: Test orders do not accept fiscal documents from live tokens. `invalid_state`: The resource is not in a state that allows this operation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/invoice_issuer_mismatch","title":"The store does not accept NF-e from apps","status":409,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`idempotency_key_reuse`: Idempotency-Key reused with a different request. `validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/idempotency_key_reuse","title":"Idempotency-Key reused with a different request","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/orders/{order_id}/invoices/{access_key}/cancel":{"post":{"operationId":"cancelInvoice","tags":["Invoices"],"summary":"Report that the NF-e was cancelled at SEFAZ","description":"Required scope: `invoices:write`.","x-required-scope":"invoices:write","x-emits-events":["invoice.cancelled"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"description":"Order id (o_…).","schema":{"type":"string"}},{"name":"access_key","in":"path","required":true,"description":"44-digit access key.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Justificativa sent to SEFAZ.","maxLength":255}}}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"409":{"description":"`invoice_issuer_mismatch`: The store does not accept NF-e from apps","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/invoice_issuer_mismatch","title":"The store does not accept NF-e from apps","status":409,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/orders/{order_id}/fulfillments":{"post":{"operationId":"createFulfillment","tags":["Fulfillments"],"summary":"Mark the order as shipped with carrier and tracking code","description":"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.\n\nRequired scope: `fulfillments:write`.","x-required-scope":"fulfillments:write","x-emits-events":["fulfillment.shipped"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"description":"Order id (o_…).","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrier":{"type":"string","description":"Carrier name (Correios, Jadlog, Loggi, J&T Express, Total Express or another).","minLength":1},"service":{"type":"string","description":"Service (PAC, SEDEX…)."},"tracking_code":{"type":"string","description":"Tracking code.","minLength":6,"maxLength":30},"tracking_url":{"type":"string","description":"Carrier tracking URL, if any.","format":"uri"}},"required":["carrier","tracking_code"],"example":{"carrier":"Correios","service":"SEDEX","tracking_code":"SS123456785BR"}},"example":{"carrier":"Correios","service":"SEDEX","tracking_code":"SS123456785BR"}}}},"responses":{"200":{"description":"Already registered with the same access key / tracking code (idempotent).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fulfillment"}}}},"201":{"description":"Success. A replayed idempotent request has the header Idempotent-Replayed: true.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fulfillment"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"409":{"description":"`fiscal_document_required`: The order needs an authorised NF-e or DC-e before shipping. `invalid_state`: The resource is not in a state that allows this operation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/fiscal_document_required","title":"The order needs an authorised NF-e or DC-e before shipping","status":409,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`idempotency_key_reuse`: Idempotency-Key reused with a different request. `validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/idempotency_key_reuse","title":"Idempotency-Key reused with a different request","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/orders/{order_id}/fulfillments/delivered":{"post":{"operationId":"markDelivered","tags":["Fulfillments"],"summary":"Mark the order as delivered","description":"Required scope: `fulfillments:write`.","x-required-scope":"fulfillments:write","x-emits-events":["fulfillment.delivered"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"description":"Order id (o_…).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","description":"When it was delivered (ISO 8601); default now.","format":"date-time"}}}}}},"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fulfillment"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"409":{"description":"`invalid_state`: The resource is not in a state that allows this operation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/invalid_state","title":"The resource is not in a state that allows this operation","status":409,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/webhook_endpoints":{"get":{"operationId":"listWebhookEndpoints","tags":["Webhooks"],"summary":"List webhook endpoints of this app or token","description":"Required scope: `webhooks:manage`.","x-required-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"},"description":"Page of WebhookEndpoint objects."},"next_cursor":{"type":["string","null"],"description":"Cursor of the next page; null on the last page."}},"required":["data","next_cursor"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}},"post":{"operationId":"createWebhookEndpoint","tags":["Webhooks"],"summary":"Subscribe a URL to events (returns the signing secret once)","description":"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).\n\nRequired scope: `webhooks:manage`.","x-required-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS URL.","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["order.created","order.paid","order.updated","order.cancelled","refund.completed","invoice.authorized","invoice.cancelled","fulfillment.shipped","fulfillment.delivered","product.created","product.updated","product.deleted","inventory.updated","app.uninstalled"]},"description":"Event types.","minItems":1},"description":{"type":"string","description":"Free text.","maxLength":120}},"required":["url","events"],"example":{"url":"https://erp.exemplo.com.br/webhooks/tfshop","events":["order.paid","order.cancelled"],"description":"ERP produção"}},"example":{"url":"https://erp.exemplo.com.br/webhooks/tfshop","events":["order.paid","order.cancelled"],"description":"ERP produção"}}}},"responses":{"201":{"description":"Success. A replayed idempotent request has the header Idempotent-Replayed: true.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`idempotency_key_reuse`: Idempotency-Key reused with a different request. `validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/idempotency_key_reuse","title":"Idempotency-Key reused with a different request","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/webhook_endpoints/{endpoint_id}":{"delete":{"operationId":"deleteWebhookEndpoint","tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Required scope: `webhooks:manage`.","x-required-scope":"webhooks:manage","security":[{"bearerAuth":[]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"we_…","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires. `app_suspended`: The app was suspended by TF Shop Cloud","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"404":{"description":"`not_found`: Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/not_found","title":"Resource not found","status":404,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}},"/events":{"get":{"operationId":"listEvents","tags":["Events"],"summary":"List events of the last 30 days (catch up after downtime)","description":"Oldest first. Only event types your scopes can read are listed.\n\nRequired scope: `orders:read`.","x-required-scope":"orders:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","required":false,"description":"Event type filter (comma-separated).","schema":{"type":"string"}},{"name":"created_since","in":"query","required":false,"description":"ISO 8601.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100 (default 50).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `next_cursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"},"description":"Page of Event objects."},"next_cursor":{"type":["string","null"],"description":"Cursor of the next page; null on the last page."}},"required":["data","next_cursor"]}}}},"401":{"description":"`unauthorized`: Missing, unknown or revoked API token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/unauthorized","title":"Missing, unknown or revoked API token","status":401,"instance":"req_Xk2mP9qL0aZt3w"}}}},"403":{"description":"`insufficient_scope`: The token lacks the scope this operation requires","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/insufficient_scope","title":"The token lacks the scope this operation requires","status":403,"instance":"req_Xk2mP9qL0aZt3w"}}}},"422":{"description":"`validation_failed`: The request has invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/validation_failed","title":"The request has invalid fields","status":422,"instance":"req_Xk2mP9qL0aZt3w"}}}},"429":{"description":"`rate_limited`: Too many requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://developers.tfshop.cloud/errors/rate_limited","title":"Too many requests","status":429,"instance":"req_Xk2mP9qL0aZt3w"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}}}}},"webhooks":{"order.created":{"post":{"operationId":"webhook_order_created","summary":"order.created","description":"Sent to endpoints subscribed to `order.created` (needs `orders:read`). Thin payload: fetch the order with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"order.created"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"order.paid":{"post":{"operationId":"webhook_order_paid","summary":"order.paid","description":"Sent to endpoints subscribed to `order.paid` (needs `orders:read`). Thin payload: fetch the order with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"order.paid"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"order.updated":{"post":{"operationId":"webhook_order_updated","summary":"order.updated","description":"Sent to endpoints subscribed to `order.updated` (needs `orders:read`). Thin payload: fetch the order with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"order.updated"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"order.cancelled":{"post":{"operationId":"webhook_order_cancelled","summary":"order.cancelled","description":"Sent to endpoints subscribed to `order.cancelled` (needs `orders:read`). Thin payload: fetch the order with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"order.cancelled"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"refund.completed":{"post":{"operationId":"webhook_refund_completed","summary":"refund.completed","description":"Sent to endpoints subscribed to `refund.completed` (needs `orders:read`). Thin payload: fetch the refund with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"refund.completed"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"invoice.authorized":{"post":{"operationId":"webhook_invoice_authorized","summary":"invoice.authorized","description":"Sent to endpoints subscribed to `invoice.authorized` (needs `orders:read`). Thin payload: fetch the invoice with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"invoice.authorized"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"invoice.cancelled":{"post":{"operationId":"webhook_invoice_cancelled","summary":"invoice.cancelled","description":"Sent to endpoints subscribed to `invoice.cancelled` (needs `orders:read`). Thin payload: fetch the invoice with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"invoice.cancelled"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"fulfillment.shipped":{"post":{"operationId":"webhook_fulfillment_shipped","summary":"fulfillment.shipped","description":"Sent to endpoints subscribed to `fulfillment.shipped` (needs `orders:read`). Thin payload: fetch the fulfillment with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"fulfillment.shipped"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"fulfillment.delivered":{"post":{"operationId":"webhook_fulfillment_delivered","summary":"fulfillment.delivered","description":"Sent to endpoints subscribed to `fulfillment.delivered` (needs `orders:read`). Thin payload: fetch the fulfillment with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"fulfillment.delivered"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"product.created":{"post":{"operationId":"webhook_product_created","summary":"product.created","description":"Sent to endpoints subscribed to `product.created` (needs `products:read`). Thin payload: fetch the product with GET for its current state.","x-required-scope":"products:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"product.created"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"product.updated":{"post":{"operationId":"webhook_product_updated","summary":"product.updated","description":"Sent to endpoints subscribed to `product.updated` (needs `products:read`). Thin payload: fetch the product with GET for its current state.","x-required-scope":"products:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"product.updated"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"product.deleted":{"post":{"operationId":"webhook_product_deleted","summary":"product.deleted","description":"Sent to endpoints subscribed to `product.deleted` (needs `products:read`). Thin payload: fetch the product with GET for its current state.","x-required-scope":"products:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"product.deleted"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"inventory.updated":{"post":{"operationId":"webhook_inventory_updated","summary":"inventory.updated","description":"Sent to endpoints subscribed to `inventory.updated` (needs `inventory:read`). Thin payload: fetch the inventory level with GET for its current state.","x-required-scope":"inventory:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"inventory.updated"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}},"app.uninstalled":{"post":{"operationId":"webhook_app_uninstalled","summary":"app.uninstalled","description":"Sent to endpoints subscribed to `app.uninstalled` (needs `orders:read`). Thin payload: fetch the app with GET for its current state.","x-required-scope":"orders:read","parameters":[{"name":"webhook-id","in":"header","required":true,"description":"Event id (evt_…): deduplicate with it.","schema":{"type":"string"}},{"name":"webhook-timestamp","in":"header","required":true,"description":"Unix seconds. Reject messages older than 5 minutes.","schema":{"type":"string"}},{"name":"webhook-signature","in":"header","required":true,"description":"Space-separated `v1,<base64>` signatures (several during a secret rotation).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"app.uninstalled"}}}]}}}},"responses":{"2XX":{"description":"Received. Any other status (or no answer in 10 s) is retried."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"tfs_live_… / tfs_test_…","description":"Store-bound API token (merchant token or app installation token). Scopes: store:read, products:read, products:write, inventory:read, inventory:write, orders:read, orders:write, orders.pii:read, invoices:write, fulfillments:write, webhooks:manage."}},"schemas":{"Store":{"type":"object","properties":{"id":{"type":"string","description":"Store id (st_…). The token belongs to exactly one store."},"name":{"type":"string","description":"Store name shown to shoppers."},"slug":{"type":"string","description":"Store slug ({slug}.tfshop.cloud and /s/{slug})."},"url":{"type":"string","description":"Public storefront URL (primary domain).","format":"uri"},"status":{"type":"string","description":"draft (not public yet), published or paused.","enum":["draft","published","paused"]},"domains":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string","description":"Hostname."},"type":{"type":"string","description":"subdomain (free) or custom.","enum":["subdomain","custom"]},"status":{"type":"string","description":"DNS / certificate status.","enum":["pending_dns","verifying","active","error"]},"primary":{"type":"boolean","description":"The canonical storefront address."}},"required":["hostname","type","status","primary"]},"description":"Domains of the storefront."},"legal":{"type":"object","properties":{"name":{"type":"string","description":"Legal name (razão social)."},"document":{"type":"string","description":"CNPJ (14 characters) or CPF (11 digits) of the seller, without punctuation. NF-e issuer (emit) when the store issues through TF Fiscal."},"document_type":{"type":"string","description":"cnpj or cpf.","enum":["cnpj","cpf"]},"state_registration":{"type":["string","null"],"description":"Inscrição estadual (IE), digits only, or null."},"address":{"type":"object","properties":{"zip":{"type":"string","description":"CEP, 8 digits.","pattern":"^\\d{8}$"},"street":{"type":"string","description":"Logradouro."},"number":{"type":"string","description":"Número."},"complement":{"type":["string","null"],"description":"Complemento."},"district":{"type":"string","description":"Bairro."},"city":{"type":"string","description":"Município."},"state":{"type":"string","description":"UF.","pattern":"^[A-Z]{2}$"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","enum":["BR"]},"ibge_code":{"type":["string","null"],"description":"7-digit IBGE municipality code, or null when unknown."}},"required":["zip","street","number","complement","district","city","state","country","ibge_code"],"description":"Seller address (shown in the storefront footer, Decreto 7.962/2013)."},"email":{"type":"string","description":"Customer-service e-mail."},"phone":{"type":"string","description":"Phone in E.164 (+55…), or empty."}},"required":["name","document","document_type","state_registration","address","email","phone"]},"currency":{"type":"string","description":"Always BRL.","enum":["BRL"]},"timezone":{"type":"string","description":"Always America/Sao_Paulo.","enum":["America/Sao_Paulo"]},"locale":{"type":"string","description":"Always pt-BR.","enum":["pt-BR"]},"invoice_issuer":{"type":"string","description":"Who issues the NF-e: tf_fiscal (the store) or erp (apps post it with POST /orders/{order_id}/invoices).","enum":["tf_fiscal","erp"]},"plan":{"type":"object","properties":{"id":{"type":"string","description":"Plan id.","enum":["start","business","advanced","enterprise"]},"name":{"type":"string","description":"Plan name."},"limits":{"type":"object","properties":{"products":{"type":["integer","null"],"description":"Max products; null = unlimited."},"staff":{"type":["integer","null"],"description":"Max staff users; null = unlimited."},"stores":{"type":"integer","description":"Stores included."},"orders_per_month":{"type":["integer","null"],"description":"Max orders per month; null = unlimited."},"storage_gb":{"type":"integer","description":"Media storage in GB."}},"required":["products","staff","stores","orders_per_month","storage_gb"]}},"required":["id","name","limits"]},"payment_methods":{"type":"object","properties":{"pix":{"type":"boolean","description":"Pix enabled."},"credit_card":{"type":"boolean","description":"Credit card enabled."},"boleto":{"type":"boolean","description":"Boleto enabled."}},"required":["pix","credit_card","boleto"],"description":"Methods the store's C6 account accepts at checkout."},"shipping_origin_cep":{"type":["string","null"],"description":"CEP the parcels ship from (8 digits), or null when not configured."},"created_at":{"type":"string","format":"date-time","description":"Creation time."},"published_at":{"type":["string","null"],"format":"date-time","description":"When the store went live, or null."}},"required":["id","name","slug","url","status","domains","legal","currency","timezone","locale","invoice_issuer","plan","payment_methods","shipping_origin_cep","created_at","published_at"],"description":"The store a token belongs to. Read it first: the NF-e issuer and the legal entity decide which operations apply.","example":{"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":{"type":"object","properties":{"type":{"type":"string","description":"URL of the problem type (https://developers.tfshop.cloud/errors/<slug>).","format":"uri"},"title":{"type":"string","description":"Short summary of the problem type."},"status":{"type":"integer","description":"HTTP status."},"detail":{"type":"string","description":"What went wrong with this request."},"instance":{"type":"string","description":"Request id (req_…), also in the X-Request-Id header."},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"JSON path of the field (items[2].sku)."},"message":{"type":"string","description":"Why it is invalid."}},"required":["field","message"]},"description":"Field errors (validation_failed)."}},"required":["type","title","status"],"description":"RFC 9457 problem details, served as application/problem+json.","example":{"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":{"type":"object","properties":{"zip":{"type":"string","description":"CEP, 8 digits.","pattern":"^\\d{8}$"},"street":{"type":"string","description":"Logradouro."},"number":{"type":"string","description":"Número (may be \"S/N\")."},"complement":{"type":["string","null"],"description":"Complemento."},"district":{"type":"string","description":"Bairro."},"city":{"type":"string","description":"Município."},"state":{"type":"string","description":"UF.","pattern":"^[A-Z]{2}$"},"country":{"type":"string","description":"ISO 3166-1 alpha-2.","enum":["BR"]},"ibge_code":{"type":["string","null"],"description":"7-digit IBGE municipality code (NF-e cMun); null when unknown.","pattern":"^\\d{7}$"}},"required":["zip","street","number","district","city","state","country"],"description":"Brazilian address. Without `orders.pii:read`, street, number, complement and district are masked and the CEP keeps only its first 5 digits."},"Buyer":{"type":"object","properties":{"type":{"type":"string","description":"PF (person) or PJ (company).","enum":["PF","PJ"]},"name":{"type":"string","description":"Name or company name."},"document":{"type":"string","description":"CPF (11 digits) or CNPJ (14 characters, may be alphanumeric), without punctuation."},"document_type":{"type":"string","description":"cpf or cnpj.","enum":["cpf","cnpj"]},"email":{"type":"string","description":"E-mail."},"phone":{"type":"string","description":"Phone in E.164 (+55…)."},"state_registration":{"type":["string","null"],"description":"Inscrição estadual (IE), when informed."},"ie_indicator":{"type":"integer","description":"NF-e indIEDest: 1 contribuinte, 2 isento, 9 não contribuinte (always 9 for PF).","enum":[1,2,9]},"masked":{"type":"boolean","description":"True when the token lacks orders.pii:read: name, document, e-mail and phone are masked."}},"required":["type","name","document","document_type","email","phone","state_registration","ie_indicator","masked"],"description":"NF-e recipient (dest)."},"OrderLine":{"type":"object","properties":{"line_id":{"type":"string","description":"Stable line id (`{order_id}:{n}`), referenced by partial invoices, fulfillments and refunds."},"product_id":{"type":"string","description":"Product id."},"variant_id":{"type":"string","description":"Variant id."},"sku":{"type":"string","description":"SKU (the mapping key between the store and the ERP)."},"title":{"type":"string","description":"Product title at the time of the order."},"variant_title":{"type":"string","description":"Variant title (\"Preto / 2 m\")."},"quantity":{"type":"integer","description":"Quantity.","minimum":1},"unit_price":{"type":"integer","description":"Unit price charged (wholesale / member price when applicable). In centavos.","minimum":0},"list_price":{"type":"integer","description":"Retail unit price before wholesale / member pricing. In centavos.","minimum":0},"discount_allocated":{"type":"integer","description":"Order discount allocated to the line (coupon + Pix), pro rata; the lines add up to the order discount. NF-e vDesc. In centavos.","minimum":0},"freight_allocated":{"type":"integer","description":"Order freight allocated to the line, pro rata; the lines add up to the order freight. NF-e vFrete. In centavos.","minimum":0},"total":{"type":"integer","description":"unit_price × quantity − discount_allocated + freight_allocated. In centavos.","minimum":0},"ncm":{"type":["string","null"],"description":"NCM from the store's product data, as a hint (8 digits). Optional: the ERP's fiscal data prevails.","pattern":"^\\d{8}$"},"cest":{"type":["string","null"],"description":"CEST hint (7 digits)."},"origin":{"type":"integer","description":"Origem da mercadoria (0–8) hint.","minimum":0,"maximum":8},"gtin":{"type":["string","null"],"description":"GTIN/EAN of the variant."}},"required":["line_id","product_id","variant_id","sku","title","variant_title","quantity","unit_price","list_price","discount_allocated","freight_allocated","total","ncm","cest","origin","gtin"]},"OrderShipping":{"type":"object","properties":{"carrier":{"type":"string","description":"Carrier (Correios, Jadlog, Loggi…)."},"service":{"type":"string","description":"Service (PAC, SEDEX, .Package…)."},"price":{"type":"integer","description":"Freight charged to the buyer. In centavos.","minimum":0},"business_days":{"type":"integer","description":"Quoted transit time in business days."},"tracking_code":{"type":["string","null"],"description":"Tracking code once a label exists."},"tracking_url":{"type":["string","null"],"description":"Public tracking page."}},"required":["carrier","service","price","business_days","tracking_code","tracking_url"]},"Payment":{"type":"object","properties":{"method":{"type":"string","description":"Payment method.","enum":["pix","credit_card","boleto"]},"status":{"type":"string","description":"Payment status.","enum":["created","pending","confirmed","failed","expired","cancelled","refund_pending","refunded","partially_refunded"]},"paid_at":{"type":["string","null"],"format":"date-time","description":"When the payment was confirmed."},"installments":{"type":"integer","description":"Number of installments (1 for Pix and boleto).","minimum":1},"nfe_payment_code":{"type":"string","description":"NF-e tPag: 17 Pix dinâmico, 03 cartão de crédito, 15 boleto.","enum":["17","03","15"]},"card_brand":{"type":["string","null"],"description":"Card brand (visa, mastercard, elo, amex, hipercard)."},"nfe_card_brand":{"type":["string","null"],"description":"NF-e tBand (01 Visa, 02 Mastercard, 03 Amex, 06 Elo, 07 Hipercard, 99 other)."},"card_last4":{"type":["string","null"],"description":"Last 4 digits of the card."},"acquirer_cnpj":{"type":["string","null"],"description":"CNPJ of the payment institution (NF-e card group CNPJ). Card and Pix only."},"authorization_code":{"type":["string","null"],"description":"Card authorisation code (NF-e cAut)."},"pix_end_to_end_id":{"type":["string","null"],"description":"Pix end-to-end id (E + ISPB + timestamp + sequence)."},"provider":{"type":"string","description":"Payment provider: c6, or manual when the merchant marked it as paid.","enum":["c6","manual"]},"provider_payment_id":{"type":["string","null"],"description":"Payment id at the provider."}},"required":["method","status","paid_at","installments","nfe_payment_code","provider"],"description":"Money goes straight to the merchant's own C6 account; refunds are made by the store."},"FiscalHints":{"type":"object","properties":{"ind_pres":{"type":"integer","description":"NF-e indPres: 2 = internet.","enum":[2]},"ind_intermed":{"type":"integer","description":"NF-e indIntermed: 0 = own website (no marketplace intermediary).","enum":[0,1]},"ind_final":{"type":"integer","description":"NF-e indFinal: 1 consumidor final, 0 resale (wholesale buyer buying to resell).","enum":[0,1]}},"required":["ind_pres","ind_intermed","ind_final"]},"Invoice":{"type":"object","properties":{"order_id":{"type":"string","description":"Order id."},"number":{"type":"integer","description":"NF-e number (nNF)."},"series":{"type":"integer","description":"NF-e series."},"access_key":{"type":"string","description":"44-digit access key (chave de acesso).","pattern":"^\\d{6}[0-9A-Z]{14}\\d{24}$"},"issued_at":{"type":"string","format":"date-time","description":"Issue date."},"source":{"type":"string","description":"tf_fiscal (issued by the store) or erp (posted by an app).","enum":["tf_fiscal","erp"]},"status":{"type":"string","description":"authorized or cancelled.","enum":["authorized","cancelled"]},"xml_url":{"type":["string","null"],"description":"Authorised XML."},"danfe_url":{"type":["string","null"],"description":"DANFE PDF."}},"required":["order_id","number","series","access_key","issued_at","source","status","xml_url","danfe_url"],"example":{"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":{"type":"object","properties":{"acknowledged_at":{"type":"string","format":"date-time","description":"When this app acknowledged the order."},"external_id":{"type":["string","null"],"description":"Order id in the app's system."}},"required":["acknowledged_at","external_id"],"description":"This app's export acknowledgement (each app has its own)."},"Order":{"type":"object","properties":{"id":{"type":"string","description":"Order id (immutable). Use it as the unique key in your system."},"number":{"type":"integer","description":"Order number shown to the buyer and the merchant (#1011)."},"created_at":{"type":"string","format":"date-time","description":"Creation time."},"updated_at":{"type":"string","format":"date-time","description":"Last change (latest timeline entry). Use with `updated_since`."},"status":{"type":"string","description":"Order status.","enum":["pending_payment","paid","fulfilling","fulfilled","cancelled","expired","return_requested","refunded","partially_refunded"]},"payment_status":{"type":"string","description":"Payment status (see Payment.status)."},"fulfillment_status":{"type":"string","description":"Fulfillment status.","enum":["unfulfilled","label_purchased","shipped","delivered","returned"]},"invoice_status":{"type":"string","description":"NF-e status.","enum":["not_required","pending","authorized","error","cancelled"]},"test":{"type":"boolean","description":"Test order placed by the merchant: never issue an NF-e for it."},"channel":{"type":"string","description":"Sales channel.","enum":["online_store","whatsapp","manual","vendedor","mercado_livre","shopee","tiktok_shop"]},"currency":{"type":"string","description":"Always BRL.","enum":["BRL"]},"subtotal":{"type":"integer","description":"Sum of the lines (unit_price × quantity). In centavos.","minimum":0},"discount":{"type":"integer","description":"Coupon + Pix discount. In centavos.","minimum":0},"shipping_total":{"type":"integer","description":"Freight charged (same as shipping.price). In centavos.","minimum":0},"total":{"type":"integer","description":"subtotal − discount + shipping_total. In centavos.","minimum":0},"refunded":{"type":"integer","description":"Refunded so far. In centavos.","minimum":0},"buyer":{"$ref":"#/components/schemas/Buyer"},"shipping_address":{"$ref":"#/components/schemas/Address"},"billing_address":{"$ref":"#/components/schemas/Address","description":"Same as the shipping address in v1 (the checkout has a single address)."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"},"description":"Order lines."},"shipping":{"$ref":"#/components/schemas/OrderShipping"},"payment":{"$ref":"#/components/schemas/Payment"},"fiscal_hints":{"$ref":"#/components/schemas/FiscalHints"},"invoice":{"oneOf":[{"$ref":"#/components/schemas/Invoice"},{"type":"null"}],"description":"Current NF-e, or null."},"export":{"oneOf":[{"$ref":"#/components/schemas/OrderExportStatus"},{"type":"null"}],"description":"This app's acknowledgement, or null when not yet imported."}},"required":["id","number","created_at","updated_at","status","payment_status","fulfillment_status","invoice_status","test","channel","currency","subtotal","discount","shipping_total","total","refunded","buyer","shipping_address","billing_address","lines","shipping","payment","fiscal_hints","invoice","export"],"description":"NF-e-ready order payload.","example":{"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":{"type":"object","properties":{"sku":{"type":"string","description":"SKU."},"variant_id":{"type":"string","description":"Variant id."},"product_id":{"type":"string","description":"Product id."},"on_hand":{"type":"integer","description":"Units in stock.","minimum":0},"reserved":{"type":"integer","description":"Units held by unpaid Pix / boleto orders.","minimum":0},"available":{"type":"integer","description":"on_hand − reserved (never below 0): what the storefront sells.","minimum":0},"updated_at":{"type":"string","format":"date-time","description":"Last stock change."}},"required":["sku","variant_id","product_id","on_hand","reserved","available","updated_at"],"example":{"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":{"type":"object","properties":{"id":{"type":"string","description":"Variant id."},"product_id":{"type":"string","description":"Product id."},"sku":{"type":"string","description":"SKU, unique in the store."},"title":{"type":"string","description":"\"Preto / 2 m\" (\"Padrão\" for products without options)."},"options":{"type":"object","additionalProperties":{"type":"string"},"description":"Option values by option name ({\"Cor\": \"Preto\"})."},"price":{"type":"integer","description":"Retail price. In centavos.","minimum":0},"compare_at_price":{"type":["integer","null"],"description":"\"De\" price shown struck through (centavos), or null.","minimum":0},"gtin":{"type":["string","null"],"description":"GTIN/EAN."},"inventory":{"type":"object","properties":{"on_hand":{"type":"integer","description":"Units in stock."},"reserved":{"type":"integer","description":"Units held by unpaid orders."},"available":{"type":"integer","description":"on_hand − reserved."}},"required":["on_hand","reserved","available"]}},"required":["id","product_id","sku","title","options","price","compare_at_price","gtin","inventory"]},"Product":{"type":"object","properties":{"id":{"type":"string","description":"Product id."},"title":{"type":"string","description":"Title."},"handle":{"type":"string","description":"URL slug (set on creation, never changes)."},"status":{"type":"string","description":"active (on sale), draft or archived.","enum":["active","draft","archived"]},"description":{"type":"string","description":"Plain-text description."},"category_id":{"type":["string","null"],"description":"Primary category id."},"brand":{"type":["string","null"],"description":"Brand."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags."},"fiscal":{"type":"object","properties":{"ncm":{"type":["string","null"],"description":"NCM, 8 digits, or null when not informed (optional; required only when the store issues the NF-e itself).","pattern":"^\\d{8}$"},"cest":{"type":["string","null"],"description":"CEST, 7 digits."},"origin":{"type":"integer","description":"Origem da mercadoria (0–8).","minimum":0,"maximum":8}},"required":["ncm","cest","origin"]},"weight_grams":{"type":"integer","description":"Shipping weight in grams.","minimum":0},"dimensions_cm":{"type":"object","properties":{"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}},"required":["length","width","height"],"description":"Package dimensions in cm."},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Public image URL."},"alt":{"type":["string","null"],"description":"Alt text."}},"required":["url","alt"]},"description":"Gallery, first = main image."},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"},"description":"Variants (at least one)."},"created_at":{"type":"string","format":"date-time","description":"Creation time."},"updated_at":{"type":"string","format":"date-time","description":"Last change of product data (not stock)."}},"required":["id","title","handle","status","description","category_id","brand","tags","fiscal","weight_grams","dimensions_cm","images","variants","created_at","updated_at"],"description":"The store is the source of truth for products, prices and stock.","example":{"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":{"type":"object","properties":{"id":{"type":"string","description":"Fulfillment id (`{order_id}:f1`)."},"order_id":{"type":"string","description":"Order id."},"status":{"type":"string","description":"shipped or delivered.","enum":["shipped","delivered"]},"carrier":{"type":"string","description":"Carrier."},"service":{"type":"string","description":"Service."},"tracking_code":{"type":"string","description":"Tracking code (Correios: S10 with a valid check digit)."},"tracking_url":{"type":["string","null"],"description":"Public tracking page."},"shipped_at":{"type":["string","null"],"format":"date-time","description":"When the order was marked as shipped."},"delivered_at":{"type":["string","null"],"format":"date-time","description":"When it was delivered."}},"required":["id","order_id","status","carrier","service","tracking_code","tracking_url","shipped_at","delivered_at"],"example":{"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":{"type":"object","properties":{"id":{"type":"string","description":"Endpoint id (we_…)."},"url":{"type":"string","description":"HTTPS URL that receives the events.","format":"uri"},"description":{"type":["string","null"],"description":"Free text."},"events":{"type":"array","items":{"type":"string","enum":["order.created","order.paid","order.updated","order.cancelled","refund.completed","invoice.authorized","invoice.cancelled","fulfillment.shipped","fulfillment.delivered","product.created","product.updated","product.deleted","inventory.updated","app.uninstalled"]},"description":"Subscribed event types."},"status":{"type":"string","description":"enabled or disabled.","enum":["enabled","disabled"]},"created_at":{"type":"string","format":"date-time","description":"Creation time."},"secret":{"type":"string","description":"Signing secret (whsec_…). Returned only by the create call: store it."}},"required":["id","url","description","events","status","created_at"]},"Event":{"type":"object","properties":{"id":{"type":"string","description":"Event id (evt_…), also the webhook-id header: deduplicate with it."},"type":{"type":"string","description":"Event type.","enum":["order.created","order.paid","order.updated","order.cancelled","refund.completed","invoice.authorized","invoice.cancelled","fulfillment.shipped","fulfillment.delivered","product.created","product.updated","product.deleted","inventory.updated","app.uninstalled"]},"timestamp":{"type":"string","format":"date-time","description":"When the change happened."},"api_version":{"type":"string","description":"API version of the payload.","enum":["v1"]},"store_id":{"type":"string","description":"Store id."},"actor":{"type":"object","properties":{"type":{"type":"string","description":"Who caused the change.","enum":["store","buyer","app","system"]},"app_id":{"type":["string","null"],"description":"App that caused it: ignore your own echoes."}},"required":["type","app_id"]},"data":{"type":"object","properties":{"object":{"type":"string","description":"Object type.","enum":["order","product","inventory_level","invoice","fulfillment","app"]},"id":{"type":"string","description":"Object id (order id, product id, variant id, NF-e access key, fulfillment id, installation id)."},"reference":{"type":["string","null"],"description":"Human reference: order number, SKU, product handle or tracking code. Never personal data."},"status":{"type":["string","null"],"description":"Object status after the change."},"test":{"type":"boolean","description":"Test order: skip it unless you are testing."},"order_id":{"type":["string","null"],"description":"Parent order of invoice and fulfillment events."}},"required":["object","id"]}},"required":["id","type","timestamp","api_version","store_id","actor","data"],"description":"Thin payload: fetch the object with GET to read its current state (access checked against your scopes).","example":{"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}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key (e.g. a UUID) to retry this request safely for 24 h.","schema":{"type":"string","maxLength":255}}},"headers":{"X-Request-Id":{"description":"Request id (req_…); quote it to support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Bucket size (burst).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the bucket.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the bucket is full again.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"Idempotent-Replayed":{"description":"\"true\" when the response was replayed from an earlier request with the same Idempotency-Key.","schema":{"type":"string"}}}}}