Cadastro de Produto (PROD) — Documentação Complementar

https://<host>:<porta>/root/dicionario?userToken=<token>

Antes de incluir um produto, os cadastros abaixo precisam existir no ERP, porque são referenciados pelo produto e validados pelo servidor na inclusão:

Cadastro	Campo em PROD	Observação
Grupo e Subgrupo de produtos	GP_COD, SG_COD	O par (grupo, subgrupo) é validado em conjunto. Obrigatório.
Tipo de Produto (TPPRO)	TP_COD	Obrigatório. Define se o produto controla estoque e qual a sua natureza no SPED. Campo central: condiciona controle de série e alterações futuras.
Linha de Produto (LINPROD)	LP_COD	Obrigatório.
Unidade (PRODUNI)	PD_UNI, PD_UNI2, PD_UNI3, PD_UNITRIB	A sigla da unidade deve existir na tabela de unidades. PD_UNI (venda) é obrigatório.
NCM (PRODNCM)	PD_CODNCM	Obrigatório por regra de negócio, e o código informado deve estar cadastrado na tabela de NCM.
Tabela de Preço (TABPRECO1)	—	Necessária apenas se você for informar preço (Passo 7).
Fornecedor padrão (CLIFOR1)	PD_CFCODPADRAO	Opcional. Ver página Cadastro de Pessoas.
Códigos de tributação	TRB_CODICMS, TRB_CODIPI, TRB_CODPIS, TRB_CODCOFINS e demais	Opcionais no cadastro, mas normalmente exigidos pela operação fiscal. Podem ser herdados do NCM.

Esses cadastros são mantidos pela operação dentro do próprio ERP. Para conhecer os objetos exatos expostos pela API para cada um deles e as chaves de referência aceitas, consulte o dicionário oficial da sua instância.

O código identificador do produto (PD_COD) é a chave primária da tabela PROD e deve ser informado pelo integrador no momento da criação. O ERP não gera esse código automaticamente em uma sequence dedicada — a regra de negócio é simples: o próximo código livre é o maior código existente mais 1.

Como descobrir o próximo código

Antes de cada inclusão, faça uma consulta prévia via API ("method": "GET") sobre o objeto PROD, recuperando o maior valor da coluna PD_COD atualmente cadastrado. O próximo código a enviar no POST é esse valor incrementado em 1:

próximo PD_COD = MAX(PD_COD na tabela PROD) + 1

A forma exata de pedir esse agregado — campos, filtros, parâmetros de ordenação ou de seleção (fields, where, orderBy, limit) — está descrita no dicionário oficial da sua API, na entrada do objeto PROD.

Exemplo — consultar o maior código

{
    "method": "GET",
    "objectType": "TABLE",
    "objectName": "PROD",
    "fields": [
        { "name": "PD_COD" }
    ],
    "orderBy": [
        { "name": "PD_COD", "direction": "DESC" }
    ],
    "limit": 1
}

Confirme no dicionário oficial a sintaxe de fields, orderBy e limit aceita pela sua instância.

Campos obrigatórios

São os campos sem os quais a inclusão em PROD é rejeitada:

Campo	Tipo	Descrição
PD_COD	numérico (6)	Código do produto — chave primária. Obtido no Passo 2.
PD_DES	texto (120)	Descrição do produto.
GP_COD	numérico (3)	Grupo do produto.
SG_COD	numérico (3)	Subgrupo do produto, dentro do grupo informado.
TP_COD	numérico (4)	Tipo de produto.
LP_COD	numérico (6)	Linha de produto.
PD_UNI	texto (5)	Unidade de venda. Sigla existente na tabela de unidades.
PD_CODNCM	texto (10)	NCM do produto. Exigido por regra de negócio, com máscara 9999.99.99, e o código deve existir na tabela de NCM.
PD_GENERICO	numérico (1)	Produto genérico para uso em orçamento. 0 = não, 1 = sim. Assume 0 quando omitido.

Campos fortemente recomendados

• PD_UNI3 — unidade de estoque. É a unidade de referência de todas as equivalências e de todo o controle de saldo. Alterá-la depois que o produto for movimentado é bloqueado (ver Passo 8).
• PD_UNI2 — unidade de compra; PD_UNITRIB — unidade tributável (usada no XML fiscal).
• PD_STATUS — situação do produto: 1 = ativo, 0 = inativo.
• PD_REF — referência do produto. Atenção: algumas empresas configuram a referência como exclusiva; nesse caso, repetir uma referência já usada gera erro apontando o produto que a utiliza.

Campos preenchidos automaticamente pelo servidor

Não é necessário enviar os campos abaixo; o servidor os resolve na inclusão:

• PD_ITM — item do produto dentro do grupo/subgrupo; auto-numerado (maior item do par grupo+subgrupo + 1) quando enviado como 0 ou omitido.
• PD_DATA — data de atualização do cadastro; sempre sobrescrita pelo servidor.
• PD_CLF — classificação fiscal; recebe o PD_CODNCM quando não informada.
• PD_CEST — herdado do cadastro de NCM quando não informado.
• PD_UNIORC — sub-unidade de orçamento; recebe PD_UNI3 quando vazia.
• GP_COD, SG_COD, TP_COD, LP_COD, PD_UNI, PD_UNI2, PD_UNI3, PD_UNITRIB e os métodos de pauta — herdados do cadastro de NCM quando enviados zerados ou vazios.

Com os pré-requisitos verificados e o próximo código em mãos, inclua o produto por uma requisição com "method": "POST" sobre PROD.

Exemplo — POST PROD

{
    "method": "POST",
    "objectType": "TABLE",
    "objectName": "PROD",
    "dataFields": [
        { "name": "PD_COD",     "value": 1201 },
        { "name": "PD_DES",     "value": "PARAFUSO SEXTAVADO 1/2 X 2" },
        { "name": "PD_REF",     "value": "PSX-1202" },
        { "name": "GP_COD",     "value": 10 },
        { "name": "SG_COD",     "value": 3 },
        { "name": "TP_COD",     "value": 1 },
        { "name": "LP_COD",     "value": 1 },
        { "name": "PD_UNI",     "value": "PC" },
        { "name": "PD_UNI2",    "value": "CX" },
        { "name": "PD_UNI3",    "value": "PC" },
        { "name": "PD_UNITRIB", "value": "PC" },
        { "name": "PD_CODNCM",  "value": "7318.15.00" },
        { "name": "PD_STATUS",  "value": 1 },
        { "name": "PD_GENERICO","value": 0 }
    ]
}

Valores ilustrativos. Os códigos, siglas e o NCM acima são exemplos. Use os cadastros da sua instância. A lista completa e autoritativa de campos de PROD está no dicionário oficial.

O que o servidor faz imediatamente após a inclusão

• Cria as equivalências de unidade. Para cada unidade declarada no produto (PD_UNI3, PD_UNI2, PD_UNI, PD_UNI4 e PD_UNITRIB), o servidor insere a linha correspondente em PRODEQUIV com fator 1, se ela ainda não existir. Se a sua unidade de compra comporta mais de uma unidade de estoque, o fator precisa ser corrigido no Passo 5.
• Gera o código de barras quando a empresa está configurada para geração automática: o servidor monta um EAN-13 a partir do código do produto, grava em PRODBARCOD na unidade de venda e replica em PROD.PD_BARCOD se este estiver vazio.

A tabela PRODEQUIV declara quanto vale cada unidade do produto em relação à unidade de estoque. É ela que permite comprar em caixa, estocar em peça e vender em peça, com conversão automática nos documentos.

A chave é (PD_COD, PD_UNISIGLA), e o campo central é PD_UNIFAT — o fator de equivalência.

Quando intervir

• Corrigir um fator. As linhas criadas no Passo 4 nascem com fator 1. Se CX contém 100 PC, é preciso um PUT ajustando PD_UNIFAT para 100.
• Adicionar uma unidade extra que não está declarada em PROD — por exemplo, uma unidade de embalagem usada apenas em determinado cliente: POST em PRODEQUIV.
• Informar peso, dimensões ou a unidade para NF-e daquela unidade específica (PD_UNPESOLIQ, PD_UNPESOBRT, PD_UNINFE, PD_UNIDESNFE).

Regras aplicadas pelo servidor

Regra	Detalhe
Unidade de estoque tem fator 1	A linha cuja sigla é igual à unidade de estoque do produto (PD_UNI3) não pode ter fator diferente de 1.
Fator zero	Rejeitado, exceto quando a empresa usa equivalência variável. Fator negativo é sempre rejeitado.
Unidade tributável	Quando a empresa usa equivalência variável, a unidade tributável ainda assim não aceita fator 0.
Múltiplo em pedido/orçamento	PD_QTDMULTIPLA não pode ser negativo e só é aceito em unidades cujo fator de equivalência é um número inteiro.
Alteração de fator ou de unidade de NF-e	Exige o nível de acesso SpallaProdutoAlterarEquivalencia1 para o usuário do token.
Exclusão	Bloqueada se a unidade já foi usada em pedido, ordem de compra ou nota fiscal.

Exemplo — ajustar o fator da unidade de compra

{
    "method": "PUT",
    "objectType": "TABLE",
    "objectName": "PRODEQUIV",
    "dataFields": [
        { "name": "PD_UNIFAT", "value": "100" }
    ],
    "where": [
        { "type": "field", "name": "PD_COD",     "key": true, "value": 1201 },
        { "type": "field", "name": "PD_UNISIGLA","key": true, "value": "CX" }
    ]
}

No PUT, envie em dataFields apenas o campo a alterar e identifique o registro no where, marcando cada campo da chave primária com "key": true.

Um produto pode ter vários códigos de barras, um por embalagem. A chave da tabela é (PD_COD, PD_BARCOD), e cada código é vinculado a uma unidade através de PD_UNISIGLA.

Campos

Campo	Descrição
PD_COD	Código do produto.
PD_BARCOD	Código de barras. Obrigatório e validado como EAN.
PD_UNISIGLA	Unidade a que o código se refere. Obrigatória e existente na tabela de unidades.
PD_ENVXML	Marca o código que será enviado no XML da NF-e. Apenas um por combinação de produto e unidade.
PD_SITUACAOGTIN	Situação do código no cadastro GTIN: 0 não classificado, 1 validado, 2 inválido/inexistente.

Exemplo — POST PRODBARCOD

{
    "method": "POST",
    "objectType": "TABLE",
    "objectName": "PRODBARCOD",
    "dataFields": [
        { "name": "PD_COD",      "value": 1201 },
        { "name": "PD_BARCOD",   "value": "7891234567895" },
        { "name": "PD_UNISIGLA", "value": "PC" },
        { "name": "PD_ENVXML",   "value": 1 }
    ]
}

Se a empresa usa geração automática de código de barras, o produto já nasceu com um código interno criado pelo servidor (Passo 4). Nesse cenário, ao registrar o EAN real do fabricante, avalie qual dos dois deve carregar a marca PD_ENVXML.

O preço não reside no produto: reside na relação entre uma tabela de preço e o produto. São duas tabelas:

• TABPRECO1 — a tabela de preço em si (código, descrição, validade, filial, condição de pagamento, moeda). Mantida pela operação na retaguarda; a integração normalmente apenas a referencia.
• TABPRECO2 — o produto dentro daquela tabela, com o seu preço. É aqui que a integração grava.

Campos de TABPRECO2

Campo	Descrição
TBP_COD	Código da tabela de preço. Parte da chave. Deve existir em TABPRECO1.
PD_COD	Código do produto. Parte da chave.
TBP_PRC	Preço. Obrigatório. Use ponto decimal, sem separador de milhar e sem símbolo de moeda.
TBP_UNI	Unidade a que o preço se refere. Obrigatória — ver o pré-requisito abaixo. Quando omitida na inclusão, o servidor assume a unidade de venda do produto (PROD.PD_UNI).
TBP_DCSMAX	Percentual de desconto máximo permitido para o produto nessa tabela.
TBP_PCOM1, TBP_PCOM2	Percentuais de comissão do vendedor representante e do vendedor operacional.
CF_COD	Opcional. Restringe o preço a um cliente específico.

Comportamento na gravação

• Permissão. Incluir, alterar ou excluir preço exige o nível de acesso TabeladePreos1 com a permissão correspondente para o usuário do userToken.
• Histórico de preço. O servidor mantém o preço anterior (TBP_PRCANTERIOR) e a data do último reajuste (TBP_DAT) automaticamente. Não envie esses campos.
• Troca de produto. Alterar o PD_COD de uma linha existente é bloqueado — exclua a linha e inclua novamente.
• Composição de preço. Se a tabela de preço estiver configurada para usar composição, o preço não é administrado diretamente em TBP_PRC: ele é a soma do preço base com os cinco compostos (TBP_COMPPRCB e TBP_COMPPRC1 a TBP_COMPPRC5). Nesse cenário, um PUT que altere apenas TBP_PRC é reinterpretado pelo servidor como um fator de reajuste aplicado ao preço base. Confirme com a operação se a tabela usa composição antes de integrar reajustes.

Exemplo — POST TABPRECO2

{
    "method": "POST",
    "objectType": "TABLE",
    "objectName": "TABPRECO2",
    "dataFields": [
        { "name": "TBP_COD", "value": 1 },
        { "name": "PD_COD",  "value": 1201 },
        { "name": "TBP_UNI", "value": "PC" },
        { "name": "TBP_PRC", "value": "12.500000" }
    ]
}

Para reajustar, use "method": "PUT" com TBP_COD e PD_COD marcados como "key": true no where.

A alteração é feita por uma requisição com "method": "PUT" sobre PROD. Envie em dataFields apenas os campos a alterar e identifique o registro no where, com PD_COD marcado como "key": true.

Alterações bloqueadas em produto já movimentado

O servidor protege campos estruturais depois que o produto entrou em movimento (orçamento, pedido, ordem de compra, nota fiscal, ordem de produção ou acerto de estoque):

Campo	Bloqueio
PD_UNI3 (unidade de estoque)	Não pode ser alterada em produto movimentado, nem quando existirem equivalências cadastradas — nesse caso, exclua as equivalências primeiro.
TP_COD (tipo de produto)	Em produto movimentado, só é aceita a troca para um tipo compatível. E se o produto já constar no livro fiscal, a troca é limitada a tipos com a mesma classificação SPED.
PD_CTRLNSERIE, PD_SUGESTAOSERIE	Parâmetros de número de série não podem ser alterados em produto movimentado.
PD_USAENDESTOQ	Controle de endereço de estoque não pode ser alterado em produto com movimento de estoque.
PD_USALOTE	Controle de lote é validado por rotina própria antes de permitir a mudança.
PD_GENERICO	Não pode ser alterado se o produto já foi usado em orçamento, pedido ou nota fiscal.
PD_PRODCTRL	Em empresas que usam produto controlado, não pode ser alterado após a primeira movimentação.
PD_PATCOLETIVO	Desmarcar patrimônio coletivo é bloqueado se existir bem com estoque maior que 1.

Campos com permissão dedicada

Alterar (ou informar na inclusão) qualquer um dos percentuais abaixo exige que o usuário do userToken tenha o nível de acesso correspondente:

Campo	Nível de acesso exigido
PD_DESCFORM — desconto do fornecedor	SpacomCadastroProdutoDescontoForn
PD_MRGLUCRO — margem de lucro	SpacomCadastroProdutoMargemLucro
PD_DCS — desconto padrão	SpacomCadastroProdutoDescontoPad
PD_DCSMIN — desconto mínimo	SpacomCadastroProdutoDescontoMin
PD_DCSMAX — desconto máximo	SpacomCadastroProdutoDescontoMax

Exemplo — PUT PROD (atualizar descrição e estoque mínimo)

{
    "method": "PUT",
    "objectType": "TABLE",
    "objectName": "PROD",
    "dataFields": [
        { "name": "PD_DES", "value": "PARAFUSO SEXTAVADO 1/2 X 2 ZINCADO" },
        { "name": "PD_MIN", "value": "500.000000" }
    ],
    "where": [
        { "type": "field", "name": "PD_COD", "key": true, "value": 1201 }
    ]
}

Inativação — o caminho recomendado

Para retirar um produto de circulação, altere PD_STATUS de 1 (ativo) para 0 (inativo) por uma requisição PUT. O histórico de movimentação é preservado.

Exemplo — inativar o produto

{
    "method": "PUT",
    "objectType": "TABLE",
    "objectName": "PROD",
    "dataFields": [
        { "name": "PD_STATUS", "value": 0 }
    ],
    "where": [
        { "type": "field", "name": "PD_COD", "key": true, "value": 1201 }
    ]
}

Exclusão

A exclusão ("method": "DELETE") é possível apenas para produtos sem nenhum vínculo. O produto é referenciado por dezenas de tabelas do ERP — itens de pedido, notas fiscais, movimentos de estoque, ordens de produção, tabelas de preço, entre outras — e a integridade referencial do banco impede a remoção enquanto qualquer uma dessas referências existir. Em produto recém-criado por engano, a exclusão funciona; em produto movimentado, ela sempre falhará.

Cadastros dependentes que a exclusão do produto remove em cascata: equivalências de unidade, códigos de barras e dados por filial. Já a ficha de estoque é removida pelo próprio banco no processo.

Use requisições com "method": "GET" para ler o cadastro. O verbo de leitura é geralmente liberado mesmo quando os verbos de escrita são restritos.

• Conferir o produto criado — GET em PROD filtrado por PD_COD mostra também os campos resolvidos pelo servidor (PD_ITM, PD_CLF, PD_CEST, herança do NCM).
• Verificar as equivalências criadas — GET em PRODEQUIV por PD_COD lista as unidades e os fatores, incluindo as linhas geradas automaticamente.
• Localizar por código de barras — GET em PRODBARCOD filtrado por PD_BARCOD resolve o produto a partir do EAN lido.
• Consultar preços vigentes — GET em TABPRECO2 por PD_COD, cruzando com TABPRECO1 para conhecer a validade e o escopo da tabela.
• Sincronização incremental — o campo PD_DATA guarda a data da última atualização do cadastro e é indexado; use-o para trazer somente os produtos alterados desde a última carga.
• Próximo código (Passo 2) — recuperar o maior PD_COD atual antes de uma nova inclusão.

Os parâmetros aceitos na consulta (fields, where, orderBy, limit, offset) e a estrutura de retorno estão descritos no dicionário oficial.