rev3-2026-05-14 Protheus 12.1.33

CadastroEntidade05

CRUD de Entidade do Plano Contabil 05 (tabela CV0) via MsExecAuto do CTBA800. O plano e fixo (CV0_PLANO = "05", hardcoded no endpoint); o cliente passa apenas CV0_CODIGO no path. Para planos 06/07/08 use os endpoints irmaos CadastroEntidade06/07/08, todos compartilhando o mesmo wrapper U_CT800Exc.

Bloqueio TOTVS: tabela CV0 plano 05 — campo CV0_MSBLQL nao presente no SX3 desta base; padrao MSBLQL/MSBLQD nao implementado no wrapper CT800EXC. Ver Pendencias.

Vinculacao com o ERP

Tabela mestre CV0 Entidades dos planos contabeis

Rotina automatica CTBA800 MsExecAuto · plano fixo "05"

Wrapper AdvPL U_CT800Exc src/lib/CTB/CT800EXC.prw

Operacoes & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependencias de ambiente

Constante

Plano contabil "05"

CV0_PLANO hardcoded em PLANO_FIXO = "05"
endpoints irmaos: CadastroEntidade06, 07, 08

Chave composta

CV0 · indice 1

CV0_FILIAL + CV0_PLANO + CV0_CODIGO
DbSeek usa PadR em cada componente

Wrapper compartilhado

CT800EXC.prw

U_CT800Exc e reutilizado por WSCV005..008
invoca CTBA800 com array auto-montado a partir do payload

Convencoes

Plano fixo "05". Este endpoint nao expoe CV0_PLANO no payload — o valor e sempre "05", definido no .prw (#Define PLANO_FIXO "05"). Para outros planos, use os endpoints irmaos (CadastroEntidade06, 07, 08), todos compartilhando o mesmo wrapper U_CT800Exc.

Identificador externo. A rota /WsEntidade05/{codigo} recebe CV0_CODIGO direto no path (string, padronizada via PadR para o tamanho do SX3). O Protheus nao gera sequencia aqui — o cliente decide o codigo no POST. Para buscar pela chave tecnica (RecNo / CV0_MSUID), use /_byid?tipo=recno|msuid&valor=….

DELETE nao requer CV0_ITEM. Conforme a DT do CTBA800, a exclusao trabalha apenas com a chave PLANO + CODIGO. O endpoint nao expoe nem exige CV0_ITEM no DELETE.

Paginacao e delta-sync. /_list usa page/pageSize (default 50, max 500). Para sincronizacao incremental, alterne para orderBy=recno e use since/cursor conforme o nextCursor retornado.

Encoding e acentos. Descricoes (CV0_DESC) aceitam acentos do portugues (Windows-1252). Filtros de busca em /_list?desc=… sao normalizados sem acento (via U_NoAcento) e em uppercase antes do DbSeek.

Entidade05

CRUD por codigo (CV0_CODIGO) no plano fixo 05

GET /WsEntidade05/{codigo} Consulta entidade por codigo

Descricao

Retorna a entidade do plano 05 pesquisada pelo codigo. Aplica filtro de filial (xFilial("CV0")) e respeita o whitelist CAMPOS_GET definido no .prw. O parametro opcional fields reduz o conjunto de campos retornados.

Path parameter

codigo string · path · obrigatorio CV0.CV0_CODIGO

Codigo da entidade. String padronizada via PadR ate TamSX3("CV0_CODIGO").

Query parameters

fields string · query · opcional

Lista de campos separados por virgula. Validados contra CAMPOS_GET.

Cenario

Exemplo da requisicao (cenario ativo)

Consulta direta — apenas o codigo no path; retorna todos os campos de CAMPOS_GET.

RequestHTTP/1.1 · sem body

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

Consulta com fields — usa ?fields=… para reduzir o payload de resposta.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsEntidade05/ZTEST?fields=CV0_CODIGO,CV0_DESC
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Entidade encontrada. Envelope { success: true, data: Entidade }.

400

Codigo vazio ou maior que TamSX3("CV0_CODIGO"). Tier: validation-error.

404

Entidade inexistente no plano 05 para o codigo informado. Tier: not-found.

500

Erro interno (DbSeek, serializacao). Tier: business-error.

POST /WsEntidade05/INCLUIR/{codigo} Inclui nova entidade no plano 05

Descricao

Inclui uma entidade nova no plano contabil 05 via CTBA800 em modo 3 (MODEL_OPERATION_INSERT). O endpoint preenche automaticamente CV0_PLANO = "05" e usa CV0_CODIGO recebido no path. Demais campos vem do payload.

Whitelist: ver EntidadePayload.
Se ja existir entidade com mesmo CV0_CODIGO no plano 05, retorna 409.

Path parameter

codigo string · path · obrigatorio CV0.CV0_CODIGO

Codigo da entidade a criar. Maximo TamSX3("CV0_CODIGO").

Cenario

Body fields (variam por cenario)

CV0_DESC string · obrigatorio CV0.CV0_DESC

Descricao da entidade.

CV0_ITEM string · opcional CV0.CV0_ITEM

Item / sequencia hierarquica dentro do plano (ex: "000099").

Exemplo da requisicao (cenario ativo)

Payload minimo — apenas CV0_DESC obrigatorio para o CTBA800. Fixture: fixtures/post-cv005-test.json.

RequestHTTP/1.1 · application/json

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

{
  "CV0_DESC": "ENTIDADE ZTEST PLANO05"
}

Payload completo — descricao + item/sequencia hierarquica.

RequestHTTP/1.1 · application/json

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

{
  "CV0_DESC": "ENTIDADE ZTEST PLANO05",
  "CV0_ITEM": "000099"
}

Respostas

201

Entidade incluida. Envelope CrudResponse com data contendo a chave gravada (CV0_PLANO/CV0_CODIGO).

400

Codigo invalido ou payload mal formado. Tier: validation-error.

409

Entidade ja existe no plano 05 para o CV0_CODIGO informado. Tier: business-error.

422

Payload rejeitado pelo MsExecAuto do CTBA800 (campo fora do whitelist, valor invalido). Tier: business-error.

500

Erro interno.

PUT /WsEntidade05/ALTERAR/{codigo} Altera entidade existente

Descricao

Altera campos da entidade via CTBA800 em modo 4 (MODEL_OPERATION_UPDATE). Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW. A chave (CV0_PLANO+CV0_CODIGO) nao e alteravel — CV0_PLANO e fixo "05" e CV0_CODIGO vem do path.

Path parameter

codigo string · path · obrigatorio CV0.CV0_CODIGO

Codigo da entidade a alterar.

Cenario

Body fields (variam por cenario)

CV0_DESC string · opcional CV0.CV0_DESC

Nova descricao. Campos omitidos preservam o valor anterior.

Exemplo da requisicao (cenario ativo)

Alteracao de descricao — atualiza apenas CV0_DESC. Fixture: fixtures/put-cv005-test.json.

RequestHTTP/1.1 · application/json

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

{
  "CV0_DESC": "ENTIDADE ZTEST PLANO05 ALTERADA"
}

Respostas

200

Entidade alterada. Envelope CrudResponse.

400

Codigo invalido. Tier: validation-error.

404

Entidade inexistente no plano 05. Tier: not-found.

422

Payload rejeitado pelo MsExecAuto do CTBA800. Tier: business-error.

500

Erro interno.

DEL /WsEntidade05/EXCLUIR/{codigo} Exclui entidade

Descricao

Exclui a entidade via CTBA800 em modo 5 (MODEL_OPERATION_DELETE). DELETE nao requer CV0_ITEM — conforme DT do CTBA800, a chave usada e apenas CV0_PLANO + CV0_CODIGO. O MsExecAuto rejeita exclusao quando a entidade possui dependencias contabeis vinculadas (lancamentos, configuracoes).

Path parameter

codigo string · path · obrigatorio CV0.CV0_CODIGO

Codigo da entidade a excluir.

Cenario

Exemplo da requisicao (cenario ativo)

Delete direto — exclusao via CTBA800 modo 5 usando apenas PLANO+CODIGO.

RequestHTTP/1.1 · sem body

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

Respostas

200

Entidade excluida. Envelope CrudResponse.

400

Codigo invalido. Tier: validation-error.

404

Entidade inexistente no plano 05. Tier: not-found.

422

Entidade possui dependencias contabeis (lancamentos, configuracoes). Tier: business-error.

500

Erro interno.

GET /WsEntidade05/_byid Consulta entidade por id tecnico (recno|msuid)

Descricao

Busca a entidade por id tecnico — util para integracoes que persistem o RecNo do AdvPL ou o identificador universal (CV0_MSUID) e querem reconfirmar o registro sem reconstruir a chave de negocio.

Atencao: nesta base o campo CV0_MSUID nao existe no SX3 — chamadas com tipo=msuid respondem 501. Ver Pendencias.

Query parameters

tipo string · query · obrigatorio

Indica qual id tecnico esta sendo usado.

recnomsuid

valor string · query · obrigatorio

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

Cenario

Exemplo da requisicao (cenario ativo)

Por recno — sempre disponivel; valor e o RecNo() do AdvPL.

RequestHTTP/1.1 · sem body

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

Por msuid — nesta base CV0_MSUID esta ausente no SX3, retorna 501. Documentado para uniformidade do padrao; quando o ambiente receber UPDDISTR habilitando o campo, este cenario passa a responder 200.

RequestHTTP/1.1 · sem body · 501 nesta base

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

Respostas

200

Entidade encontrada. Envelope { success: true, data: Entidade }.

400

Parametros tipo/valor ausentes ou tipo fora do enum.

404

Entidade nao localizada. Tier: not-found.

501

Busca por msuid requer CV0_MSUID presente no dicionario, indisponivel neste ambiente.

500

Erro interno.

Listagem

Listagem paginada de entidades do plano 05

GET /WsEntidade05/_list Lista entidades com filtros e paginacao

Descricao

Lista entidades do plano 05 com filtros por cod (CV0_CODIGO exato) ou desc (prefixo normalizado, sem acento). Suporta dois modos de ordenacao:

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

Query parameters

cod string · query · opcional CV0.CV0_CODIGO

CV0_CODIGO exato (indice 1).

desc string · query · opcional CV0.CV0_DESC

Prefixo de CV0_DESC (normalizado sem acento, uppercase).

fields string · query · opcional

Lista de campos validados contra CAMPOS_GET.

page integer · query · opcional

Pagina (default 1, minimo 1).

pageSize integer · query · opcional

Tamanho da pagina (default 50, max 500).

orderBy string · query · opcional

Modo de ordenacao. Default chave.

chaverecno

since integer · query · opcional

Inicio do delta-sync (valido com orderBy=recno).

cursor integer · query · opcional

Cursor retornado em nextCursor de pagina anterior.

Cenarios

Exemplo da requisicao (cenario ativo)

Lista por pagina — default orderBy=chave, pageSize=50.

RequestHTTP/1.1 · sem body

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

Lista por prefixo — filtra CV0_DESC normalizando acentos via U_NoAcento.

RequestHTTP/1.1 · sem body

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

Delta-sync — orderBy=recno + cursor retomavel via nextCursor retornado na pagina anterior.

RequestHTTP/1.1 · sem body

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

Respostas

200

Pagina de entidades. Envelope com data (array de Entidade), page, pageSize, count, opcionalmente nextCursor.

400

Parametro fora do dominio (ex: orderBy invalido, pageSize > 500).

500

Erro interno.

Schemas

Definicoes canonicas — campos com origem SX3 rastreavel

Entidade

object

Representacao retornada nos GETs (/{codigo}, /_list, /_byid). Inclui chave de negocio (CV0_PLANO/CV0_CODIGO), descricao e item. Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields.

CV0_PLANOstring · opcionalCV0.CV0_PLANO

Plano contabil. Sempre "05" neste endpoint.

CV0_CODIGOstring · opcionalCV0.CV0_CODIGO

Codigo da entidade (chave de negocio).

CV0_ITEMstring · opcionalCV0.CV0_ITEM

Item / sequencia hierarquica dentro do plano (ex: "000099").

CV0_DESCstring · opcionalCV0.CV0_DESC

Descricao da entidade.

recnointeger · opcional

Id tecnico do registro (RecNo do AdvPL).

msuidstring · opcional

Identificador universal CV0_MSUID (presente se o dicionario tiver o campo — ausente nesta base).

msuidtstring · opcional

Timestamp tecnico associado ao msuid.

EntidadePayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW no .prw. A chave (CV0_PLANO fixo "05" + CV0_CODIGO via path) nao aparece no payload.

CV0_DESCstring · opcionalCV0.CV0_DESC

Descricao da entidade. No POST e tipicamente obrigatorio para o CTBA800 aceitar a inclusao.

CV0_ITEMstring · opcionalCV0.CV0_ITEM

Item / sequencia hierarquica (ex: "000099"). Quando omitido, o CTBA800 assume o default do dicionario.

CrudResponse

object · envelope

Envelope padrao das respostas de POST / PUT / DELETE. data traz a chave gravada (POST) ou string vazia (PUT/DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatorio

Mensagem editorial de sucesso.

datastring | object · opcional

Em POST, contem a chave gravada (CV0_PLANO/CV0_CODIGO). Em PUT/DELETE pode ser string vazia ou objeto auxiliar.

Erro

object · envelope

Envelope padrao de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog do CTBA800) para tratamento programatico, quando aplicavel.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatorio

Mensagem editorial do erro (apresentavel ao usuario final).

datastring · opcional

Token interno / detalhe tecnico (ex: log do MsExecAuto).

Cenarios

Catalogo de combinacoes de payload/query reconhecidas pelos metodos do plano 05. Tier semantico no slug; endpoint no type-pill.

payload-minimo

POST /WsEntidade05/INCLUIR/{codigo}

Inclusao basica — apenas CV0_DESC no body. CV0_PLANO e fixo "05", CV0_CODIGO vem do path. CV0_ITEM assume o default do dicionario.

Quando usar: caso de uso padrao do CRUD; cliente nao precisa controlar item.

payload-completo

POST /WsEntidade05/INCLUIR/{codigo}

Inclusao com CV0_DESC + CV0_ITEM explicito — usado quando a entidade compoe um nivel hierarquico definido no plano contabil.

Quando usar: integracoes que precisam preservar a sequencia hierarquica de origem.

payload-alterar-descricao

PUT /WsEntidade05/ALTERAR/{codigo}

Altera apenas CV0_DESC via CTBA800 modo 4. Campos omitidos preservam o valor anterior; chave (CV0_PLANO+CV0_CODIGO) nao e alteravel.

Quando usar: renomear a entidade sem alterar hierarquia.

delete-direto

DELETE /WsEntidade05/EXCLUIR/{codigo}

Exclusao via CTBA800 modo 5. Conforme DT, basta PLANO+CODIGO.

Bloqueio: 422 quando ha dependencias contabeis (lancamentos, configuracoes) vinculadas a entidade.

consulta-direta

GET /WsEntidade05/{codigo}

DbSeek pelo indice 1 (filial+plano+codigo, todos com PadR). Retorna envelope { success, data: Entidade } com todos os campos do CAMPOS_GET.

consulta-com-fields

GET /WsEntidade05/{codigo}

Mesma busca, mas com filtro ?fields=… reduzindo o payload de resposta. Cada campo solicitado e validado contra CAMPOS_GET; campo fora do whitelist devolve 400.

byid-por-recno

GET /WsEntidade05/_byid

Busca por RecNo() do AdvPL via tipo=recno&valor=N. Identificador tecnico sempre disponivel — defesa multi-filial verifica que CV0_FILIAL bate com a filial corrente.

byid-por-msuid

GET /WsEntidade05/_byid

501 nesta base — o campo CV0_MSUID nao esta presente no SX3, entao o endpoint nao consegue procurar por id universal. Documentado para uniformidade do padrao; o cenario passa a responder 200 quando o ambiente receber UPDDISTR habilitando o campo. Ver Pendencias.

list-por-pagina

GET /WsEntidade05/_list

Default orderBy=chave + page/pageSize. Paginacao por offset sobre o indice 1 da CV0, restrita ao plano fixo "05".

list-por-prefixo

GET /WsEntidade05/_list

Filtra por cod (CV0_CODIGO exato pelo indice) ou desc (prefixo de CV0_DESC com normalizacao via U_NoAcento). Os dois sao combinaveis com page/pageSize.

list-delta-sync

GET /WsEntidade05/_list

orderBy=recno + cursor retomavel via nextCursor retornado na pagina anterior. since (corta RecNo() < since) tambem aceito.

Quando usar: sincronizacao incremental de consumer (Angular embarcado, integradores externos).

Pendencias conhecidas (rev3)

MSUID indisponivel nesta base (501 ambiental). O dicionario (SX3) desta instalacao nao expoe CV0_MSUID nem CV0_MSUIDT. O endpoint detecta a ausencia via U_RestCamposOpc e responde 501 em GET /_byid?tipo=msuid. Documentado para uniformidade do padrao — quando a base receber UPDDISTR habilitando os campos, o cenario passa a responder 200 sem alteracao no .prw.

Bloqueio MSBLQL/MSBLQD nao implementado. O padrao da biblioteca (validado em SA1/SA2/SB1/SB5/SC1) ainda nao chegou ao wrapper CT800EXC. Hoje PUT e DELETE nao verificam CV0_MSBLQL/CV0_MSBLQD antes do MsExecAuto. Quando o campo estiver presente no SX3 e o padrao for portado, a regra de "apenas o par MSBLQL/MSBLQD aceito em registro bloqueado" sera replicada de WsSA1.

Sem _search de sugestao. Diferente de endpoints como WsSA1/WsSB1, este nao expoe GET /_search?q=… para sugestao rapida em UI de digitacao incremental. /_list?desc=… cobre o caso, mas devolve a Entidade inteira; _search devolveria so {codigo, desc}. Backlog se houver demanda do consumer.

Wrapper CT800EXC compartilhado entre 4 endpoints. Mudancas no helper U_CT800Exc afetam simultaneamente CadastroEntidade05/06/07/08. Cada slot que toca a lib deve revalidar smoke dos 4 antes de promover, mesmo que o caso de uso original seja so um plano.