Gravação de Ordens de Compra (PED1 / PED2) — Documentação Complementar

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

Antes de gravar uma ordem de compra, os cadastros abaixo precisam existir no ERP, porque são referenciados pelo cabeçalho (PED1) ou pelos itens (PED2) e validados pelo servidor na inclusão:

Cadastro	Campo em PED1/PED2	Observação
Fornecedor (CLIFOR1)	CF_COD	Pessoa do tipo fornecedor, cadastro completo e ativo. Ver página Cadastro de Pessoas.
Tipo de Movimento (TMOV)	TM_COD	Deve ser um tipo de entrada/compra compatível com CF_TIPO = 'F'. Define o tipo de documento, controle de estoque, preço e tributação. Ex.: E001.
Produto (PROD)	PD_COD	Cada item aponta para um produto cadastrado, obrigatoriamente com NCM.
Condição de Pagamento (PRAZO)	PZ_COD	Validada para o tipo F.
Forma de Pagamento (FORPAG)	FP_COD	Validada para o tipo F.
Carteira de Cobrança (PORTA)	PT_COD	Referência de portador.
Local de Estoque (LOCEST)	LE_COD	Precisa estar ativo; é onde a mercadoria dará entrada.
Centro de Custo (SETOR)	ST_COD	Validado na inclusão.
Comprador (VEND)	VD_COD	Na O.C., o campo VD_COD representa o comprador. Precisa estar ativo.
Transportadora (TRANS)	TR_COD	Obrigatória; use o código da transportadora padrão quando não houver frete.

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

O código da ordem de compra (PE_COD) compõe a chave primária de PED1 junto com FL_COD (empresa) e CF_TIPO, e deve ser informado pelo integrador na criação. O ERP não gera esse código em uma sequence dedicada — a regra é: o próximo código livre é o maior PE_COD existente, para a mesma empresa e tipo, mais 1.

próximo PE_COD = MAX(PE_COD em PED1 onde FL_COD = empresa e CF_TIPO = 'F') + 1

Recupere esse máximo com uma consulta prévia (method: GET) sobre PED1. Note o filtro CF_TIPO = 'F': pedidos de venda e ordens de compra têm numeração independente. A forma exata de pedir o agregado está no dicionário oficial, na entrada do objeto PED1.

Com o PE_COD livre obtido, inclua o cabeçalho por uma requisição com "method": "POST" sobre a tabela PED1.

Campos obrigatórios (não preenchidos automaticamente)

Os campos abaixo são NOT NULL e não têm preenchimento automático — precisam vir no corpo da requisição:

Campo	Descrição
FL_COD	Código da empresa/filial.
CF_TIPO	Fixo "F" para ordem de compra.
PE_COD	Código da O.C. obtido no Passo 2.
CF_COD	Código do fornecedor (pessoa).
TM_COD	Tipo de movimento (entrada/compra). Campo central: dirige documento, estoque, preço e tributação.
VD_COD	Comprador.
PZ_COD	Condição de pagamento.
FP_COD	Forma de pagamento.
PT_COD	Carteira de cobrança / portador.
LE_COD	Local de estoque de entrada.
ST_COD	Centro de custo.
TR_COD	Transportadora.
PE_DAT	Data de emissão da O.C.

Campos preenchidos automaticamente pelo servidor

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

• PE_ID — sequencial único (maior + 1).
• PE_STATUS — uma O.C. nunca é incluída fechada; na inclusão o valor é forçado para 0 (aberto), mesmo que você envie outro valor.
• CF_COD2 e CF_COD3 — quando nulos, recebem o próprio CF_COD.
• PE_CTRLESTOQUE e PE_USAPRECOCHEIO — derivados do tipo de movimento (TM_COD).
• PE_USERCTRL, PE_DATPRO, PE_STATUSDATA — usuário e datas de controle.
• TBP_COD (tabela de preço) e PE_CLAUSULA (modelo padrão de O.C.) — quando não informados.

Campos opcionais úteis à O.C.: PE_NOTAS (observações/notas da ordem de compra) e PE_PAGFRT (tipo de frete).

Exemplo — POST PED1 (cabeçalho da O.C.)

{
    "method": "POST",
    "objectType": "TABLE",
    "objectName": "PED1",
    "dataFields": [
        { "name": "FL_COD",    "value": 1 },
        { "name": "CF_TIPO",   "value": "F" },
        { "name": "PE_COD",    "value": 33 },
        { "name": "CF_COD",    "value": 107 },
        { "name": "TM_COD",    "value": "E001" },
        { "name": "VD_COD",    "value": 2 },
        { "name": "PZ_COD",    "value": 30 },
        { "name": "FP_COD",    "value": 1004 },
        { "name": "PT_COD",    "value": 1001 },
        { "name": "LE_COD",    "value": 1 },
        { "name": "ST_COD",    "value": 3 },
        { "name": "TR_COD",    "value": 1 },
        { "name": "PE_DAT",    "value": "2026-07-18" },
        { "name": "PE_STATUS", "value": 0 }
    ]
}

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

Com o cabeçalho criado, inclua um POST em PED2 para cada produto. A chave do item é (FL_COD, CF_TIPO, PE_COD, PE_ITM, PD_COD), e deve apontar para o cabeçalho recém-criado.

Campos que você informa

Campo	Descrição
FL_COD, CF_TIPO, PE_COD	Iguais aos do cabeçalho (CF_TIPO = "F").
PD_COD	Código do produto.
PE_QTDCONV	Quantidade na unidade operacional (a "quantidade" que o usuário digitaria).
PE_UNICONV	Unidade dessa quantidade. Se omitida, assume a unidade de compra do produto.
PE_PRCCONVCHEIO	Preço unitário de compra na unidade informada. Opcional: se omitido, o sistema sugere o preço da tabela de preços de compra.

Campos preenchidos automaticamente pelo servidor

• PE_ITM — número do item; auto-incrementado (maior item da O.C. + 1) quando enviado como 0 ou omitido.
• TM_COD2 — tipo de movimento do item; herda o TM_COD do cabeçalho quando não informado.
• PD_CODNCM — NCM do produto (erro se o produto não tiver NCM).
• PE_PRCSUG, PE_PRCBASE, TBP_COD, FAT_COD — preço sugerido/base e fator, buscados na tabela de preços.
• Unidades e quantidades derivadas: PE_UNI (para compra, assume a unidade de compra do produto), PE_UNIEST, PE_FATOR, PE_FATCONV, PE_QTD, PE_QTDEST, PE_PRC, PE_SALQTD.

Exemplo — POST PED2 (um item)

{
    "method": "POST",
    "objectType": "TABLE",
    "objectName": "PED2",
    "dataFields": [
        { "name": "FL_COD",          "value": 1 },
        { "name": "CF_TIPO",         "value": "F" },
        { "name": "PE_COD",          "value": 33 },
        { "name": "PD_COD",          "value": 120 },
        { "name": "PE_UNICONV",      "value": "KG" },
        { "name": "PE_QTDCONV",      "value": "500" },
        { "name": "PE_PRCCONVCHEIO", "value": "42.50" }
    ]
}

Repita a requisição, alterando PD_COD/quantidade/preço, para cada produto da ordem. Cada inclusão marca a O.C. como pendente de cálculo (o total só é apurado no Passo 5).

Após inserir todos os itens, execute a procedure PRC_CALCULAPEDIDO por uma requisição com "method": "PATCH". É esse cálculo que consolida a O.C.: apura os impostos e valores de cada item, totaliza o cabeçalho (tabela PEDT) e gera o financeiro (contas a pagar).

Parâmetros

Parâmetro	Descrição
VFL_COD	Código da empresa (igual ao FL_COD da O.C.).
VCF_TIPO	"F" para ordem de compra.
VPE_COD	Código da O.C. (PE_COD).
VOP	Opcional. 0 (padrão) = calcula itens e totais; 1 = calcula somente os totais.

Exemplo — PATCH PRC_CALCULAPEDIDO

{
    "method": "PATCH",
    "objectType": "PROCEDURE",
    "objectName": "PRC_CALCULAPEDIDO",
    "params": [
        { "name": "VFL_COD",  "value": 1 },
        { "name": "VCF_TIPO", "value": "F" },
        { "name": "VPE_COD",  "value": 33 }
    ]
}

Ao final, a procedure marca a O.C. como calculada (PEDT.PE_TOT_CALCULADO = 1) e dispara a geração/verificação do financeiro.

Com a O.C. calculada e conferida, feche o cabeçalho por uma requisição com "method": "PUT" sobre PED1, alterando PE_STATUS de 0 para 1 (cadeado fechado / concluído).

O que o fechamento dispara (tipo F)

A transição de PE_STATUS 0 → 1 aciona, no servidor, uma sequência de validações e rotinas:

• Permissão de cadeado — o usuário do userToken precisa do acesso SpaComFecharCadeadoOrdComp1.
• Recálculo automático — se a O.C. estiver pendente (PE_TOT_CALCULADO = 0), o servidor chama PRC_CALCULAPEDIDO.
• Validação de crédito / limite da pessoa — conforme cadastro do fornecedor.
• Liberação da ordem de compra — regras de liberação de compra são executadas.

Diferente do pedido de venda, a O.C. não aplica a checagem de faturamento mínimo nem as regras de inadimplência/carteira de clientes.

Exemplo — PUT PED1 (fechar a O.C.)

{
    "method": "PUT",
    "objectType": "TABLE",
    "objectName": "PED1",
    "dataFields": [
        { "name": "PE_STATUS", "value": 1 }
    ],
    "where": [
        { "type": "field", "name": "FL_COD",  "key": true, "value": 1 },
        { "type": "field", "name": "CF_TIPO", "key": true, "value": "F" },
        { "type": "field", "name": "PE_COD",  "key": true, "value": 33 }
    ]
}

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

• Totais da O.C. — consulte a tabela PEDT (por FL_COD, CF_TIPO, PE_COD) para ver total bruto, líquido, impostos e o indicador PE_TOT_CALCULADO.
• Cabeçalho — GET em PED1 confirma PE_STATUS e demais campos resolvidos pelo servidor.
• Itens — GET em PED2 filtrado pelo PE_COD mostra as quantidades, unidades e valores calculados.
• Próximo código (Passo 2) — recuperar o maior PE_COD atual (com CF_TIPO = 'F') 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.