API legada/Referência completa/PDV e terminal de balcão

Produtos e clientes do PDV

Baixa, de forma paginada, os produtos e os clientes da loja para a base local do terminal de balcão.

O terminal precisa funcionar mesmo com a internet lenta, então ele guarda uma cópia dos produtos e dos clientes e consulta essa cópia no balcão. Estas duas rotas alimentam a cópia: pos_products devolve os produtos com preço, código de barras e estoque, e pos_customers devolve os clientes com nome, e-mail e telefone. As duas são só de leitura, paginadas e exigem um usuário administrador.

GET/api/v1.0/pos_productsAdmin

Venddor 1.0: produtos para o terminal (ids UUID)

Lista os produtos da loja. pos_barcode é igual ao SKU (product_code): o código de barras é o próprio SKU do produto.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido volta para 1.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora disso volta para 10.

searchstring

Busca por palavras: cada palavra precisa aparecer no nome, na descrição, no SKU, no código de barras ou nas palavras-chave do produto. Também aceita colar o id do produto.

GET/api/pos_productsAdmin

Produtos para o terminal, forma sem versão (ids decimais)

Igual a GET /api/v1.0/pos_products, com product_id em número decimal (string).

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250.

searchstring

Busca por palavras no nome, na descrição, no SKU e no código de barras.

GET/api/v1.0/pos_customersAdmin

Venddor 1.0: clientes para o terminal (ids UUID)

Lista os usuários do tipo cliente (compradores), do cadastro mais novo para o mais antigo. Administradores e sellers não entram.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250.

searchstring

Busca por texto no nome, no sobrenome e no e-mail. Com 3 ou mais dígitos, também procura no CPF e no CNPJ.

GET/api/pos_customersAdmin

Clientes para o terminal, forma sem versão (ids decimais)

Igual a GET /api/v1.0/pos_customers, com user_id em número decimal (string).

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250.

searchstring

Busca por texto no nome, no sobrenome e no e-mail (e no CPF/CNPJ com 3 ou mais dígitos).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1.0/pos_products?page=1&items_per_page=50" \
  -u "$ADMIN_EMAIL:$API_KEY"

curl "$BASE_URL/api/v1.0/pos_customers?search=maria" \
  -u "$ADMIN_EMAIL:$API_KEY"

Resposta

200Produtos

json

{
  "status": 200,
  "data": {
    "success": true,
    "message": "",
    "products": [
      {
        "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
        "product": "Notebook Vintage Vermelho 04018",
        "price": "1678.95",
        "product_code": "SD-004018-C",
        "pos_barcode": "SD-004018-C",
        "image_path": "/uploads/minhaloja/notebook-vermelho.png",
        "amount": "77",
        "options": []
      }
    ],
    "search": { "page": 1, "items_per_page": 10, "total_items": 4985 }
  }
}

200Clientes

json

{
  "status": 200,
  "data": {
    "success": true,
    "message": "",
    "customers": [
      {
        "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
        "email": "maria.souza@example.com",
        "firstname": "Maria",
        "lastname": "Souza",
        "phone": "+5511999990000"
      }
    ],
    "search": { "page": 1, "items_per_page": 20, "total_items": 1 }
  }
}

Campos da resposta

data.products[].product_idstring

Id do produto (UUID, ou decimal em /api). É o product_id do fechamento.

data.products[].productstring

Nome do produto.

data.products[].pricestring

Preço de venda em string decimal ("1678.95"). É o preço de catálogo; promoções por cliente não entram.

data.products[].product_codestring

SKU. Vazio quando o produto não tem SKU.

data.products[].pos_barcodestring

Código de barras para a leitura no balcão. Igual ao SKU; vazio sem SKU.

data.products[].image_pathstring

Caminho da primeira imagem do produto, relativo ao domínio da loja. Vazio sem imagem.

data.products[].amountstring

Estoque disponível, em string ("77"). Pode ter casas decimais em produtos vendidos por peso.

data.products[].optionsarray

Sempre vazia: variações e opções do produto não são enviadas por esta rota.

data.customers[].user_idstring

Id do cliente (UUID, ou decimal em /api).

data.customers[].emailstring

E-mail do cliente.

data.customers[].firstnamestring

Nome.

data.customers[].lastnamestring

Sobrenome.

data.customers[].phonestring

Telefone, como foi cadastrado.

data.searchobject

Paginação: page, items_per_page (o valor efetivamente usado) e total_items (total que atende à busca, em todas as páginas).

Erros

Status	Quando	Corpo
200	Falha ao consultar a base (`success: false`)	`{"status":200,"data":{"success":false,"message":"..."}}`
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`

Veja também

Produtos e clientes do PDV

Baixa, de forma paginada, os produtos e os clientes da loja para a base local do terminal de balcão.

GET/api/v1.0/pos_productsAdmin

Venddor 1.0: produtos para o terminal (ids UUID)

Lista os produtos da loja. pos_barcode é igual ao SKU (product_code): o código de barras é o próprio SKU do produto.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido volta para 1.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora disso volta para 10.

searchstring

Busca por palavras: cada palavra precisa aparecer no nome, na descrição, no SKU, no código de barras ou nas palavras-chave do produto. Também aceita colar o id do produto.

GET/api/pos_productsAdmin

Produtos para o terminal, forma sem versão (ids decimais)

Igual a GET /api/v1.0/pos_products, com product_id em número decimal (string).

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250.

searchstring

Busca por palavras no nome, na descrição, no SKU e no código de barras.

GET/api/v1.0/pos_customersAdmin

Venddor 1.0: clientes para o terminal (ids UUID)

Lista os usuários do tipo cliente (compradores), do cadastro mais novo para o mais antigo. Administradores e sellers não entram.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250.

searchstring

Busca por texto no nome, no sobrenome e no e-mail. Com 3 ou mais dígitos, também procura no CPF e no CNPJ.

GET/api/pos_customersAdmin

Clientes para o terminal, forma sem versão (ids decimais)

Igual a GET /api/v1.0/pos_customers, com user_id em número decimal (string).

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250.

searchstring

Busca por texto no nome, no sobrenome e no e-mail (e no CPF/CNPJ com 3 ou mais dígitos).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1.0/pos_products?page=1&items_per_page=50" \
  -u "$ADMIN_EMAIL:$API_KEY"

curl "$BASE_URL/api/v1.0/pos_customers?search=maria" \
  -u "$ADMIN_EMAIL:$API_KEY"

Resposta

200Produtos

json

{
  "status": 200,
  "data": {
    "success": true,
    "message": "",
    "products": [
      {
        "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
        "product": "Notebook Vintage Vermelho 04018",
        "price": "1678.95",
        "product_code": "SD-004018-C",
        "pos_barcode": "SD-004018-C",
        "image_path": "/uploads/minhaloja/notebook-vermelho.png",
        "amount": "77",
        "options": []
      }
    ],
    "search": { "page": 1, "items_per_page": 10, "total_items": 4985 }
  }
}

200Clientes

json

{
  "status": 200,
  "data": {
    "success": true,
    "message": "",
    "customers": [
      {
        "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
        "email": "maria.souza@example.com",
        "firstname": "Maria",
        "lastname": "Souza",
        "phone": "+5511999990000"
      }
    ],
    "search": { "page": 1, "items_per_page": 20, "total_items": 1 }
  }
}

Campos da resposta

data.products[].product_idstring

Id do produto (UUID, ou decimal em /api). É o product_id do fechamento.

data.products[].productstring

Nome do produto.

data.products[].pricestring

Preço de venda em string decimal ("1678.95"). É o preço de catálogo; promoções por cliente não entram.

data.products[].product_codestring

SKU. Vazio quando o produto não tem SKU.

data.products[].pos_barcodestring

Código de barras para a leitura no balcão. Igual ao SKU; vazio sem SKU.

data.products[].image_pathstring

Caminho da primeira imagem do produto, relativo ao domínio da loja. Vazio sem imagem.

data.products[].amountstring

Estoque disponível, em string ("77"). Pode ter casas decimais em produtos vendidos por peso.

data.products[].optionsarray

Sempre vazia: variações e opções do produto não são enviadas por esta rota.

data.customers[].user_idstring

Id do cliente (UUID, ou decimal em /api).

data.customers[].emailstring

E-mail do cliente.

data.customers[].firstnamestring

Nome.

data.customers[].lastnamestring

Sobrenome.

data.customers[].phonestring

Telefone, como foi cadastrado.

data.searchobject

Paginação: page, items_per_page (o valor efetivamente usado) e total_items (total que atende à busca, em todas as páginas).

Erros

Status	Quando	Corpo
200	Falha ao consultar a base (`success: false`)	`{"status":200,"data":{"success":false,"message":"..."}}`
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`