rev1-2026-05-16

ExcecaoFiscal

CRUD de Exceção Fiscal Tributária (tabela SF7) via wrapper U_MT540MVC / MATA540. Cada registro combina um grupo tributário (F7_GRTRIB) com uma sequência (F7_SEQUEN) e define alíquotas e percentuais por estado, tipo de cliente e grupo de cliente.

Sequência auto-calculada. F7_SEQUEN é determinado pelo endpoint no POST (maior sequência do grupo + 1) — o chamador não precisa informar. O código gerado retorna em data.sequen.

Vinculação com o ERP

TabelaSF7Exceção Fiscal Tributária

Rotina automáticaMATA540MsExecAuto · op 3/4/5

Wrapper AdvPLU_MT540MVCsrc/lib/MAT/MT540MVC.prw

Fonte RESTWsSF7.prwsrc/api/ExcecaoFiscal/

Chave paiF7_GRTRIBGrupo tributário — path do POST

Chave linhaF7_SEQUENSequência — calculada no POST; path do PUT/DELETE

Notas de estrutura

Tabela única

SF7

Não há tabela de itens separada. Cada registro SF7 é uma linha de exceção fiscal identificada por F7_GRTRIB + F7_SEQUEN.

CAMPOS_GET

Campos retornados no GET

F7_FILIAL, F7_GRTRIB, F7_SEQUEN, F7_EST, F7_TIPOCLI, F7_GRPCLI, F7_ALIQINT, F7_ALIQEXT, F7_MARGEM, F7_ALIQDST, F7_ISS, F7_VLR_ICM, F7_VLR_IPI, F7_VLR_PIS, F7_VLR_COF, F7_VLRICMP, F7_ALIQIPI, F7_ALIQPIS, F7_ALIQCOF, F7_BASEICM, F7_BASEIPI, F7_REDPIS, F7_REDCOF, F7_ICMPAUT, F7_UFBUSCA, F7_BSICMST, F7_PRCUNIC, F7_DTINCLU, F7_ORIGEM, F7_SITTRIB

CAMPOS_DET (whitelist PUT/POST)

Campos aceitos em mutação

CAMPOS_GET menos F7_FILIAL e F7_GRTRIB; F7_SEQUEN é ignorado no payload (calculado internamente).

Convenções

Envelope canônico. { success, message, data }. POST 201 retorna data.grtrib e data.sequen.

URL POST. /WsSF7/{grtrib} — apenas o grupo tributário. Sequência é auto-calculada.

URL PUT/DELETE. /WsSF7/{grtrib}/{seq} — grupo e sequência juntos.

GET dispatcher. /WsSF7/{grtrib} lista o grupo; /WsSF7/_search?term= faz typeahead; /WsSF7/_byid/{recno} busca por recno.

Exceção Fiscal — mutação

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

POST/WsSF7/ICMS-SPInclui linha de exceção — MATA540 op=3

Descrição

Inclui nova linha de exceção fiscal no grupo tributário {grtrib}. F7_SEQUEN é calculado automaticamente (maior sequência existente no grupo + 1) e retornado em data.sequen.

Path parameter

grtribstring · obrigatório

Código do grupo tributário (F7_GRTRIB).

Cenário

Request body

F7_ESTstring · opcional

UF de destino (2 chars).

F7_TIPOCLIstring · opcional

Tipo de cliente.

F7_ALIQINTnumber · opcional

Alíquota interna (%).

F7_ALIQEXTnumber · opcional

Alíquota externa (%).

F7_MARGEMnumber · opcional

Margem de valor agregado (%).

Linha mínima. UF SP + alíquotas interna/externa.

Request

POST https://erpapi.jetme.com.br/api/99/01/WsSF7/ICMS-SP

{
  "F7_EST": "SP",
  "F7_TIPOCLI": "F",
  "F7_ALIQINT": 12.00,
  "F7_ALIQEXT": 7.00,
  "F7_MARGEM": 40.00
}

Response 201

{
  "success": true,
  "message": "Excecao fiscal criada com sucesso.",
  "data": {
    "grtrib": "ICMS-SP",
    "sequen": "001"
  }
}

Respostas

201

Criado. data.grtrib e data.sequen retornados.

400

Grupo tributário ausente no path, ou payload inválido.

422

Erro MATA540 (campo inválido, violação de regra fiscal).

PUT/WsSF7/ICMS-SP/001Altera linha de exceção — MATA540 op=4

Descrição

Altera linha existente identificada por {grtrib} + {seq}. Apenas os campos enviados no payload são alterados.

Path parameters

grtribstring · obrigatório

Código do grupo tributário.

seqstring · obrigatório

Sequência da linha (retornada no POST).

Cenário

Request body

F7_MARGEMnumber · opcional

Nova margem de valor agregado (%).

F7_ALIQINTnumber · opcional

Nova alíquota interna (%).

Ajustar margem.

Request

PUT https://erpapi.jetme.com.br/api/99/01/WsSF7/ICMS-SP/001

{
  "F7_MARGEM": 45.00
}

Respostas

200

Alterado.

400

Grupo ou sequência ausentes no path, ou payload inválido.

404

Linha não localizada.

422

Erro MATA540.

DELETE/WsSF7/ICMS-SP/001Exclui linha de exceção — MATA540 op=5

Descrição

Exclui linha de exceção fiscal identificada por {grtrib} + {seq}. Sem body.

Cenário

Exemplo

Request

DELETE https://erpapi.jetme.com.br/api/99/01/WsSF7/ICMS-SP/001

Respostas

200

Excluída.

404

Linha não localizada.

422

Erro MATA540.

Consulta

Listagem por grupo, busca por recno e typeahead.

GET/WsSF7/ICMS-SPLista todas as linhas do grupo tributário

Cenário

Exemplo

Request

GET https://erpapi.jetme.com.br/api/99/01/WsSF7/ICMS-SP

Response 200

{
  "success": true,
  "data": {
    "grtrib": "ICMS-SP",
    "count": 2,
    "items": [
      {
        "F7_GRTRIB": "ICMS-SP",
        "F7_SEQUEN": "001",
        "F7_EST": "SP",
        "F7_ALIQINT": "12.00",
        "F7_MARGEM": "40.00"
      }
    ]
  }
}

GET/WsSF7/_byid/1234Linha por recno

Descrição

Retorna linha SF7 pelo recno físico. Útil para inspecionar um registro específico após o POST (que retorna o sequen, não o recno).

Cenário

Exemplo

Request

GET https://erpapi.jetme.com.br/api/99/01/WsSF7/_byid/1234

GET/WsSF7/_searchTypeahead por F7_GRTRIB

Descrição

Busca via TCGenQry em SF7 com F7_GRTRIB LIKE <term>%. Retorna lista de grupos distintos. Mínimo 1 caractere em term; limite default 10 (max 25).

Query parameters

termstring · obrigatório

Prefixo do grupo tributário.

limitinteger · default 10, max 25

Limite de sugestões.

Cenário

Exemplo

Request

GET https://erpapi.jetme.com.br/api/99/01/WsSF7/_search?term=ICMS&limit=5

Schemas

Componentes do contrato

ExcecaoFiscalPayload

object

Payload de entrada para POST e PUT. Campos da whitelist CAMPOS_DET do WsSF7.prw.

F7_ESTstringSF7.F7_EST

UF de destino (2 chars).

F7_TIPOCLIstringSF7.F7_TIPOCLI

Tipo de cliente.

F7_GRPCLIstringSF7.F7_GRPCLI

Grupo de cliente.

F7_ALIQINTnumberSF7.F7_ALIQINT

Alíquota interna (%).

F7_ALIQEXTnumberSF7.F7_ALIQEXT

Alíquota externa (%).

F7_MARGEMnumberSF7.F7_MARGEM

Margem de valor agregado (%).

F7_ALIQDSTnumberSF7.F7_ALIQDST

Alíquota diferencial (%).

F7_ISSnumberSF7.F7_ISS

Alíquota ISS (%).

F7_ALIQIPI, F7_ALIQPIS, F7_ALIQCOFnumber

Alíquotas IPI / PIS / COFINS (%).

F7_BASEICM, F7_BASEIPInumber

Base de cálculo ICMS / IPI.

F7_REDPIS, F7_REDCOFnumber

Redução PIS / COFINS (%).

F7_ICMPAUTnumberSF7.F7_ICMPAUT

ICMS pautas (%).

F7_UFBUSCAstringSF7.F7_UFBUSCA

UF de busca ST.

F7_BSICMSTnumberSF7.F7_BSICMST

Base ICMS-ST (%).

F7_PRCUNICnumberSF7.F7_PRCUNIC

Preço único ST.

F7_DTINCLUstring (date)SF7.F7_DTINCLU

Data de inclusão.

F7_ORIGEMstringSF7.F7_ORIGEM

Origem da mercadoria.

F7_SITTRIBstringSF7.F7_SITTRIB

Situação tributária.

Registro

object · SF7

Linha SF7 retornada nos GETs. Campos de CAMPOS_GET.

F7_FILIALstring

Filial.

F7_GRTRIBstring

Grupo tributário.

F7_SEQUENstring

Sequência da linha no grupo.

recnointeger

Recno físico — usar em _byid.

F7_EST ... F7_SITTRIBmixed

Demais campos de CAMPOS_GET (ver Vinculação ERP).

EnvelopeSucesso

object

Envelope canônico.

success/message/data

Padrão da biblioteca.

EnvelopeErro

object

success=false + message.

message

Causa do erro.

Cenários

1-pra-1 com YAML.

incluir

POST /WsSF7/{grtrib}

Nova linha SF7 com UF + alíquotas.

grtrib

ICMS-SP

F7_EST, F7_ALIQINT, F7_ALIQEXT, F7_MARGEM

SP / 12.00 / 7.00 / 40.00

alterar

PUT /WsSF7/{grtrib}/{seq}

Ajusta margem da linha 001.

grtrib / seq

ICMS-SP / 001

F7_MARGEM

45.00

excluir

DELETE /WsSF7/{grtrib}/{seq}

Sem body.

grtrib / seq

ICMS-SP / 001

consulta-grupo

GET /WsSF7/{grtrib}

Todas as linhas do grupo ICMS-SP.

grtrib

ICMS-SP

consulta-byid

GET /WsSF7/_byid/{recno}

Linha pelo recno físico.

recno

1234

typeahead

GET /WsSF7/_search

Grupos começando em "ICMS", limite 5.

term / limit

ICMS / 5

Pendências conhecidas (rev2)

VLR_* campos numéricos. F7_VLR_ICM, F7_VLR_IPI, F7_VLR_PIS, F7_VLR_COF, F7_VLRICMP são valores absolutos por nota — confirmar se MATA540 aceita via payload nesta base antes de usar.

Smoke test E2E pendente. Validação depende de grupo tributário de referência no ambiente. Confirmar F7_GRTRIB existente via GET antes do primeiro POST.