rev1-2026-05-16 Protheus 12.1.33

ApropriacaoNaoCotas

Execução batch da rotina FINA182 (Apropriação Não Cotas) via REST. Endpoint Tier 3 — verbo no path com prefixo underscore: /_apropriar (FINA182 nOper=3). POST único, sem GET — a rotina é batch e não expõe state público; o efeito colateral (apropriações geradas) é contabilizado nas tabelas auxiliares CTK/CTJ e deve ser verificado via relatórios padrão Protheus.

Modo blind. O wrapper usa MsExecAuto com isBlind()=.T. — a rotina FINA182 não abre tela. Sucesso significa que o MsExecAuto retornou sem lMsErroAuto=.T.; pode retornar success=true mesmo se a base não tinha dados a apropriar (operação idempotente).

Bloqueio TOTVS: endpoint de processo; não manipula MSBLQL. Bloqueio aplicável recai sobre as próprias tabelas contábeis (CTK/CTJ), avaliado pelo FINA182.

Vinculação com o ERP

Módulo SIGAFIN Financeiro · Apropriação Não Cotas

Tabela mestre — batch · sem state público; resultado em CTK/CTJ

Rotina automática FINA182 MsExecAuto · modo blind

Wrapper AdvPL U_FN182Exc src/lib/FIN/FN182EXC.prw

Operações & modos

POST /_apropriar op 3 — Apropriar (única operação)

Dependências de ambiente

Tabelas alvo

Auxiliares contábeis (CTK/CTJ)

o efeito colateral da apropriação é gravado nessas tabelas
verificação pós-execução via relatórios padrão Protheus

Parâmetros (MV_PARxx)

FINA182 espera 3 parâmetros

MV_PAR01 = data de referência (Date; default dDataBase)
MV_PAR02 = recalcular (1=Sim default, 2=Não)
MV_PAR03 = mostrar lançamento (1=Sim, 2=Não default)

Wrapper

U_FN182Exc

src/lib/FIN/FN182EXC.prw · closure de 2 parâmetros
segundo argumento literal .T. ativa isBlind(); retorna {lOk, cMsg}

Build

Protheus 240223P+

build mínimo validado: 240223P; padrão herdado do WsBaixaPagar
thread REST: oWsSelf capturado antes de Begin Sequence;
uso de ::SetStatus após MsExecAuto (Self pode invalidar)

Convenções

Operação batch sem state público. A rotina FINA182 é processo contábil — não tem cadastro a consultar nem entidade a expor. O endpoint provê apenas a execução; o resultado vai para CTK/CTJ e deve ser consultado por relatórios padrão ou ferramentas de inspeção contábil.

Verbo no path (Tier 3). Apenas uma ação aceita: /_apropriar (FINA182 nOper=3). Qualquer outro segmento retorna 400 com mensagem "Verbo invalido. Use POST /WsApropNCotas/_apropriar."

Body opcional. Todos os campos têm defaults seguros — pode-se enviar payload vazio {}: data assume dDataBase, recalcular=true, mostrarLancamento=false. O body em si é obrigatório (não pode ser vazio ou ausente; 400 caso contrário).

Alias data / dataRef. Os dois nomes apontam para o mesmo MV_PAR01. O endpoint procura dataRef primeiro; se vazio, cai para data; se ambos vazios, usa dDataBase.

Formato de data. data aceita string ISO YYYY-MM-DD. Conversão interna usa SToD(StrTran(cString, "-", "")); ou seja "2026-05-16" vira SToD("20260516").

Mapeamento boolean → MV_PARxx. Os booleans recalcular e mostrarLancamento são convertidos para 1 (Sim) ou 2 (Não) via If(lValor, 1, 2). Default seguro: recalcular=true e mostrarLancamento=false.

Idempotência. Quando recalcular=true (default), a apropriação é idempotente — pode rodar várias vezes para a mesma data sem duplicar efeito. O smoke test não precisa cleanup.

Status HTTP. 200 em sucesso (mesmo se base não tiver dados a apropriar); 400 verbo inválido / body ausente / JSON malformado; 422 FINA182 rejeitou (vide message); 500 exceção não tratada.

Apropriação Não Cotas (FINA182)

Execução batch da FINA182 em modo blind — Tier 3 (verbo no path)

POST /WsApropNCotas/_apropriar Executa apropriação não cotas (FINA182 nOper=3)

Descrição

Dispara FINA182 em modo blind via U_FN182Exc(aArray, 3). Mapeia os 3 campos do body para os parâmetros MV_PAR01..03 da rotina e devolve 200 com eco dos parâmetros aplicados, ou 422 com a mensagem de erro do MsExecAuto.

Status HTTP.

200 — apropriação executada (mesmo se ambiente sem dados a apropriar).
400 — verbo inválido, body ausente ou JSON malformado.
422 — FINA182 rejeitou a execução.
500 — exceção não tratada.

Cenário

Ambos cenários usam o mesmo schema (ApropriacaoRequest) — varia apenas se a data é informada ou herdada do dDataBase.

Request body

application/json ApropriacaoRequest · obrigatório

Parâmetros da apropriação. Body em si obrigatório; conteúdo pode ser {} (defaults seguros). Schema completo em ApropriacaoRequest.

data string (date) · opcional

Data de referência (YYYY-MM-DD). Default dDataBase. Alias: dataRef.

recalcular boolean · opcional

Recalcula apropriação existente? Default true → MV_PAR02=1.

mostrarLancamento boolean · opcional

Exibir lançamento contábil? Default false → MV_PAR03=2.

Exemplo da requisição (cenário ativo)

Apropriação com defaults — usa dDataBase e flags default. Forma mais comum em job batch noturno. Fixture: fixtures/apropriar.json.

RequestHTTP/1.1 · application/json

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

{
  "recalcular":        true,
  "mostrarLancamento": false
}

Apropriação numa data específica — aciona a apropriação retroativa ou prospectiva, informando a data alvo. Útil para reprocessamento pontual após acerto contábil.

RequestHTTP/1.1 · application/json

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

{
  "data":              "2026-05-16",
  "recalcular":        true,
  "mostrarLancamento": false
}

Respostas

200

Apropriação executada. Envelope RespostaSucesso com eco dos parâmetros aplicados.

400

Verbo inválido, body ausente ou JSON malformado.

422

FINA182 rejeitou a execução (vide message).

500

Exceção não tratada.

Exemplo de resposta

Response · 200 OKapplication/json

{
  "success": true,
  "message": "Apropriacao executada com sucesso.",
  "data": {
    "dataRef":           "20260516",
    "recalcular":        true,
    "mostrarLancamento": false
  }
}

Schemas

Definições canônicas — parâmetros MV_PARxx da rotina FINA182

ApropriacaoRequest

object

Parâmetros da execução da FINA182. Todos os campos são opcionais — defaults seguros aplicados pelo endpoint.

datastring (date) · opcionalMV_PAR01 · Date

Data de referência ISO YYYY-MM-DD. Default dDataBase.

dataRefstring (date) · opcionalMV_PAR01 · Date

Alias de data; quando ambos vêm, dataRef prevalece.

recalcularboolean · opcionalMV_PAR02 · 1=Sim 2=Não

Recalcula apropriação existente. Default true → 1.

mostrarLancamentoboolean · opcionalMV_PAR03 · 1=Sim 2=Não

Exibe lançamento contábil. Default false → 2.

RespostaSucesso

object · envelope

Envelope da resposta 200. data traz eco dos parâmetros aplicados (formato AAAAMMDD para a data) — útil para o consumidor confirmar qual data foi usada quando o body veio vazio.

successboolean · const: true

Sempre true em 200.

messagestring · obrigatório

Mensagem editorial do sucesso.

data.dataRefstring · obrigatório

Data efetivamente usada (AAAAMMDD).

data.recalcularboolean · obrigatório

Valor efetivo aplicado em MV_PAR02.

data.mostrarLancamentoboolean · obrigatório

Valor efetivo aplicado em MV_PAR03.

RespostaErro

object · envelope

Envelope das respostas 400 / 422 / 500.

successboolean · const: false

Sempre false em erro.

messagestring · obrigatório

Descrição editorial do erro.

datastring · opcional

Detalhe técnico opcional.

Cenários

Catálogo de combinações reconhecidas pela ação /_apropriar.

apropriar-padrao

POST /_apropriar

Execução com defaults seguros — sem informar data (assume dDataBase) e mantém recalcular=true / mostrarLancamento=false.

Quando usar: job batch agendado, acerto periódico, smoke test idempotente.
Pré-condições: nenhuma — operação segura mesmo se a base não tiver dados a apropriar (a rotina responde 200 sem efeito).
Resultado: 200 OK com eco dos parâmetros aplicados.

recalcularboolean · opcionalMV_PAR02

Default true.

mostrarLancamentoboolean · opcionalMV_PAR03

Default false.

apropriar-data-especifica

POST /_apropriar

Apropriação para uma data customizada, diferente da dDataBase do AppServer.

Quando usar: reprocessamento retroativo após acerto contábil; apropriação prospectiva para fechamento futuro.
Pré-condições: data informada deve estar dentro do exercício contábil aberto.
Resultado: 200 OK com dataRef ecoando o valor utilizado.

datastring (date) · obrigatório (no cenário)MV_PAR01

Data ISO YYYY-MM-DD.

recalcularboolean · opcionalMV_PAR02

Default true.

mostrarLancamentoboolean · opcionalMV_PAR03

Default false.

Pendências conhecidas (rev1)

Sucesso não implica efeito. O endpoint responde 200 quando o MsExecAuto retorna sem lMsErroAuto=.T.. Isso inclui o caso em que a base não tem dados a apropriar — a rotina executa silenciosamente sem gravar nada. Não há, hoje, como saber pela resposta REST quantas linhas foram criadas em CTK/CTJ. Evolução: retornar data.linhasGravadas via consulta posterior na CTK por data/filial.

Sem GET de inspeção. A rotina não expõe state público — não há endpoint para listar apropriações existentes nem desfazer uma rodada. Verificação manual via relatórios padrão Protheus ou consulta direta nas tabelas CTK/CTJ. Avaliar GET _status?data=YYYY-MM-DD em revisão futura.

Smoke test pode reportar WARN em ambiente vazio. O test-apropriacao-nao-cotas.sh passa em ambientes sem dados a apropriar (a resposta ainda é 200 com success=true), mas o efeito esperado não pode ser observado. Idealmente, criar fixture mínima em CN9/CNE (contrato + medição) antes do smoke, em sessão dedicada de fixture-builder.

Sem distinção de filial cruzada. A FINA182 opera sobre a filial implícita do AppServer (cFilAnt); o endpoint não aceita um parâmetro de filial alvo. Para processar várias filiais, chamar o endpoint N vezes apontando para URLs /api/{empresa}/{filial} distintas.