Integra Contador: DCTFWeb

Endpoints da WebApiAlcance que expõem os serviços da DCTFWeb (Declaração de Débitos e Créditos Tributários Federais Web) através do Integra Contador do Serpro. Cada rota monta o pacote padrão do Integra Contador (contratante, autorPedidoDados, contribuinte, pedidoDados) e aciona um serviço específico do sistema DCTFWEB - emitir guia (DARF), consultar recibo de transmissão, obter o relatório completo da declaração e emitir guia de valores em andamento.

Duas rotas foram REMOVIDAS da API

POST /integra-contador/dctf/consultar-xml e POST /integra-contador/dctf/transmitir não existem mais: foram retiradas da WebApi e não ganharam alias de compatibilidade. Elas validavam o corpo contra schemas que não correspondiam ao contrato do Serpro e nunca chegaram a operar. Chamadas a esses caminhos passam a responder 404.

O substituto é DCTFWeb: Transmissão, sob o prefixo consolidado /api/v1/dctfweb/transmissao. Não é uma renomeação: o contrato é outro (a consulta do XML virou etapa interna do fluxo, não uma rota), e transmitir passou a exigir perfil administrador/diretoria e sessão de usuário - API Key é recusada.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O contratante e o autor do pedido são fixos, definidos por variáveis de ambiente (SERPRO_ECOMMERCE_CONTRATANTE_* e SERPRO_AUTOR_*) - o cliente envia apenas dados e contribuinte. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/integra-contador/dctf

Escopos necessários

O escopo é derivado da rota: o recurso vem do primeiro segmento após /api/v1/, ou seja integra-contador → integra_contador (hífen → underscore), e o método HTTP define a ação (read para GET/HEAD/OPTIONS, write para POST/PUT/PATCH/DELETE).

integra_contador:write - todas as rotas deste router são POST, portanto todas exigem a ação write.
integra_contador:read - não é usado por nenhuma rota do DCTFWeb (não há GET aqui), mas pertence ao mesmo recurso.

Escopo compartilhado

O recurso integra_contador é compartilhado por todos os módulos sob /api/v1/integra-contador/* - Simples Nacional (/sn), DCTFWeb (/dctf), MIT (/mit) e Radar (/radar/*). Uma API Key com integra_contador:write autoriza operações de escrita em qualquer um deles, pois o escopo é resolvido apenas pelo primeiro segmento da rota. Conceda-o com cautela.

Envelope de resposta

Toda resposta segue o envelope padrão:

{
  "success": true,
  "message": "...",
  "data": {}
}

Em erro de validação de dados, a API responde 422 Unprocessable Entity com detail contendo errors, um hint de campos obrigatórios ausentes e, quando disponível, um example.

Payload de entrada

Todas as rotas recebem o mesmo envelope de entrada (OnlyContribuintePayload):

Campo	Tipo	Obrigatório	Descrição
`dados`	`object`	sim	Objeto específico do serviço acionado (validado por schema - ver abaixo).
`contribuinte`	`object`	sim	Identificação do contribuinte (`ParteIdentificacao`).

O contribuinte segue o schema ParteIdentificacao: tipo (1 = PF/CPF, 2 = PJ/CNPJ) e numero (CPF ou CNPJ, preferencialmente só dígitos).

Chamada síncrona ao Serpro

Estas rotas não enfileiram tasks Celery. Cada requisição monta um IntegraRequest e chama o Integra Contador do Serpro de forma síncrona (SerproHttpClient.call), com idSistema = "DCTFWEB" e o idServico correspondente. O tipo de acionamento (Emitir / Consultar) é resolvido pelo mapa de serviços. Automações em lote de DCTFWeb ficam no módulo Radar (/integra-contador/radar/*), fora deste router.

Endpoints

`POST /integra-contador/dctf/gerar-guia`

Emite o documento de arrecadação (DARF) da DCTFWeb. Aciona o serviço Serpro GERARGUIA31 (tipo Emitir) do sistema DCTFWEB.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (OnlyContribuintePayload): dados valida contra o schema DCTFWebGerarGuiaDados (obrigatórios categoria, anoPA, mesPA; aceita campos extras) e contribuinte segue ParteIdentificacao.

Request

{
  "dados": {
    "categoria": "GERAL_MENSAL",
    "anoPA": 2025,
    "mesPA": 8,
    "tipoDar": "ORIGINAL",
    "tipoIdentificacaoGeracaoDocumento": "CNPJ",
    "identificador": "00000000000000"
  },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Guia gerada com sucesso.",
  "data": {}
}

Escopo: integra_contador:write

`POST /integra-contador/dctf/consultar-recibo`

Consulta o recibo de transmissão da declaração. Aciona o serviço Serpro CONSRECIBO32 (tipo Consultar).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (OnlyContribuintePayload): dados valida contra o schema DCTFWebConsultarReciboDados (obrigatórios categoria, anoPA, mesPA; aceita campos extras) e contribuinte segue ParteIdentificacao.

Request

{
  "dados": { "categoria": "GERAL_MENSAL", "anoPA": 2025, "mesPA": 8 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Recibo consultado com sucesso.",
  "data": {
    "numeroRecibo": "0000000000000000",
    "dataTransmissao": "2025-09-15T10:20:00-03:00"
  }
}

Escopo: integra_contador:write

`POST /integra-contador/dctf/consultar-relatorio-completo`

Retorna o relatório completo da declaração. Aciona o serviço Serpro CONSDECCOMPLETA33 (tipo Consultar).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (OnlyContribuintePayload): dados valida contra o schema DCTFWebConsultarRelatorioCompletoDados (obrigatórios categoria, anoPA; mesPA e diaPA podem ser exigidos conforme a categoria; aceita campos extras) e contribuinte segue ParteIdentificacao.

Request

{
  "dados": { "categoria": "GERAL_MENSAL", "anoPA": 2025, "mesPA": 8 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Relatório completo consultado com sucesso.",
  "data": {}
}

Escopo: integra_contador:write

`POST /integra-contador/dctf/gerar-guia-andamento`

Emite a guia (DARF) considerando valores da apuração em andamento. Aciona o serviço Serpro GERARGUIAANDAMENTO313 (tipo Emitir).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (OnlyContribuintePayload): dados valida contra o schema DCTFWebGerarGuiaAndamentoDados (obrigatórios categoria fixa em GERAL_MENSAL, anoPA, mesPA; aceita campos extras) e contribuinte segue ParteIdentificacao.

Request

{
  "dados": {
    "categoria": "GERAL_MENSAL",
    "anoPA": 2025,
    "mesPA": 8,
    "tipoDar": "ORIGINAL",
    "tipoIdentificacaoGeracaoDocumento": "CNPJ",
    "identificador": "00000000000000"
  },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Guia em andamento gerada com sucesso.",
  "data": {}
}

Escopo: integra_contador:write

Enum `DCTFCategoria`

Valores aceitos no campo categoria. O Serpro aceita o rótulo (string) ou o código numérico; estas rotas enviam o rótulo.

Valor	Código	Descrição
`GERAL_MENSAL`	`40`	Mensal - Pessoa Jurídica.
`GERAL_13o_SALARIO`	`41`	13º salário - Pessoa Jurídica (anual, sem `mesPA`).
`AFERICAO`	`44`	Aferição de obra (CNO). Grafia sem acento, conforme o contrato.
`ESPETACULO_DESPORTIVO`	`45`	Espetáculo desportivo (exige `diaPA`).
`RECLAMATORIA_TRABALHISTA`	`46`	Reclamatória trabalhista (exige `numProcReclamatoria`).
`PF_MENSAL`	`50`	Mensal - Pessoa Física.
`PF_13o_SALARIO`	`51`	13º salário - Pessoa Física (anual, sem `mesPA`).

Correção: `RETIFICACAO` e `RECLAMATORIA` nunca existiram

Versões anteriores desta página listavam RETIFICACAO e RECLAMATORIA como valores do enum. Nenhum dos dois existe no contrato do Integra Contador e ambos foram removidos do código. Não há categoria de retificação: retificar é indicado dentro do XML, na tag indRetificacao, e não trocando a categoria da declaração. O valor correto para reclamatória trabalhista é RECLAMATORIA_TRABALHISTA (código 46).

O catálogo completo, com nome amigável, descrição e campos condicionais de cada categoria, é servido pela própria API em GET /dctfweb/categorias.

Schemas

`DCTFWebGerarGuiaDados`

Serviço GERARGUIA31. Aceita campos extras (extra="allow").

Campo	Tipo	Obrigatório	Observações
`categoria`	`DCTFCategoria`	sim	Ex.: `GERAL_MENSAL`.
`anoPA`	`int`	sim	Ano de Apuração (ex.: `2025`).
`mesPA`	`int` (1-12)	sim	Mês de Apuração.
`tipoDar`	`str`	não	Opcional.
`tipoEmissao`	`str`	não	Opcional.
`darProcuracao`	`bool`	não	Opcional.
`tipoIdentificacaoGeracaoDocumento`	`str`	não	Geralmente `"CNPJ"`.
`identificador`	`str`	não	CNPJ (somente números).
`numeroReciboEntrega`	`str`	não	Opcional.

`DCTFWebConsultarReciboDados`

Serviço CONSRECIBO32. Aceita campos extras (extra="allow").

Campo	Tipo	Obrigatório	Observações
`categoria`	`DCTFCategoria`	sim	-
`anoPA`	`int`	sim	Ano de Apuração.
`mesPA`	`int` (1-12)	sim	Mês de Apuração.
`diaPA`	`int` (1-31)	não	Opcional.
`cnoAfericao`	`str`	não	Opcional.
`numeroReciboEntrega`	`str`	não	Opcional.
`numProcReclamatoria`	`str`	não	Opcional.

`DCTFWebConsultarRelatorioCompletoDados`

Serviço CONSDECCOMPLETA33. Aceita campos extras (extra="allow").

Campo	Tipo	Obrigatório	Observações
`categoria`	`DCTFCategoria`	sim	-
`anoPA`	`int`	sim	Ano de Apuração.
`mesPA`	`int` (1-12)	não	Pode ser exigido conforme a categoria.
`diaPA`	`int` (1-31)	não	Pode ser exigido conforme a categoria.
`cnoAfericao`	`str`	não	Opcional.
`numeroReciboEntrega`	`str`	não	Opcional.
`numProcReclamatoria`	`str`	não	Opcional.

`DCTFWebGerarGuiaAndamentoDados`

Serviço GERARGUIAANDAMENTO313. Aceita campos extras (extra="allow").

Campo	Tipo	Obrigatório	Observações
`categoria`	`"GERAL_MENSAL"`	sim	Categoria fixa para guia mensal em andamento.
`anoPA`	`int`	sim	Ano de Apuração.
`mesPA`	`int` (1-12)	sim	Mês de Apuração.
`tipoDar`	`str`	não	Opcional.
`tipoEmissao`	`str`	não	Opcional.
`darProcuracao`	`bool`	não	Opcional.
`tipoIdentificacaoGeracaoDocumento`	`str`	não	Geralmente `"CNPJ"`.
`identificador`	`str`	não	CNPJ (somente números).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Contratante e autor do pedido nunca são enviados pelo cliente - são injetados a partir do .env (SERPRO_ECOMMERCE_CONTRATANTE_*, SERPRO_AUTOR_*). Se não configurados, a API responde 500.
O campo dados é serializado como string JSON escapada dentro de pedidoDados antes de ir ao Serpro - o cliente sempre envia dados como objeto.
Os 4 endpoints são POST e, portanto, exigem integra_contador:write - escopo compartilhado com Simples Nacional, MIT e Radar sob /integra-contador/*.
consultar-xml e transmitir foram removidos da API e não têm alias de compatibilidade (ver aviso no topo da página). Para transmitir a declaração, use /api/v1/dctfweb/transmissao.
Para automações/lotes de DCTFWeb (guias e recibos), use o prefixo consolidado /api/v1/dctfweb/emissao/*. Os caminhos antigos /integra-contador/radar/{guias,recibos}/* continuam funcionando, porém deprecados.