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: 10, Máximo: 100)
id	int	Não	ID específico do produto
code	string	Não	Referência específica do produto
status	int	Não	1 retorna apenas os ativos
updated_at	string	Não	Data de atualização (YYYY-MM-DD HH:mm:ss)
search	string	Não	Busca por nome (name) ou referência (code)
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 Miss Misses Preto",
      "code": "REF123",
      "created_at": "2025-12-15 12:30:00",
      "updated_at": "2026-02-19 15:00:00",
      "brand": "Miss Misses",
      "collection": "Verão 2026",
      "categories": [
        "Roupas",
        "Roupas > Vestidos",
        "Roupas > Vestidos > Vestidos de Festa"
      ],
      "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,
          "type": "Vestido",
          "color": "Vermelho",
          "color_html": "#FF0000",
          "size": "P",
          "sku": "5475902402",
          "ean": "7890000001",
          "price": {
            "retail": 395.90,
            "wholesale": 179.90
          },
          "sale_price": {
            "retail": 395.90,
            "wholesale": 179.90
          },
          "quantity": {
            "available": 2,
            "hold": 0,
            "total": 2
          } 
        },
        {
          "id": 1287729,
          "type": "Vestido",
          "color": "Vermelho",
          "color_html": "#FF0000",
          "size": "M",
          "sku": "5475902403",
          "ean": "7908981970950",
          "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"
        }
      ],
      "composition": "Composição do produto..."
      "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
code	string	Sim*	Código do produto pai
option_id	int	**	ID da variante (opcional se enviar sku ou ean)
sku	string	**	SKU da variante (opcional se enviar option_id ou ean)
ean	string	**	Código de barras (opcional se enviar option_id ou sku)
quantity	int	Sim	Quantidade

* Pelo menos um identificador de produto (product_id, code) deve ser fornecido. * Pelo menos um identificador de variante (option_id, sku, ean) deve ser fornecido.

Exemplo de Requisição (JSON)

// Atualização em Lote

[
  {
    "product_id": 185743,
    "option_id": 1287728,
    "quantity": 50
  },
  {
    "code": "54759024",
    "sku": "5475902402",
    "quantity": 35
  }
]

check_circle 200 OK

{
  "status": "ok",
  "results": [
    {
      "status": "ok",
      "data": {
        "product_id": 185743,
        "code": "54759024",
        "option_id": 1287728,
        "sku": "5475902402",
        "ean": "7980323238781",
        "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*	Referência (code) do produto.
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*	Referência (code) do produto.
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
        }
      }
    }
  ]
}

Atualizar Produto

PUT

Atualiza dados de um produto existente. O comportamento de variações (options) opera no formato UPSERT completo: as variações que você enviar no array e já existirem (por `option_id`, `ean` ou `sku`) serão atualizadas mantendo seus outros parâmetros intocados. Variantes não encontradas serão criadas. E qualquer variação já existente no banco que for OMITIDA no payload será apagada/inativada.

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

Parâmetros do Body (JSON)

Campo	Tipo	Obrigatório	Descrição
product_id	int	Ou code	ID interno único do produto para localizar.
code	string	Ou id	Referência do produto para localizar (caso não envie o ID).
Campos de Atualização Opcionais
new_code	string	Não	Se enviado, substitui o Reference Code atual do produto.
name	string	Não	Novo Nome/Título do produto.
brand	string	Não	Nome da marca. Se enviada, associa caso exista, ou cria uma nova.
brand_id	int	Não	ID da marca diretamente (tem prioridade sobre brand).
collection	string	Não	Nome da coleção. Se enviada, associa ou cria nova.
collection_id	int	Não	ID da coleção (prioritário sobre collection).
description	string	Não	Descrição detalhada (HTML permitido).
composition	string	Não	Composição longa de materiais.
weight	string	Não	Peso em KG (Ex: "0.350").
ncm	string	Não	Nomenclatura Comum do Mercosul.
ucom	string	Não	Unidade Comercial (Ex: "UN", "M2").
utrib	string	Não	Unidade Tributável.
options	array	Não	Lista completa e definitiva de variações sob regime de UPSERT. O sistema faz match prioritário por `option_id` -> `ean` -> `sku`. • Atenção: Qualquer opção já existente no produto que não for enviada neste array será apagada permanentemente. • Validação: Para criar novas opções, é obrigatório enviar `sku`, `price_retail` e `size`. Tentar atualizar um `option_id` inexistente também gera bloqueio. Atributos dentro de cada objeto: option_id, sku (ou code), ean, color_name, color_html, size (ou option), type, quantity, price_cost, price_wholesale, price_retail

Exemplo de Requisição

application/json

{
  "code": "REF123",
  "name": "Vestido Coleção Nova 2026",
  "brand": "Miss Misses",
  "description": "Vestido leve 100% viscose.",
  "weight": "0.350",
  "options": [
    {
      "sku": "NEW-SKU-1",
      "ean": "7890000001",
      "type": "Vestido",
      "color_name": "Vermelho",
      "color_html": "#FF0000",
      "size": "P",
      "quantity": 10,
      "price_cost": 45.00,
      "price_wholesale": 90.00,
      "price_retail": 189.90
    },
    {
      "option_id": 12892,
      "color_name": "Preto Mescla",
      "price_retail": 199.90
    }
  ]
}

check_circle 200 OK

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

error 400 Bad Request

Acontece caso tente atualizar um produto que pertence a outro lojista (segurança de sessão).

{
  "return": {
    "status": "error",
    "error": "Can't update this product. You are not the owner, view only."
  }
}

error 400 Bad Request

Retornado quando você tenta criar uma Variação nova, mas não providencia a tríade obrigatória.

{
  "return": {
    "status": "error",
    "error": "Missing mandatory fields (sku, price_retail, size or option) for creating new variant."
  }
}

error 400 Bad Request

Retornado quando você tenta mirar num option_id que o banco confirma não existir para aquele produto no payload de Upsert.

{
  "return": {
    "status": "error",
    "error": "Option ID 99999 not found."
  }
}

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 única do produto.
name	string	Sim	Nome/Título do produto.
brand	string	Não	Nome da marca. Se não existir, será criada automaticamente.
collection	string	Não	Nome da coleção. Se não existir, será criada automaticamente.
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.
weight	float	Não	Peso do produto em kg. exemplo: 0.350
length	int	Não	Comprimento do produto em cm. exemplo: 20
width	int	Não	Largura do produto em cm. exemplo: 20
height	int	Não	Altura do produto em cm. exemplo: 2
options	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": "REF123",
  "name": "Vestido Miss Misses Preto",
  "brand": "Miss Misses",
  "collection": "Verão 2026",
  "description": "<p>Vestido longo com fenda lateral.</p>",
  "composition": "<p>100% Viscose</p>",
  "price_cost": 45.00,
  "price_wholesale": 90.00,
  "price_retail": 189.90,
  "weight": "0.350",
  "options": [
    {
      "sku": "5475902402",
      "type": "Vestido",
      "color_name": "Vermelho",
      "color_html": "#FF0000",
      "size": "P",
      "ean": "7890000001",
      "quantity": 10
    },
    {
      "sku": "5475902403",
      "type": "Vestido",
      "color_name": "Vermelho",
      "color_html": "#FF0000",
      "size": "M",
      "ean": "7890000001",
      "quantity": 15
    }
  ],
  "photos": [
    {
      "url": "https://site.com/foto1.jpg",
      "width": 800,
      "height": 1200
    }
  ]
}

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "data": {
      "id": 185744,
        "options": {
        "id": 1287730
      }
    }
  }
}

error 400 Bad Request

Ocorre se code ou name estiverem vazios.

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

Consultar Estoque Reservado

GET

Retorna a quantidade de estoque reservado (aguardando pagamento, pago ou em separação) dos produtos.

GET https://api2.popstore.com.br/products/holding-stock

Parâmetros (Query String)

Campo	Tipo	Obrigatório	Descrição
product_id	int	Não	ID do Produto para filtrar as reservas de apenas um produto. Deixe vazio para retornar todos.

URL de Requisição

GET /products/holding-stock?product_id=185743

check_circle 200 OK

{
  "data": {
    "1287729": {
      "option_id": 1287729,
      "sku": "5475902402",
      "pending": 2,
      "approved": 1,
      "picked": 0,
      "total": 3
    }
  }
}

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 (YYYY-MM-DD)
date_to	string	Não	Data final (YYYY-MM-DD)
updated_at	string	Não	Data de atualização (YYYY-MM-DD HH:mm:ss)
page	int	Não	1
limit	int	Não	Itens por página (Padrão: 10, Máximo: 100)
order_id	int	Não	Número do Pedido interno
external_id	string	Não	ID estrangeiro exato associado ao pedido de origem externa (Ex. Mercado Livre)
sort	string	Não	ASC / DESC

Status do Pedido

O campo status pode retornar um dos seguintes valores:

Pending In Analysis Approved Ready to Ship 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,
      "external_id": PED-123456,
      "created_at": "2026-02-19 16:54:26",
      "updated_at": "2026-02-20 17:50:00",
      "type": "retail",
      "status": "Approved",
      "marketplace": "Vesti",
      "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",
      "shipping_deadline": "2",
      "tracking_code": "EG1234567890BR",
      "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=EG1234567890BR",
      "payment_method": "PIX",
      "sub_total": 379.74,
      "discount": 37.97,
      "shipping": 10.00,
      "total": 351.77,
      "items": [
        {
          "product_id": "185743",
          "option_id": "1287729",
          "sku": "5475902402",
          "ean": "7908981970950",
          "name": "Vestido Miss Misses Preto",
          "color": "Vermelho",
          "size": "M",
          "cost": 45.00,
          "price": 90.00
          "quantity": 1,
        }
      ]
    },
    {
       // ... demais pedidos
    }
  ]
}

Criar Pedido

POST

Cria um novo pedido no sistema. O estoque dos produtos será atualizado automaticamente.

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

Parâmetros (JSON Body)

Campo	Tipo	Obrigatório	Descrição
external_id	string	Sim	ID único do pedido no seu sistema.
type	string	Não	"retail" para varejo, "wholesale" para atacado.
status	string	Sim	Pending, Approved
marketplace	string	Não	Nome do marketplace. Ex: "Vesti".
Dados do Cliente
name	string	Sim	Nome completo.
email	string	Sim	E-mail de contato.
phone	string	Sim	Telefone com DDD.
birth_date	string	Não	Data de nascimento (formato: DD/MM/YYYY).
cpf	string	Não	CPF (apenas números).
company_name	string	Não	Razão Social.
cnpj	string	Não	CNPJ (apenas números).
ie	string	Não	Inscrição Estadual.
Endereço de Entrega
zip_code	string	Sim	CEP (apenas números).
address	string	Sim	Logradouro.
number	string	Sim	Número.
address2	string	Não	Complemento.
neighborhood	string	Sim	Bairro.
city	string	Sim	Cidade.
state	string	Sim	Nome do Estado.
state_iso	string	Sim	Sigla do Estado (ex: SP).
country	string	Não	País (Padrão: Brasil).
country_iso	string	Não	Sigla do País (Padrão: BR).
Valores e Envio
shipping_type	string	Sim	Forma de envio (ex: CORREIOS - SEDEX). O mesmo do campo name que retorna em /shipping
shipping_deadline	int	Sim	Prazo de envio em dias (ex: 5).
payment_method	string	Não	Forma de pagamento (ex: PIX).
sub_total	float	Sim	Valor total dos produtos.
discount	float	Sim	Valor do desconto.
discount_code	string	Não	Código do cupom.
shipping	float	Sim	Valor do frete.
total	float	Sim	Valor total final do pedido.
Itens do Pedido
items	array	Obrigatório	Lista de objetos contendo os seguintes campos:
└─ product_id ou code	string	Sim	ID interno ou referência SKU do produto.
└─ option_id ou sku ou ean	string	Sim	ID da variação, SKU da variação ou EAN13.
└─ quantity	integer	Sim	Quantidade desejada.
└─ price	float	Sim	Preço unitário do item.

Exemplo de Requisição

application/json

{
  "external_id": "PED-123456",
  "status": "Pending",
  "marketplace": "Vesti",
  "type": "retail",
  "name": "João da Silva",
  "email": "[email protected]",
  "phone": "(11) 98888-7777",
  "birth_date": "25/10/1985",
  "cpf": "12345678901",
  "zip_code": "01310-930",
  "address": "Avenida Paulista",
  "number": "1578",
  "address2": "apt 221",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "São Paulo",
  "state_iso": "SP",
  "country": "Brasil",
  "country_iso": "BR",
  "shipping_type": "CORREIOS - SEDEX",
  "shipping_deadline": 5,
  "payment_method": "Cartão",
  "sub_total": 1000.00,
  "discount": 100.00,
  "discount_code": "CUPOM10",
  "shipping": 25.00,
  "total": 925.00,
  "items": [
    {
      "product_id": "185743",
      "option_id": "1287728",
      "price": 250.00,
      "quantity": 2
    },
    {
      "code": "REF123",
      "sku": "5475902402",
      "price": 250.00,
      "quantity": 1
    },
    {
      "code": "REF123",
      "ean": "7890000001",
      "price": 250.00,
      "quantity": 1
    }
  ] 
}

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "id": 900500
  }
}

Atualizar Pedido

PUT

Atualiza o Status de Pagamento/Evolução de um pedido da loja. O sistema protege automaticamente pedidos já finalizados, permitindo apenas a transição de um pedido que esteja como Pending.

Atenção ao Cancelamento: Quando um pedido pendente transaciona para Canceled, a API executa um script interno automático que lê todos os produtos que estavam em seu carrinho e devolve completamente os estoques daquelas respectivas grades (options) de volta à loja. O histórico do pedido (status_history) é reescrito a cada transação automaticamente.

PUT https://api2.popstore.com.br/orders/update

Parâmetros do Body (JSON)

Campo	Tipo	Obrigatório	Descrição
order_id	integer	Ou external_id	ID interno absoluto na Popstore.
external_id	string	Ou order_id	Código estrangeiro do pedido (ID do Mktplace, ID do ERP).
Atualização de Estado
status	string	Não	Novo status que o pedido adotará. Somente: `Pending`, `Approved`, ou `Canceled`.

Exemplo de Requisição

application/json

{
  "external_id": "123444400-PAGARME",
  "status": "Approved"
}

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "data": {
      "id": 900044,
      "order_status": Approved
    }
  }
}

error 400 Bad Request

Ocorre caso tente modificar um pedido que já consta no banco como finalizado (Aprovado ou Cancelado).

{
  "return": {
    "status": "error",
    "error": "Order is already finalized (Approved/Canceled) and cannot be changed."
  }
}

error 400 Bad Request

Ocorre se tentar atualizar um pedido que pertence a outro lojista ou que não existe.

{
  "return": {
    "status": "error",
    "error": "Order not found or you do not have permission."
  }
}

Listar Categorias

GET

Lista todas as categorias de produtos vinculadas à loja atual. Retorna o ID, nome, parent_id e slug de cada categoria.

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

URL de Requisição

GET /products/categories

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "data": [
      {
        "id": 10,
        "parent_id": 0,
        "name": "Roupas",
        "slug": "roupas"
      },
      {
        "id": 11,
        "parent_id": 10,
        "name": "Vestidos",
        "slug": "vestidos-de-festa"
      }
    ]
  }
}

Criar Categoria

POST

Cria uma nova categoria de produto. Retorna o ID caso a categoria já exista com o mesmo nome e mesmo `parent_id`.

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

Payload (JSON)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	O nome da categoria.
parent_id	int	Não*	ID da categoria pai. Envie 0 para categoria primária. Padrão ao omitir: 0.
slug	string	Não	URL amigável da categoria (ex: roupas-de-inverno). Gerado automaticamente se omitido.

URL de Requisição

POST /products/categories/create

data_object Body (JSON)

{
  "name": "Vestidos",
  "parent_id": 10,
  "slug": "meus-vestidos-lindos"
}

check_circle 200 OK

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

Listar Marcas

GET

Lista todas as marcas vinculadas à loja atual.

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

URL de Requisição

GET /products/brands

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "data": {
      "123": "Marca Exemplo",
      "456": "Outra Marca"
    }
  }
}

Criar Marca

POST

Cria uma nova marca ou retorna o ID da marca existente caso ela já tenha sido criada anteriormente com o mesmo nome para a sua loja.

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

Payload (JSON)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	O nome interno ou fantasia da marca.

URL de Requisição

POST /products/brands/create

data_object Body (JSON)

{
  "name": "Marca Exemplo"
}

check_circle 200 OK

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

Listar Coleções

GET

Lista todas as coleções vinculadas à loja atual.

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

URL de Requisição

GET /products/collections

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "data": {
      "123": "Coleção Verão",
      "456": "Coleção Inverno"
    }
  }
}

Criar Coleção

POST

Cria uma nova coleção ou retorna o ID da coleção existente caso ela já tenha sido criada anteriormente com o mesmo nome para a sua loja.

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

Payload (JSON)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	O nome da coleção.
brand_id	int	Não	ID da marca opcional para vincular à coleção.
brand_name	string	Não	Nome da marca. Se o ID não for informado, a API buscará ou criará automaticamente a marca a partir deste nome.

URL de Requisição

POST /products/collections/create

data_object Body (JSON)

{
  "name": "Coleção Verão",
  "brand_id": 123,
  "brand_name": "Nome da Marca"
}

check_circle 200 OK

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

Listar Opções

GET

Lista todas as opções (grades) vinculadas à loja atual. (ex: P, M, G, Único)

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

URL de Requisição

GET /products/options

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "data": {
      "1": "P",
      "2": "M",
      "3": "G"
    }
  }
}

Criar Opção

POST

Cria uma nova opção de grade (ex: G) ou retorna o ID da opção existente caso ela já tenha sido criada anteriormente com o mesmo nome para a sua loja.

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

Payload (JSON)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	O nome interno da opção de grade.

URL de Requisição

POST /products/options/create

data_object Body (JSON)

{
  "name": "G"
}

check_circle 200 OK

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

Listar Tipos

GET

Lista todos os tipos de produtos vinculados à loja atual. (ex: Vestido, Blusa, Calça)

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

URL de Requisição

GET /products/types

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "data": {
      "1": "Vestido",
      "2": "Blusa",
      "3": "Calça"
    }
  }
}

Criar Tipo

POST

Cria um novo tipo de produto (ex: Vestido) ou retorna o ID do tipo existente caso ele já tenha sido criado anteriormente com o mesmo nome para a sua loja.

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

Payload (JSON)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	O nome interno do tipo de produto.

URL de Requisição

POST /products/types/create

data_object Body (JSON)

{
  "name": "Vestido"
}

check_circle 200 OK

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

Listar Clientes

GET

Retorna a lista de clientes, permitindo paginação e busca detalhada.

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

Parâmetros (Query String)

Campo	Tipo	Obrigatório	Descrição
page	int	Não	Número da página para paginação. Padrão: 1.
limit	int	Não	Quantidade de clientes por página. Padrão: 10. Máximo: 100.
search	string	Não	Termo de busca genérico. Busca por ID, nome, e-mail, CPF ou CNPJ.
id	int	Não	ID específico do cliente para filtragem direta. Retornará apenas um cliente se encontrado.

URL de Requisição

GET /customers?limit=10&page=1

check_circle 200 OK

{
  "return": {
    "status": "ok"
  },
  "data": [
    {
      "id": 123,
      "register_type": "person",
      "name": "Maria Oliveira",
      "email": "[email protected]",
      "phone": "(11) 99999-8888",
      "birth_date": "15/06/1990",
      "cpf": "11122233344",
      "company_name": "",
      "cnpj": "",
      "ie": "",
      "zip_code": "01310-100",
      "address": "Av. Paulista",
      "number": "1000",
      "address2": "Apto 31",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "São Paulo",
      "state_iso": "SP",
      "country": "Brasil",
      "country_iso": "BR",
      "created_at": "2023-11-20 10:30:00",
      "status": "active"
    }
  ],
  "meta": {
    "total_items": 1,
    "total_pages": 1,
    "current_page": 1,
    "items_per_page": 10
  }
}

Criar Cliente

POST

Cria um cliente validando seus dados obrigatórios e definindo automaticamente seu status. É obrigatório informar o tipo de cliente (type), sendo retail para pessoa física e wholesale para pessoa jurídica. Dependendo do type, torna-se obrigatório informar cpf para retail e cnpj para wholesale.

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

Corpo da Requisição (JSON)

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de cliente: `retail` ou `wholesale`.
name	string	Sim	Nome completo do cliente.
email	string	Sim	E-mail para login e contato (deve ser único).
phone	string	Sim	Telefone de contato com DDD.
birth_date	string	Não	Data de nascimento formato DD/MM/YYYY.
cpf	string	Condicional	CPF do titular. Obrigatório se `type` for `retail`.
company_name	string	Não	Razão Social (PJ).
cnpj	string	Condicional	CNPJ (PJ). Obrigatório se `type` for `wholesale`.
ie	string	Não	Inscrição Estadual (PJ).
password	string	Não	Senha de acesso do cliente. Gerada automaticamente caso não seja preenchida.
Endereço de Entrega
zip_code	string	Sim	CEP.
address	string	Sim	Logradouro / Rua.
number	string	Sim	Número.
address2	string	Não	Complemento.
neighborhood	string	Sim	Bairro.
city	string	Sim	Cidade.
state	string	Sim	Estado (Nome Completo).
state_iso	string	Sim	UF do Estado.
country	string	Não	País.
country_iso	string	Não	País (ISO).

Exemplo de Requisição (JSON)

{
  "type": "retail",
  "name": "João Albergossi",
  "email": "[email protected]",
  "password": "senha_segura_123",
  "phone": "(11) 98888-7777",
  "birth_date": "25/10/1985",
  "cpf": "12345678901",
  "zip_code": "01310-930",
  "address": "Avenida Paulista",
  "number": "1578",
  "address2": "Apto 204",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "São Paulo",
  "state_iso": "SP",
  "country": "Brasil",
  "country_iso": "BR"
}

check_circle 200 OK

{
  "return": {
    "status": "ok",
    "id": 501
  }
}

Obter Cotações de Frete

GET

Retorna todas as opções de frete ativas na loja para um determinado CEP, peso e dimensões. A API se encarrega de consultar todas as transportadoras (como Correios) e retornar o array unificado ordenado pelo menor preço.

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

Parâmetros (Query String)

Campo	Tipo	Obrigatório	Descrição
zip_code	string	Sim	CEP de destino. Ex: 00000-000 ou apenas números.
weight	float	Sim	Peso do pacote em Quilogramas (Kg). Ex: 0.3 para 300g, 1.2 para 1.2kg.
height, width, depth	int	Não	Dimensões da caixa em centímetros: Altura, Largura e Profundidade.
total	float	Sim	Valor total do carrinho, exigido para calcular promoções de frete grátis e seguro.

URL de Requisição

GET /shipping?zip_code=01001-000&weight=0.300&total=250.00

check_circle 200 OK

{
  "success": true,
  "rates": [
    {
      "name": "CORREIOS - PAC",
      "price": 0.00,
      "deadline": 8,
      "tag": "Free Shipping"
    },
    {
      "name": "CORREIOS - SEDEX",
      "price": 18.90,
      "deadline": 2
    }
  ]
}

Cadastrar ou Alterar Webhook

POST

Este endpoint é utilizado tanto para registrar um novo webhook quanto para atualizá-lo. A URL vinculada à sua Chave de API (Bearer Token) será cadastrada (ou sobrescrita caso já exista) para receber as notificações de eventos da plataforma.

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

data_object Corpo da Requisição (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
webhook	string	Sim	A URL completa (incluindo https://) que receberá as notificações. Formato válido de URL requerido.

call_made Formato do Disparo (O que você recebe)

Quando houver alterações nos registros da loja, o PopStore fará uma requisição POST automatizada em lotes (agrupando até 500 eventos por vez) para a sua URL cadastrada contendo o payload em application/json neste formato restrito abaixo, devolvendo apenas os IDs numéricos para proteção de dados:

{
  "orders": [900044, 900055, 900078],
  "products": [185743, 185754],
  "customers": [123456]
}

lightbulb É de sua responsabilidade consultar/injetar estes IDs nas outras rotas da API (`GET /orders/[id]`, etc.) para baixar a carga processada em ambiente seguro.

Exemplo de Requisição (JSON)

{
  "webhook": "https://int.seusistema.com.br/webhooks/popstore"
}

check_circle 200 OK

{
  "return": {
    "status": "ok"
  },
  "data": {
    "webhook": "https://int.seusistema.com.br/webhooks/popstore",
    "message": "Webhook registered successfully for this API Key."
  }
}