APIs para o Quick Order Form

Esta página descreve a API pública da família de recursos do Quick Order Form. Um único endpoint trata os três tipos de registro relacionados, diferenciados por um campo type:

• quick_order_page — uma página independente de Quick Order Form.
• quick_buy_collection — o recurso Quick Buy nas páginas de coleção e nos cards de produto.
• quick_buy_variant — a Variant Table em uma página de produto.

As 4 operações usam a mesma URL base, os mesmos cabeçalhos e a mesma autenticação descritos em APIs públicas.

Criar um registro

Endpoint

POST https://wholesale.samita.io/api/v1/quick-order-forms

Cabeçalhos da requisição

Cabeçalho	Descrição	Obrigatório
X-SAMITA-API-KEY	Chave de API fornecida no app Wholesale	Sim
X-SAMITA-SHOP-URL	Domínio da loja Shopify no formato xxx.myshopify.com	Sim
CONTENT-TYPE	Deve ser application/json	Sim

Esta API exige a permissão Create na chave de API, para o type específico que você está criando.

Campos comuns (todos os tipos)

Campo	Tipo	Obrigatório	Descrição
title	string, máx. 255	Sim	O nome do registro no app.
status	boolean	Sim	Indica se está ativo.
type	string	Sim	quick_order_page, quick_buy_collection ou quick_buy_variant.

Os demais campos obrigatórios dependem do type:

Campo	Tipo	Observações
apply_product	object (obrigatório)	type: products ou collections.
apply_product.product_ids	array	Obrigatório quando type é products.
apply_product.collection_ids	array	Obrigatório quando type é collections.
display_on_page	string (obrigatório)	O handle da página da Shopify em que este formulário é exibido.
pagination	object (obrigatório)	type: pagination ou load_more_button; per_page: número de 1 a 50.
columns	object (obrigatório)	product_stock: boolean — mostra/oculta a coluna de estoque.

Exemplo:

{
  "title": "Wholesale Order Form",
  "status": true,
  "type": "quick_order_page",
  "apply_product": {
    "type": "collections",
    "collection_ids": [123456789]
  },
  "display_on_page": "wholesale-order-form",
  "pagination": {
    "type": "pagination",
    "per_page": 20
  },
  "columns": {
    "product_stock": true
  }
}

Campo	Tipo	Observações
apply_product	object (obrigatório)	type: all, products, collections ou product-tags, com product_ids / collection_ids / product_tags correspondentes.
exclude_product	object (obrigatório)	type: none, products ou collections, com os IDs correspondentes.
apply_customer	object (obrigatório)	type: all, logged, non-logged ou customer-tags, com tags quando aplicável.
exclude_customer	object (obrigatório)	type: none ou customer-tags, com tags quando aplicável.
display_on_pages	array (obrigatório)	Qualquer um de index, collection, search, another_page.
columns	object (obrigatório)	Booleans: stock_status, quantity, variant, volume_discount, add_to_cart.

Exemplo:

{
  "title": "Quick Buy on Collections",
  "status": true,
  "type": "quick_buy_collection",
  "apply_product": { "type": "all", "product_ids": [], "product_tags": [], "collection_ids": [] },
  "exclude_product": { "type": "none", "product_ids": [], "collection_ids": [] },
  "apply_customer": { "type": "customer-tags", "tags": ["wholesale"] },
  "exclude_customer": { "type": "none", "tags": [] },
  "display_on_pages": ["collection", "index"],
  "columns": {
    "stock_status": true,
    "quantity": true,
    "variant": true,
    "volume_discount": true,
    "add_to_cart": true
  }
}

Campo	Tipo	Observações
apply_product	object (obrigatório)	Mesma estrutura de quick_buy_collection.
exclude_product	object (obrigatório)	Mesma estrutura de quick_buy_collection.
apply_customer	object (obrigatório)	Mesma estrutura de quick_buy_collection.
exclude_customer	object (obrigatório)	Mesma estrutura de quick_buy_collection.
template	string (obrigatório)	default ou matrix-column.
columns	object (obrigatório)	stock: boolean — mostra/oculta a coluna de estoque.

Exemplo:

{
  "title": "Variant Table",
  "status": true,
  "type": "quick_buy_variant",
  "apply_product": { "type": "all", "product_ids": [], "product_tags": [], "collection_ids": [] },
  "exclude_product": { "type": "none", "product_ids": [], "collection_ids": [] },
  "apply_customer": { "type": "logged", "tags": [] },
  "exclude_customer": { "type": "none", "tags": [] },
  "template": "default",
  "columns": {
    "stock": true
  }
}

Nota

Os objetos apply_product/exclude_product/apply_customer/exclude_customer controlam as mesmas regras de segmentação que você definiria na interface do app. Estilo, ordem das colunas e outras configurações de exibição usam padrões adequados na criação — para alterá-los, atualize o registro depois ou edite-o no app.

Resposta

200 – Success retorna o registro criado. Veja o exemplo em Obter um registro, abaixo.

Atualizar um registro

PUT https://wholesale.samita.io/api/v1/quick-order-forms/{id}

Mesmos cabeçalhos da criação. Envie apenas os campos que deseja alterar — title, status, configs e product_configs são todos opcionais; os campos não informados mantêm o valor atual. Esta API exige a permissão Update.

Obter um registro

GET https://wholesale.samita.io/api/v1/quick-order-forms/{id}

Mesmos cabeçalhos da criação, sem corpo na requisição. Esta API exige a permissão View.

Exemplo de 200 – Success (type: quick_order_page):

{
  "id": 1,
  "title": "Wholesale Order Form",
  "status": true,
  "type": "quick_order_page",
  "apply_product": {
    "type": "collections",
    "product_ids": [],
    "collection_ids": [123456789]
  },
  "display_on_page": "wholesale-order-form",
  "pagination": {
    "type": "pagination",
    "per_page": 20
  },
  "columns": {
    "product": true,
    "product_stock": true,
    "quantity": true,
    "action": true
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

Excluir um registro

DELETE https://wholesale.samita.io/api/v1/quick-order-forms/{id}

Mesmos cabeçalhos da criação. Informe um parâmetro ids — uma lista de IDs de registros a excluir separados por vírgula (como parâmetro de query string ou campo do corpo JSON), por exemplo ids=1,2,3. Esta API exige a permissão Delete.

200 – Success:

{
  "success": true
}

Respostas de erro

Os 4 endpoints compartilham as mesmas respostas de erro do restante da API pública — veja APIs públicas para 401 Unauthorized, 403 Forbidden e 429 Too Many Requests.