rev1-2026-05-16

CadastroTransportadora

CRUD do cadastro de Transportadora (SA4) via wrapper MATA050. Chave externa A4_COD no path. Suporta bloqueio TOTVS padrão (A4_MSBLQL/A4_MSBLQD) via helper U_C980Blq.

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

Vinculação com o ERP

Tabela mestreSA4Transportadoras

Rotina automáticaMATA050MsExecAuto · op 3/4/5

Wrapper AdvPLU_MT050Excsrc/lib/MAT/MT050EXC.prw

Fonte RESTWsSA4.prwsrc/api/CadastroTransportadora/

Chave externaA4_CODno path · 6 chars

BloqueioA4_MSBLQL/A4_MSBLQDU_C980Blq

Dependências e índices

Índice 1

A4_FILIAL+A4_COD

byid e listagem por código.

Índice 2

A4_FILIAL+A4_NOME

filtros por nome (typeahead via TCGenQry).

Validação

A4_CGC (CPF/CNPJ)

X3_VALID nativo TOTVS; CGC inválido → 422.

Bloqueio

U_C980Blq(SA4)

checa A4_MSBLQL=1 ou A4_MSBLQD<dDataBase antes do PUT.

Convenções

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

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

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

Whitelist de campos. Payload aceita A4_NOME, A4_NREDUZ, A4_EMAIL, A4_TEL, A4_CGC, A4_END, A4_BAIRRO, A4_MUN, A4_EST, A4_CEP, A4_MSBLQL, A4_MSBLQD. Demais ignorados.

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

Transportadora — mutação

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

POST/WsSA4/INCLUIR/000001Inclui transportadora — MATA050 op=3

Descrição

Inclui transportadora em SA4. {transportadora} = A4_COD único; duplicidade → 409. A4_CGC validado por X3_VALID.

Path parameter

transportadorastring · max 6 · obrigatório

Código (A4_COD).

Cenário

Request body

A4_NOMEstring · obrigatório

Nome completo.

A4_NREDUZstring · opcional

Nome reduzido.

A4_VIAstring (F/J) · opcional

R=rodov, A=aerea, F=fluvial, M=maritima.

A4_CGCstring · opcional

CPF/CNPJ — X3_VALID.

A4_EMAILstring · opcional

Email.

A4_VIAnumber · opcional

Via de transporte (R/A/F/M).

Mínimo. Só A4_NOME.

Request

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

{
  "A4_NOME": "Transportes XYZ"
}

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

Request

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

{
  "A4_NOME": "Transportes XYZ",
  "A4_NREDUZ": "TRANSP",
  "A4_VIA": "F",
  "A4_CGC": "12345678901",
  "A4_EMAIL": "contato@xyz.com",
  "A4_VIA": R
}

Respostas

201

Criado. data.A4_COD.

400

Código/payload inválido.

409

Já cadastrado.

422

Erro MATA050 (CGC inválido etc).

PUT/WsSA4/ALTERAR/000001Altera transportadora — MATA050 op=4

Descrição

Altera transportadora. Bloqueio TOTVS: transportadora bloqueado só aceita PUT em A4_MSBLQL/A4_MSBLQD; outros campos → 422.

Cenário

Request body

A4_NOMEstring · opcional

Novo nome.

A4_EMAILstring · opcional

Novo email.

A4_VIAnumber · opcional

Nova via de transporte.

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

1=bloqueado, 2=ativo.

A4_MSBLQDstring (date) · opcional

Data ISO; bloqueio quando dDataBase > A4_MSBLQD.

Alterar dados comuns.

Request

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

{
  "A4_EMAIL": "contato@nova.com",
  "A4_VIA": R
}

Bloquear. A4_MSBLQL=1 + data.

Request

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

{
  "A4_MSBLQL": "1",
  "A4_MSBLQD": "2026-05-17"
}

Desbloquear. Único campo permitido em bloqueado.

Request

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

{
  "A4_MSBLQL": "2"
}

Respostas

200

Alterado.

404

Não encontrado.

422

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

DELETE/WsSA4/EXCLUIR/000001Exclui transportadora — MATA050 op=5

Descrição

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

Cenário

Exemplo

Request

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

Respostas

200

Excluído.

404

Não encontrado.

422

Em uso.

Consulta

Consulta por código, listagem e typeahead.

GET/WsSA4/000001Transportadora por código

Descrição

Retorna campos do whitelist CAMPOS_GET.

Cenário

Exemplo

Request

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

Response 200

{
  "success": true,
  "data": {
    "A4_COD": "000001",
    "A4_NOME": "Transportes XYZ",
    "A4_VIA": "F",
    "A4_VIA": R,
    "A4_MSBLQL": "2"
  }
}

GET/WsSA4/_listListagem paginada

Query parameters

codstring · opcional

Prefixo A4_COD.

nomestring · opcional

Prefixo A4_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/WsSA4/_list?nome=JOA&page=1&pageSize=25

GET/WsSA4/_searchTypeahead por nome

Descrição

TCGenQry A4_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/WsSA4/_search?q=JOA&limit=5

Schemas

Componentes do contrato OpenAPI

TransportadoraPayload

object

Payload plano de POST/PUT. Whitelist CAMPOS_ALLOW.

A4_NOMEstring · obrigatório (POST)SA4.A4_NOME

Nome completo (40 chars).

A4_NREDUZstring · opcionalSA4.A4_NREDUZ

Nome reduzido (15).

A4_VIAstring · opcionalSA4.A4_VIA

R=rodov, A=aerea, F=fluvial, M=maritima.

A4_CGCstring · opcionalSA4.A4_CGC

CPF/CNPJ — X3_VALID.

A4_EMAIL, A4_TELstring · opcional

Contato.

A4_END, A4_BAIRRO, A4_MUN, A4_EST, A4_CEPstring · opcional

Endereço.

A4_VIAnumber · opcionalSA4.A4_VIA

Via de transporte (R/A/F/M).

A4_MSBLQLstring · opcionalSA4.A4_MSBLQL

1=bloqueado, 2=ativo.

A4_MSBLQDstring (date) · opcionalSA4.A4_MSBLQD

Data ISO.

Transportadora

object · SA4

Transportadora retornado pelo GET (CAMPOS_GET). A4_MSBLQD não entra (Date pendente).

A4_COD + campos do TransportadoraPayload exceto A4_MSBLQD

A4_COD é a chave; demais seguem o payload.

EnvelopeSucesso

object · envelope

Envelope canônico.

success

true.

message

Texto.

data

{ A4_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 (A4_MSBLQD)".

message

Causa.

Cenários

1-pra-1 com examples: do YAML.

incluir-minimo

POST /WsSA4/INCLUIR/{transportadora}

Mínimo viável — só A4_NOME.

A4_NOME

"Transportes XYZ"

incluir-completo

POST /WsSA4/INCLUIR/{transportadora}

PF com CGC, email, comissão.

A4_NOME, A4_VIA=F, A4_CGC, A4_EMAIL, A4_VIA

PF completo.

alterar-dados

PUT /WsSA4/ALTERAR/{transportadora}

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

A4_EMAIL, A4_VIA

Atualização.

bloquear

PUT /WsSA4/ALTERAR/{transportadora}

A4_MSBLQL=1 + data.

A4_MSBLQL=1, A4_MSBLQD=2026-05-17

Bloqueia.

desbloquear

PUT /WsSA4/ALTERAR/{transportadora}

A4_MSBLQL=2 — único campo permitido em bloqueado.

A4_MSBLQL=2

Reativa.

excluir

DELETE /WsSA4/EXCLUIR/{transportadora}

DELETE sem body. Falha quando referenciado em SC5.

path.transportadora

A4_COD sem referências.

consulta-byid

GET /WsSA4/{transportadora}

Transportadora 000001.

path.transportadora

000001

listagem

GET /WsSA4/_list

Transportadoras com nome "JOA", pag 25.

nome / pageSize

"JOA" / 25

typeahead

GET /WsSA4/_search

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

q / limit

"JOA" / 5

Pendências conhecidas (rev2)

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

Hierarquia regional. SA4 não tem campos de hierarquia padrão; agrupamento por região pode usar A4_EST/A4_MUN.