Produtos

Os produtos cadastrados são o que o operador vê na tela do Smart POS para vender direto no app, sem digitar valor. São três cadastros: categoria e marca, que organizam a exibição, e o produto, que é o item vendido.

Ordem de cadastro

Um produto só aponta para uma categoria ou marca já cadastrada. A ordem, portanto, é sempre a mesma:

Categoria — os agrupamentos que aparecem na tela.
Marca — opcional, mas cadastrada antes do produto que a referencia.
Produto — em lote, referenciando as duas anteriores.

Conceitos comuns

Antes dos endpoints, duas regras valem para os três recursos. Paginação, ordenação e códigos de resposta seguem o padrão comum a toda a API — veja a página de Referência.

Identificador

Categoria, marca e produto são endereçados por um identificador — um código definido por você (SKU, código interno). É ele que aparece nas URLs e nos vínculos entre os recursos, não o id numérico que a API devolve.

Regra	Valor
Tamanho	1 a 32 caracteres
Caracteres aceitos	letras (A–Z, a–z), números (0–9) e hífen
Unicidade	não pode repetir dentro da mesma empresa

O identificador não é editável

Não existe operação para trocar o identificador de um registro. Para mudá-lo, exclua e cadastre outro — o que também desfaz os vínculos de produtos que apontavam para ele. Escolha o padrão de código antes de carregar a base.

Imagem

O campo imagem é opcional nos três recursos. Quando enviado, é a imagem codificada em base64 com prefixo data URI:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

Limite	Valor
Formatos	PNG, JPG, JPEG, GIF, TIFF
Tamanho	1 MB
Dimensões	512 × 512 pixels

Nas respostas, imagem vem como a URL pública do arquivo — nunca como base64.

Categoria

Agrupa produtos na tela do Smart POS. É o primeiro dos três cadastros.

Endpoints

Método	Endpoint	Descrição
`POST`	`/produto/categoria`	Cadastrar categoria
`PUT`	`/produto/categoria`	Editar categoria
`GET`	`/produto/categoria`	Listar categorias
`DELETE`	`/produto/categoria/{identificador}`	Excluir categoria

Cadastrando

curl --request POST \
  --url 'https://api.pinpdv.com.br/produto/categoria' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "identificador": "BEBIDAS",
    "nome": "Bebidas geladas",
    "ordenar": 1,
    "descricao": "Refrigerantes, sucos e água",
    "cor": "#1E88E5"
  }'

Campo	Tipo	Obrigatório	Regra
`identificador`	texto	sim	1–32 caracteres, único
`nome`	texto	sim	4 a 80 caracteres
`ordenar`	número	não	0 a 255 — ordem de exibição na tela
`descricao`	texto	não	até 180 caracteres
`cor`	texto	não	até 12 caracteres (ex.: `#1E88E5`)
`imagem`	texto	não	ver Imagem

200 - OK

{
  "id": 42,
  "identificador": "BEBIDAS",
  "nome": "Bebidas geladas",
  "ordenar": 1,
  "descricao": "Refrigerantes, sucos e água",
  "imagem": null,
  "cor": "#1E88E5"
}

Editando

O identificador vai no corpo e serve para localizar o registro.

curl --request PUT \
  --url 'https://api.pinpdv.com.br/produto/categoria' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "identificador": "BEBIDAS",
    "nome": "Bebidas",
    "ordenar": 2,
    "descricao": "Bebidas em geral",
    "cor": "#0D47A1",
    "imagem": null,
    "removerImagem": false
  }'

A imagem tem três comportamentos, combinando imagem e removerImagem:

`imagem`	`removerImagem`	Resultado
preenchida	`false`	substitui a imagem
vazia ou nula	`false`	mantém a imagem atual
vazia ou nula	`true`	remove a imagem

202 - Accepted

Listando

curl --request GET \
  --url 'https://api.pinpdv.com.br/produto/categoria?paginaNumero=1&qtdRegistro=50&ordenarPor=Nome&ordenarTipo=ASC' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

Valores aceitos em ordenarPor: Id, Identificador, Nome, Descricao, CadastradoEm, AtualizadoEm.

Cada item de data:

{
  "id": 42,
  "identificador": "BEBIDAS",
  "nome": "Bebidas",
  "ordenar": 1,
  "descricao": "Bebidas em geral",
  "imagem": "https://cdn.pinpdv.com.br/produto-categorias/42/abc123.png",
  "cor": "#1E88E5",
  "cadastradoPor": { "id": 12, "nome": "Fulano", "dataHora": "2026-08-01T10:22:00" },
  "atualizadoPor": { "id": 12, "nome": "Fulano", "dataHora": "2026-08-20T14:05:00" }
}

Excluindo

curl --request DELETE \
  --url 'https://api.pinpdv.com.br/produto/categoria/BEBIDAS' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

202 - Accepted

Excluir a categoria não exclui nem bloqueia os produtos vinculados a ela — eles continuam à venda, apenas deixam de exibir a categoria.

Marca

O contrato é idêntico ao de categoria — mesmos campos, mesmas regras, mesmas respostas, mesmo comportamento de imagem. Muda apenas a rota.

Endpoints

Método	Endpoint	Descrição
`POST`	`/produto/marca`	Cadastrar marca
`PUT`	`/produto/marca`	Editar marca
`GET`	`/produto/marca`	Listar marcas
`DELETE`	`/produto/marca/{identificador}`	Excluir marca

Cadastrando

curl --request POST \
  --url 'https://api.pinpdv.com.br/produto/marca' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "identificador": "COCACOLA",
    "nome": "Coca-Cola",
    "ordenar": 1,
    "descricao": "Refrigerantes Coca-Cola",
    "cor": "#E53935"
  }'

200 - OK

{
  "id": 8,
  "identificador": "COCACOLA",
  "nome": "Coca-Cola",
  "ordenar": 1,
  "descricao": "Refrigerantes Coca-Cola",
  "imagem": null,
  "cor": "#E53935"
}

Editando

curl --request PUT \
  --url 'https://api.pinpdv.com.br/produto/marca' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "identificador": "COCACOLA",
    "nome": "Coca-Cola Brasil",
    "ordenar": 2,
    "descricao": "Bebidas Coca-Cola",
    "cor": "#B71C1C",
    "imagem": null,
    "removerImagem": false
  }'

202 - Accepted

Listando e excluindo

# Listar
curl --request GET \
  --url 'https://api.pinpdv.com.br/produto/marca?paginaNumero=1&qtdRegistro=50&ordenarPor=Nome&ordenarTipo=ASC' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

# Excluir
curl --request DELETE \
  --url 'https://api.pinpdv.com.br/produto/marca/COCACOLA' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

Valores aceitos em ordenarPor: Id, Identificador, Nome, Descricao, CadastradoEm, AtualizadoEm. O formato dos itens é o mesmo da listagem de categorias.

Como na categoria, excluir a marca não afeta os produtos vinculados.

Produto

O item vendido. Cadastrado em lote, editado um a um.

Endpoints

Método	Endpoint	Descrição
`POST`	`/produto`	Cadastrar produtos (1 a 100 por chamada)
`GET`	`/produto`	Listar produtos
`PUT`	`/produto`	Editar produto
`PUT`	`/produto/{identificador}/ativar`	Ativar produto
`PUT`	`/produto/{identificador}/desativar`	Desativar produto
`DELETE`	`/produto/{identificador}`	Excluir produto

Cadastrando

Os produtos vão em data, de 1 até 100 por requisição.

curl --request POST \
  --url 'https://api.pinpdv.com.br/produto' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "identificador": "REFRI-350",
      "nome": "Refrigerante lata 350ml",
      "preco": 6.50,
      "unidade": "Unidade",
      "descricao": "Lata 350ml gelada",
      "categoria": "BEBIDAS",
      "marca": "COCACOLA",
      "modelo": "Lata",
      "codigoBarras": "7894900011517"
    }
  ]'

Campo	Tipo	Obrigatório	Regra
`identificador`	texto	sim	1–32 caracteres, único
`nome`	texto	sim	4 a 80 caracteres
`preco`	decimal	sim	maior que 0 e até 999999,99
`unidade`	texto	não	ver Unidades — padrão `Unidade`
`descricao`	texto	não	até 180 caracteres
`categoria`	texto	não	identificador de uma categoria existente
`marca`	texto	não	identificador de uma marca existente
`modelo`	texto	não	até 60 caracteres
`codigoBarras`	texto	não	até 40 caracteres
`imagem`	texto	não	ver Imagem

A validação do lote é tudo ou nada

Um único item inválido reprova a requisição inteira com 422 — nenhum produto do lote é gravado. Também não repita o mesmo identificador dentro da mesma chamada.

Ao carregar listas grandes, prefira lotes menores: fica mais simples identificar qual item reprovou.

A resposta traz um objeto por produto criado:

200 - OK

[
  {
    "id": 981,
    "identificador": "REFRI-350",
    "nome": "Refrigerante lata 350ml",
    "isAtivo": true,
    "preco": 6.50,
    "descricao": "Lata 350ml gelada",
    "categoria": { "key": "BEBIDAS", "value": "Bebidas" },
    "marca": { "key": "COCACOLA", "value": "Coca-Cola" },
    "modelo": "Lata",
    "codigoBarras": "7894900011517"
  }
]

Unidades

Valores aceitos em unidade:

Unidade, Litro, Quilograma.

Editando

Um produto por requisição. O corpo é o produto direto, sem array.

curl --request PUT \
  --url 'https://api.pinpdv.com.br/produto' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "identificador": "REFRI-350",
    "nome": "Refrigerante lata 350ml",
    "preco": 7.00,
    "unidade": "Unidade",
    "descricao": "Lata 350ml",
    "categoria": "BEBIDAS",
    "marca": "COCACOLA",
    "modelo": "Lata",
    "codigoBarras": "7894900011517",
    "imagem": null
  }'

É substituição completa, não alteração parcial

Campo omitido é gravado como vazio. Para mudar só o preço, ainda assim envie o produto inteiro — nome, categoria, marca, código de barras e o resto. Leia o produto na listagem, altere o campo e devolva tudo.

Consequência direta: categoria ou marca enviadas vazias desvinculam o produto.

Há uma exceção à regra acima: imagem vazia ou nula mantém a imagem atual — não a apaga.

A resposta é o produto atualizado, no mesmo formato do cadastro.

Listando

curl --request GET \
  --url 'https://api.pinpdv.com.br/produto?paginaNumero=1&qtdRegistro=100&ordenarPor=Nome&ordenarTipo=ASC' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

Valores aceitos em ordenarPor: Id, Identificador, Nome, Descricao, Categoria, Marca, Modelo, CodigoBarras, IsAtivo, Preco, CadastradoEm, AtualizadoEm.

Há ainda um parâmetro exclusivo desta listagem:

Parâmetro	Efeito
`removerImagem`	`true` omite as imagens da resposta — útil em sincronizações grandes, onde as URLs não interessam

Cada item de data traz categoria e marca expandidas, não apenas o identificador:

{
  "id": 981,
  "identificador": "REFRI-350",
  "nome": "Refrigerante lata 350ml",
  "descricao": "Lata 350ml",
  "categoria": { "id": 42, "identificador": "BEBIDAS", "nome": "Bebidas", "cor": "#1E88E5" },
  "marca": { "id": 8, "identificador": "COCACOLA", "nome": "Coca-Cola", "cor": "#E53935" },
  "modelo": "Lata",
  "codigoBarras": "7894900011517",
  "unidade": "Unidade",
  "preco": 7.00,
  "isAtivo": true,
  "imagens": [
    { "url": "https://cdn.pinpdv.com.br/produtos/981/abc123.png", "padrao": true }
  ],
  "cadastradoPor": { "id": 12, "nome": "Fulano", "dataHora": "2026-08-01T10:22:00" },
  "atualizadoPor": { "id": 12, "nome": "Fulano", "dataHora": "2026-08-20T14:05:00" }
}

A listagem traz produtos ativos e inativos — use isAtivo para distinguir.

Ativando e desativando

Prefira desativar a excluir: o produto some da tela do Smart POS mas permanece no cadastro, pronto para voltar.

# Desativar
curl --request PUT \
  --url 'https://api.pinpdv.com.br/produto/REFRI-350/desativar' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

# Ativar
curl --request PUT \
  --url 'https://api.pinpdv.com.br/produto/REFRI-350/ativar' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

202 - Accepted

Excluindo

curl --request DELETE \
  --url 'https://api.pinpdv.com.br/produto/REFRI-350' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

202 - Accepted

O produto sai do cadastro, mas permanece nas vendas já registradas — o histórico não é afetado.

Erros mais comuns

Mensagem	Causa
`O Identificador já existe cadastrado.`	identificador em uso na empresa
`O Identificador contém caracteres inválidos.`	use apenas letras, números e hífen
`O Nome deve ter no mínimo 4 caracteres`	nome curto demais
`O Preço deve ser maior que zero (0.00)`	preço zerado ou negativo
`Nenhuma categoria foi encontrada com o identificador fornecido`	cadastre a categoria antes do produto
`Nenhuma marca foi encontrada com o identificador fornecido`	cadastre a marca antes do produto
`O formato da imagem é inválido.`	falta o prefixo `data:image/...;base64,` ou o formato não é aceito

Teste antes de escrever código

A coleção do Postman traz as requisições prontas, nas pastas Cadastro de Categorias, Cadastro de Marcas e Cadastro de Produtos — nessa ordem — para você experimentar antes de escrever a primeira linha de código.

Print Server

Transações

Documentacao

Multiplus Card [Docs]

Title here

Produtos

Ordem de cadastro

Conceitos comuns

Identificador

Imagem

Categoria

Endpoints

Cadastrando

Editando

Listando

Excluindo

Marca

Endpoints

Cadastrando

Editando

Listando e excluindo

Produto

Endpoints

Cadastrando

Unidades

Editando

Listando

Ativando e desativando

Excluindo

Erros mais comuns

Produtos

Ordem de cadastro#

Conceitos comuns#

Identificador#

Imagem#

Categoria#

Endpoints#

Cadastrando#

Editando#

Listando#

Excluindo#

Marca#

Endpoints#

Cadastrando#

Editando#

Listando e excluindo#

Produto#

Endpoints#

Cadastrando#

Unidades#

Editando#

Listando#

Ativando e desativando#

Excluindo#

Erros mais comuns#

Ordem de cadastro

Conceitos comuns

Identificador

Imagem

Categoria

Endpoints

Cadastrando

Editando

Listando

Excluindo

Marca

Endpoints

Cadastrando

Editando

Listando e excluindo

Produto

Endpoints

Cadastrando

Unidades

Editando

Listando

Ativando e desativando

Excluindo

Erros mais comuns