APIs públicas

1. Escopo de uso da API

a. Recursos compatíveis com a API

A API pública permite interagir com os principais recursos do app Wholesale, incluindo:

• Recursos principais: Wholesale Pricing, Volume Pricing, Registration form, Quick Order Form, Quick Buy Collection, Quick Buy Variant
• Recursos complementares: Order Limit, Shipping Rate, Extra Fee, Payment Term (em breve)

b. Métodos compatíveis

A API oferece operações CRUD completas com os seguintes métodos HTTP:

• GET: consultar dados
• POST: criar novos dados
• PUT: atualizar dados existentes
• DELETE: remover dados

As chaves de API podem receber os seguintes níveis de permissão: Read Only/Write Only, Read & Write

As ações compatíveis incluem: Get list - Get item - Create item - Update item - Delete item

c. Planos da Shopify compatíveis:

A API pública do app Wholesale está disponível para lojas Shopify que atendam aos seguintes requisitos:

• Ser uma loja de produção (não vale para lojas de desenvolvimento ou de teste)
• Ter assinado o plano Gold

---

2. Autenticação

Todas as requisições à API precisam ser autenticadas corretamente antes de serem processadas.

a. Parâmetros obrigatórios

Cada requisição à API deve incluir os seguintes parâmetros obrigatórios:

Parâmetro	Descrição
shop	Domínio da loja Shopify (por exemplo, mystore.myshopify.com)
api_key	Chave de API gerada no app Wholesale

Se algum desses parâmetros estiver ausente, a requisição será rejeitada.

b. Gerenciamento de chaves de API

As chaves de API são criadas e gerenciadas diretamente na interface de administração do app Wholesale.
Quem administra a loja pode configurar permissões específicas para cada chave de API: Read only/Write only, Read & Write

---

3. Estrutura da API e formato da resposta

a. Endpoint da API

Todas as requisições à API devem usar a seguinte URL base:

https://wholesale.samita.io/v1/

b. Endpoints específicos de cada recurso

Cada grupo de recursos tem seu próprio endpoint. Por exemplo:

• Recurso Wholesale:

  https://wholesale.samita.io/v1/wholesale/

• Recurso Volume Pricing:

  https://wholesale.samita.io/v1/volume/

(Os endpoints reais podem variar conforme a funcionalidade.)

c. Parâmetros de consulta compatíveis

A API aceita vários parâmetros de consulta comuns:

Parâmetro	Descrição
status	Status dos registros
page	Número da página para paginação
limit	Número de registros por página
sort	Critério de ordenação
query	Condição de busca ou filtro

Exemplo de requisição:

GET /wholesale?page=1&limit=20&sort=created_at

---

4. Códigos de resposta

Cada requisição à API retorna um dos seguintes códigos de status:

a. Respostas de erro comuns

401 – Não autorizado

Motivos possíveis:

• URL da loja ausente
• Chave de API ausente
• URL da loja inválida
• Chave de API inválida
• A chave de API não corresponde à loja

---

403 – Esta ação não é autorizada

• A chave de API não tem permissão para realizar a ação solicitada
• Permissões insuficientes para View / Create / Update / Delete

---

429 – Excesso de requisições

• O limite de requisições foi excedido
• A frequência de chamadas à API excede o limite permitido

---

b. Resposta de sucesso

200 – Sucesso

• A requisição é válida
• A ação da API foi executada com sucesso
• Os dados são retornados no formato correto

---

5. Limite de requisições

Para garantir o desempenho e a estabilidade do sistema, o uso da API está sujeito a um limite diário de requisições. Não há mais limitação por requisição ou por intervalo curto: você pode chamar a API quantas vezes precisar, desde que fique dentro da cota diária do seu plano.

O limite diário depende do plano da loja:

Plano	Limite diário de requisições
Free	5 requisições/dia
Starter	50 requisições/dia
Growth	250 requisições/dia
Enterprise	500 requisições/dia

O contador diário é zerado à meia-noite (horário do servidor) todos os dias.

Se o limite diário for excedido, o sistema retornará:

429 – Too Many Requests

{
  "message": "Daily request limit exceeded (X requests/day)."
}