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, recuperar o XML, transmitir a declaração assinada e emitir guia de valores em andamento.

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/consultar-xml`

Recupera o XML da declaração. Aciona o serviço Serpro CONSXMLDECLARACAO38 (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 DCTFWebConsultarXmlDados (obrigatório numeroControle) e contribuinte segue ParteIdentificacao.

Request

{
  "dados": { "numeroControle": "2025-08-ABCDEF1234567890" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "XML da declaração recuperado com sucesso.",
  "data": {}
}

Escopo: integra_contador:write

`POST /integra-contador/dctf/transmitir`

Transmite a declaração assinada. Aciona o serviço Serpro TRANSDECLARACAO310 (tipo transmissão).

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 DCTFWebTransmitirDados (obrigatórios numeroControle e conteudoAssinado, documento assinado em base64) e contribuinte segue ParteIdentificacao.

Request

{
  "dados": {
    "numeroControle": "2025-08-ABCDEF1234567890",
    "conteudoAssinado": "<base64>"
  },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Declaração transmitida 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:

Valor	Descrição
`GERAL_MENSAL`	Declaração geral mensal.
`RETIFICACAO`	Declaração retificadora.
`AFERICAO`	Aferição (grafia sem acento conforme documentação).
`RECLAMATORIA`	Reclamatória trabalhista.

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.

`DCTFWebConsultarXmlDados`

Serviço CONSXMLDECLARACAO38.

Campo	Tipo	Obrigatório	Observações
`numeroControle`	`str`	sim	Número de controle da declaração (UUID/ID).

`DCTFWebTransmitirDados`

Serviço TRANSDECLARACAO310.

Campo	Tipo	Obrigatório	Observações
`numeroControle`	`str`	sim	Número de controle da declaração (UUID/ID).
`conteudoAssinado`	`str`	sim	Documento assinado em base64.

`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.
Todos os 6 endpoints são POST e, portanto, exigem integra_contador:write - escopo compartilhado com Simples Nacional, MIT e Radar sob /integra-contador/*.
Para automações/lotes de DCTFWeb (guias, recibos, pagamentos), consulte o módulo Radar em /api/v1/integra-contador/radar/*.