rev4-2026-05-14 Protheus 12.1.33

ItemContabil

CRUD de item contábil (tabela CTD) via MsExecAuto da rotina automática CTBA040. A chave natural é CTD_ITEM (alfanumérico, fornecido pelo cliente no path, até 9 caracteres) — esta tabela não usa GetSXENum. Datas de vigência (CTD_DTEXIS/CTD_DTEXSF) trafegam em ISO YYYY-MM-DD. O campo CTD_CCSUP é aceito no payload (relacionamento livre com centro de custo superior).

Vinculação com o ERP

Tabela mestre CTD Cadastro de itens contábeis

Rotina automática CTBA040 MsExecAuto · rotina automática

Wrapper AdvPL U_CT040Exc src/lib/CTB/CT040EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro

Bloqueio CTD (não TOTVS-padrão)

tabela CTD · campo CTD_BLOQ
"1"=Bloqueado, "2"=Desbloqueado (sem par MSBLQL/MSBLQD)

Vínculo opcional

Centro de custo superior

campo CTD_CCSUP aceito no payload
uso típico: agrupar itens contábeis sob um CC pai

Chave natural

CTD_ITEM fornecido pelo cliente

alfanumérico, até 9 caracteres · sem GetSXENum
uniqueness validada por DbSeek antes do MsExecAuto

Convenções

Paths verb-based para CRUD mutável. Por herança do padrão TOTVS para Item Contábil, as rotas de inclusão, alteração e exclusão usam segmento verbal explícito: /INCLUIR/{item}, /ALTERAR/{item}, /EXCLUIR/{item}. Já o GET segue REST puro (/{item}, /_list, /_byid).

Persistência via MsExecAuto. Diferente de endpoints com base em FwLoadModel, o WSCTD chama o wrapper U_CT040Exc, que monta o array aCampos e dispara CTBA040 sob MsExecAuto. Erros do modelo viram 422 com a mensagem original do NomeAutoLog repassada em data.

Bloqueio simples via CTD_BLOQ. Diferente dos cadastros mestre/loja (SA1/SA2/SB1), esta tabela não usa o par TOTVS-padrão MSBLQL/MSBLQD. O bloqueio é um único campo: "1"=Bloqueado, "2"=Desbloqueado. Não há "caminho de desbloqueio" privilegiado — qualquer PUT pode alterar o flag junto com outros campos.

Formato de datas. CTD_DTEXIS e CTD_DTEXSF no payload aceitam string ISO YYYY-MM-DD; string vazia é equivalente a "sem data". Conversão interna usa sToD(StrTran(…, "-", "")).

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.

ItemContabil

CRUD por código do item (CTD_ITEM)

GET /WsItemContabil/{item} Consulta item contábil por código

Descrição

Retorna a item contábil identificada por CTD_ITEM. Aplica filtro de filial (xFilial("CTD")) e respeita o whitelist de CAMPOS_GET definido no .prw. O parâmetro opcional fields reduz o conjunto retornado.

Path parameter

item string · path · obrigatório CTD.CTD_ITEM

Código da item contábil. 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/WsItemContabil/000ZTEST
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/WsItemContabil/000ZTEST?fields=CTD_ITEM,CTD_DESC01,CTD_BLOQ
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Item encontrado. Envelope { success: true, data: ItemContabil }.

400

Parâmetro item vazio ou fields com campo fora do whitelist. Tier: validation-error.

404

Item inexistente. Tier: not-found.

500

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

POST /WsItemContabil/INCLUIR/{item} Inclui nova item contábil

Descrição

Inclui nova item contábil via CTBA040 em modo 3 (MODEL_OPERATION_INSERT). A chave CTD_ITEM é fornecida pelo cliente no path — esta tabela não usa GetSXENum.

Whitelist de campos: ver ItemContabilPayload.
Antes do MsExecAuto, faz DbSeek em CTD para detectar conflito de chave (retorna 409).

Path parameter

item string · path · obrigatório CTD.CTD_ITEM

Código alfanumérico do novo item. Até 9 caracteres.

Request body

application/json ItemContabilPayload · obrigatório

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

Payload completo — espelha a fixture canônica de smoke (item analítico com vigência longa e CCSUP). Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "CTD_DESC01": "ITEM CONTABIL ZTEST",
  "CTD_CLASSE": "2",
  "CTD_NORMAL": "0",
  "CTD_BLOQ": "2",
  "CTD_DTEXIS": "2011-01-01",
  "CTD_DTEXSF": "2029-12-31",
  "CTD_CCSUP": "000000000"
}

Com vínculo — exemplifica CTD_CCSUP apontando para um centro de custo agregador e vigência customizada.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsItemContabil/INCLUIR/000ZTST2
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "CTD_DESC01": "ITEM CONTABIL VIGENCIA",
  "CTD_CLASSE": "2",
  "CTD_NORMAL": "2",
  "CTD_BLOQ": "2",
  "CTD_CCSUP": "000000000",
  "CTD_DTEXIS": "2026-01-01",
  "CTD_DTEXSF": "2026-12-31"
}

Respostas

201

Item incluído. Envelope CrudResponse com data contendo o CTD_ITEM persistido.

400

item vazio ou payload inválido (JSON malformado, campo fora do whitelist). Tier: validation-error.

409

Item já existe para CTD_ITEM. Tier: business-error.

422

Regra de negócio do CTBA040 rejeitou (enum inválido, classe analítica sem hierarquia consistente, datas inconsistentes). Tier: business-error.

500

Erro interno (exceção fora do envelope NomeAutoLog).

PUT /WsItemContabil/ALTERAR/{item} Altera item contábil existente

Descrição

Altera campos do item via CTBA040 em modo 4 (MODEL_OPERATION_UPDATE). Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW; campos ausentes preservam o valor atual.

Bloqueio. CTD_BLOQ pode ser alterado livremente como qualquer outro campo — não há caminho de desbloqueio privilegiado como em SA1/SA2 (esta tabela não usa o par TOTVS MSBLQL/MSBLQD).

Path parameter

item string · path · obrigatório CTD.CTD_ITEM

Código do item existente.

Request body

application/json ItemContabilPayload · obrigatório

Subconjunto do whitelist. Não enviar CTD_CCSUP.

Alteração comum — atualiza descrição mantendo bloqueio em "Desbloqueado". Fixture: fixtures/put-update.json.

RequestHTTP/1.1 · application/json

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

{
  "CTD_DESC01": "ITEM CONTABIL ZTEST ALTERADO",
  "CTD_BLOQ": "2"
}

Bloquear item — marca CTD_BLOQ="1". O item permanece visível em GET/_list mas operações contábeis a recusam.

RequestHTTP/1.1 · application/json

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

{
  "CTD_BLOQ": "1"
}

Encerra vigência — fixa CTD_DTEXSF no passado. Combinável com bloqueio no mesmo payload.

RequestHTTP/1.1 · application/json

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

{
  "CTD_DTEXSF": "2025-12-31",
  "CTD_BLOQ": "1"
}

Respostas

200

Item alterado. Envelope CrudResponse.

400

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

404

Item inexistente. Tier: not-found.

422

Regra de negócio do CTBA040 rejeitou (enum, datas, hierarquia). Tier: business-error.

500

Erro interno (exceção fora do envelope NomeAutoLog).

DEL /WsItemContabil/EXCLUIR/{item} Exclui item contábil

Descrição

Exclui a item contábil via CTBA040 em modo 5 (MODEL_OPERATION_DELETE). O CTBA040 rejeita exclusão quando o item tem lançamentos contábeis vinculados ou é referenciado por outros registros do plano (movimentos, rateios, classificadores).

Path parameter

item string · path · obrigatório CTD.CTD_ITEM

Código do item a excluir.

Cenario

Exemplo da requisicao (cenario ativo)

Exclusao direta — chama CTBA040 op=5. Falha 422 se houver lancamento contabil vinculado.

RequestHTTP/1.1 · sem body

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

Respostas

200

Item excluído. Envelope CrudResponse.

400

Parâmetro item ausente. Tier: validation-error.

404

Item inexistente. Tier: not-found.

422

Item com lançamentos contábeis ou referenciada como superior. Tier: business-error.

500

Erro interno.

GET /WsItemContabil/_byid Consulta item por id técnico (recno|msuid)

Descrição

Busca a conta por id técnico — útil para integrações que persistem a chave interna (recno) ou o identificador universal (msuid) e querem reconfirmar o registro sem reconstruir o CTD_ITEM.

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; CTD nao expoe CTD_MSUID no SX3.

RequestHTTP/1.1 · sem body

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

Por MSUID — retorna 501 nesta base (CTD sem CTD_MSUID). Ver Pendencias.

RequestHTTP/1.1 · sem body

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

Respostas

200

Item encontrado. Envelope { success: true, data: ItemContabil }.

400

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

404

Item não localizado. Tier: not-found.

501

Busca por msuid requer CTD_MSUID no dicionário; ausente neste ambiente.

500

Erro interno.

Listagem

Listagem paginada e delta-sync

GET /WsItemContabil/_list Lista itens com filtros e paginação

Descrição

Lista itens com filtros por cod (prefixo de CTD_ITEM) ou desc (prefixo de CTD_DESC01 normalizado, sem acento). Suporta dois modos de ordenação:

orderBy=chave (default) — paginação por page/pageSize; since filtra RecNo >= since inline.
orderBy=recno — delta-sync; usa cursor e devolve nextCursor.

Query parameters

cod string · query · opcional CTD.CTD_ITEM

Prefixo de CTD_ITEM.

desc string · query · opcional CTD.CTD_DESC01

Prefixo de CTD_DESC01 normalizado (sem acento, uppercase).

fields string · query · opcional

Lista de campos validados contra CAMPOS_GET.

page integer · query · opcional

Página (default 1).

pageSize integer · query · opcional

Tamanho (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/WsItemContabil/_list?cod=1&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/WsItemContabil/_list?orderBy=recno&cursor=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de itens. Envelope com data (array de ItemContabil), orderBy, 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

ItemContabil

object

Representação retornada nos GETs (/{item}, /_list, /_byid). Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields.

CTD_ITEMstring · opcionalCTD.CTD_ITEM

Código do item (chave natural). Alfanumérico até 9 caracteres.

CTD_DESC01string · opcionalCTD.CTD_DESC01

Descrição principal do item.

CTD_CLASSEstring · opcionalCTD.CTD_CLASSE

Classe do item. "1"=Sintética, "2"=Analítica.

12

CTD_NORMALstring · opcionalCTD.CTD_NORMAL

Natureza. "0"=Nenhum, "1"=Receita, "2"=Despesa.

012

CTD_BLOQstring · opcionalCTD.CTD_BLOQ

Bloqueio simples. "1"=Bloqueado, "2"=Desbloqueado (sem par TOTVS MSBLQL/MSBLQD).

12

CTD_CCSUPstring · opcionalCTD.CTD_CCSUP

Centro de custo superior associado ao item. Aceito no payload de POST/PUT; retornado no GET quando presente.

CTD_CCLPstring · opcionalCTD.CTD_CCLP

Centro de custo de longo prazo / alternativo (LP).

recnointeger · opcional

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

msuidstring · opcional

Identificador universal MS_UID (presente apenas se CTD_MSUID existir no dicionário).

msuidtstring · opcional

Timestamp técnico associado ao msuid.

ItemContabilPayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW. CTD_CCSUP está propositadamente fora — enviar provoca 500 no CTBA040 da build 240223P.

CTD_DESC01string · opcionalCTD.CTD_DESC01

Descrição principal do item.

CTD_CLASSEstring · opcionalCTD.CTD_CLASSE

"1"=Sintética, "2"=Analítica.

12

CTD_NORMALstring · opcionalCTD.CTD_NORMAL

"0"=Nenhum, "1"=Receita, "2"=Despesa.

012

CTD_BLOQstring · opcionalCTD.CTD_BLOQ

"1"=Bloqueado, "2"=Desbloqueado. CTBA040 rejeita valores fora do domínio.

12

CTD_CCLPstring · opcionalCTD.CTD_CCLP

Grupo de vencimento.

CTD_DTEXISstring (date) · opcionalCTD.CTD_DTEXIS

Início de existência. ISO YYYY-MM-DD ou vazia.

CTD_DTEXSFstring (date) · opcionalCTD.CTD_DTEXSF

Fim de existência. ISO YYYY-MM-DD ou vazia.

CTD_CCSUPstring · opcionalCTD.CTD_CCSUP

Centro de custo superior. Aceito no payload.

CTD_CCPONstring · opcionalCTD.CTD_CCPON

Centro de custo ponderado.

CTD_BOOKstring · opcionalCTD.CTD_BOOK

Book contábil (multi-book).

CTD_RESstring · opcionalCTD.CTD_RES

Resultado / classificador adicional.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz o CTD_ITEM persistido em POST e string vazia ou objeto auxiliar em 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 o CTD_ITEM persistido. Em PUT/DELETE pode ser string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog em falhas do MsExecAuto) para tratamento programático.

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 /WsItemContabil/{item}

Consulta direta por CTD_ITEM sem filtro de campos. Resposta traz o whitelist completo de CAMPOS_GET.

consulta-com-fields

GET /WsItemContabil/{item}?fields=...

Reduz o payload de retorno a um subconjunto de CAMPOS_GET. Util em integracoes mobile/JIT.

payload-minimo-analitica

POST /WsItemContabil/INCLUIR/{item}

Inclusao minima de item analitico (CTD_CLASSE="2") — somente CTD_DESC01, CTD_CLASSE, CTD_NORMAL, CTD_BLOQ. Sem vigencia, sem CCSUP. Tier happy-path-minimal.

payload-com-vigencia

POST /WsItemContabil/INCLUIR/{item}

Inclusao com vigencia explicita (CTD_DTEXIS/CTD_DTEXSF) e CTD_CCSUP apontando para centro de custo superior. Espelha fixture canonica de smoke. Tier happy-path-realistic.

alterar-descricao

PUT /WsItemContabil/ALTERAR/{item}

Atualizacao parcial: somente CTD_DESC01. Demais campos preservam o valor atual via CTBA040 op=4.

alterar-bloqueio

PUT /WsItemContabil/ALTERAR/{item}

Flag CTD_BLOQ de "2" (Desbloqueado) para "1" (Bloqueado). Sem caminho privilegiado: pode vir junto com outros campos no mesmo PUT (CTD nao tem par MSBLQL/MSBLQD).

alterar-vigencia

PUT /WsItemContabil/ALTERAR/{item}

Atualiza vigencia (CTD_DTEXSF) — caminho usual para encerrar item antes da data original. Combinavel com CTD_BLOQ no mesmo payload.

delete-direto

DELETE /WsItemContabil/EXCLUIR/{item}

Exclusao via CTBA040 op=5. Falha com 422 se houver lancamento contabil vinculado ao item.

byid-recno

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

Lookup por recno da CTD — caminho recomendado e funcional nesta base.

byid-msuid

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

Lookup por identificador universal — retorna 501 nesta base (CTD nao expoe CTD_MSUID no SX3). Ver Pendencias.

listagem-paginada

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

Paginacao classica com page/pageSize em orderBy=chave (default). Combinavel com filtros cod/desc. Tamanho default 50, maximo 500.

delta-sync

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

Sincronizacao incremental por recno: cliente envia cursor=<ultimo recno> e itera via nextCursor ate retorno vazio.

Pendências conhecidas (rev3)

GET _byid?tipo=msuid retorna 501. A tabela CTD nesta base nao expoe os campos tecnicos CTD_MSUID/CTD_MSUIDT no SX3 — o caminho msuid e respondido com 501 (Not Implemented) ate o dicionario ser enriquecido. Workaround: usar tipo=recno.

Bloqueio TOTVS-padrao nao implementado. O wrapper U_CT040Exc ainda nao chama U_C980Blq("CTD"); PUT em registro com CTD_BLOQ="1" nao e barrado por regra externa — o proprio CTBA040 aplica suas validacoes internas. Padrao MSBLQL/MSBLQD nao se aplica (campo unico CTD_BLOQ).

Sem _search. Nao ha endpoint de sugestao por similaridade. Cliente que precisa autocomplete usa /_list?desc=<prefixo> com pageSize=10. Ate haver demanda real, fica aberto.

Hierarquia CCSUP/CCLP/CCPON nao validada. Os campos sao gravados como recebidos; nao ha DbSeek para confirmar que o codigo apontado existe no plano. Erro de integracao so aparece em rotinas downstream (lancamento contabil, rateio).