rev1-2026-05-16

BonificacaoFinanceira

CRUD de Bonificação Financeira (cabeçalho AI1 + itens AI2) via wrapper FATA180. Cabeçalho define vigência e tipo da bonificação; itens listam produtos beneficiados com o valor bonificado.

Código auto-gerado. AI1_CODBNF é gerado por GetSXENum no POST — o endpoint retorna o código gerado em data.AI1_CODBNF. {codigo} no path do POST é placeholder (qualquer valor).

Vinculação com o ERP

CabeçalhoAI1Bonificação Financeira

ItensAI2Produtos da bonificação

Rotina automáticaFATA180MsExecAuto · op 3/4/5

Wrapper AdvPLU_FT180Excsrc/lib/MAT/FT180EXC.prw

Fonte RESTWsAI1.prwsrc/api/BonificacaoFinanceira/

ChaveAI1_CODBNFGetSXENum no POST

Dependências

Cadastro

Produto (SB1)

AI2_CODPRO validado contra SB1 pelo FATA180.

Cadastro

Moeda (SM2)

AI1_MOEDA opcional; default da empresa.

Tabela

Tipo de hora (SX5 da empresa)

AI1_TPHORA + AI1_HORADE/AI1_HORATE definem janela horária da regra.

Convenções

Envelope canônico. { success, message, data }. POST retorna data.AI1_CODBNF auto-gerado.

Datas em ISO. AI1_DATDE/AI1_DATATE aceitam YYYY-MM-DD ou AAAAMMDD.

Whitelist. Cabeçalho: AI1_DESCRI, AI1_CODCLI, AI1_LOJA, AI1_DATDE, AI1_DATATE. Itens: AI2_CODPRO, AI2_VALORC, AI2_VALORB.

Sem typeahead. Endpoint expõe só _list + GET por código.

Bonificação Financeira — mutação

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

POST/WsAI1/INCLUIR/000001Inclui regra — FATA180 op=3

Descrição

Inclui bonificação financeira. Código AI1_CODBNF é gerado pelo GetSXENum — path é placeholder.

Cenário

Request body

cabecalho.AI1_DESCRIstring · obrigatório

Descrição da regra.

cabecalho.AI1_DATDEstring (date) · obrigatório

Data inicial.

cabecalho.AI1_DATATEstring (date) · obrigatório

Data final.

itens[].AI2_CODPROstring · obrigatório p/ item

Produto (SB1).

itens[].AI2_VALORBnumber · obrigatório p/ item

valor bonificado.

Período só. Regra geral aplicada a todos os produtos.

Request

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

{
  "cabecalho": {
    "AI1_DESCRI": "Bonif. Cliente Premium",
    "AI1_DATDE": "2026-11-24",
    "AI1_DATATE": "2026-11-30"
  }
}

Com produtos. 2 produtos com 15% e 20%.

Request

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

{
  "cabecalho": {
    "AI1_DESCRI": "Bonif. Cliente PJ",
    "AI1_DATDE": "2026-11-24",
    "AI1_DATATE": "2026-11-30"
  },
  "itens": [
    { "AI2_CODPRO": "000001", "AI2_VALORB": 15.0 },
    { "AI2_CODPRO": "000001", "AI2_VALORB": 20.0 }
  ]
}

Respostas

201

Criado. data.AI1_CODBNF auto-gerado.

400

Payload inválido.

422

Erro FATA180 (produto inválido, datas, sobreposição).

PUT/WsAI1/ALTERAR/000001Altera regra — FATA180 op=4

Descrição

Altera regra existente. Cabeçalho e itens opcionais. Itens via LINPOS + AUTDELETA como em PedidoVenda.

Cenário

Request body

cabecalho.AI1_DATATEstring (date) · opcional

Nova data final.

cabecalho.AI1_DESCRIstring · opcional

Nova descrição.

Estender data final.

Request

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

{
  "cabecalho": {
    "AI1_DATATE": "2026-12-05"
  }
}

Respostas

200

Alterado.

404

Não encontrada.

422

Erro FATA180.

DELETE/WsAI1/EXCLUIR/000001Exclui regra — FATA180 op=5

Descrição

Exclui regra. Sem body.

Cenário

Exemplo

Request

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

Respostas

200

Excluída.

404

Não encontrada.

Consulta

Por código + listagem (sem typeahead).

GET/WsAI1/000001Regra por código

Cenário

Exemplo

Request

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

Response 200

{
  "success": true,
  "data": {
    "cabecalho": {
      "AI1_CODBNF": "000001",
      "AI1_DESCRI": "Bonif. Cliente Premium",
      "AI1_DATDE": "20261124",
      "AI1_DATATE": "20261130"
    },
    "itens": [
      { "AI2_ITEM": "01", "AI2_CODPRO": "000001", "AI2_VALORB": 15.0 }
    ]
  }
}

GET/WsAI1/_listListagem paginada

Query parameters

page, pageSizeinteger

Paginação (default 1/50, max 500).

Cenário

Exemplo

Request

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

Schemas

Componentes do contrato

BonificacaoFinanceiraPayload

object

Cabeçalho + array de itens.

cabecalhoCabecalho

Ver Cabecalho.

itensarray[Item]

Ver Item.

Cabecalho

object · AI1

Cabeçalho. Whitelist CAMPOS_CAB_ALLOW.

AI1_DESCRIstringAI1.AI1_DESCRI

Descrição.

AI1_TIPOstringAI1.AI1_TIPO

Tipo de regra.

AI1_TIPDESstringAI1.AI1_TIPDES

Tipo de bonificação (% ou valor).

AI1_MOEDAstringAI1.AI1_MOEDA

Moeda (SM2).

AI1_DATDE, AI1_DATATEstring (date)

Vigência.

AI1_TPHORA, AI1_HORADE, AI1_HORATEstring

Janela horária da regra.

Item

object · AI2

Produto beneficiado.

AI2_CODPROstring · obrigatório

Produto (SB1).

AI2_VALORBnumber · obrigatório

valor bonificado.

EnvelopeSucesso

object

Envelope canônico.

success/message/data

Padrão.

EnvelopeErro

object

success=false + message.

message

Causa.

Cenários

1-pra-1 com YAML.

incluir-periodo

POST /WsAI1/INCLUIR/{codigo}

Regra geral só com vigência.

cabecalho.{DESCRI,DATDE,DATATE}

Sem produtos = aplicável a todos.

incluir-com-produtos

POST /WsAI1/INCLUIR/{codigo}

Vigência + 2 produtos com %.

itens[]

2 itens (000001 15%, 000001 20%).

alterar

PUT /WsAI1/ALTERAR/{codigo}

Estende AI1_DATATE.

cabecalho.AI1_DATATE

Nova data fim.

excluir

DELETE /WsAI1/EXCLUIR/{codigo}

Sem body.

path.codigo

000001

consulta-byid

GET /WsAI1/{codigo}

Cabeçalho + itens.

path.codigo

000001

listagem

GET /WsAI1/_list

Primeira página.

page, pageSize

1, 25

Pendências conhecidas (rev2)

Sem typeahead. Não há GET /_search. Filtros via /_list com page/pageSize.

AI1_CODBNF auto-gerado. Path no POST é placeholder; código real vem do GetSXENum e retorna em data.AI1_CODBNF.