DCTFWeb: Transmissão

Endpoints da WebApiAlcance que entregam a declaração da DCTFWeb à Receita Federal pelo Integra Contador (Serpro), serviço TRANSDECLARACAO310, mais o histórico de tentativas e a consulta da situação da declaração no fisco.

É a única superfície da DCTFWeb que escreve no fisco. Todo o resto do domínio - Guias, Recibos, Emissão e Catálogos - consulta, coleta ou registra. Aqui a operação é irreversível: não existe rota que cancele ou desfaça uma transmissão.

Base path

/api/v1/dctfweb/transmissao

A consulta de situação fica fora desse sub-prefixo, em /api/v1/dctfweb/situacao: ela é leitura pura e não faz parte do recurso "transmissão".

Escopos necessários

• dctfweb:write - POST /dctfweb/transmissao/ e POST /dctfweb/transmissao/simular.
• dctfweb:read - GET /dctfweb/transmissao/, GET /dctfweb/transmissao/{transmissao_id} e GET /dctfweb/situacao.

O recurso vem do primeiro segmento do path (dctfweb) e a ação, do método HTTP. Estes caminhos nasceram sob o prefixo consolidado: não existe alias legado para eles. Tokens emitidos antes da consolidação não carregam dctfweb:read / dctfweb:write - relogue ou atualize a API Key.

Envelope

As cinco rotas usam o envelope padrão da WebApi:

{
  "status": "success",
  "message": "Mensagem em PT-BR",
  "data": {}
}

Erros têm duas formas, e a diferença importa para quem trata a resposta:

A segunda forma é o handler global de erros da WebApi: ele serializa o detail sob a chave message, não detail. Nas recusas vindas do Serpro, message é um objeto (ver Erros do Serpro); na validação dos query params de GET /dctfweb/situacao, é uma lista de { "loc", "msg" }.

Como a transmissão funciona

Uma chamada a POST /dctfweb/transmissao/ executa, do lado do servidor, três etapas contra o Integra Contador - o consumidor da API não faz nenhuma delas:

Depois do sucesso vem o encadeamento, na mesma operação: CONSRECIBO32 (recibo de entrega, com PDF) + GERARGUIA31 (DARF). Os artefatos são gravados nos registros internos de Recibos e Guias, e seus IDs voltam na resposta.

Endpoints

POST /dctfweb/transmissao/

Transmite (ou retransmite) a declaração da DCTFWeb do período informado. Responde 200 OK - inclusive quando o desfecho é "já estava transmitida".

Parâmetros

Sem parâmetros de rota ou query - os dados vão no corpo (DctfwebTransmitirRequest, ver DctfwebTransmitirRequest).

Request

{
  "cnpj": "27898481000150",
  "categoria": "GERAL_MENSAL",
  "anoPA": "2026",
  "mesPA": "04",
  "idsSistemaOrigem": [1, 6, 7]
}

Response 200 OK

{
  "status": "success",
  "message": "Transmissão processada.",
  "data": {
    "id": 118,
    "id_cliente": 123,
    "cnpj": "27898481000150",
    "categoria": "GERAL_MENSAL",
    "competencia": "2026-04",
    "modo": "real",
    "estado": "transmitida",
    "mensagem": "Declaração transmitida com sucesso à Receita Federal.",
    "codigo_serpro": null,
    "classe_desfecho": null,
    "numero_recibo": "12.34.56.78-90",
    "encadeamento": {
      "estado": "ok",
      "numero_recibo": "12.34.56.78-90",
      "id_recibo": 5120,
      "id_guia": 8830,
      "detalhe": null
    },
    "payload_simulado": null
  }
}

O campo estado é o que decide o que fazer em seguida:

transmitida e ja_transmitida não foram fundidas de propósito: as duas significam "a declaração está entregue", mas só a primeira significa "foi esta execução que a entregou". A auditoria depende dessa diferença.

Escopo: dctfweb:write + perfil administrador ou diretoria + sessão de usuário (API Key recusada)

POST /dctfweb/transmissao/simular

DRY-RUN. Executa as etapas 1 e 2 (consulta o XML na Receita e assina com o certificado A1), monta o payload do TRANSDECLARACAO310 e para antes do envio. Responde 200 OK.

Serve para conferir exatamente o que seria enviado sem declarar nada: qual período, qual recibo alvo, qual categoria, e se o XML da apuração já existe e é assinável. É a forma de validar o fluxo inteiro contra produção sem tocar no fisco.

Parâmetros

Sem parâmetros de rota ou query - o corpo é o mesmo DctfwebTransmitirRequest da transmissão real. forcar_retransmissao é aceito, mas irrelevante aqui: a simulação não passa pelos guards de idempotência, de propósito - o dry-run precisa continuar disponível justamente quando o período já está transmitido, que é o caso da conferência de uma retransmissão.

Request

{
  "cnpj": "27898481000150",
  "categoria": "GERAL_MENSAL",
  "anoPA": "2026",
  "mesPA": "04"
}

Response 200 OK

{
  "status": "success",
  "message": "Simulação concluída — nada foi transmitido à Receita.",
  "data": {
    "id": 117,
    "id_cliente": 123,
    "cnpj": "27898481000150",
    "categoria": "GERAL_MENSAL",
    "competencia": "2026-04",
    "modo": "simulacao",
    "estado": "simulada",
    "mensagem": "Simulação concluída. O XML foi consultado e assinado, e o payload abaixo é EXATAMENTE o que seria enviado — nada foi transmitido à Receita.",
    "codigo_serpro": "DRY-RUN",
    "classe_desfecho": null,
    "numero_recibo": null,
    "encadeamento": null,
    "payload_simulado": {
      "idSistema": "DCTFWEB",
      "idServico": "TRANSDECLARACAO310",
      "acionamento": "/Declarar",
      "contribuinte": { "tipo": 2, "numero": "27898481000150" },
      "dados": {
        "categoria": "GERAL_MENSAL",
        "anoPA": "2026",
        "mesPA": "04"
      },
      "xml_assinado": {
        "tamanho": 412880,
        "sha256": "9f2a1c7d3b5e0a44",
        "preview": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48UHJvY0RjdGY"
      },
      "xml_original": {
        "tamanho": 401220,
        "sha256": "3b77de91c04a5f28",
        "preview": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48UHJvY0RjdGY"
      }
    }
  }
}

Observe que payload_simulado.dados traz o payload completo, exceto xmlAssinadoBase64 - o XML assinado da DCTFWeb tem de centenas de KB a megabytes, e devolvê-lo estouraria payload, log e tela sem ajudar ninguém. No lugar dele vem um resumo verificável (tamanho + sha256 + preview), que serve para comparar duas execuções e confirmar que o XML existe e mudou (ou não).

Uma simulação é registrada no histórico, com modo: "simulacao" e estado: "simulada", e é excluída do guard de idempotência - um dry-run não prova nada sobre o que a Receita tem registrado.

Escopo: dctfweb:write + perfil administrador ou diretoria + sessão de usuário (API Key recusada)

GET /dctfweb/transmissao/

Histórico de transmissões (trilha de auditoria fiscal), no envelope paginado, com filtros e ordenação. Um registro por tentativa - inclusive as simuladas e as que falharam.

Parâmetros de query

Request

GET /api/v1/dctfweb/transmissao/?id_cliente=123&estado=indeterminado&page=1&per_page=20

Response 200 OK

{
  "status": "success",
  "message": "Transmissões recuperadas com sucesso!",
  "data": {
    "items": [
      {
        "id": 118,
        "id_cliente": 123,
        "id_usuario": 7,
        "atividade_id": 90514,
        "categoria": "GERAL_MENSAL",
        "competencia": "2026-04",
        "modo": "real",
        "estado": "transmitida",
        "numero_recibo": "12.34.56.78-90",
        "codigo_serpro": null,
        "classe_desfecho": null,
        "mensagem": "Declaração transmitida com sucesso à Receita Federal.",
        "id_recibo": 5120,
        "id_guia": 8830,
        "encadeamento_estado": "ok",
        "data_hora_inicio": "2026-08-05T09:12:44-03:00",
        "data_hora_desfecho": "2026-08-05T09:13:29-03:00"
      }
    ],
    "total": 1,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 20
  }
}

A listagem não traz encadeamento_detalhe (texto longo, pode concatenar várias mensagens) nem os campos do período (ano_pa, mes_pa, dia_pa, cno_afericao, num_proc_reclamatoria, chave_periodo, numero_recibo_alvo, ids_sistema_origem). Para o registro completo use GET /dctfweb/transmissao/{transmissao_id}.

Ordenação

sort_by aceita apenas estes valores; qualquer outro resulta em 422 (validação do FastAPI):

Há desempate estável por id, na mesma direção do sort_dir - sem ele, valores repetidos deixariam a ordem indefinida entre páginas.

Escopo: dctfweb:read

GET /dctfweb/transmissao/{transmissao_id}

Detalhe de uma transmissão, com o registro completo - incluindo o período discriminado e o encadeamento_detalhe.

Parâmetros de rota

Response 200 OK

{
  "status": "success",
  "message": "Transmissão encontrada com sucesso!",
  "data": {
    "id": 118,
    "id_cliente": 123,
    "id_usuario": 7,
    "atividade_id": 90514,
    "categoria": "GERAL_MENSAL",
    "competencia": "2026-04",
    "chave_periodo": "GERAL_MENSAL|2026|04|-|-|-",
    "ano_pa": "2026",
    "mes_pa": "04",
    "dia_pa": null,
    "cno_afericao": null,
    "num_proc_reclamatoria": null,
    "modo": "real",
    "estado": "transmitida",
    "numero_recibo": "12.34.56.78-90",
    "numero_recibo_alvo": null,
    "codigo_serpro": null,
    "classe_desfecho": null,
    "mensagem": "Declaração transmitida com sucesso à Receita Federal.",
    "ids_sistema_origem": "1,6,7",
    "id_recibo": 5120,
    "id_guia": 8830,
    "encadeamento_estado": "ok",
    "encadeamento_detalhe": null,
    "data_hora_inicio": "2026-08-05T09:12:44-03:00",
    "data_hora_desfecho": "2026-08-05T09:13:29-03:00"
  }
}

ID inexistente retorna 404 com "Transmissão de DCTFWeb com ID {id} não encontrada!".

Escopo: dctfweb:read

GET /dctfweb/situacao

Diz o que a Receita tem para o período - e, ao lado, o que nós registramos. É leitura pura: não muta nada.

Parâmetros de query

As regras condicionais são as mesmas da transmissão - ver Campos condicionais por categoria. Violá-las devolve 422.

Diferente da transmissão, esta rota não valida se a categoria é transmissível: perguntar a situação de uma categoria que não se pode transmitir é legítimo.

Request

GET /api/v1/dctfweb/situacao?cnpj=27898481000150&categoria=GERAL_MENSAL&anoPA=2026&mesPA=04

Response 200 OK

{
  "status": "success",
  "message": "Situação consultada com sucesso!",
  "data": {
    "id_cliente": 123,
    "cnpj": "27898481000150",
    "categoria": "GERAL_MENSAL",
    "competencia": "2026-04",
    "situacao": "ATIVA",
    "numero_recibo": "12.34.56.78-90",
    "codigo_serpro": null,
    "mensagem": "A Receita tem uma declaração ATIVA para este período (recibo 12.34.56.78-90).",
    "ultima_tentativa_local": {
      "id": 118,
      "estado": "transmitida",
      "codigo_serpro": null,
      "numero_recibo": "12.34.56.78-90",
      "data_hora_inicio": "2026-08-05T09:12:44-03:00"
    }
  }
}

Os 4 estados de situacao

Não existe serviço de "consultar situação" no Integra Contador. O vocabulário é derivado do único sinal disponível, o desfecho do CONSRECIBO32:

Escopo: dctfweb:read

Idempotência: por que uma transmissão repetida não duplica

A proteção é feita em quatro camadas, porque nenhuma sozinha basta:

Duas observações sobre o guard, porque afetam o que você vê na resposta:

• A decisão vem do desfecho da chamada, não do número do recibo. O CONSRECIBO32 só responde para declaração ATIVA; se ele respondeu, há declaração entregue - mesmo que a extração do numeroReciboEntrega devolva null. Por isso numero_recibo pode vir nulo em um resultado ja_transmitida ou em uma situacao: "ATIVA": isso degrada a informação exibida, nunca a decisão.
• Guard remoto inconclusivo não bloqueia. Se o CONSRECIBO32 falhar por instabilidade (código diferente de MG10/RELAT00), a transmissão segue - as outras três camadas continuam de pé. Bloquear ali impediria uma entrega devida por causa de uma consulta que nem é a operação pedida.

Não há índice único no banco por (cliente, categoria, período): retransmitir é caso de uso legítimo, e um índice único bloquearia exatamente o cenário que o domínio existe para atender.

A chave que identifica o que se declara

O guard não compara "cliente + competência + categoria" - isso não identifica uma declaração. Duas aferições de obras diferentes, ou dois espetáculos em dias diferentes do mesmo mês, são declarações distintas. A chave inclui os discriminadores da categoria:

<categoria>|<anoPA>|<mesPA>|<diaPA>|<cnoAfericao>|<numProcReclamatoria>

Campos ausentes viram - (posicional, nunca omitido - assim 2026|04|- não colide com 2026|-|04). Exemplo de uma mensal: GERAL_MENSAL|2026|04|-|-|-.

O estado INDETERMINADO e a regra de consumo

O /Declarar nunca é repetido automaticamente pela API. Um retry por timeout numa transmissão é exatamente como se cria uma declaração duplicada: o cliente não recebeu a resposta, mas a Receita pode ter processado o envio - e o segundo envio chega como uma nova declaração, não como a mesma.

Por isso, em /Declarar, timeout, erro de conexão ou 5xx sem veredito no corpo não propagam "falhou": produzem a classe indeterminado, que é um terceiro estado, diferente de sucesso e de falha.

Quando o corpo de um 5xx traz um código reconhecido (TRANS11, TRANS01...), a Receita deu um veredito explícito - aí o desfecho é conhecido e vale o erro classificado, não o indeterminado.

Erros do Serpro: classe e status HTTP

A API não repassa o status HTTP do Serpro nem o corpo cru da resposta. Cada recusa é classificada, traduzida para pt-BR e recebe um status derivado da classe:

O corpo do erro (sob a chave message, ver Envelope) tem esta forma:

{
  "message": {
    "classe": "negocio",
    "codigo": "TRANS01",
    "mensagem": "A declaração não está em estado que permita transmissão. Verifique a situação do período no portal da DCTFWeb antes de tentar de novo.",
    "acionamento": "/Declarar",
    "codigos": [{ "codigo": "TRANS01", "tipo": "Erro", "sistema": "DCTFWEB" }]
  }
}

mensagem é sempre texto nosso, redigido para o contador saber o que fazer - nunca o texto do Serpro. O codigo é o identificador curto e estável do parceiro, útil para diagnóstico e correlação com o log.

Códigos catalogados

Um TRANS14 numa transmissão bem-sucedida não vira erro: ele entra como mensagem do resultado (com classe_desfecho: "sucesso_com_aviso"), porque é a informação mais importante daquela transmissão para o contador.

Demais erros da API

Dois 422 merecem destaque, porque acontecem antes de qualquer envio:

• MG10 sem recibo alvo - há uma declaração mais recente em andamento e a Receita precisa saber qual é o alvo. O corpo é {"message": {"codigo": "MG10", "mensagem": "..."}}. Informe numeroReciboEntrega e repita.
• XML ausente - "A Receita não devolveu o XML da declaração para este período (campo XMLStringBase64 ausente). Confirme que a apuração está encerrada antes de transmitir." Quase sempre significa apuração não encerrada.

Campos condicionais por categoria

As regras são as mesmas de todo o domínio DCTFWeb e vêm do mesmo catálogo - não há uma segunda tabela que possa divergir. A referência completa (código, rótulo, exigeMesPA, camposExtras) está em DCTFWeb: Catálogos. Em resumo:

• mesPA - obrigatório, exceto nas categorias de 13º salário (41 GERAL_13o_SALARIO e 51 PF_13o_SALARIO), que são anuais. Nelas, informar mesPA é recusado com "'mesPA' não se aplica à categoria {rótulo} (declaração anual de 13º salário)."
• diaPA - somente em ESPETACULO_DESPORTIVO (45), onde é obrigatório.
• numProcReclamatoria - somente em RECLAMATORIA_TRABALHISTA (46), onde é obrigatório.
• cnoAfericao - somente em AFERICAO (44), onde é obrigatório.

Informar um desses campos fora da sua categoria devolve 422 com "'{campo}' só se aplica à categoria {rótulo}."; omiti-lo na categoria dona devolve "'{campo}' é obrigatório na categoria {rótulo}."

Nas categorias anuais, a competencia derivada é "AAAA" (e não "AAAA-MM"): nenhum mês sintético é inventado. Isso afeta o filtro competencia da listagem e o campo competencia de todas as respostas.

Schemas

DctfwebTransmitirRequest

Corpo de POST /dctfweb/transmissao/ e de POST /dctfweb/transmissao/simular.

Note a convenção mista de nomes, que é deliberada: campos que vão crus para o Integra Contador mantêm o nome do contrato em camelCase (anoPA, numeroReciboEntrega, idsSistemaOrigem); campos nossos usam snake_case (cnpj, forcar_retransmissao).

DctfwebTransmissaoResultado

data das duas rotas POST.

EncadeamentoOut

ok exige recibo e guia sem nenhuma ressalva; falha é recibo com erro e guia não gravada; qualquer meio-termo é parcial.

PayloadSimulado

Só existe no dry-run.

Base64Resumo

O base64 completo nunca é devolvido.

DctfwebSituacaoOut

data de GET /dctfweb/situacao.

UltimaTentativaLocal

Simulações não entram aqui: um dry-run não prova nada sobre o que a Receita registrou.

DctfwebTransmissaoListItem

Item de GET /dctfweb/transmissao/.

DctfwebTransmissaoRead

data de GET /dctfweb/transmissao/{transmissao_id}. Tem todos os campos do item da listagem, mais:

PaginatedDctfwebTransmissoes

Notas

• As duas rotas POST não aceitam API Key. É a única superfície da DCTFWeb com essa restrição.
• POST /dctfweb/transmissao/ responde 200, não 201 - inclusive quando cria um registro no histórico. O recurso criado é a tentativa, e o que interessa ao consumidor é o estado.
• Todo registro é uma tentativa, inclusive as barradas pelo guard (que nunca chamaram o /Declarar) e as simuladas. Quem tentou e foi barrado faz parte da auditoria.
• A autoria sobrevive à exclusão do usuário: id_usuario vira null, o registro permanece. O mesmo vale para recibo, guia e atividade referenciados.
• Não há rota de cancelamento, exclusão ou edição de transmissão. O histórico é somente-leitura pela API.
• Estas rotas não substituem nada: POST /integra-contador/dctf/transmitir e POST /integra-contador/dctf/consultar-xml foram removidas (validavam contra schemas incorretos e nunca operaram) e não ganharam alias - respondem 404. A superfície nova nasceu sob /dctfweb e não tem caminho legado.