rev4-2026-05-14 Protheus 12.1.33

ContaContabil

CRUD de conta contábil (tabela CT1) via FwLoadModel da rotina automática CTBA020. A chave natural é CT1_CONTA (alfanumérica, fornecida pelo cliente no path) — diferente dos cadastros mestre/loja, esta tabela não usa sequência gerada pelo Protheus. Hierarquia entre contas é inferida pelo prefixo do CT1_CONTA; o campo CT1_CCSUP não deve ser enviado no payload (ver convenções).

Vinculação com o ERP

Tabela mestre CT1 Plano de contas contábeis

Rotina automática CTBA020 FwLoadModel · MVC

Wrapper AdvPL U_CT010Exc src/lib/CTB/CT010EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro

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

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

Hierarquia

Conta superior

campo CT1_CCSUP inferido pelo prefixo de CT1_CONTA
read-only no GET · não enviar em POST/PUT

Chave natural

CT1_CONTA fornecido pelo cliente

alfanumérico, até 20 caracteres · sem GetSXENum
uniqueness validada por DbSeek antes do FwLoadModel

Convenções

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

Não envie CT1_CCSUP no payload. Em build 240223P, CTBA020 retorna 500 quando o payload contém CT1_CCSUP — mesmo com valor consistente. A hierarquia é resolvida pelo prefixo do CT1_CONTA; o campo continua retornado no GET, mas é tratado como read-only pelo endpoint.

Bloqueio simples via CT1_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. CT1_DTEXIS e CT1_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.

ContaContabil

CRUD por código da conta (CT1_CONTA)

GET /WsContaContabil/{conta} Consulta conta contábil por código

Descrição

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

Path parameter

conta string · path · obrigatório CT1.CT1_CONTA

Código da conta contábil. Alfanumérico, até 20 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/WsContaContabil/ZTEST001
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/WsContaContabil/ZTEST001?fields=CT1_CONTA,CT1_DESC01,CT1_BLOQ
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Conta encontrada. Envelope { success: true, data: ContaContabil }.

400

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

404

Conta inexistente. Tier: not-found.

500

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

POST /WsContaContabil/INCLUIR/{conta} Inclui nova conta contábil

Descrição

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

Whitelist de campos: ver ContaContabilPayload.
CT1_CCSUP não deve ser enviado (ver convenções).
Antes do FwLoadModel, faz DbSeek em CT1 para detectar conflito (retorna 409).

Path parameter

conta string · path · obrigatório CT1.CT1_CONTA

Código alfanumérico da nova conta. Até 20 caracteres.

Request body

application/json ContaContabilPayload · obrigatório

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

Payload mínimo (analítica) — apenas obrigatórios do CTBA020. Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "CT1_DESC01": "CONTA ZTEST INCLUSAO",
  "CT1_CLASSE": "1",
  "CT1_NORMAL": "1",
  "CT1_BLOQ": "2"
}

Com vigência — define janela CT1_DTEXIS/CT1_DTEXSF e grupo de vencimento.

RequestHTTP/1.1 · application/json

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

{
  "CT1_DESC01": "CONTA ZTEST VIGENCIA",
  "CT1_CLASSE": "2",
  "CT1_NORMAL": "2",
  "CT1_BLOQ": "2",
  "CT1_GRPVEN": "001",
  "CT1_DTEXIS": "2026-01-01",
  "CT1_DTEXSF": "2026-12-31"
}

Respostas

201

Conta incluída. Envelope CrudResponse com data contendo o CT1_CONTA persistido.

400

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

409

Conta já existe para CT1_CONTA. Tier: business-error.

422

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

500

Erro interno — inclui o caso conhecido de CT1_CCSUP presente no payload (não enviar).

PUT /WsContaContabil/ALTERAR/{conta} Altera conta contábil existente

Descrição

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

Bloqueio. CT1_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

conta string · path · obrigatório CT1.CT1_CONTA

Código da conta existente.

Request body

application/json ContaContabilPayload · obrigatório

Subconjunto do whitelist. Não enviar CT1_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/WsContaContabil/ALTERAR/ZTEST001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "CT1_DESC01": "CONTA ZTEST ALTERADA",
  "CT1_BLOQ": "2"
}

Bloquear conta — marca CT1_BLOQ="1". A conta 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/WsContaContabil/ALTERAR/ZTEST001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "CT1_BLOQ": "1"
}

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

RequestHTTP/1.1 · application/json

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

{
  "CT1_DTEXSF": "2025-12-31",
  "CT1_BLOQ": "1"
}

Respostas

200

Conta alterada. Envelope CrudResponse.

400

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

404

Conta inexistente. Tier: not-found.

422

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

500

Erro interno (inclui o caso de CT1_CCSUP no payload).

DEL /WsContaContabil/EXCLUIR/{conta} Exclui conta contábil

Descrição

Exclui a conta contábil via CTBA020 em modo 5 (MODEL_OPERATION_DELETE). O FwLoadModel rejeita exclusão quando a conta tem lançamentos contábeis vinculados ou é referenciada como conta superior de outra conta.

Path parameter

conta string · path · obrigatório CT1.CT1_CONTA

Código da conta a excluir.

Cenario

Exemplo da requisicao (cenario ativo)

Exclusao direta — chama CTBA020 op=5. Falha 422 se houver lancamentos vinculados ou filhos.

RequestHTTP/1.1 · sem body

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

Respostas

200

Conta excluída. Envelope CrudResponse.

400

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

404

Conta inexistente. Tier: not-found.

422

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

500

Erro interno.

GET /WsContaContabil/_byid Consulta conta 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 CT1_CONTA.

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/WsContaContabil/_byid?tipo=recno&valor=1234
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Por MSUID — retorna 501 caso CT1 nao exponha CT1_MSUID no SX3.

RequestHTTP/1.1 · sem body

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

Respostas

200

Conta encontrada. Envelope { success: true, data: ContaContabil }.

400

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

404

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

501

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

500

Erro interno.

Listagem

Listagem paginada e delta-sync

GET /WsContaContabil/_list Lista contas com filtros e paginação

Descrição

Lista contas com filtros por cod (prefixo de CT1_CONTA) ou desc (prefixo de CT1_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 CT1.CT1_CONTA

Prefixo de CT1_CONTA.

desc string · query · opcional CT1.CT1_DESC01

Prefixo de CT1_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/WsContaContabil/_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/WsContaContabil/_list?orderBy=recno&cursor=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

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

ContaContabil

object

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

CT1_CONTAstring · opcionalCT1.CT1_CONTA

Código da conta (chave natural). Alfanumérico até 20 caracteres.

CT1_DESC01string · opcionalCT1.CT1_DESC01

Descrição principal da conta.

CT1_CLASSEstring · opcionalCT1.CT1_CLASSE

Classe da conta. "1"=Sintética, "2"=Analítica.

12

CT1_NORMALstring · opcionalCT1.CT1_NORMAL

Natureza do saldo normal. "1"=Devedora, "2"=Credora.

12

CT1_BLOQstring · opcionalCT1.CT1_BLOQ

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

12

CT1_CCSUPstring · opcional · read-onlyCT1.CT1_CCSUP

Conta superior na hierarquia. Inferido pelo prefixo do CT1_CONTA; não deve ser enviado no payload (CTBA020 retorna 500).

CT1_GRPVENstring · opcionalCT1.CT1_GRPVEN

Grupo de vencimento associado à conta.

recnointeger · opcional

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

msuidstring · opcional

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

msuidtstring · opcional

Timestamp técnico associado ao msuid.

ContaContabilPayload

object

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

CT1_DESC01string · opcionalCT1.CT1_DESC01

Descrição principal da conta.

CT1_CLASSEstring · opcionalCT1.CT1_CLASSE

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

12

CT1_NORMALstring · opcionalCT1.CT1_NORMAL

"1"=Devedora, "2"=Credora.

12

CT1_BLOQstring · opcionalCT1.CT1_BLOQ

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

12

CT1_GRPVENstring · opcionalCT1.CT1_GRPVEN

Grupo de vencimento.

CT1_DTEXISstring (date) · opcionalCT1.CT1_DTEXIS

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

CT1_DTEXSFstring (date) · opcionalCT1.CT1_DTEXSF

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

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz o CT1_CONTA 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 CT1_CONTA 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 FwLoadModel) 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 FwLoadModel).

Cenarios

Combinacoes documentadas (1 por example do openapi.yaml)

consulta-direta

GET /WsContaContabil/{conta}

Consulta direta por CT1_CONTA. Resposta inclui CT1_CCSUP (hierarquia inferida pelo prefixo).

consulta-com-fields

GET /WsContaContabil/{conta}?fields=...

Reduz payload de retorno; util em integracoes mobile.

payload-minimo-analitica

POST /WsContaContabil/INCLUIR/{conta}

Inclusao minima de conta analitica (CT1_CLASSE="2") com obrigatorios: CT1_DESC01, CT1_CLASSE, CT1_NORMAL, CT1_BLOQ. Nao enviar CT1_CCSUP. Tier happy-path-minimal.

payload-com-vigencia

POST /WsContaContabil/INCLUIR/{conta}

Inclusao com vigencia explicita (CT1_DTEXIS/CT1_DTEXSF) + classificacao normal/inversa. Sem CT1_CCSUP — a hierarquia e inferida pelo prefixo de CT1_CONTA. Tier happy-path-realistic.

alterar-descricao

PUT /WsContaContabil/ALTERAR/{conta}

Atualiza somente CT1_DESC01; demais campos preservados.

alterar-bloqueio

PUT /WsContaContabil/ALTERAR/{conta}

Toggle de CT1_BLOQ; sem caminho privilegiado (CT1 nao tem par MSBLQL/MSBLQD).

alterar-vigencia

PUT /WsContaContabil/ALTERAR/{conta}

Atualiza vigencia (CT1_DTEXSF) — caminho usual para encerrar conta antes da data original.

delete-direto

DELETE /WsContaContabil/EXCLUIR/{conta}

Exclusao via CTBA020 op=5. Falha 422 se a conta tiver lancamentos contabeis.

byid-recno

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

Lookup por recno da CT1 — caminho recomendado e funcional.

byid-msuid

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

Lookup por identificador universal — retorna 501 nesta base (CT1 sem CT1_MSUID no SX3). Ver Pendencias.

listagem-paginada

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

Paginacao classica com page/pageSize em orderBy=chave. Combinavel com filtro cod (navega hierarquia por niveis) ou desc. Default 50, maximo 500.

delta-sync

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

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

Pendências conhecidas (rev3)

CT1_CCSUP no payload causa 500 no CTBA020. Memoria documentada (ct1-ccsup-500): qualquer valor enviado em CT1_CCSUP via POST faz o MsExecAuto abortar com erro nao-mapeado retornado como 500. Workaround: omitir o campo — a hierarquia e inferida pelo prefixo de CT1_CONTA apos a gravacao. Para POST somente leitura via GET o campo aparece corretamente preenchido.

GET _byid?tipo=msuid retorna 501. A CT1 nesta base nao expoe CT1_MSUID/CT1_MSUIDT no SX3. Workaround: tipo=recno.

Bloqueio TOTVS-padrao nao implementado. O wrapper ainda nao chama U_C980Blq("CT1"); padrao MSBLQL/MSBLQD nao se aplica (campo unico CT1_BLOQ).

Sem _search. Autocomplete usa /_list?desc=<prefixo> com pageSize=10.

Hierarquia CT1_GRPVEN nao validada. O campo e gravado como recebido; nao ha DbSeek para confirmar existencia do grupo de vendas.