Documentação da API

Bem-vindo à documentação oficial da API PopStore v2. Nossa API é baseada em REST, utiliza JSON para requisições e respostas, e utiliza códigos de status HTTP padrão.

info

A URL base para todas as requisições é: https://api2.popstore.com.br

Autenticação

A API utiliza autenticação via Bearer Token. Este token identifica sua loja (Store ID) e garante a segurança das transações.

Você deve incluir o token no cabeçalho Authorization de todas as requisições.


                            Authorization: Bearer {sua_api_key}

Listar Produtos

GET

Retorna uma lista de produtos cadastrados na loja.

GET https://api2.popstore.com.br/products

Parâmetros (Query String)

Campo	Tipo	Obrigatório	Descrição
page	int	Não	Número da página (Padrão: 1)
limit	int	Não	Itens por página (Padrão: 100)
id	int	Não	ID específico do produto
search	string	Não	Busca por nome ou referência
collection_id	int	Não	ID da coleção
category_id	int	Não	ID da categoria
manufacturer	int	Não	ID do fabricante/marca

URL de Requisição

GET /products?limit=5&page=1

check_circle 200 OK

{
  "data": [
    {
      "id": 185743,
      "name": "Vestido Francisca Midi C/Alca Larga Vermelho",
      "code": "54759024",
      "date_created": "15/12/2025 11:01:29",
      "brand": "Miss Misses",
      "brand_id": 216,
      "collection": "Miss & Misses Verão 2026",
      "collection_id": 1390,
      "weight": "0.600",
      "height": 35,
      "width": 25,
      "depth": 7,
      "ncm": "62044200",
      "ucom": "UN",
      "utrib": "UN",
      "status": {
        "retail": 1,
        "wholesale": 1
      },
      "discount_percent": {
        "retail": 0,
        "wholesale": 0
      },
      "options": [
        {
          "id": 1287728,
          "color": "Vermelho",
          "size": "P",
          "code": "5475902402",
          "ean": "5475902402",
          "ean_system": "100012877284",
          "price": {
            "retail": 395.90,
            "wholesale": 179.90
          },
          "sale_price": {
            "retail": 395.90,
            "wholesale": 179.90
          },
          "quantity": {
            "available": 2,
            "hold": 0,
            "total": 2
          }
        },
        {
          "id": 1287729,
          "color": "Vermelho",
          "size": "M",
          "code": "5475902403",
          "ean": "5475902403",
          "ean_system": "100012877291",
          "price": {
            "retail": 395.90,
            "wholesale": 179.90
          },
          "sale_price": {
            "retail": 395.90,
            "wholesale": 179.90
          },
          "quantity": {
            "available": 3,
            "hold": 1,
            "total": 4
          }
        }
      ],
      "photos": [
        {
          "url": "https://popstore.com.br/.../produto.webp"
        }
      ],
      "videos": [
        {
          "url": "https://popstore.com.br/.../produto.mp4"
        }
      ],
      "description": "Descrição do produto..."
    }
  ]
}

Atualizar Estoque

PUT

Atualiza a quantidade de estoque de um produto ou variante específica. Suporta atualização individual ou em lote (enviando um array de itens). A quantidade informada deve ser a contagem física total. O sistema automaticamente desconta itens reservados em pedidos.

PUT https://api2.popstore.com.br/products/stock_update

Parâmetros (Body / JSON)

Campo	Tipo	Obrigatório	Descrição
product_id	int	Sim	ID do produto pai
quantity	int	Sim	Quantidade física contada
stock_id	int	*	ID da variante (opcional se enviar code ou ean)
code	string	*	SKU da variante (opcional se enviar stock_id ou ean)
ean	string	*	Código de barras (opcional se enviar stock_id ou code)

* Pelo menos um identificador de variante (stock_id, code, ean) deve ser fornecido.

Exemplo de Requisição (JSON)

// Atualização em Lote

[
  {
    "product_id": 185743,
    "stock_id": 1287728,
    "quantity": 50
  },
  {
    "product_id": 185743,
    "code": "5475902403",
    "quantity": 35
  }
]

check_circle 200 OK

{
  "status": "ok",
  "results": [
    {
      "status": "ok",
      "data": {
        "product_id": 185743,
        "stock_id": 1287728,
        "old_quantity": 10,
        "quantity": {
          "available": 45,
          "hold": 5,
          "total": 50
        }
      }
    },
    {
      "status": "ok",
      "data": {
         ...
      }
    }
  ]
}

Atualizar Preços

PUT

Atualiza os preços de venda e atacado de todas as opções de um produto, identificado pelo product_id ou code (Store Code).

PUT https://api2.popstore.com.br/products/price_update

Parâmetros (Body / JSON)

Campo	Tipo	Opcional	Descrição
product_id	int	Não*	ID do produto pai.
code	string	Não*	Código da loja (Store Code).
price.retail	float	Sim	Novo Preço de Varejo (para todas as opções).
price.wholesale	float	Sim	Novo Preço de Atacado (para todas as opções).

* É necessário enviar product_id OU code. Se ambos forem enviados, o ID tem prioridade.

Exemplo de Requisição (Batch)

[
  {
    "product_id": 185743,
    "price": {
        "retail": 150.00,
        "wholesale": 80.00
    }
  },
  {
    "code": "REF123",
    "price": {
        "retail": 199.90
    }
  }
]

check_circle 200 OK

{
  "status": "ok",
  "results": [
    {
      "status": "ok",
      "data": {
        "product_id": 185743,
        "price": {
           "retail": 150.00,
           "wholesale": 80.00
        }
      }
    },
    ...
  ]
}

Atualizar Descontos

PUT

Atualiza os descontos do produto (Retail e Wholesale). Você pode enviar o percentual de desconto diretamente no objeto discount ou o preço final desejado no objeto sale_price (o sistema calculará o percentual necessário baseado no preço atual do produto).

PUT https://api2.popstore.com.br/products/discount_update

Parâmetros (Body / JSON)

Campo	Tipo	Opcional	Descrição
product_id	int	Não*	ID do produto pai.
code	string	Não*	Código da loja (Store Code).
discount.retail	float	Sim**	% Desconto Varejo (0-100).
discount.wholesale	float	Sim**	% Desconto Atacado (0-100).
sale_price.retail	float	Sim**	Preço final desejado (Varejo). Sistema calculará % desconto.
sale_price.wholesale	float	Sim**	Preço final desejado (Atacado). Sistema calculará % desconto.

* É necessário enviar product_id OU code. Se ambos forem enviados, o ID tem prioridade.
** Se enviar discount e sale_price, o valor de discount (percentual) tem precedência.

Exemplo de Requisição

[
  {
    "product_id": 185743,
    "discount": {
        "retail": 10,
        "wholesale": 0
    }
  },
  {
    "code": "REF123",
    // Calcular desconto para chegar no preço final
    "sale_price": {
        "retail": 135.00
    }
  }
]

check_circle 200 OK

{
  "status": "ok",
  "results": [
    {
      "status": "ok",
      "updated_fields": ["discount_retail"],
      "data": {
        "product_id": 185743,
        "store_code": "REF123",
        "discount_percent": {
           "retail": 10,
           "wholesale": 0
        }
      }
    }
  ]
}

Criar Produto

POST

Cria um novo produto na loja. Este endpoint permite o cadastro completo, incluindo variações (SKUs), fotos e preços.

POST https://api2.popstore.com.br/products/create

Parâmetros do Body (JSON)

Campo	Tipo	Obrigatório	Descrição
code	string	Sim	Código de referência (SKU pai) único do produto.
name	string	Sim	Nome/Título do produto.
description	string	Não	Descrição detalhada do produto (HTML permitido).
price_cost	float	Não	Preço de custo.
price_whlesale	float	Não	Preço de atacado.
price_retail	float	Não	Preço de varejo.
variants	array	Não	Lista de variações (tamanho/cor). Veja o exemplo.
photos	array	Não	Lista de fotos (URL ou Base64).

Exemplo de Requisição

application/json

"code": "VEST-VERAO-24",
"name": "Vestido Floral Verão",
"description": "<p>Vestido leve 100% viscose.</p>",
"price_cost": 45.00,
"price_wholesale": 90.00,
"price_retail": 189.90,
"weight": "0.350",
"variants": [
  {
    "code": "VEST-VERAO-24-P",
    "ean": "7890000001",
    "color_name": "Vermelho",
    "color_html": "#FF0000",
    "size": "P",
    "stock": 10
  },
  {
    "code": "VEST-VERAO-24-M",
    "ean": "7890000001",
    "color_name": "Vermelho",
    "color_html": "#FF0000",
    "size": "M",
    "stock": 15
  }
],
"photos": [
  {
    "url": "https://site.com/foto1.jpg"
    "width": 800
    "height": 1200
  }
]

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "data": {
      "id": 54821
    }
  }
}

error 400 Bad Request

Ocorre se code ou name estiverem vazios.

{
  "return": {
    "status": "error",
    "error": "code is empty"
  }
}

Listar Pedidos

GET

Retorna uma lista de pedidos realizados na loja filtrados por um intervalo de datas.

GET https://api2.popstore.com.br/orders

Parâmetros (Query String)

Campo	Tipo	Obrigatório	Descrição
date_from	string	Não	Data inicial (dd/mm/YYYY)
date_to	string	Não	Data final (dd/mm/YYYY)
page	int	Não	1
limit	int	Não	100
order_id	int	Não	Número do Pedido
sort	string	Não	ASC / DESC

Status do Pedido

O campo status pode retornar um dos seguintes valores:

Pending Approved Shipped Received Canceled

URL de Requisição

GET /orders?date_from=11/12/2025&date_to=12/12/2025

check_circle 200 OK

{
  "data": [
    {
      "id": 900044,
      "created_at": "11/12/2025 16:54:26",
      "type": "retail",
      "status": "Approved",
      "name": "Nome Sobrenome",
      "cpf": "00000000000",
      "company_name": "Empresa",
      "cnpj": "00000000000000",
      "ie": "00000000000",
      "email": "[email protected]",
      "phone": "(11) 999999999",
      "zip_code": "99999999",
      "address": "Rua Teste",
      "number": "1000",
      "address2": "Complemento",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "São Paulo",
      "state_iso": "SP",
      "country": "Brasil",
      "country_iso": "BR",
      "shipping_type": "CORREIOS - SEDEX",
      "payment_method": "PIX",
      "sub_total": 379.74,
      "discount": 37.97,
      "shipping": 10.00,
      "total": 351.77,
      "items": [
        {
          "name": "Vestido Floral Verão",
          "code": "VEST-VERAO-24-P",
          "color": "Vermelho",
          "size": "M",
          "ean": "7890000001",
          "quantity": 1,
          "cost": 45.00,
          "price": 90.00
        }
      ]
    },
    {
       // ... demais pedidos
    }
  ]
}