rev1-2026-05-07 Protheus 12.1.33

ProdutoFornecedor

CRUD do vínculo Produto x Fornecedor (tabela SA5) via rotina automática MATA060. Modelo 1 (cabeçalho simples) com chave composta de três partes — A5_FORNECE (6) + A5_LOJA (2) + A5_PRODUTO (15) — enviada concatenada no path. Pré-requisito: o fornecedor (SA2) e o produto (SB1) já cadastrados; este endpoint apenas registra o relacionamento entre eles.

Base URL https://erpapi.jetme.com.br/api/99/01 Empresa 99 · Filial 01

Vinculação com o ERP

Tabela mestre SA5 Vínculo Produto x Fornecedor

Rotina automática MATA060 Modelo 1 · MsExecAuto

Wrapper AdvPL U_MT060Exc src/lib/MT060EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro · pré-requisito

Fornecedor

tabela SA2 · chave A2_COD + A2_LOJA
o par A5_FORNECE + A5_LOJA precisa existir em SA2 antes do POST

Cadastro · pré-requisito

Produto

tabela SB1 · chave B1_COD
o valor de A5_PRODUTO precisa existir em SB1 antes do POST

Cadastro · opcional

Fabricante

tabela SA2 · campos A5_FABR + A5_LOJFAB
quando preenchidos, devem apontar para fornecedor existente; MATA060 valida no MsExecAuto

Índices SIX

Estratégia de busca

ordem 1: A5_FILIAL+A5_FORNECE+A5_LOJA+A5_PRODUTO
ordem 2: A5_FILIAL+A5_PRODUTO+A5_FORNECE+A5_LOJA

Convenções

Chave composta no path. Todas as rotas /WsSA5/{chave}, /INCLUIR/{chave}, /ALTERAR/{chave} e /EXCLUIR/{chave} recebem a chave concatenada crua: {A5_FORNECE}{A5_LOJA}{A5_PRODUTO}. Os tamanhos (6+2+1..15) são lidos do dicionário (TamSX3) em runtime; A5_PRODUTO pode vir curto e é completado com PadR internamente.

Campos da chave vêm do path, não do body. Em POST/PUT, se o payload trouxer A5_FORNECE, A5_LOJA ou A5_PRODUTO, eles são ignorados — o endpoint sempre usa o que veio na URL.

Pré-requisitos no ERP. O MATA060 exige que o fornecedor (SA2 com A2_COD + A2_LOJA) e o produto (SB1 com B1_COD) já estejam cadastrados. Faltando qualquer um, o MsExecAuto rejeita com 422 e mensagem do NomeAutoLog.

Sem bloqueio TOTVS-padrão. A SA5 não expõe o par *_MSBLQL/*_MSBLQD; o endpoint não tem caminho de desbloqueio. Para suspender um vínculo, use DELETE.

Paginação. /_list usa page/pageSize (default 50, máx 500). Os filtros fornece, loja e produto escolhem o índice mais seletivo automaticamente (ordem 1 quando há fornece, ordem 2 quando há só produto).

Vínculo

CRUD por chave composta

GET /WsSA5/{chave} Consulta vínculo por chave composta

Descrição

Retorna o vínculo Produto x Fornecedor pesquisado pela chave composta concatenada {A5_FORNECE}{A5_LOJA}{A5_PRODUTO}. Aplica xFilial("SA5") e respeita o whitelist CAMPOS_GET do .prw.

Path parameter

chave string · path · obrigatório SA5.A5_FORNECE+A5_LOJA+A5_PRODUTO

Concatenação A5_FORNECE (6) + A5_LOJA (2) + A5_PRODUTO (1..15). Mínimo 9 chars, máximo 23.

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA5/TST00101TST_REST_PRD01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Vínculo encontrado. Envelope { success: true, data: Vinculo }.

400

Chave composta vazia ou fora do tamanho esperado. Tier: validation-error.

404

Vínculo inexistente para a chave informada. Tier: not-found.

500

Erro interno (DbSeek, serialização). Tier: business-error.

POST /WsSA5/INCLUIR/{chave} Inclui novo vínculo Produto x Fornecedor

Descrição

Inclui um novo vínculo via MATA060 em modo 3 (MODEL_OPERATION_INSERT). A chave composta vem do path; o payload traz apenas os atributos do relacionamento (nome do fornecedor, código no fornecedor, prazo de entrega, prioridade, etc.). Os campos A5_FORNECE/A5_LOJA/A5_PRODUTO são ignorados se vierem no body.

O fornecedor (SA2) e o produto (SB1) precisam existir; senão o MsExecAuto rejeita com 422.
Whitelist de campos: ver VinculoPayload.

Path parameter

chave string · path · obrigatório SA5.A5_FORNECE+A5_LOJA+A5_PRODUTO

Concatenação crua {A5_FORNECE}{A5_LOJA}{A5_PRODUTO}.

Request body

application/json VinculoPayload · obrigatório

Payload plano com campos do whitelist CAMPOS_ALLOW. Schema completo em VinculoPayload.

Payload mínimo — só os atributos descritivos do vínculo. Fixture do smoke test: test-produto-fornecedor.sh::CREATE_PAYLOAD.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsSA5/INCLUIR/TST00101TST_REST_PRD01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "A5_NOMEFOR": "FORN TESTE_REST",
  "A5_NOMPROD": "PROD TESTE_REST",
  "A5_PE": 7,
  "A5_PRIOR": "1"
}

Payload realista — vínculo com fabricante, condições comerciais e controle de qualidade.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsSA5/INCLUIR/TST00101TST_REST_PRD01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "A5_NOMEFOR": "FORNECEDOR TESTE LTDA",
  "A5_NOMPROD": "PRODUTO PARA TESTE REST",
  "A5_CODPRF": "FORN-SKU-0007",
  "A5_FABR": "TST002",
  "A5_LOJFAB": "01",
  "A5_PRIOR": "1",
  "A5_PE": 7,
  "A5_LE": 100,
  "A5_FATURA": 5000,
  "A5_CONDPAG": "001",
  "A5_MOEDA": 1,
  "A5_TPCQ": "N"
}

Respostas

201

Vínculo incluído. Envelope CrudResponse com data = { A5_FORNECE, A5_LOJA, A5_PRODUTO } ecoando a chave gravada.

400

Chave composta inválida, body ausente ou JSON malformado. Tier: validation-error.

409

Vínculo já cadastrado para essa chave. Tier: business-error.

422

MsExecAuto do MATA060 rejeitou (fornecedor/produto inexistente, fabricante inválido, enums fora do domínio, etc.). Tier: business-error.

500

Erro interno.

PUT /WsSA5/ALTERAR/{chave} Altera vínculo existente

Descrição

Altera campos do vínculo via MATA060 em modo 4 (MODEL_OPERATION_UPDATE). Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW; os campos da chave continuam vindo do path. A SA5 não tem bloqueio TOTVS-padrão — qualquer alteração de atributo é aceita desde que passe na validação do MsExecAuto.

Path parameter

chave string · path · obrigatório SA5.A5_FORNECE+A5_LOJA+A5_PRODUTO

Concatenação crua {A5_FORNECE}{A5_LOJA}{A5_PRODUTO}.

Request body

application/json VinculoPayload · obrigatório

Subconjunto do whitelist. Não envie campos da chave — eles vêm do path.

Ajuste de prazo e prioridade — fixture do smoke test: test-produto-fornecedor.sh::UPDATE_PAYLOAD.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSA5/ALTERAR/TST00101TST_REST_PRD01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "A5_NOMEFOR": "FORN TESTE_REST",
  "A5_NOMPROD": "PROD TESTE_REST",
  "A5_PE": 15,
  "A5_PRIOR": "2"
}

Update mínimo — apenas o prazo de entrega. Os demais campos não enviados permanecem inalterados.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSA5/ALTERAR/TST00101TST_REST_PRD01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "A5_PE": 10
}

Respostas

200

Vínculo alterado. Envelope CrudResponse com data ecoando a chave.

400

Chave composta inválida, body ausente ou JSON malformado.

404

Vínculo inexistente para a chave. Tier: not-found.

422

Validação de payload (whitelist, enum, fabricante inexistente). Tier: business-error.

500

Erro interno.

DEL /WsSA5/EXCLUIR/{chave} Exclui vínculo Produto x Fornecedor

Descrição

Exclui o vínculo via MATA060 em modo 5 (MODEL_OPERATION_DELETE). A exclusão remove o relacionamento entre o fornecedor e o produto — não toca em SA2/SB1. O MsExecAuto do MATA060 pode rejeitar a exclusão quando o vínculo estiver referenciado em pedidos de compra abertos (SC7).

Path parameter

chave string · path · obrigatório SA5.A5_FORNECE+A5_LOJA+A5_PRODUTO

Concatenação crua {A5_FORNECE}{A5_LOJA}{A5_PRODUTO}.

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSA5/EXCLUIR/TST00101TST_REST_PRD01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Vínculo excluído. Envelope CrudResponse.

400

Chave composta inválida. Tier: validation-error.

404

Vínculo inexistente. Tier: not-found.

422

Vínculo referenciado em movimento aberto (ex: pedido de compra SC7 em SA5). Tier: business-error.

500

Erro interno.

GET /WsSA5/_byid Lookup explícito por fornecedor OU produto

Descrição

Atalho para quando o cliente conhece só uma das pontas do vínculo (apenas o fornecedor ou apenas o produto) e quer enumerar todas as ocorrências. Internamente usa o índice 1 quando tipo=fornece e o índice 2 quando tipo=produto.

Query parameters

tipo string · query · obrigatório

Define qual ponta do vínculo está sendo usada como filtro.

forneceproduto

valor string · query · obrigatório

Valor de A5_FORNECE (quando tipo=fornece) ou A5_PRODUTO (quando tipo=produto).

Chamada de exemplo

Request · por fornecedorHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA5/_byid?tipo=fornece&valor=TST001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · por produtoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA5/_byid?tipo=produto&valor=TST_REST_PRD01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista de vínculos. Envelope com data (array de Vinculo) e count.

400

Parâmetros tipo/valor ausentes ou tipo fora do enum.

500

Erro interno.

Listagem

Listagem paginada e typeahead

GET /WsSA5/_list Lista vínculos com filtros e paginação

Descrição

Lista vínculos com filtros opcionais por fornece, loja (só vale junto com fornece) e produto. O endpoint escolhe automaticamente o índice mais seletivo:

Com fornece: ordem 1 (A5_FILIAL+A5_FORNECE+A5_LOJA+A5_PRODUTO).
Com produto só: ordem 2 (A5_FILIAL+A5_PRODUTO+A5_FORNECE+A5_LOJA).
Sem filtros: scan na filial em ordem 1.

Query parameters

fornece string · query · opcional SA5.A5_FORNECE

Prefixo de A5_FORNECE (índice 1).

loja string · query · opcional SA5.A5_LOJA

A5_LOJA exato. Só tem efeito quando combinado com fornece.

produto string · query · opcional SA5.A5_PRODUTO

Prefixo de A5_PRODUTO. Usa índice 2 quando fornece está ausente.

fields string · query · opcional

Lista de campos separados por vírgula, validados contra CAMPOS_GET.

page integer · query · opcional

Página (default 1, mínimo 1).

pageSize integer · query · opcional

Tamanho da página (default 50, máx 500).

Chamada de exemplo

Request · por fornecedorHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA5/_list?fornece=TST001&page=1&pageSize=50
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · por produtoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA5/_list?produto=TST_REST_PRD01&pageSize=100
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de vínculos. Envelope com data (array de Vinculo), page, pageSize, count.

400

Parâmetro fora do domínio (ex: fields com campo não whitelistado).

500

Erro interno.

GET /WsSA5/_search Typeahead por nome do fornecedor ou do produto

Descrição

Busca rápida (typeahead) para autocomplete de UI. O termo é comparado contra A5_NOMEFOR + A5_NOMPROD concatenados e normalizados (sem acento, uppercase) via U_NoAcento. Retorna uma lista enxuta — não devolve o schema completo de Vinculo.

Como a SA5 não tem índice por nome, o endpoint faz um scan limitado a 2000 registros por chamada.

Query parameters

q string · query · obrigatório

Termo de busca. Mínimo 2 caracteres.

match string · query · opcional

Modo de match. Default prefix.

prefixcontains

limit integer · query · opcional

Quantidade máxima de sugestões (default 10, máx 25).

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA5/_search?q=forn&match=prefix&limit=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · containsHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA5/_search?q=teste&match=contains&limit=25
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista enxuta de sugestões. Envelope: success, count, data[] com itens SugestaoItem.

400

q ausente ou < 2 caracteres.

500

Erro interno.

Schemas

Definições canônicas — campos com origem SX3 rastreável

Vinculo

object

Representação retornada nos GETs (/{chave}, /_list, /_byid). Inclui a chave composta e os atributos comerciais e logísticos do vínculo. Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields.

A5_FORNECEstring · obrigatórioSA5.A5_FORNECE

Código do fornecedor (parte 1 da chave). Aponta para SA2.A2_COD.

A5_LOJAstring · obrigatórioSA5.A5_LOJA

Loja do fornecedor (parte 2 da chave). Aponta para SA2.A2_LOJA.

A5_PRODUTOstring · obrigatórioSA5.A5_PRODUTO

Código do produto (parte 3 da chave). Aponta para SB1.B1_COD.

A5_NOMEFORstring · opcionalSA5.A5_NOMEFOR

Nome do fornecedor (espelha A2_NOME no momento da gravação).

A5_NOMPRODstring · opcionalSA5.A5_NOMPROD

Nome do produto (espelha B1_DESC no momento da gravação).

A5_CODPRFstring · opcionalSA5.A5_CODPRF

Código do produto no fornecedor (SKU externo).

A5_FABRstring · opcionalSA5.A5_FABR

Código do fabricante (aponta para outro registro de SA2).

A5_LOJFABstring · opcionalSA5.A5_LOJFAB

Loja do fabricante.

A5_PRIORstring · opcionalSA5.A5_PRIOR

Prioridade do fornecedor para o produto. Valores típicos: "1" (preferencial) a "9".

A5_PEnumber · opcionalSA5.A5_PE

Prazo de entrega em dias.

A5_LEnumber · opcionalSA5.A5_LE

Lote econômico (quantidade mínima de compra rentável).

A5_FATURAnumber · opcionalSA5.A5_FATURA

Faturamento mínimo exigido pelo fornecedor.

A5_CONDPAGstring · opcionalSA5.A5_CONDPAG

Condição de pagamento default deste vínculo (aponta para SE4).

A5_TPCQstring · opcionalSA5.A5_TPCQ

Tipo de Controle de Qualidade (CQ).

A5_SKIPLOTstring · opcionalSA5.A5_SKIPLOT

Skip-lote para inspeção amostral.

VinculoPayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW no .prw. Os campos da chave (A5_FORNECE/A5_LOJA/A5_PRODUTO) vêm do path e são ignorados se vierem aqui.

A5_NOMEFORstring · opcionalSA5.A5_NOMEFOR

Nome do fornecedor.

A5_NOMPRODstring · opcionalSA5.A5_NOMPROD

Nome do produto.

A5_CODPRFstring · opcionalSA5.A5_CODPRF

Código do produto no fornecedor (SKU externo).

A5_FABRstring · opcionalSA5.A5_FABR

Código do fabricante. Precisa existir em SA2 quando informado.

A5_LOJFABstring · opcionalSA5.A5_LOJFAB

Loja do fabricante. Combinado com A5_FABR deve apontar para registro SA2 válido.

A5_PRIORstring · opcionalSA5.A5_PRIOR

Prioridade ("1" a "9").

A5_PEnumber · opcionalSA5.A5_PE

Prazo de entrega em dias.

A5_LEnumber · opcionalSA5.A5_LE

Lote econômico.

A5_FATURAnumber · opcionalSA5.A5_FATURA

Faturamento mínimo.

A5_TPCQstring · opcionalSA5.A5_TPCQ

Tipo de Controle de Qualidade.

A5_SKIPLOTstring · opcionalSA5.A5_SKIPLOT

Skip-lote.

A5_CONDPAGstring · opcionalSA5.A5_CONDPAG

Condição de pagamento (chave de SE4).

A5_FRETEnumber · opcionalSA5.A5_FRETE

Valor do frete acordado.

A5_TIPEstring · opcionalSA5.A5_TIPE

Tipo de entrega.

A5_MOEDAnumber · opcionalSA5.A5_MOEDA

Código da moeda (default 1 = Real).

SugestaoItem

object

Forma enxuta retornada por /_search. Suficiente para popular uma lista de autocomplete sem trazer todos os atributos do vínculo.

fornecestringSA5.A5_FORNECE

Código do fornecedor (trimmed).

lojastringSA5.A5_LOJA

Loja do fornecedor (trimmed).

produtostringSA5.A5_PRODUTO

Código do produto (trimmed).

nomeForstringSA5.A5_NOMEFOR

Nome do fornecedor (trimmed).

nomeProdstringSA5.A5_NOMPROD

Nome do produto (trimmed).

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data em POST/PUT ecoa a chave gravada (A5_FORNECE/A5_LOJA/A5_PRODUTO); em DELETE retorna string vazia.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso (ex: "Vinculo incluido com sucesso.").

datastring | object · opcional

Em POST/PUT contém { A5_FORNECE, A5_LOJA, A5_PRODUTO } ecoando a chave; em DELETE pode ser string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. message traz o texto do NomeAutoLog (ou outro detalhe do MsExecAuto) quando MATA060 recusa a operação.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro (apresentável ao usuário final).

datastring · opcional

Token interno / detalhe técnico (ex: log do MsExecAuto).