DCTFWeb: Catálogos

Dois endpoints de leitura pura que expõem o vocabulário da DCTFWeb: as categorias de declaração e os sistemas de origem da guia. São os catálogos que a interface consome para montar seletores, rótulos e regras de campo condicional sem reimplementar as tabelas em TypeScript.

Nenhum dos dois toca o Serpro, o banco ou qualquer emissão - são estáticos por natureza, porque o domínio é definido pela Receita e não é configurável por cliente. Vêm por HTTP, e não hard-coded no front, para que rótulo, descrição e ressalva possam ser corrigidos sem redeploy do frontend.

Base path

/api/v1/dctfweb

Os dois caminhos são completos, sem sub-prefixo: /dctfweb/categorias e /dctfweb/sistemas-origem.

Escopos necessários

• dctfweb:read - as duas rotas são GET.

Estes caminhos nasceram sob o prefixo consolidado: não existe alias legado para eles, e nunca existiram sob /dctfweb-guias, /dctfweb-recibos ou /integra-contador/*.

Endpoints

GET /dctfweb/categorias

Catálogo das 7 categorias de declaração da DCTFWeb, ordenado por código.

Parâmetros

Nenhum - sem parâmetros de rota, query ou corpo.

Response 200 OK

{
  "status": "success",
  "message": "Categorias da DCTFWeb recuperadas com sucesso!",
  "data": [
    {
      "codigo": 40,
      "rotulo": "GERAL_MENSAL",
      "nome": "Mensal — Pessoa Jurídica",
      "descricao": "A declaração do dia a dia da empresa. Use no fechamento de cada competência para declarar as contribuições previdenciárias e as retenções apuradas naquele mês.",
      "exigeMesPA": true,
      "camposExtras": [],
      "habilitadaTransmissao": true,
      "observacao": ""
    },
    {
      "codigo": 41,
      "rotulo": "GERAL_13o_SALARIO",
      "nome": "13º salário — Pessoa Jurídica",
      "descricao": "Declaração exclusiva da folha do décimo terceiro salário. É ANUAL: não se informa mês de apuração, apenas o ano.",
      "exigeMesPA": false,
      "camposExtras": [],
      "habilitadaTransmissao": true,
      "observacao": "Não informe o mês de apuração — esta declaração é anual."
    }
  ]
}

O data é uma lista, não um objeto.

Escopo: dctfweb:read

Campos de cada item

As 7 categorias

Todas retornam habilitadaTransmissao: true hoje.

Regras de campo condicional

O que a interface precisa derivar do catálogo, sem if por categoria espalhado no código:

• mesPA - obrigatório em todas, exceto nas categorias de 13º salário (41 e 51), que são anuais: nelas se informa apenas anoPA. É exatamente o que exigeMesPA: false sinaliza.
• diaPA - existe somente na categoria 45 (espetáculo desportivo). A apuração é por dia do evento.
• numProcReclamatoria - existe somente na categoria 46 (reclamatória trabalhista). É o número do processo na Justiça do Trabalho.
• cnoAfericao - existe somente na categoria 44 (aferição de obra). É o número da obra (CNO).

Cada um desses campos aparece em camposExtras da categoria correspondente - prefira ler camposExtras a repetir a regra no cliente.

GET /dctfweb/sistemas-origem

Catálogo dos 5 sistemas de origem da guia (idsSistemaOrigem), mais os presets sugeridos e a observação sobre omissão do campo.

Parâmetros

Nenhum - sem parâmetros de rota, query ou corpo.

Response 200 OK

{
  "status": "success",
  "message": "Sistemas de origem recuperados com sucesso!",
  "data": {
    "sistemas": [
      {
        "codigo": 1,
        "rotulo": "eSocial",
        "nome": "eSocial (folha de pagamento)",
        "descricao": "Traz para a guia as contribuições previdenciárias apuradas na folha enviada ao eSocial: INSS descontado dos segurados, contribuição patronal, RAT/FAP e Terceiros, incluindo 13º salário e rescisões.",
        "presets": ["pessoal"]
      },
      {
        "codigo": 8,
        "rotulo": "MIT",
        "nome": "MIT — Módulo de Inclusão de Tributos",
        "descricao": "Traz para a guia os débitos não previdenciários informados no MIT dentro da DCTFWeb (IRPJ, CSLL, PIS, COFINS, IPI, IOF e demais tributos federais da apuração fiscal).",
        "presets": ["fiscal"]
      }
    ],
    "presets": {
      "pessoal": [1, 6, 7],
      "fiscal": [8]
    },
    "observacao": "Campo opcional no Integra Contador: quando informado, a guia é gerada contendo apenas as receitas dos sistemas de origem escolhidos; quando omitido, a guia sai com todas as receitas."
  }
}

Escopo: dctfweb:read

Estrutura do data

Cada item de sistemas:

Os 5 sistemas

Não há códigos 2, 3 e 4 - a numeração do domínio oficial é descontínua.

Presets

São sugestões de valor inicial para a tela, espelhando o que os fluxos de emissão já enviam hoje ([1, 6, 7] na variante eSocial, [8] na variante MIT). Não são restrições: qualquer subconjunto não vazio dos 5 códigos é válido, inclusive combinando pessoal e fiscal na mesma guia - o próprio exemplo oficial do Integra Contador mistura eSocial e MIT ([1, 8]).

Demais regras de validação

Quando o campo é informado, a lista é validada de forma fail-closed antes de qualquer chamada ao Serpro - o valor segue cru para a Receita, e o erro do gateway (APIGUIA03 — IdSistemaOrigem inválido: X) é opaco. As regras:

Violações resultam em 422, com a mensagem em pt-BR e a lista dos códigos aceitos.

Notas

• Os dois endpoints são GET puros: não leem banco, não chamam o Serpro e não têm efeito colateral. São seguros para cachear no cliente por sessão.
• As categorias vêm da mesma fonte de verdade que alimenta as regras condicionais dos schemas de emissão e transmissão - o catálogo não é uma segunda tabela que possa divergir.
• Os textos de nome, descricao e observacao são apenas de exibição: nenhuma lógica os lê. Podem ser reescritos sem impacto funcional.
• Prefira consumir exigeMesPA e camposExtras a codificar as regras por categoria no cliente - foi para isso que o catálogo foi exposto.