rev4-2026-05-14

CentroCusto

CRUD de Centro de Custo (tabela CTT) via MsExecAuto do CTBA030. A chave externa é a própria chave técnica CTT_CUSTO — alfanumérica, com até 9 caracteres, fornecida pelo cliente (não há geração por GetSXENum). Datas em formato ISO YYYY-MM-DD em entrada e saída.

Vinculação com o ERP

Tabela mestre CTT Centros de Custo

Rotina automática CTBA030 MsExecAuto · contabilidade

Wrapper AdvPL U_CT030Exc src/lib/CTB/CT030EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Chave natural

CTT_CUSTO fornecido pelo cliente

alfanumérico · até 9 caracteres · sem GetSXENum
o consumidor é responsável pela unicidade — duplicidade retorna 409

Bloqueio nativo

CTT_BLOQ (campo próprio da CTT)

"1"=Bloqueado · "2"=Desbloqueado
CTT não usa o par MSBLQL/MSBLQD padrão TOTVS

Hierarquia · opcional

Centro de custo superior

CTT_CCSUP referencia outro CTT_CUSTO
vazio = raiz · CTT_CLASSE deve ser coerente (1=Sintética, 2=Analítica)

Vigência

CTT_DTEXIS / CTT_DTEXSF

janela de existência do centro de custo
ISO YYYY-MM-DD · default histórico 1980-01-01 → 2029-12-31

Convenções

Identificador externo. Todas as rotas /WsCentroCusto/{custo} usam CTT_CUSTO diretamente — alfanumérico, máximo 9 caracteres, sem espaços. Não há chave técnica separada (não há GetSXENum); o cliente fornece o código e é responsável pela unicidade — colisão retorna 409.

Bloqueio (CTT_BLOQ). Diferente do padrão TOTVS *_MSBLQL/*_MSBLQD, a CTT usa o campo nativo CTT_BLOQ: "1"=Bloqueado, "2"=Desbloqueado. O bloqueio é editorial — o endpoint apenas grava o valor; a regra de negócio sobre o que fazer com um centro bloqueado fica nas rotinas consumidoras (contabilização, rateio, etc).

Classe e hierarquia. CTT_CLASSE "1"=Sintética (agrupa filhos, não recebe lançamento), "2"=Analítica (folha, recebe lançamento). O campo opcional CTT_CCSUP aponta para o centro pai. Em inclusões raiz, deixar CTT_CCSUP="".

Formato de datas. CTT_DTEXIS (início de existência) e CTT_DTEXSF (fim de existência) aceitam string ISO YYYY-MM-DD. No GET o campo é serializado pelo mesmo formato. Não use DD/MM/YYYY — é rejeitado na conversão para tipo Date.

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.

CentroCusto

CRUD por código (CTT_CUSTO)

GET /WsCentroCusto/{custo} Consulta centro de custo por código

Descrição

Retorna o centro de custo pesquisado por CTT_CUSTO. Aplica filtro de filial (xFilial("CTT")) e respeita o whitelist de CAMPOS_GET definido no .prw. O parâmetro opcional fields reduz o conjunto de campos retornados.

Path parameter

custo string · path · obrigatório CTT.CTT_CUSTO

Código do Centro de Custo. Alfanumérico, máximo 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/WsCentroCusto/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/WsCentroCusto/ZTEST___?fields=CTT_CUSTO,CTT_DESC01,CTT_BLOQ,CTT_CCSUP
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Centro de custo encontrado. Envelope { success: true, data: CentroCusto }.

400

Código fora do formato (vazio, > 9 chars). Tier: validation-error.

404

Centro de custo inexistente. Tier: not-found.

500

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

POST /WsCentroCusto/INCLUIR/{custo} Inclui novo centro de custo

Descrição

Inclui um centro de custo novo via CTBA030 em modo 3. A chave CTT_CUSTO vem do path — o consumidor é responsável pela unicidade. Colisão com registro existente retorna 409.

Whitelist de campos: ver CentroCustoPayload.
O segmento literal INCLUIR é exigido pela WSSYNTAX do build 240223P; sem ele o roteador devolve 404.

Path parameter

custo string · path · obrigatório CTT.CTT_CUSTO

Código do centro de custo. Alfanumérico, máximo 9 caracteres.

Request body

application/json CentroCustoPayload · obrigatório

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

Payload mínimo — apenas obrigatórios do CTBA030. Fixture: fixtures/post-no-desc.json.

RequestHTTP/1.1 · application/json

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

{
  "CTT_CLASSE": "2",
  "CTT_BLOQ": "2"
}

Payload completo — descrição, classe, normal, bloqueio, vigência. Centro raiz (CTT_CCSUP=""). Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "CTT_DESC01": "CENTRO CUSTO ZTEST",
  "CTT_CLASSE": "2",
  "CTT_NORMAL": " ",
  "CTT_BLOQ": "2",
  "CTT_DTEXIS": "1980-01-01",
  "CTT_DTEXSF": "2029-12-31",
  "CTT_CCSUP": ""
}

Respostas

201

Centro de custo incluído. Envelope CrudResponse com data = { CTT_CUSTO }.

400

Código fora do formato ou payload malformado. Tier: validation-error.

409

CTT_CUSTO já existe. Tier: business-error.

422

Payload rejeitado pelo MsExecAuto do CTBA030 (enum inválido, CTT_CCSUP inexistente, classe incoerente com hierarquia, etc). Tier: business-error.

500

Erro interno.

PUT /WsCentroCusto/ALTERAR/{custo} Altera centro de custo existente

Descrição

Altera campos do centro de custo via CTBA030 em modo 4. Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW.

Bloqueio. Diferente de cadastros que usam o par *_MSBLQL/*_MSBLQD, a CTT expõe apenas CTT_BLOQ ("1"=Bloqueado, "2"=Desbloqueado). O PUT aceita alterar CTT_BLOQ livremente — não há "caminho de desbloqueio exclusivo" como em SA1.

Path parameter

custo string · path · obrigatório CTT.CTT_CUSTO

Código do centro de custo a alterar.

Request body

application/json CentroCustoPayload · obrigatório

Subconjunto do whitelist. CTT_CUSTO nunca entra no body — é imutável (vem do path).

Alteração comum — atualiza descrição e confirma estado de bloqueio. Fixture: fixtures/put-update.json.

RequestHTTP/1.1 · application/json

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

{
  "CTT_DESC01": "CENTRO CUSTO ZTEST ALTERADO",
  "CTT_BLOQ": "2"
}

Bloquear centro de custo — passa CTT_BLOQ="1". Sem efeito intrínseco no endpoint; rotinas consumidoras (contabilização) decidem como tratar.

RequestHTTP/1.1 · application/json

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

{
  "CTT_BLOQ": "1"
}

Mover na hierarquia — define o centro pai via CTT_CCSUP. O pai precisa existir e ser CTT_CLASSE="1" (Sintética); senão o CTBA030 rejeita com 422.

RequestHTTP/1.1 · application/json

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

{
  "CTT_CCSUP": "ADMIN____"
}

Respostas

200

Centro de custo alterado. Envelope CrudResponse.

400

Código fora do formato ou payload malformado. Tier: validation-error.

404

Centro de custo inexistente. Tier: not-found.

422

Payload rejeitado pelo MsExecAuto (campo fora do whitelist, enum inválido, CTT_CCSUP inexistente). Tier: business-error.

500

Erro interno.

DEL /WsCentroCusto/EXCLUIR/{custo} Exclui centro de custo

Descrição

Exclui o centro de custo via CTBA030 em modo 5. O MsExecAuto rejeita exclusão de centro de custo com filhos (referenciado por outro como CTT_CCSUP) ou com lançamentos contábeis vinculados.

Path parameter

custo string · path · obrigatório CTT.CTT_CUSTO

Código do centro de custo a excluir.

Cenario

Exemplo da requisicao (cenario ativo)

Exclusao direta — chama CTBA030 op=5. Falha 422 se houver filhos ou dependencias (lancamentos, rateios).

RequestHTTP/1.1 · sem body

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

Respostas

200

Centro de custo excluído. Envelope CrudResponse.

400

Código fora do formato. Tier: validation-error.

404

Centro de custo inexistente. Tier: not-found.

422

Centro tem filhos ou dependências (lançamentos contábeis, rateios). Tier: business-error.

500

Erro interno.

GET /WsCentroCusto/_byid Consulta centro de custo por id técnico (recno|msuid)

Descrição

Busca o centro de custo por id técnico — útil para integrações que persistem recno ou msuid e querem reconfirmar o registro sem reconstruir o código. tipo=msuid faz scan-full em CTT_MSUID (sem índice nativo) e retorna 501 em ambientes sem o campo opcional.

Query parameters

tipo string · query · obrigatório

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

Subconjunto de CAMPOS_GET a retornar.

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

Por MSUID — scan-full em CTT_MSUID (sem indice nativo); retorna 501 se o campo nao existir no SX3.

RequestHTTP/1.1 · sem body

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

Respostas

200

Centro de custo encontrado. Envelope { success: true, data: CentroCusto }.

400

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

404

Centro de custo não localizado. Tier: not-found.

501

Busca por msuid requer o campo opcional CTT_MSUID ausente no dicionário deste ambiente.

500

Erro interno.

Listagem

Listagem paginada com delta-sync

GET /WsCentroCusto/_list Lista centros de custo com filtros e paginação

Descrição

Lista centros de custo com filtros por cod (prefixo de CTT_CUSTO) ou desc (prefixo de CTT_DESC01, normalizado sem acento). Dois modos de ordenação:

orderBy=chave (default) — paginação por page/pageSize.
orderBy=recno — delta-sync, usa since/cursor com nextCursor retornado.

Query parameters

cod string · query · opcional CTT.CTT_CUSTO

Prefixo de CTT_CUSTO.

desc string · query · opcional CTT.CTT_DESC01

Prefixo de CTT_DESC01 (normalizado sem acento, uppercase).

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 em orderBy=chave (RecNo >= since).

cursor integer · query · opcional

Cursor retornado em nextCursor (válido com 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/WsCentroCusto/_list?desc=CENTRO&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/WsCentroCusto/_list?orderBy=recno&cursor=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de centros de custo. Envelope com data (array de CentroCusto), page, pageSize, count, orderBy e 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

CentroCusto

object

Representação retornada nos GETs (/{custo}, /_list, /_byid). Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields. CTT_MSUID/CTT_MSUIDT são opcionais — só aparecem quando o dicionário do ambiente expõe o campo.

CTT_CUSTOstring · opcionalCTT.CTT_CUSTO

Código do centro de custo (chave natural).

CTT_DESC01string · opcionalCTT.CTT_DESC01

Descrição editorial do centro de custo.

CTT_CLASSEstring · opcionalCTT.CTT_CLASSE

"1"=Sintética (agrupa, não recebe lançamento), "2"=Analítica (folha, recebe lançamento).

12

CTT_NORMALstring · opcionalCTT.CTT_NORMAL

Natureza contábil: " "=Nenhum, "1"=Receita, "2"=Despesa.

12

CTT_BLOQstring · opcionalCTT.CTT_BLOQ

Bloqueio nativo da CTT: "1"=Bloqueado, "2"=Desbloqueado. Não é o par TOTVS *_MSBLQL/*_MSBLQD.

12

CTT_DTEXISstring (date) · opcionalCTT.CTT_DTEXIS

Início de vigência. ISO YYYY-MM-DD.

CTT_DTEXSFstring (date) · opcionalCTT.CTT_DTEXSF

Fim de vigência. ISO YYYY-MM-DD.

CTT_CCSUPstring · opcionalCTT.CTT_CCSUP

Centro de custo superior na hierarquia (referencia outro CTT_CUSTO). Vazio = raiz.

CTT_CCLPstring · opcionalCTT.CTT_CCLP

Centro de custo de longo prazo (rateio).

recnointeger · opcional

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

msuidstring · opcional

Identificador universal CTT_MSUID (quando exposto no dicionário).

msuidtstring · opcional

Timestamp técnico associado ao msuid.

CentroCustoPayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW no .prw. CTT_CUSTO não entra no body — é imutável (vem do path no POST e PUT, é a chave da identificação).

CTT_DESC01string · opcionalCTT.CTT_DESC01

Descrição. Recomendado no POST; aceita vazio (será preenchido com o código).

CTT_CLASSEstring · opcionalCTT.CTT_CLASSE

Classe contábil. "1"=Sintética, "2"=Analítica.

12

CTT_NORMALstring · opcionalCTT.CTT_NORMAL

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

12

CTT_BLOQstring · opcionalCTT.CTT_BLOQ

Estado de bloqueio. "1"=Bloqueado, "2"=Desbloqueado. Sem caminho de desbloqueio exclusivo — pode ser alterado em qualquer PUT.

12

CTT_DTEXISstring (date) · opcionalCTT.CTT_DTEXIS

Início de vigência. ISO YYYY-MM-DD.

CTT_DTEXSFstring (date) · opcionalCTT.CTT_DTEXSF

Fim de vigência. ISO YYYY-MM-DD.

CTT_CCLPstring · opcionalCTT.CTT_CCLP

Centro de custo de longo prazo (rateio futuro).

CTT_CCPONstring · opcionalCTT.CTT_CCPON

Centro de custo de ponderação.

CTT_BOOKstring · opcionalCTT.CTT_BOOK

Book contábil associado.

CTT_CCSUPstring · opcionalCTT.CTT_CCSUP

Centro de custo superior. Referencia outro CTT_CUSTO existente com CTT_CLASSE="1". Vazio para raiz.

CTT_RESstring · opcionalCTT.CTT_RES

Responsável pelo centro de custo (texto livre).

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz a chave gravada (POST) ou objeto vazio (PUT/DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

dataobject · opcional

Em POST, contém { "CTT_CUSTO": "ZTEST___" }. Em PUT/DELETE pode ser objeto vazio.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog do CTBA030) 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 /WsCentroCusto/{custo}

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

consulta-com-fields

GET /WsCentroCusto/{custo}?fields=...

Reduz payload de retorno; util para integracoes mobile.

payload-minimo-analitica

POST /WsCentroCusto/INCLUIR/{custo}

Inclusao minima de CC analitico (CTT_CLASSE="2") com obrigatorios: CTT_DESC01, CTT_CLASSE, CTT_BLOQ. Sem hierarquia (sem CCSUP). Tier happy-path-minimal.

payload-com-vigencia

POST /WsCentroCusto/INCLUIR/{custo}

Inclusao com vigencia explicita (CTT_DTEXIS/CTT_DTEXSF) e CTT_CCSUP apontando para CC superior. Espelha fixture canonica. Tier happy-path-realistic.

alterar-descricao

PUT /WsCentroCusto/ALTERAR/{custo}

Atualiza somente CTT_DESC01; demais campos preservados.

alterar-bloqueio

PUT /WsCentroCusto/ALTERAR/{custo}

Toggle de CTT_BLOQ; sem caminho privilegiado (CTT nao tem par MSBLQL/MSBLQD).

alterar-vigencia

PUT /WsCentroCusto/ALTERAR/{custo}

Atualiza vigencia (CTT_DTEXSF) ou move hierarquia (CTT_CCSUP) — caminhos usuais de manutencao do plano.

delete-direto

DELETE /WsCentroCusto/EXCLUIR/{custo}

Exclusao via CTBA030 op=5. Falha 422 se CC tiver lancamentos vinculados.

byid-recno

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

Lookup por recno da CTT — caminho recomendado e funcional.

byid-msuid

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

Lookup por identificador universal — scan-full em CTT_MSUID (sem indice); retorna 501 se o campo nao existir no SX3.

listagem-paginada

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

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

delta-sync

GET /WsCentroCusto/_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 CTT desta base pode nao expor CTT_MSUID/CTT_MSUIDT no SX3 — o caminho msuid responde 501. Workaround: tipo=recno.

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

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

Hierarquia CCSUP/CCLP/CCPON nao validada. Os campos sao gravados como recebidos; nao ha DbSeek para confirmar existencia do CC superior.