rev28-2026-05-15 Protheus 12.1.33

CadastroFornecedor

CRUD de fornecedor (tabela SA2) via MVC do MATA020, encapsulado pelo wrapper U_MT020MVC (src/lib/MAT/MT020MVC.prw). Identificador externo é CNPJ (14 dígitos) ou CPF (11 dígitos); a chave técnica (A2_COD/A2_LOJA) é gerada pelo Protheus no POST via GetSXENum + Soma1 + ConfirmSX8.

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

Vinculação com o ERP

Tabela mestre SA2 Cadastro de fornecedores

Rotina automática MATA020 MVC · MsExecAuto

Wrapper AdvPL U_MT020MVC src/lib/MAT/MT020MVC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Sequência

Numeração SX8

GetSXENum("SA2","A2_COD") + Soma1 + ConfirmSX8
gerada pelo Protheus no POST · loop de avanço quando o contador está dessincronizado em relação ao último registro de SA2

Lookup

Município (CC2)

tabela CC2 · X3 valid de A2_COD_MUN faz seek pela UF + nome do município; payload precisa de A2_EST + A2_MUN + A2_COD_MUN consistentes ou deixa A2_COD_MUN em branco

Estado · cadastro

Fornecedor (estado de bloqueio)

tabela SA2 · campos A2_MSBLQL + A2_MSBLQD
A2_MSBLQL pertence("12") · "1"=Inativo (bloqueado), "2"=Ativo (default)
helper U_C980Blq("SA2") em src/lib/CRM/CRM980EXC.prw · retorna {lBloq, cMotivo}

Ids técnicos · condicional

A2_MSUID / A2_MSUIDT

campos opcionais no dicionário · expostos no GET quando presentes via U_RestCamposOpc + fAddTec
ausência derruba /_byid?tipo=msuid com status 501

Convenções

Identificador externo. Todas as rotas /WsFornecedor/{cgc} aceitam apenas dígitos — 14 (CNPJ) ou 11 (CPF). Pontuação (., /, -) é rejeitada com 400. A chave interna A2_COD/A2_LOJA não é exposta como identificador externo; use /_byid?tipo=recno|msuid&valor=… quando precisar buscar por ela.

Pessoa Física / Jurídica. O endpoint distingue PF/PJ via A2_PFISICA ("F" ou "J"). O tradicional A2_PESSOA aparece no FornecedorPayload do OpenAPI por compatibilidade, mas não está no allowlist da rev9 em diante — o campo foi removido do FormModel do SA2 neste ambiente. O parser ignora A2_PESSOA silenciosamente; envie sempre A2_PFISICA.

Município & UF. A2_COD_MUN é opcional mas, quando presente, dispara o X3 valid que faz seek na CC2 pela ordem 1 (UF + nome). O payload precisa carregar A2_EST + A2_MUN + A2_COD_MUN de forma coerente — caso contrário o MsExecAuto responde 422. Para evitar o lookup, omita A2_COD_MUN.

Counter SX8 dessincronizado. Testes que abortaram antes do ConfirmSX8 podem deixar "buracos" no contador. O endpoint aplica workaround (rev15): após GetSXENum, executa Soma1 em loop enquanto a combinação A2_COD+A2_LOJA já existir em SA2. Comportamento transparente para o consumidor, mas pode produzir saltos numéricos visíveis na sequência.

Paginação e delta-sync. /_list usa page/pageSize (default 50, máx 500). Para sincronização incremental, alterne para orderBy=recno e use since/cursor conforme o nextCursor retornado (rev24).

Bloqueio TOTVS (A2_MSBLQL / A2_MSBLQD). A partir da rev25, o WSSA2 respeita o gate de bloqueio padrão TOTVS via U_C980Blq("SA2"). Em registro bloqueado, o PUT retorna 422 a menos que o payload toque exclusivamente os campos de bloqueio (caminho de desbloqueio). Bloqueio fica ativo quando A2_MSBLQL="1" ou dDataBase > A2_MSBLQD.

Polaridade do par MSBLQL/MSBLQD varia por tabela. Na SA2, A2_MSBLQL="1" é Inativo (bloqueado) e "2" é Ativo (default). Sempre confirmar no SX3 antes de replicar a polaridade em outros endpoints.

Fornecedor

CRUD por CNPJ/CPF

GET /WsFornecedor/{cgc} Consulta fornecedor por CGC

Descrição

Retorna o fornecedor pesquisado pelo CGC (CNPJ 14 dígitos ou CPF 11 dígitos). Aplica filtro de filial (xFilial("SA2")) e respeita o whitelist de CAMPOS_GET definido no .prw. O parâmetro opcional fields reduz o conjunto de campos retornados.

A resposta inclui sempre recno; msuid e msuidt aparecem quando os campos correspondentes existem no dicionário (resolvido via U_RestCamposOpc).

Path parameter

cgc string · path · obrigatório SA2.A2_CGC

CPF (11) ou CNPJ (14), apenas dígitos. Pattern: ^\d{11}$|^\d{14}$.

Query parameters

fields string · query · opcional

Lista de campos separados por vírgula. Validados contra CAMPOS_GET.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Request · com fieldsHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsFornecedor/99999999000199?fields=A2_COD,A2_NOME,A2_CGC,A2_EST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Fornecedor encontrado. Envelope { success: true, data: Fornecedor }.

400

CGC fora do pattern. Tier: validation-error.

404

Fornecedor inexistente para o CGC informado. Tier: not-found.

500

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

POST /WsFornecedor/{cgc} Inclui novo fornecedor

Descrição

Inclui um fornecedor novo via MATA020 em modo 3 (MODEL_OPERATION_INSERT). A chave técnica A2_COD/A2_LOJA é gerada pelo Protheus (GetSXENum + Soma1 + ConfirmSX8) — o cliente passa apenas o CGC no path.

Whitelist de campos: ver FornecedorPayload.
Loja default "01" quando o payload não força outra.
A2_PESSOA é silenciosamente ignorado (rev9); use A2_PFISICA.

Path parameter

cgc string · path · obrigatório SA2.A2_CGC

CPF (11) ou CNPJ (14), apenas dígitos. Pattern: ^\d{11}$|^\d{14}$.

Request body

application/json FornecedorPayload · obrigatório

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

Payload mínimo (PJ) — apenas os campos básicos para Pessoa Jurídica, sem código de município. Fixture: fixtures/create.json (variação simplificada).

RequestHTTP/1.1 · application/json

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

{
  "A2_NOME": "TESTE_REST FORNECEDOR LTDA",
  "A2_NREDUZ": "TESTE REST",
  "A2_END": "RUA TESTE 100",
  "A2_BAIRRO": "CENTRO",
  "A2_EST": "SP",
  "A2_TIPO": "J",
  "A2_PFISICA": "J"
}

Com código de município (CC2) — payload realista incluindo A2_COD_MUN "00402" (AGUAS DA PRATA/SP). Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "A2_NOME": "TESTE_REST FORNECEDOR LTDA",
  "A2_NREDUZ": "TESTE REST",
  "A2_END": "RUA TESTE 100",
  "A2_BAIRRO": "CENTRO",
  "A2_EST": "SP",
  "A2_MUN": "AGUAS DA PRATA",
  "A2_COD_MUN": "00402",
  "A2_TIPO": "J",
  "A2_PFISICA": "J"
}

Respostas

201

Fornecedor incluído. Envelope CrudResponse com data = chave técnica gerada (A2_COD/A2_LOJA).

400

CGC fora do pattern. Tier: validation-error.

409

Fornecedor já existe para o CGC (chave alternativa única). Tier: business-error.

422

Payload inválido — MsExecAuto do MATA020 rejeitou (campos fora do whitelist, enums inválidos, X3 valid de A2_COD_MUN, etc). Tier: business-error.

500

Erro interno.

PUT /WsFornecedor/{cgc} Altera fornecedor existente

Descrição

Altera campos do fornecedor via MATA020 em modo 4 (MODEL_OPERATION_UPDATE). Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW. Campos fora do allowlist são silenciosamente ignorados.

Restrições. A chave técnica (A2_COD/A2_LOJA) e a chave de negócio (A2_CGC) não podem ser alteradas via PUT — o seek é feito pelo CGC do path e o MVC bloqueia mudança da PK.

Bloqueio TOTVS. Em registro bloqueado por A2_MSBLQL="1" ou dDataBase > A2_MSBLQD, o PUT retorna 422 a menos que o payload toque exclusivamente A2_MSBLQL/A2_MSBLQD (caminho de desbloqueio).

A2_MSBLQL: "1" = Inativo, "2" = Ativo (default).
A2_MSBLQD: data ISO YYYY-MM-DD ou string vazia.
Helper backend: U_C980Blq("SA2").

Path parameter

cgc string · path · obrigatório SA2.A2_CGC

CPF (11) ou CNPJ (14), apenas dígitos.

Request body

application/json FornecedorPayload · obrigatório

Subconjunto do whitelist. Envie apenas os campos que deseja alterar.

Alteração comum — atualiza endereço e contato. Fixture: fixtures/update.json.

RequestHTTP/1.1 · application/json

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

{
  "A2_NOME": "TESTE REST FORNECEDOR ALTERADO",
  "A2_NREDUZ": "TESTE REST",
  "A2_END": "RUA TESTE 200",
  "A2_BAIRRO": "CENTRO ALT",
  "A2_DDD": "011",
  "A2_TEL": "999999999",
  "A2_EMAIL": "teste@example.com"
}

Mudança de tipo — promove fornecedor para exportação (A2_TIPO="X"). Útil quando o cadastro foi criado como nacional e precisa virar fornecedor estrangeiro.

RequestHTTP/1.1 · application/json

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

{
  "A2_TIPO": "X"
}

Liberar registro bloqueado — caminho de desbloqueio. Em fornecedor bloqueado, esse é um dos dois únicos payloads aceitos. Qualquer campo fora do par A2_MSBLQL/A2_MSBLQD provoca 422.

RequestHTTP/1.1 · application/json

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

{
  "A2_MSBLQL": "2"
}

Bloqueio manual com vigência futura — define A2_MSBLQL="1" (Inativo) e A2_MSBLQD no futuro. O MsExecAuto interpreta a data como vigência.

RequestHTTP/1.1 · application/json

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

{
  "A2_MSBLQL": "1",
  "A2_MSBLQD": "2026-12-31"
}

Limpa data de bloqueio — passa A2_MSBLQD="" para zerar a data. Combinável com mudança de A2_MSBLQL no mesmo payload.

RequestHTTP/1.1 · application/json

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

{
  "A2_MSBLQL": "2",
  "A2_MSBLQD": ""
}

Respostas

200

Fornecedor alterado. Envelope CrudResponse.

400

CGC fora do pattern. Tier: validation-error.

404

Fornecedor inexistente. Tier: not-found.

422

Validação de payload (whitelist, enum, lookup CC2 inconsistente) ou registro bloqueado — PUT em registro bloqueado só aceita payload exclusivo A2_MSBLQL/A2_MSBLQD. Tier: business-error.

500

Erro interno.

DEL /WsFornecedor/{cgc} Exclui fornecedor

Descrição

Exclui o fornecedor via MATA020 em modo 5 (MODEL_OPERATION_DELETE). O MsExecAuto do MATA020 rejeita exclusão quando há dependências (títulos a pagar em aberto, itens de cotação/pedido vinculados).

Path parameter

cgc string · path · obrigatório SA2.A2_CGC

CPF (11) ou CNPJ (14), apenas dígitos.

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsFornecedor/99999999000199
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Fornecedor excluído. Envelope CrudResponse.

400

CGC fora do pattern. Tier: validation-error.

404

Fornecedor inexistente. Tier: not-found.

422

Fornecedor tem dependências (títulos abertos, pedidos vinculados). Tier: business-error.

500

Erro interno.

GET /WsFornecedor/_byid Consulta fornecedor por id técnico (recno|msuid)

Descrição

Busca o fornecedor por id técnico — útil para integrações que persistem a chave interna (recno) ou o identificador universal (msuid) e querem reconfirmar o registro sem reconstruir o CGC. Retorna o mesmo schema Fornecedor do GET por CGC.

Busca por tipo=msuid exige que o dicionário do SA2 tenha o campo A2_MSUID. Em ambiente sem essa coluna o endpoint responde 501.

Query parameters

tipo string · query · obrigatório

Indica qual id técnico está sendo usado.

recnomsuid

valor string · query · obrigatório

Valor do id (inteiro quando tipo=recno, string quando tipo=msuid).

Chamada de exemplo

Request · por recnoHTTP/1.1 · sem body

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

Request · por msuidHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsFornecedor/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Fornecedor encontrado. Envelope { success: true, data: Fornecedor }.

400

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

404

Fornecedor não localizado. Tier: not-found.

501

Busca por msuid requer índice/coluna não disponível no ambiente (A2_MSUID ausente).

500

Erro interno.

Listagem

Listagem paginada e typeahead

GET /WsFornecedor/_list Lista fornecedores com filtros e paginação

Descrição

Lista fornecedores com filtros por cod, nome (prefix normalizado, sem acento) ou cgc (prefix). Suporta dois modos de ordenação:

orderBy=chave (default) — paginação por page/pageSize.
orderBy=recno — delta-sync, usa since/cursor com nextCursor retornado (rev24).

Query parameters

cod string · query · opcional SA2.A2_COD

A2_COD exato (índice 1).

nome string · query · opcional SA2.A2_NOME

Prefix normalizado (sem acento, uppercase).

cgc string · query · opcional SA2.A2_CGC

CGC prefix (índice 3).

fields string · query · opcional

Lista de campos 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).

orderBy string · query · opcional

Modo de ordenação. Default chave.

chaverecno

since integer · query · opcional

Início do delta-sync (válido com orderBy=recno).

cursor integer · query · opcional

Cursor retornado em nextCursor de página anterior.

Chamada de exemplo

Request · paginação por chaveHTTP/1.1 · sem body

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

Request · delta-sync por recnoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsFornecedor/_list?orderBy=recno&since=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de fornecedores. Envelope com data (array de Fornecedor), page, pageSize, count, opcionalmente nextCursor.

400

Parâmetro fora do domínio (ex: orderBy inválido, pageSize > 500).

500

Erro interno.

GET /WsFornecedor/_search Typeahead por nome ou CGC

Descrição

Busca rápida (typeahead) para autocomplete de UI. Retorna uma lista enxuta (cod, loja, cgc, nome, recno, msuid, msuidt) — não devolve o schema completo de Fornecedor.

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 (default 10, máx 25).

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Lista enxuta de sugestões. Envelope: success, count, data[] com cod/loja/cgc/nome/recno/msuid/msuidt.

400

q ausente ou < 2 caracteres, match fora do enum.

500

Erro interno.

Schemas

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

Fornecedor

object

Representação retornada nos GETs (/{cgc}, /_list, /_byid). Inclui chave técnica (A2_COD/A2_LOJA) e dados cadastrais. Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields. Os ids técnicos (recno/msuid/msuidt) são anexados por fAddTec após o registro estar posicionado.

A2_CODstring · opcionalSA2.A2_COD

Chave técnica do fornecedor (sequência gerada por GetSXENum).

A2_LOJAstring · opcionalSA2.A2_LOJA

Loja do fornecedor (default "01").

A2_NOMEstring · opcionalSA2.A2_NOME

Razão social ou nome completo.

A2_NREDUZstring · opcionalSA2.A2_NREDUZ

Nome reduzido / fantasia.

A2_ENDstring · opcionalSA2.A2_END

Endereço (logradouro + número).

A2_BAIRROstring · opcionalSA2.A2_BAIRRO

Bairro.

A2_ESTstring · opcionalSA2.A2_EST

UF (sigla, 2 letras).

A2_CEPstring · opcionalSA2.A2_CEP

CEP (8 dígitos, sem hífen).

A2_TIPOstring · opcionalSA2.A2_TIPO

Tipo do fornecedor.

JFOXR

A2_PFISICAstring · opcionalSA2.A2_PFISICA

Pessoa Física (F) ou Jurídica (J).

FJ

A2_DDDstring · opcionalSA2.A2_DDD

DDD do telefone principal.

A2_TELstring · opcionalSA2.A2_TEL

Telefone principal.

A2_EMAILstring · opcionalSA2.A2_EMAIL

E-mail principal.

A2_CGCstring · opcionalSA2.A2_CGC

CNPJ (14) ou CPF (11), apenas dígitos.

A2_MSBLQLstring · opcionalSA2.A2_MSBLQL

Flag de bloqueio TOTVS-padrão. SX3 pertence("12"), default "2". "1"=Inativo (bloqueado), "2"=Ativo (liberado).

12

recnointeger · opcional

Id técnico do registro (RecNo() do AdvPL). Sempre presente.

msuidstring · opcional

Identificador universal A2_MSUID. Presente apenas se o campo existir no dicionário.

msuidtstring · opcional

Timestamp técnico A2_MSUIDT associado ao msuid. Mesma condição de presença.

FornecedorPayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW no .prw; campos fora do whitelist são silenciosamente descartados pelo parser. Quando A2_COD_MUN é informado, o X3 valid faz seek na CC2 usando A2_EST + A2_MUN — os três campos precisam estar coerentes.

Em PUT sobre fornecedor bloqueado, o payload deve conter apenas A2_MSBLQL e/ou A2_MSBLQD — qualquer outro campo provoca 422 (caminho de desbloqueio).

A2_NOMEstring · opcionalSA2.A2_NOME

Razão social ou nome completo.

A2_NREDUZstring · opcionalSA2.A2_NREDUZ

Nome reduzido / fantasia.

A2_ENDstring · opcionalSA2.A2_END

Endereço.

A2_BAIRROstring · opcionalSA2.A2_BAIRRO

Bairro.

A2_MUNstring · opcionalSA2.A2_MUN

Município (texto). Combinado com A2_EST e A2_COD_MUN nas validações.

A2_ESTstring · opcionalSA2.A2_EST

UF (2 letras).

A2_COD_MUNstring · opcionalSA2.A2_COD_MUN

Código IBGE do município (lookup na CC2 por UF + nome). Omitir quando não há certeza do código — o cadastro funciona sem ele.

A2_CEPstring · opcionalSA2.A2_CEP

CEP (8 dígitos).

A2_PAISstring · opcionalSA2.A2_PAIS

Código de país (default "105" = Brasil).

A2_DDDstring · opcionalSA2.A2_DDD

DDD.

A2_TELstring · opcionalSA2.A2_TEL

Telefone.

A2_FAXstring · opcionalSA2.A2_FAX

Fax.

A2_EMAILstring (email) · opcionalSA2.A2_EMAIL

E-mail principal.

A2_PFISICAstring · opcionalSA2.A2_PFISICA

Pessoa Física / Jurídica. Esta é a flag autoritativa de PF/PJ neste endpoint (rev9 removeu A2_PESSOA do allowlist).

FJ

A2_TIPOstring · opcionalSA2.A2_TIPO

Tipo do fornecedor: J=Jurídico nacional, F=Físico, O=Outros, X=Exterior, R=Rural.

JFOXR

A2_MSBLQLstring · opcionalSA2.A2_MSBLQL

Flag de bloqueio TOTVS-padrão (SX3 pertence("12"), default "2"): "1"=Inativo, "2"=Ativo. MsExecAuto do MATA020 rejeita valores fora do domínio.

12

A2_MSBLQDstring · opcionalSA2.A2_MSBLQD

Bloqueio com vigência. Aceita string ISO YYYY-MM-DD ou vazia (limpa a data). Bloqueio fica ativo enquanto dDataBase > A2_MSBLQD.

A2_PESSOAstring · deprecated

Aparece no OpenAPI por compatibilidade histórica, mas foi removido do allowlist a partir da rev9 — o campo não existe no FormModel do SA2 neste ambiente. Use A2_PFISICA.

FJ

CC2_ESTstring · deprecated

Helper de lookup CC2 (UF) presente no OpenAPI. Não processado pela rev11+ — envie A2_EST diretamente.

CC2_MUNstring · deprecated

Helper de lookup CC2 (nome do município). Não processado pela rev11+ — envie A2_MUN diretamente.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz a chave técnica gerada (POST) ou string vazia (PUT/DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring | object · opcional

Em POST, contém a chave técnica gerada (A2_COD/A2_LOJA). Em PUT/DELETE pode ser string vazia ou objeto auxiliar.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx, produzido por U_RestErro (RestUtils.prw). data pode conter o token interno da causa (ex: mensagem do NomeAutoLog) para tratamento programático, quando aplicável.

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).

Cenários

Catálogo de combinações de payload reconhecidas pelos métodos de mutação. Cada cenário compartilha o mesmo schema da operação mas demonstra um uso típico distinto. Tier semântico no slug (-minimo, -com-*, -desbloqueio, etc); endpoint no type-pill.

post-minimo-pj

POST /WsFornecedor/{CGC}

Caminho feliz mínimo do POST: só os campos essenciais para incluir um fornecedor PJ. A2_TIPO="J", A2_PFISICA omitido (default vazio).

Quando usar: fornecedor PJ comum, sem endereço detalhado, sem dados fiscais especiais.

A2_NOMEstring · obrigatórioSA2.A2_NOME

Razão social.

A2_NREDUZstring · obrigatórioSA2.A2_NREDUZ

Nome reduzido.

A2_TIPOstring · obrigatórioSA2.A2_TIPO

J = Jurídica.

post-com-municipio

POST /WsFornecedor/{CGC}

POST realístico com endereço completo + código de município IBGE (A2_COD_MUN). Útil quando o fornecedor é recém-cadastrado em integração com base SIAFI/IBGE.

A2_ENDstring · opcionalSA2.A2_END

Endereço completo.

A2_MUNstring · opcionalSA2.A2_MUN

Nome do município.

A2_COD_MUNstring · opcionalSA2.A2_COD_MUN

Código IBGE do município.

A2_ESTstring · opcionalSA2.A2_EST

UF (2 chars).

put-alteracao

PUT /WsFornecedor/{CGC}

Alteração de dados cadastrais ordinários (nome, telefone, email). Caminho feliz mais comum do PUT.

A2_NREDUZstring · opcionalSA2.A2_NREDUZ

Novo nome reduzido.

A2_TELstring · opcionalSA2.A2_TEL

Telefone.

A2_EMAILstring · opcionalSA2.A2_EMAIL

Email de contato.

put-tipo-exportacao

PUT /WsFornecedor/{CGC}

Reclassifica o fornecedor para tipo X (Exportação). Útil para fornecedores estrangeiros com regime fiscal diferenciado.

A2_TIPOstring · obrigatórioSA2.A2_TIPO

X = Exportação.

put-desbloqueio

PUT /WsFornecedor/{CGC}

Libera fornecedor previamente bloqueado por A2_MSBLQL=1. Único PUT permitido em registro bloqueado é alterar o par A2_MSBLQL/A2_MSBLQD.

A2_MSBLQLstring · obrigatórioSA2.A2_MSBLQL

2 = Ativo (libera o registro).

put-bloquear-com-data

PUT /WsFornecedor/{CGC}

Programa bloqueio futuro via A2_MSBLQD (data a partir da qual o fornecedor passa a ser bloqueado). Bloqueio ativo quando dDataBase > A2_MSBLQD.

A2_MSBLQDstring (date ISO) · obrigatórioSA2.A2_MSBLQD

Data ISO YYYY-MM-DD.

put-limpar-data-bloqueio

PUT /WsFornecedor/{CGC}

Apaga A2_MSBLQD (string vazia), removendo o bloqueio programado. Usado quando a programação prévia foi cancelada.

A2_MSBLQDstring · obrigatórioSA2.A2_MSBLQD

String vazia "".