rev1-2026-05-16

CadastroVendedor

CRUD do cadastro de Vendedor (SA3) via wrapper MATA040. Chave externa A3_COD no path. Suporta bloqueio TOTVS padrão (A3_MSBLQL/A3_MSBLQD) via helper U_C980Blq.

Bloqueio TOTVS: PUT em vendedor bloqueado (A3_MSBLQL="1" ou A3_MSBLQD < data-base) só aceita alterar os próprios campos A3_MSBLQL/A3_MSBLQD; qualquer outro campo retorna 422.

Vinculação com o ERP

Tabela mestreSA3Vendedores

Rotina automáticaMATA040MsExecAuto · op 3/4/5

Wrapper AdvPLU_MT040Excsrc/lib/MAT/MT040EXC.prw

Fonte RESTWsSA3.prwsrc/api/CadastroVendedor/

Chave externaA3_CODno path · 6 chars

BloqueioA3_MSBLQL/A3_MSBLQDU_C980Blq

Dependências e índices

Índice 1

A3_FILIAL+A3_COD

byid e listagem por código.

Índice 2

A3_FILIAL+A3_NOME

filtros por nome (typeahead via TCGenQry).

Validação

A3_CGC (CPF/CNPJ)

X3_VALID nativo TOTVS; CGC inválido → 422.

Bloqueio

U_C980Blq(SA3)

checa A3_MSBLQL=1 ou A3_MSBLQD<dDataBase antes do PUT.

Convenções

Envelope canônico. { success, message, data }. POST/PUT retornam data.A3_COD.

Chave no path. POST/PUT/DELETE usam {vendedor} = A3_COD (max 6 chars).

Bloqueio MSBLQL/MSBLQD. PUT em vendedor bloqueado: só aceita os próprios campos do par bloqueio; outros → 422. Desbloqueio aceito por flag (A3_MSBLQL="2") ou data futura/vazia.

Whitelist de campos. Payload aceita A3_NOME, A3_NREDUZ, A3_TIPO, A3_EMAIL, A3_TEL, A3_COMIS, A3_CGC, A3_END, A3_BAIRRO, A3_MUN, A3_EST, A3_CEP, A3_MSBLQL, A3_MSBLQD. Demais ignorados.

A3_MSBLQD é Date. ISO YYYY-MM-DD ou vazia. Fica fora do CAMPOS_GET até U_RestMonta suportar Date-aware (transversal).

Vendedor — mutação

Inclusão / alteração / exclusão via MATA040.

POST/WsSA3/INCLUIR/000001Inclui vendedor — MATA040 op=3

Descrição

Inclui vendedor em SA3. {vendedor} = A3_COD único; duplicidade → 409. A3_CGC validado por X3_VALID.

Path parameter

vendedorstring · max 6 · obrigatório

Código (A3_COD).

Cenário

Request body

A3_NOMEstring · obrigatório

Nome completo.

A3_NREDUZstring · opcional

Nome reduzido.

A3_TIPOstring (F/J) · opcional

F=PF, J=PJ.

A3_CGCstring · opcional

CPF/CNPJ — X3_VALID.

A3_EMAILstring · opcional

Email.

A3_COMISnumber · opcional

% de comissão.

Mínimo. Só A3_NOME.

Request

POST https://erpapi.jetme.com.br/api/99/01/WsSA3/INCLUIR/000001

{
  "A3_NOME": "Joao Silva"
}

Completo. PF com CGC, email e comissão.

Request

POST https://erpapi.jetme.com.br/api/99/01/WsSA3/INCLUIR/000001

{
  "A3_NOME": "Joao Silva",
  "A3_NREDUZ": "JOAO",
  "A3_TIPO": "F",
  "A3_CGC": "12345678901",
  "A3_EMAIL": "joao@exemplo.com",
  "A3_COMIS": 3.5
}

Respostas

201

Criado. data.A3_COD.

400

Código/payload inválido.

409

Já cadastrado.

422

Erro MATA040 (CGC inválido etc).

PUT/WsSA3/ALTERAR/000001Altera vendedor — MATA040 op=4

Descrição

Altera vendedor. Bloqueio TOTVS: vendedor bloqueado só aceita PUT em A3_MSBLQL/A3_MSBLQD; outros campos → 422.

Cenário

Request body

A3_NOMEstring · opcional

Novo nome.

A3_EMAILstring · opcional

Novo email.

A3_COMISnumber · opcional

Nova comissão.

A3_MSBLQLstring ("1"/"2") · opcional

1=bloqueado, 2=ativo.

A3_MSBLQDstring (date) · opcional

Data ISO; bloqueio quando dDataBase > A3_MSBLQD.

Alterar dados comuns.

Request

PUT https://erpapi.jetme.com.br/api/99/01/WsSA3/ALTERAR/000001

{
  "A3_EMAIL": "joao@nova.com",
  "A3_COMIS": 4.0
}

Bloquear. A3_MSBLQL=1 + data.

Request

PUT https://erpapi.jetme.com.br/api/99/01/WsSA3/ALTERAR/000001

{
  "A3_MSBLQL": "1",
  "A3_MSBLQD": "2026-05-17"
}

Desbloquear. Único campo permitido em bloqueado.

Request

PUT https://erpapi.jetme.com.br/api/99/01/WsSA3/ALTERAR/000001

{
  "A3_MSBLQL": "2"
}

Respostas

200

Alterado.

404

Não encontrado.

422

Bloqueado + payload toca campo fora do par MSBLQL/MSBLQD, ou erro MATA040.

DELETE/WsSA3/EXCLUIR/000001Exclui vendedor — MATA040 op=5

Descrição

DELETE via MATA040 op=5. Falha (422) quando referenciado em SC5/SC6 etc.

Cenário

Exemplo

Request

DELETE https://erpapi.jetme.com.br/api/99/01/WsSA3/EXCLUIR/000001

Respostas

200

Excluído.

404

Não encontrado.

422

Em uso.

Consulta

Consulta por código, listagem e typeahead.

GET/WsSA3/000001Vendedor por código

Descrição

Retorna campos do whitelist CAMPOS_GET.

Cenário

Exemplo

Request

GET https://erpapi.jetme.com.br/api/99/01/WsSA3/000001

Response 200

{
  "success": true,
  "data": {
    "A3_COD": "000001",
    "A3_NOME": "Joao Silva",
    "A3_TIPO": "F",
    "A3_COMIS": 3.5,
    "A3_MSBLQL": "2"
  }
}

GET/WsSA3/_listListagem paginada

Query parameters

codstring · opcional

Prefixo A3_COD.

nomestring · opcional

Prefixo A3_NOME.

pageinteger · default 1

Página.

pageSizeinteger · default 50, max 500

Tamanho.

Cenário

Exemplo

Request

GET https://erpapi.jetme.com.br/api/99/01/WsSA3/_list?nome=JOA&page=1&pageSize=25

GET/WsSA3/_searchTypeahead por nome

Descrição

TCGenQry A3_NOME COLLATE Latin1_General_CI_AI LIKE q% — acento-insensitive. Mín 2, limit 10/25.

Query parameters

qstring · min 2 · obrigatório

Prefixo do nome.

limitinteger · default 10, max 25

Limite.

Cenário

Exemplo

Request

GET https://erpapi.jetme.com.br/api/99/01/WsSA3/_search?q=JOA&limit=5

Schemas

Componentes do contrato OpenAPI

VendedorPayload

object

Payload plano de POST/PUT. Whitelist CAMPOS_ALLOW.

A3_NOMEstring · obrigatório (POST)SA3.A3_NOME

Nome completo (40 chars).

A3_NREDUZstring · opcionalSA3.A3_NREDUZ

Nome reduzido (15).

A3_TIPOstring · opcionalSA3.A3_TIPO

F=PF, J=PJ.

A3_CGCstring · opcionalSA3.A3_CGC

CPF/CNPJ — X3_VALID.

A3_EMAIL, A3_TELstring · opcional

Contato.

A3_END, A3_BAIRRO, A3_MUN, A3_EST, A3_CEPstring · opcional

Endereço.

A3_COMISnumber · opcionalSA3.A3_COMIS

% comissão.

A3_MSBLQLstring · opcionalSA3.A3_MSBLQL

1=bloqueado, 2=ativo.

A3_MSBLQDstring (date) · opcionalSA3.A3_MSBLQD

Data ISO.

Vendedor

object · SA3

Vendedor retornado pelo GET (CAMPOS_GET). A3_MSBLQD não entra (Date pendente).

A3_COD + campos do VendedorPayload exceto A3_MSBLQD

A3_COD é a chave; demais seguem o payload.

EnvelopeSucesso

object · envelope

Envelope canônico.

success

true.

message

Texto.

data

{ A3_COD } em POST/PUT, dados completos em GET.

EnvelopeErro

object · envelope

success=false + message. Quando bloqueio TOTVS dispara: "Registro bloqueado a partir de DD/MM/YYYY (A3_MSBLQD)".

message

Causa.

Cenários

1-pra-1 com examples: do YAML.

incluir-minimo

POST /WsSA3/INCLUIR/{vendedor}

Mínimo viável — só A3_NOME.

A3_NOME

"Joao Silva"

incluir-completo

POST /WsSA3/INCLUIR/{vendedor}

PF com CGC, email, comissão.

A3_NOME, A3_TIPO=F, A3_CGC, A3_EMAIL, A3_COMIS

PF completo.

alterar-dados

PUT /WsSA3/ALTERAR/{vendedor}

Edita email/comissão de vendedor não bloqueado.

A3_EMAIL, A3_COMIS

Atualização.

bloquear

PUT /WsSA3/ALTERAR/{vendedor}

A3_MSBLQL=1 + data.

A3_MSBLQL=1, A3_MSBLQD=2026-05-17

Bloqueia.

desbloquear

PUT /WsSA3/ALTERAR/{vendedor}

A3_MSBLQL=2 — único campo permitido em bloqueado.

A3_MSBLQL=2

Reativa.

excluir

DELETE /WsSA3/EXCLUIR/{vendedor}

DELETE sem body. Falha quando referenciado em SC5.

path.vendedor

A3_COD sem referências.

consulta-byid

GET /WsSA3/{vendedor}

Vendedor 000001.

path.vendedor

000001

listagem

GET /WsSA3/_list

Vendedores com nome "JOA", pag 25.

nome / pageSize

"JOA" / 25

typeahead

GET /WsSA3/_search

Sugestões para "JOA" — acento-insensitive.

q / limit

"JOA" / 5

Pendências conhecidas (rev2)

A3_MSBLQD fora do CAMPOS_GET. U_RestMonta não tem serialização Date-aware. A3_MSBLQD entra no PUT, não no retorno. Transversal.

Hierarquia (A3_GEREN, A3_SUPER). Não estão no whitelist. Adicionar quando precisar.