rev4-2026-05-14 Protheus 12.1.33

ClasseValor

CRUD de Classe de Valor (tabela CTH) via MsExecAuto da rotina CTBA060. A chave externa é CTH_CLVL — alfanumérico de até 9 posições, fornecido pelo cliente no path da rota (não há geração automática por GetSXENum). Datas no payload sempre em ISO YYYY-MM-DD.

Vinculação com o ERP

Tabela mestre CTH Classe de Valor (contábil)

Rotina automática CTBA060 MsExecAuto · Contabilidade

Wrapper AdvPL U_CT060Exc src/lib/CTB/CT060EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro

Classe pai (hierarquia)

campo CTH_CLVLPA referencia outra CTH existente
obrigatório quando CTH_CLASSE="2" (Analítica) sob hierarquia

Vigência

Janela DTEXIS / DTEXSF

CTH_DTEXIS / CTH_DTEXSF · Date
CTBA060 exige DTEXIS <= DTEXSF e janela cobrindo a database

Dicionário

Campos opcionais CTH_MSUID / CTH_MSUIDT

detectados em runtime por U_RestCamposOpc
retornados em recno/msuid/msuidt só se existirem no SX3

Convenções

Identificador externo. Todas as rotas /WsClasseValor/{clvl} usam CTH_CLVL como chave — alfanumérico de até 9 caracteres, fornecido pelo cliente. Diferente de cadastros com numeração automática (SA1/SA2/SC7), aqui não há GetSXENum: cabe ao chamador escolher o código. Após gravar, a chave interna técnica (recno / msuid) pode ser recuperada via /_byid.

Sintética vs Analítica. CTH_CLASSE distingue o nível na hierarquia contábil — "1" = Sintética (totalizador, aceita classes filhas em CTH_CLVLPA), "2" = Analítica (folha, recebe lançamentos). Validação detalhada é responsabilidade do MsExecAuto do CTBA060; este endpoint apenas repassa o payload.

Natureza do saldo. CTH_NORMAL indica a natureza esperada do saldo da classe — "D" = Débito, "C" = Crédito. Veja a tabela de domínios no schema ClasseValorPayload.

Datas de existência. CTH_DTEXIS e CTH_DTEXSF trafegam como string ISO YYYY-MM-DD (entrada e saída). Internamente o endpoint converte para Date via sToD(StrTran(…,"-","")). Valor vazio ("") limpa o campo. O CTBA060 aceita janelas amplas (ex. 1980-01-01 → 2029-12-31); janelas com DTEXSF < DTEXIS ou cobertura nula da database são rejeitadas com 422.

Paginação e delta-sync. /_list usa page/pageSize (default 50, máx 500). Para sincronização incremental, alterne para orderBy=recno e use since/cursor conforme o nextCursor retornado. O parâmetro desc aceita prefixo normalizado (sem acento, uppercase).

Bloqueio TOTVS. CTH_BLOQ existe como flag de bloqueio editorial ("1" = Bloqueado, "2" = Desbloqueado), mas não segue o par MSBLQL/MSBLQD do padrão TOTVS-moderno — não há data de vigência nem caminho de desbloqueio especial. O PUT aceita CTH_BLOQ como qualquer outro campo do whitelist.

ClasseValor

CRUD por código CTH_CLVL

GET /WsClasseValor/{clvl} Consulta classe por código

Descrição

Retorna a Classe de Valor pesquisada pelo código. Aplica filtro de filial (xFilial("CTH")) e respeita o whitelist de CAMPOS_GET definido no .prw. O parâmetro opcional fields reduz o conjunto de campos retornados.

Path parameter

clvl string · path · obrigatório CTH.CTH_CLVL

Código da Classe de Valor. Alfanumérico, até 9 caracteres, sem espaços.

Query parameters

fields string · query · opcional

Lista de campos separados por vírgula. Validados contra CAMPOS_GET.

Cenarios

Exemplo da requisicao (cenario ativo)

Consulta direta — sem fields; retorna whitelist completo de CAMPOS_GET.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsClasseValor/ZTEST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Consulta com fields — reduz o payload de retorno via fields=.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsClasseValor/ZTEST?fields=CTH_CLVL,CTH_DESC01,CTH_BLOQ
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Classe encontrada. Envelope { success: true, data: ClasseValor }.

400

Parâmetro clvl vazio ou inválido. Tier: validation-error.

404

Classe inexistente para o código informado. Tier: not-found.

500

Erro interno (DbSeek, serialização). Tier: business-error.

POST /WsClasseValor/{clvl} Inclui nova classe

Descrição

Inclui uma Classe de Valor via CTBA060 em modo 3 (MODEL_OPERATION_INSERT). A chave externa CTH_CLVL vem do path — não há geração automática; se já existir, o endpoint retorna 409.

Whitelist de campos: ver ClasseValorPayload.
Sem dependências de localização (diferente de SA1/CRMA980BRA).

Path parameter

clvl string · path · obrigatório CTH.CTH_CLVL

Código da Classe a criar (até 9 caracteres, sem espaços).

Request body

application/json ClasseValorPayload · obrigatório

Payload plano com campos do whitelist CAMPOS_ALLOW. Schema completo em ClasseValorPayload.

Classe Analítica (folha) — corresponde à fixture fixtures/post-cth-test.json.

RequestHTTP/1.1 · application/json

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

{
  "CTH_DESC01": "CLASSE VALOR ZTEST",
  "CTH_CLASSE": "2",
  "CTH_NORMAL": "D",
  "CTH_BLOQ": "2",
  "CTH_DTEXIS": "1980-01-01",
  "CTH_DTEXSF": "2029-12-31",
  "CTH_CLVLPA": ""
}

Classe Sintética (totalizadora) — agrupa classes analíticas filhas via CTH_CLVLPA dessas. Usada como "pai" na hierarquia.

RequestHTTP/1.1 · application/json

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

{
  "CTH_DESC01": "CLASSE VALOR ZTEST PAI",
  "CTH_CLASSE": "1",
  "CTH_NORMAL": "D",
  "CTH_BLOQ": "2",
  "CTH_DTEXIS": "1980-01-01",
  "CTH_DTEXSF": "2029-12-31"
}

Respostas

201

Classe incluída. Envelope CrudResponse com data contendo a chave (CTH_CLVL).

400

Path inválido ou payload mal-formado. Tier: validation-error.

409

CTH_CLVL já existe. Tier: business-error.

422

Payload rejeitado pelo MsExecAuto do CTBA060 (campos fora do whitelist, enum inválido, janela de datas incoerente, classe pai inexistente). Tier: business-error.

500

Erro interno.

PUT /WsClasseValor/{clvl} Altera classe existente

Descrição

Altera campos da Classe via CTBA060 em modo 4 (MODEL_OPERATION_UPDATE). Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW. Diferente do padrão de bloqueio TOTVS-moderno (par MSBLQL/MSBLQD), não há caminho de desbloqueio especial — CTH_BLOQ é apenas mais um campo do payload.

Path parameter

clvl string · path · obrigatório CTH.CTH_CLVL

Código da Classe a alterar.

Request body

application/json ClasseValorPayload · obrigatório

Subconjunto do whitelist. Campos omitidos ficam inalterados.

Alteração mínima — apenas CTH_DESC01. Corresponde à fixture fixtures/put-cth-test.json.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsClasseValor/ZTEST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "CTH_DESC01": "CLASSE VALOR ZTEST ALTERADA",
  "CTH_BLOQ": "2"
}

Bloqueia classe — marca CTH_BLOQ="1". Diferente de SA1, não há data de vigência (não usa o par MSBLQL/MSBLQD).

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsClasseValor/ZTEST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "CTH_BLOQ": "1"
}

Encerra vigência — antecipa CTH_DTEXSF para uma data passada, sinalizando que a classe não vale mais para novos lançamentos a partir de então.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsClasseValor/ZTEST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "CTH_DTEXSF": "2025-12-31"
}

Respostas

200

Classe alterada. Envelope CrudResponse.

400

Path/payload inválido. Tier: validation-error.

404

Classe inexistente. Tier: not-found.

422

Validação de payload (whitelist, enum, janela de datas, classe pai). Tier: business-error.

500

Erro interno.

DEL /WsClasseValor/{clvl} Exclui classe

Descrição

Exclui a Classe de Valor via CTBA060 em modo 5 (MODEL_OPERATION_DELETE). O MsExecAuto rejeita exclusão de classes referenciadas em lançamentos contábeis ou que tenham classes filhas pendentes (CTH_CLVLPA apontando para esta).

Path parameter

clvl string · path · obrigatório CTH.CTH_CLVL

Código da Classe a excluir.

Cenario

Exemplo da requisicao (cenario ativo)

Exclusao direta — chama CTBA060 op=5. Falha 422 se houver lancamento contabil vinculado ou classes filhas.

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsClasseValor/ZTEST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Classe excluída. Envelope CrudResponse.

400

Path inválido. Tier: validation-error.

404

Classe inexistente. Tier: not-found.

422

Classe referenciada em lançamentos ou possui classes filhas. Tier: business-error.

500

Erro interno.

GET /WsClasseValor/_byid Consulta classe por id técnico (recno|msuid)

Descrição

Busca a classe por id técnico — útil para integrações que persistem recno ou msuid e querem reconfirmar o registro sem reusar o código alfanumérico.

Query parameters

tipo string · query · obrigatório

Indica qual id técnico está sendo usado.

recnomsuid

valor string · query · obrigatório

Valor do id (inteiro quando tipo=recno, string quando tipo=msuid).

fields string · query · opcional

Lista de campos validados contra CAMPOS_GET.

Cenarios

Exemplo da requisicao (cenario ativo)

Por RecNo — caminho recomendado nesta base.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsClasseValor/_byid?tipo=recno&valor=1234
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Por MSUID — pode retornar 501 nesta base se CTH nao expor CTH_MSUID no SX3. Ver Pendencias.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsClasseValor/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Classe encontrada. Envelope { success: true, data: ClasseValor }.

400

Parâmetros tipo/valor ausentes ou tipo fora do enum.

404

Classe não localizada. Tier: not-found.

501

Busca por msuid requer CTH_MSUID no dicionário (campo opcional).

500

Erro interno.

Listagem

Listagem paginada com filtros e delta-sync

GET /WsClasseValor/_list Lista classes com filtros e paginação

Descrição

Lista classes com filtros opcionais por cod (prefixo de CTH_CLVL) ou desc (prefixo de CTH_DESC01 normalizado, sem acento). Suporta dois modos:

orderBy=chave (default) — paginação por page/pageSize; aceita since inline.
orderBy=recno — delta-sync por cursor, retorna nextCursor.

Query parameters

cod string · query · opcional CTH.CTH_CLVL

Prefixo de CTH_CLVL.

desc string · query · opcional CTH.CTH_DESC01

Prefixo normalizado de CTH_DESC01 (uppercase, sem acento).

fields string · query · opcional

Lista de campos validados contra CAMPOS_GET.

page integer · query · opcional

Página (default 1, mínimo 1).

pageSize integer · query · opcional

Tamanho da página (default 50, máx 500).

orderBy string · query · opcional

Modo de ordenação. Default chave.

chaverecno

since integer · query · opcional

Filtro inline RecNo >= since em orderBy=chave.

cursor integer · query · opcional

Ponto de partida RecNo > cursor em orderBy=recno.

Cenarios

Exemplo da requisicao (cenario ativo)

Paginacao por chave — modo default orderBy=chave com page/pageSize.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsClasseValor/_list?desc=RECEITA&page=1&pageSize=50
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Delta-sync por RecNo — sincronizacao incremental; cliente itera via nextCursor ate vazio.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsClasseValor/_list?orderBy=recno&cursor=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de classes. Envelope com data (array de ClasseValor), page, pageSize, count, opcionalmente nextCursor.

400

Parâmetro fora do domínio (ex: orderBy inválido, pageSize > 500).

500

Erro interno.

Schemas

Definições canônicas — campos com origem SX3 rastreável

ClasseValor

object

Representação retornada nos GETs (/{clvl}, /_list, /_byid). Inclui chave externa (CTH_CLVL) e os campos cadastrais do CTBA060. Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields. Os identificadores técnicos (recno/msuid/msuidt) aparecem apenas quando o dicionário contém os campos opcionais CTH_MSUID/CTH_MSUIDT.

CTH_CLVLstring · opcionalCTH.CTH_CLVL

Código da Classe (chave externa, até 9 caracteres).

CTH_DESC01string · opcionalCTH.CTH_DESC01

Descrição da classe.

CTH_CLASSEstring · opcionalCTH.CTH_CLASSE

Nível na hierarquia: "1" = Sintética (totalizador), "2" = Analítica (folha).

12

CTH_NORMALstring · opcionalCTH.CTH_NORMAL

Natureza esperada do saldo: "D" = Débito, "C" = Crédito.

DC

CTH_BLOQstring · opcionalCTH.CTH_BLOQ

Flag de bloqueio: "1" = Bloqueado, "2" = Desbloqueado.

12

CTH_CLVLPAstring · opcionalCTH.CTH_CLVLPA

Código da classe pai na hierarquia. Vazio para raiz.

CTH_DTEXISstring (date) · opcionalCTH.CTH_DTEXIS

Data inicial de existência (ISO YYYY-MM-DD).

CTH_DTEXSFstring (date) · opcionalCTH.CTH_DTEXSF

Data final de existência (ISO YYYY-MM-DD).

recnointeger · opcional

Id técnico do registro (RecNo do AdvPL).

msuidstring · opcional

Identificador universal MS_UID (presente só se CTH_MSUID existir no SX3).

msuidtstring · opcional

Timestamp técnico associado ao msuid.

ClasseValorPayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW no .prw. Em PUT, campos omitidos ficam inalterados. CTH_CLVL não aparece aqui — vem sempre do path da URL.

CTH_DESC01string · opcionalCTH.CTH_DESC01

Descrição da classe.

CTH_CLASSEstring · opcionalCTH.CTH_CLASSE

Nível na hierarquia: Sintética ("1") agrupa filhas; Analítica ("2") recebe lançamentos.

12

CTH_NORMALstring · opcionalCTH.CTH_NORMAL

Natureza do saldo: Débito ("D") ou Crédito ("C").

DC

CTH_BLOQstring · opcionalCTH.CTH_BLOQ

Flag de bloqueio editorial: "1"=Bloqueado, "2"=Desbloqueado. Não usa par MSBLQL/MSBLQD.

12

CTH_CLVLPAstring · opcionalCTH.CTH_CLVLPA

Classe pai na hierarquia. Deve apontar para outra CTH existente; vazio = raiz.

CTH_DTEXISstring (date) · opcionalCTH.CTH_DTEXIS

Data inicial de existência (ISO YYYY-MM-DD). Vazio limpa a data.

CTH_DTEXSFstring (date) · opcionalCTH.CTH_DTEXSF

Data final de existência (ISO YYYY-MM-DD). Deve ser >= CTH_DTEXIS.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz a chave externa gravada (POST) ou um objeto auxiliar / string vazia (PUT/DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring | object · opcional

Em POST, contém a chave gravada (CTH_CLVL). Em PUT/DELETE pode ser string vazia ou objeto auxiliar.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog do CTBA060) para tratamento programático, quando aplicável.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro (apresentável ao usuário final).

datastring · opcional

Token interno / detalhe técnico (ex: log do MsExecAuto).

Cenarios

Combinacoes documentadas (1 por example do openapi.yaml)

consulta-direta

GET /WsClasseValor/{clvl}

Consulta direta por CTH_CLVL. Resposta inclui o whitelist completo de CAMPOS_GET.

consulta-com-fields

GET /WsClasseValor/{clvl}?fields=...

Reduz payload de retorno; util em integracoes mobile.

payload-minimo-analitica

POST /WsClasseValor/INCLUIR/{clvl}

Inclusao minima de classe analitica (CTH_CLASSE="2"): somente CTH_DESC01, CTH_CLASSE, CTH_BLOQ. Sem vigencia, sem hierarquia. Tier happy-path-minimal.

payload-com-vigencia

POST /WsClasseValor/INCLUIR/{clvl}

Inclusao com vigencia explicita (CTH_DTEXIS/CTH_DTEXSF) e demais campos do whitelist. Espelha fixture canonica de smoke. Tier happy-path-realistic.

alterar-descricao

PUT /WsClasseValor/ALTERAR/{clvl}

Atualiza somente CTH_DESC01; demais campos preservados.

alterar-bloqueio

PUT /WsClasseValor/ALTERAR/{clvl}

Toggle de CTH_BLOQ; sem caminho privilegiado (CTH nao tem par MSBLQL/MSBLQD).

alterar-vigencia

PUT /WsClasseValor/ALTERAR/{clvl}

Atualiza vigencia (CTH_DTEXSF) — caminho usual para encerrar classe antes da data original.

delete-direto

DELETE /WsClasseValor/EXCLUIR/{clvl}

Exclusao via CTBA060 op=5. Falha 422 se classe tiver lancamentos vinculados.

byid-recno

GET /WsClasseValor/_byid?tipo=recno&valor=...

Lookup por recno da CTH — caminho recomendado e funcional.

byid-msuid

GET /WsClasseValor/_byid?tipo=msuid&valor=...

Lookup por identificador universal — retorna 501 caso CTH nao exponha CTH_MSUID no SX3 desta base.

listagem-paginada

GET /WsClasseValor/_list?page=...&pageSize=...

Paginacao classica com page/pageSize em orderBy=chave. Combinavel com filtros cod/desc. Default 50, maximo 500.

delta-sync

GET /WsClasseValor/_list?orderBy=recno&cursor=...

Sincronizacao incremental por recno; cliente itera via nextCursor ate vazio.

Pendências conhecidas (rev3)

GET _byid?tipo=msuid pode retornar 501. A tabela CTH desta base pode nao expor CTH_MSUID/CTH_MSUIDT no SX3 — o caminho msuid responde 501. Workaround: usar tipo=recno.

Bloqueio TOTVS-padrao nao implementado. O wrapper U_CT060Exc ainda nao chama U_C980Blq("CTH"); PUT em registro bloqueado nao e barrado por regra externa. Padrao MSBLQL/MSBLQD nao se aplica (campo unico CTH_BLOQ).

Sem _search. Nao ha endpoint de sugestao por similaridade. Cliente que precisa autocomplete usa /_list?desc=<prefixo> com pageSize=10.

Hierarquia CLVLPA nao validada. O campo CTH_CLVLPA (classe pai) e gravado como recebido; nao ha DbSeek para confirmar que o codigo existe no plano de classes.