rev1-2026-05-04 Protheus 12.1.33

RateioContabil

CRUD de Rateio Contábil (tabela CTQ) via MsExecAuto da rotina CTBA270. A estrutura é cabeçalho + array de itens: CTQ_RATEIO identifica o cabeçalho (chave natural fornecida pelo cliente, sem GetSXENum) e CTQ_SEQUEN identifica cada item. PUT substitui o conjunto inteiro de itens (não é merge).

Base URL https://erpapi.jetme.com.br/api/99/01 Empresa 99 · Filial 01

Vinculação com o ERP

Tabela mestre CTQ Rateio Contábil (cabeçalho + itens na mesma tabela)

Rotina automática CTBA270 MsExecAuto · cabeçalho + array de itens

Wrapper AdvPL U_CT270Exc src/lib/CTB/CT270EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Chave natural

CTQ_RATEIO fornecido pelo cliente

identificador externo · alfanumérico · até 6 chars
não há GetSXENum/Soma1; o cliente passa o código no path e o endpoint cria com esse valor (409 se já existir)

Cadastro

Bloqueio (estado administrativo)

tabela CTQ · campo CTQ_MSBLQL
SX3 pertence("12") · "1"=Inativo (bloqueado), "2"=Ativo (default)
sem CTQ_MSBLQD no dicionario — so o flag, sem vigencia
gate (U_C980Blq+fSoBlq) ainda nao implementado — slot _prep/wsctq-bloqueio pendente

Itens

Array itens obrigatório

POST e PUT exigem itens com no mínimo 1 elemento
PUT substitui todos os itens — não é merge por CTQ_SEQUEN

Convenções

Identificador externo. Todas as rotas /WsRateioContabil/<VERBO>/{rateio} aceitam CTQ_RATEIO como chave natural — string alfanumérica (até 6 caracteres). Diferente de cadastros com loja (SA1/SA2), aqui não há chave técnica gerada pelo ERP via GetSXENum; o cliente fornece o código no path. Tentativa de POST com chave já existente retorna 409.

Verbos no path. O endpoint usa WSSYNTAX com sufixo descritivo: POST /WsRateioContabil/INCLUIR/{rateio}, PUT /WsRateioContabil/ALTERAR/{rateio}, DELETE /WsRateioContabil/EXCLUIR/{rateio}. Convenção legada do framework REST do Protheus — o método HTTP correspondente continua sendo o canônico; o sufixo apenas atende ao roteador.

Cabeçalho + itens na mesma tabela. A CTQ guarda cabeçalho e linhas no mesmo alias: o cabeçalho é a linha com CTQ_SEQUEN em branco; os itens são as linhas subsequentes com a mesma CTQ_RATEIO. O GET remonta a estrutura aninhada (data.itens[]) na serialização REST.

PUT substitui, não mescla. O array itens enviado em PUT reescreve o conjunto inteiro de itens do rateio — CTQ_SEQUEN ausentes no payload são removidos. Para alteração granular, leia o rateio com GET antes, edite e devolva o array completo.

Bloqueio TOTVS (CTQ_MSBLQL). Flag SX3 pertence("12") com default "2". "1" = Inativo (bloqueado), "2" = Ativo (liberado). A polaridade segue o padrão SA1/ SA2 — outras tabelas TOTVS podem inverter, consultar SX3 antes de replicar. Esta versão expõe apenas CTQ_MSBLQL; não há campo CTQ_MSBLQD (data de vigência) no dicionário da CTQ, então não há caminho de bloqueio com vigência — apenas o flag administrativo.

Status de implementação. O gate canônico (U_C980Blq + fSoBlq) que devolve 422 quando o PUT em registro bloqueado toca qualquer campo além de CTQ_MSBLQL ainda não está implementado no WSCTQ.prw — slot _prep/wsctq-bloqueio pendente. Este documento descreve o contrato-alvo (mesmo padrão do WsSA1).

Paginação. /_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. A listagem devolve um item por rateio (cabeçalho + count_itens) — sem expandir os itens.

RateioContabil

CRUD por código do rateio (CTQ_RATEIO)

POST /WsRateioContabil/INCLUIR/{rateio} Inclui rateio (cabeçalho + itens)

Descrição

Cria um novo rateio na CTQ via CTBA270 em modo 3 (INSERT). O cliente fornece a chave CTQ_RATEIO no path; o cabeçalho e o array itens vão no body. Retorna 409 se a chave já existir.

O array itens é obrigatório e deve ter ao menos 1 elemento — caso contrário responde 422.
Whitelist de campos do cabeçalho: ver RateioContabilPayload.
Whitelist de campos do item: ver RateioItem.

Path parameter

rateio string · path · obrigatório CTQ.CTQ_RATEIO

Código do rateio (alfanumérico, máx 6 chars, sem espaços). Fornecido pelo cliente — não é gerado pelo ERP.

Request body

application/json RateioContabilPayload · obrigatório

Cabeçalho plano + array itens (≥1). Schema completo em RateioContabilPayload.

Payload mínimo — cabeçalho enxuto + 1 item com 100% de rateio. Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "CTQ_DESC": "RATEIO ZTEST",
  "CTQ_TIPO": "1",
  "CTQ_CTPAR": "11101",
  "CTQ_CTORI": "31101",
  "CTQ_PERBAS": 100,
  "CTQ_MSBLQL": "2",
  "itens": [
    {
      "CTQ_SEQUEN": "001",
      "CTQ_CTCPAR": "11301",
      "CTQ_UM": "AR",
      "CTQ_VALOR": 1000,
      "CTQ_PERCEN": 100,
      "CTQ_INTERC": "2",
      "CTQ_STATUS": "1"
    }
  ]
}

Rateio TI — exemplo realista com descrição editorial. Equivale ao bloco example: do openapi.yaml.

RequestHTTP/1.1 · application/json

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

{
  "CTQ_DESC": "RATEIO TI",
  "CTQ_TIPO": "1",
  "CTQ_CTPAR": "11101",
  "CTQ_CCPAR": "",
  "CTQ_CTORI": "31101",
  "CTQ_PERBAS": 100,
  "CTQ_MSBLQL": "2",
  "itens": [
    {
      "CTQ_SEQUEN": "001",
      "CTQ_CTCPAR": "11301",
      "CTQ_UM": "AR",
      "CTQ_VALOR": 1000,
      "CTQ_PERCEN": 100,
      "CTQ_INTERC": "2",
      "CTQ_STATUS": "1"
    }
  ]
}

Respostas

201

Rateio incluído. Envelope CrudResponse com data = CTQ_RATEIO.

400

Path vazio ou JSON inválido. Tier: validation-error.

409

Rateio já existe para o CTQ_RATEIO informado. Tier: business-error.

422

itens ausente ou vazio · enum inválido (CTQ_MSBLQL, CTQ_TIPO) · MsExecAuto do CTBA270 rejeitou (contas inexistentes, percentuais inválidos). Tier: business-error.

500

Erro interno.

GET /WsRateioContabil/{rateio} Consulta rateio (cabeçalho + itens)

Descrição

Retorna o rateio com seu cabeçalho e o array completo de itens (data.itens[]). Aplica filtro de filial (xFilial("CTQ")) e respeita os whitelists CAMPOS_CAB_GET e CAMPOS_ITEM_GET. O parâmetro opcional fields reduz o conjunto de campos retornados no cabeçalho.

Path parameter

rateio string · path · obrigatório CTQ.CTQ_RATEIO

Código do rateio (alfanumérico, máx 6 chars).

Query parameters

fields string · query · opcional

Lista de campos do cabeçalho separados por vírgula. Validados contra CAMPOS_CAB_GET.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Request · com fieldsHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsRateioContabil/ZZT?fields=CTQ_RATEIO,CTQ_DESC,CTQ_MSBLQL
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Rateio encontrado. Envelope { success: true, data: RateioContabil } com data.itens[] populado.

400

Path vazio ou fields com campo fora do whitelist. Tier: validation-error.

404

Rateio inexistente para o CTQ_RATEIO informado. Tier: not-found.

500

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

PUT /WsRateioContabil/ALTERAR/{rateio} Substitui cabeçalho e itens

Descrição

Altera o rateio via CTBA270 em modo 4 (UPDATE). PUT substitui o conjunto inteiro de itens — não há merge por CTQ_SEQUEN: qualquer item antigo ausente do payload é removido.

Bloqueio TOTVS. Em registro com CTQ_MSBLQL="1" (Inativo), o PUT só aceita payload que toque exclusivamente CTQ_MSBLQL (caminho de desbloqueio). Qualquer outro campo no cabeçalho ou presença de itens retorna 422.

itens é obrigatório em alteração comum (≥1 elemento).
Para desbloquear, envie apenas { "CTQ_MSBLQL": "2" } sem itens.

Path parameter

rateio string · path · obrigatório CTQ.CTQ_RATEIO

Código do rateio existente.

Request body

application/json RateioContabilPayload · obrigatório

Cabeçalho + array itens completo (substitui o existente). Em rateio bloqueado, ver convenções.

Alteração comum — atualiza descrição e ajusta valor do item. Fixture: fixtures/put-update.json.

RequestHTTP/1.1 · application/json

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

{
  "CTQ_DESC": "RATEIO ZTEST ALTERADO",
  "CTQ_TIPO": "1",
  "CTQ_CTPAR": "11101",
  "CTQ_CTORI": "31101",
  "CTQ_PERBAS": 100,
  "CTQ_MSBLQL": "2",
  "itens": [
    {
      "CTQ_SEQUEN": "001",
      "CTQ_CTCPAR": "11301",
      "CTQ_UM": "AR",
      "CTQ_VALOR": 2000,
      "CTQ_PERCEN": 100,
      "CTQ_INTERC": "2",
      "CTQ_STATUS": "1"
    }
  ]
}

Liberar registro bloqueado — caminho de desbloqueio. Em rateio bloqueado, esse é o único payload aceito; qualquer outro campo (inclusive itens) provoca 422.

RequestHTTP/1.1 · application/json

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

{
  "CTQ_MSBLQL": "2"
}

Respostas

200

Rateio alterado. Envelope CrudResponse.

400

Path vazio ou JSON inválido. Tier: validation-error.

404

Rateio inexistente. Tier: not-found.

422

Validação de payload (whitelist, enum, itens vazio) ou registro bloqueado com payload fora de CTQ_MSBLQL. Tier: business-error.

500

Erro interno.

DEL /WsRateioContabil/EXCLUIR/{rateio} Exclui rateio (cabeçalho + itens)

Descrição

Exclui o rateio via CTBA270 em modo 5 (DELETE). A operação remove o cabeçalho e todos os itens da CTQ em uma chamada. O MsExecAuto rejeita exclusão de rateio referenciado por outros cadastros (lançamentos contábeis, esqueletos) — nesse caso retorna 422 com o motivo.

Path parameter

rateio string · path · obrigatório CTQ.CTQ_RATEIO

Código do rateio existente.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Rateio excluído. Envelope CrudResponse.

400

Path vazio. Tier: validation-error.

404

Rateio inexistente. Tier: not-found.

422

Rateio bloqueado ou com dependências (lançamentos, esqueletos). Tier: business-error.

500

Erro interno.

GET /WsRateioContabil/_byid Consulta rateio por id técnico (recno|msuid)

Descrição

Busca o rateio por id técnico — útil para integrações que persistem recno ou msuid e querem reconfirmar o registro sem reconstruir a chave natural. Resolve o cabeçalho e retorna o mesmo schema do GET por código, com data.itens[] populado.

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).

Chamada de exemplo

Request · por recnoHTTP/1.1 · sem body

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

Request · por msuidHTTP/1.1 · sem body

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

Respostas

200

Rateio encontrado. Envelope { success: true, data: RateioContabil }.

400

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

404

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

501

Busca por msuid requer índice/coluna não disponível no ambiente.

500

Erro interno.

Listagem

Listagem paginada de rateios (um item por cabeçalho)

GET /WsRateioContabil/_list Lista rateios com filtros e paginação

Descrição

Lista os rateios com filtros por prefixo de cod (CTQ_RATEIO) e desc (CTQ_DESC). Devolve um item por rateio — apenas o cabeçalho + count_itens (contagem de itens), sem expandir o array de itens. Suporta 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 CTQ.CTQ_RATEIO

Prefix de CTQ_RATEIO.

desc string · query · opcional CTQ.CTQ_DESC

Prefix de CTQ_DESC.

fields string · query · opcional

Lista de campos validados contra CAMPOS_CAB_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

Início do delta-sync (válido com orderBy=recno).

cursor integer · query · opcional

Cursor retornado em nextCursor de página anterior.

Chamada de exemplo

Request · paginação por chaveHTTP/1.1 · sem body

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

Request · delta-sync por recnoHTTP/1.1 · sem body

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

Respostas

200

Página de rateios. Envelope com data[] contendo CTQ_RATEIO, CTQ_DESC, count_itens, recno; mais 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

RateioContabil

object

Representação retornada nos GETs (/{rateio}, /_byid). Inclui cabeçalho da CTQ e o array itens. Campos efetivamente retornados dependem de CAMPOS_CAB_GET e do filtro fields.

CTQ_RATEIOstring · obrigatórioCTQ.CTQ_RATEIO

Código do rateio (chave natural, alfanumérico, máx 6).

CTQ_DESCstring · opcionalCTQ.CTQ_DESC

Descrição editorial do rateio.

CTQ_TIPOstring · opcionalCTQ.CTQ_TIPO

Tipo do rateio (combobox SX3).

CTQ_CTPARstring · opcionalCTQ.CTQ_CTPAR

Conta partida (lado a ratear).

CTQ_CCPARstring · opcionalCTQ.CTQ_CCPAR

Centro de custo partida.

CTQ_CTORIstring · opcionalCTQ.CTQ_CTORI

Conta origem (base do rateio).

CTQ_CCORIstring · opcionalCTQ.CTQ_CCORI

Centro de custo origem.

CTQ_PERBASnumber · opcionalCTQ.CTQ_PERBAS

Percentual base do rateio (tipicamente 100).

CTQ_MSBLQLstring · opcionalCTQ.CTQ_MSBLQL

Flag de bloqueio TOTVS-padrão. SX3 pertence("12"), default "2". "1"=Inativo (bloqueado), "2"=Ativo (liberado).

12

itensarray<RateioItem> · opcional

Array de itens do rateio. Schema em RateioItem.

countinteger · opcional

Quantidade de itens retornados.

recnointeger · opcional

Id técnico do cabeçalho (RecNo do AdvPL).

msuidstring · opcional

Identificador universal MS_UID.

msuidtstring · opcional

Timestamp técnico associado ao msuid.

RateioItem

object

Item do rateio. Cada linha vive na mesma tabela CTQ que o cabeçalho, identificada por CTQ_SEQUEN. Whitelists separadas: leitura por CAMPOS_ITEM_GET, gravação por CAMPOS_ITEM_ALLOW.

CTQ_SEQUENstring · obrigatórioCTQ.CTQ_SEQUEN

Sequência do item (ordena dentro do rateio, ex: "001").

CTQ_CTCPARstring · opcionalCTQ.CTQ_CTCPAR

Conta contrapartida do item.

CTQ_CCCPARstring · opcionalCTQ.CTQ_CCCPAR

Centro de custo contrapartida.

CTQ_ITCPARstring · opcionalCTQ.CTQ_ITCPAR

Item contábil contrapartida.

CTQ_CLCPARstring · opcionalCTQ.CTQ_CLCPAR

Classe de valor contrapartida.

CTQ_UMstring · opcionalCTQ.CTQ_UM

Unidade de medida do item (ex: "AR").

CTQ_VALORnumber · opcionalCTQ.CTQ_VALOR

Valor do item (preserva tipo numérico no JSON).

CTQ_PERCENnumber · opcionalCTQ.CTQ_PERCEN

Percentual do item (soma esperada = CTQ_PERBAS).

CTQ_INTERCstring · opcionalCTQ.CTQ_INTERC

Indicador de intercompany (combobox SX3).

CTQ_STATUSstring · opcionalCTQ.CTQ_STATUS

Status do item (combobox SX3).

RateioContabilPayload

object

Payload aceito em POST e PUT. Whitelist do cabeçalho em CAMPOS_CAB_ALLOW, dos itens em CAMPOS_ITEM_ALLOW. O array itens é obrigatório (≥1 elemento), exceto no caminho de desbloqueio (PUT com apenas CTQ_MSBLQL).

CTQ_DESCstring · opcionalCTQ.CTQ_DESC

Descrição editorial.

CTQ_TIPOstring · opcionalCTQ.CTQ_TIPO

Tipo do rateio (combobox SX3).

CTQ_CTPARstring · opcionalCTQ.CTQ_CTPAR

Conta partida.

CTQ_CCPARstring · opcionalCTQ.CTQ_CCPAR

Centro de custo partida.

CTQ_ITPARstring · opcionalCTQ.CTQ_ITPAR

Item contábil partida.

CTQ_CLPARstring · opcionalCTQ.CTQ_CLPAR

Classe de valor partida.

CTQ_CTORIstring · opcionalCTQ.CTQ_CTORI

Conta origem.

CTQ_CCORIstring · opcionalCTQ.CTQ_CCORI

Centro de custo origem.

CTQ_ITORIstring · opcionalCTQ.CTQ_ITORI

Item contábil origem.

CTQ_CLORIstring · opcionalCTQ.CTQ_CLORI

Classe de valor origem.

CTQ_PERBASnumber · opcionalCTQ.CTQ_PERBAS

Percentual base.

CTQ_MSBLQLstring · opcionalCTQ.CTQ_MSBLQL

Flag de bloqueio TOTVS-padrão (SX3 pertence("12"), default "2"): "1"=Inativo, "2"=Ativo. MsExecAuto do CTBA270 rejeita valores fora do domínio.

12

itensarray<RateioItem> · obrigatório (≥1)

Itens do rateio. Mínimo 1; o PUT substitui o conjunto inteiro. Schema do elemento em RateioItem.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz o CTQ_RATEIO envolvido na operação (POST/PUT/DELETE) ou objeto auxiliar quando aplicável.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring | object · opcional

Em POST, contém o CTQ_RATEIO incluído. 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) 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).