DCTFWeb: Transmissão

Endpoints da WebApiAlcance que entregam a declaração da DCTFWeb à Receita Federal pelo Integra Contador (Serpro), serviço TRANSDECLARACAO310, mais a reconciliação de tentativas sem veredito, a marcação de transmissões feitas no e-CAC, o histórico de tentativas e a consulta da situação da declaração no fisco.

A transmissão apenas transmite: não emite recibo nem guia. Para isso use Recibos e Emissão.

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

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de autenticação.

Operação irreversível - leia a regra do estado INDETERMINADO antes de integrar

POST /dctfweb/transmissao/ entrega uma declaração à Receita em nome do cliente. Quando o /Declarar não devolve veredito (timeout ou 5xx sem código), a API responde 504 com estado indeterminado: a declaração pode ter entrado.

A regra de consumo é absoluta: não retransmita. Consulte GET /dctfweb/situacao e resolva o registro com POST /dctfweb/transmissao/reconciliar (ou repita o POST, que consulta o recibo antes de decidir). Reenviar às cegas é exatamente como se cria uma declaração duplicada no fisco. Detalhes em Estado INDETERMINADO.

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/, /simular, /reconciliar, /marcar-externa e /desmarcar-externa.
  • dctfweb:read - GET /dctfweb/transmissao/, /resumo-competencia, /{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.

As rotas POST exigem login de usuário com permissão

As cinco rotas POST (transmitir, simular, reconciliar, marcar e desmarcar externa) acumulam três camadas de autorização:

  1. Escopo dctfweb:write - derivado do path, como em todo o resto da API.
  2. Permissão: o usuário precisa ter permissão para a ação; sem ela, a resposta é 403.
  3. Credencial: exigem login de usuário (sessão). Credenciais de integração recebem 403, mesmo com o escopo correto. Transmitir é ato fiscal irreversível e fica registrado com a autoria de quem o disparou.

Consequência prática: automação sem usuário não transmite DCTFWeb. As rotas de leitura (GET) exigem apenas o escopo.

O CNPJ precisa ser de um cliente do escritório

Em POST /, /simular, /reconciliar e GET /dctfweb/situacao, o documento informado é resolvido contra a carteira interna (busca por dígitos, porque cpfecnpj está em formato misto na base). CNPJ que não pertence a nenhum cliente cadastrado recebe 403:

"O documento informado não pertence a nenhum cliente do escritório. A transmissão de DCTFWeb só é permitida para clientes cadastrados."

Isso vale inclusive para a consulta de situação - situação fiscal de terceiro é vazamento mesmo em leitura.

Cliente inativo não transmite nem simula

POST /dctfweb/transmissao/ e POST /dctfweb/transmissao/simular respondem 409 ("Cliente inativo: automações bloqueadas.") quando o cliente do CNPJ está inativo. /reconciliar e a consulta de situação não têm essa trava.

Envelope

As 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:

Origem do erroCorpo
Validação do corpo pelo FastAPI/Pydantic (POST){ "detail": [ { "loc": [...], "msg": "...", "type": "..." } ] }
Qualquer HTTPException da aplicação (inclusive Serpro){ "message": <detalhe> } - o detalhe pode ser string, objeto ou lista

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:

#EtapaO que acontece
1CONSXMLDECLARACAO38 (acionamento /Consultar)Busca na Receita o XML da declaração do período (XMLStringBase64).
2Assinatura local (XMLDSig)Assina o XML com o certificado digital do escritório.
3TRANSDECLARACAO310 (acionamento /Declarar)Envia o XML assinado - é o passo que entrega a declaração.

E a operação termina aí: a transmissão não emite recibo nem guia. O recibo e o DARF são obtidos pelas rotas de Recibos, Guias e Emissão. Quando a Receita informa o número do recibo na resposta do /Declarar, ele vem em numero_recibo; o campo pode ser null mesmo com a declaração entregue.

A operação é síncrona

Uma transmissão faz até 3 chamadas à Receita (XML, /Declarar e, no guard, a consulta de recibo), cada uma com timeout próprio. A requisição só responde quando tudo termina - dimensione o timeout do seu cliente HTTP de acordo. Não há fila, callback nem polling: o resultado vem no corpo da 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": "11222333000181",
  "categoria": "GERAL_MENSAL",
  "anoPA": "2026",
  "mesPA": "04"
}

Response 200 OK

{
  "status": "success",
  "message": "Transmissão processada.",
  "data": {
    "id": 118,
    "id_cliente": 123,
    "cnpj": "11222333000181",
    "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": null,
    "payload_simulado": null
  }
}

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

estadoHTTPSignificadoO que fazer
transmitida200O /Declarar aceitou nesta execução.Nada. Recibo e guia, se precisar, pelas rotas de Recibos e Emissão.
ja_transmitida200A declaração já estava entregue - via guard local/remoto ou via TRANS11. Não é erro.Nada. É o estado desejado.
indeterminado504O /Declarar não respondeu. Pode ter entrado.NÃO retransmita. Consulte GET /dctfweb/situacao.
falha422, 500, 502Recusa com veredito conhecido (negócio, assinatura, entrada inválida).Corrigir a causa. O código do Serpro vem na resposta.

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.

`forcar_retransmissao` serve a UM cenário

O default é false, e nesse modo o guard barra a operação quando o período já consta entregue (respondendo ja_transmitida, sem reenviar nada). forcar_retransmissao: true segue mesmo assim - é o caminho do cenário real de retransmissão: a apuração foi reaberta (tipicamente para corrigir a EFD-Reinf), reencerrada, e a declaração precisa voltar a ATIVA.

Ele não libera o estado indeterminado. Nesse caso, forçar não tem efeito nenhum: a dúvida só se resolve por consulta de recibo.

Escopo: dctfweb:write. Exige login de usuário (sessão) com permissão; credenciais de integração recebem 403.

POST /dctfweb/transmissao/simular

DRY-RUN. Executa as etapas 1 e 2 (consulta o XML na Receita e assina com o certificado digital do escritório), 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.

O modo é fixado no SERVIDOR

A simulação é uma rota própria, e não um booleano do corpo. Não existe campo em DctfwebTransmitirRequest capaz de fazer /simular transmitir, nem de fazer POST /dctfweb/transmissao/ simular - a decisão é tomada no servidor, antes de qualquer chamada ao /Declarar.

É essa separação que torna a garantia verificável: nenhum erro de preenchimento do corpo transforma um dry-run em uma declaração entregue.

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": "11222333000181",
  "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": "11222333000181",
    "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": "11222333000181" },
      "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. Exige login de usuário (sessão) com permissão; credenciais de integração recebem 403.

POST /dctfweb/transmissao/reconciliar

Resolve um período preso em indeterminado sem transmitir nada. Consulta o recibo na Receita e atualiza o registro travado. Responde 200 OK.

Resultado da consultaestado devolvidoEfeito
Declaração ATIVA encontradaja_transmitidaA declaração está entregue. O registro é atualizado.
RELAT00 (sem declaração ativa)falhaNão entrou. O período volta a poder ser transmitido pelo caminho normal.
InconclusivoindeterminadoRegistro intocado. É 200: a consulta foi feita, a dúvida é o resultado.

Esta rota nunca transmite

O corpo não aceita forcar_retransmissao (campo extra resulta em 422). Retransmitir um período indeterminado é como se cria declaração duplicada no fisco, que é irreversível.

Parâmetros

Sem parâmetros de rota ou query. O corpo identifica o período, com os mesmos campos de DctfwebTransmitirRequest, exceto forcar_retransmissao.

Request

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

Response 200 OK

O data segue o formato de DctfwebTransmissaoResultado.

{
  "status": "success",
  "message": "Reconciliação processada.",
  "data": {
    "id": 118,
    "id_cliente": 123,
    "cnpj": "11222333000181",
    "categoria": "GERAL_MENSAL",
    "competencia": "2026-04",
    "modo": "real",
    "estado": "ja_transmitida",
    "mensagem": "Reconciliado: a Receita tem uma declaração ATIVA para este período, logo a transmissão que ficou sem confirmação FOI processada. Nada foi reenviado.",
    "codigo_serpro": "INDETERMINADO-RESOLVIDO",
    "classe_desfecho": "idempotente",
    "numero_recibo": "12.34.56.78-90",
    "encadeamento": null,
    "payload_simulado": null
  }
}

Erros: 403 (credencial de integração, sem permissão ou CNPJ que não é de cliente do escritório); 404 se não há tentativa registrada para o período; 409 se a última tentativa do período não está em indeterminado; 422 para corpo inválido.

Escopo: dctfweb:write. Exige login de usuário (sessão) com permissão; credenciais de integração recebem 403.

POST /dctfweb/transmissao/marcar-externa

Registra que a DCTFWeb do cliente na competência foi transmitida direto no portal e-CAC, fora deste sistema. Nada é enviado à Receita. A marcação vale para a competência inteira (não por categoria) e não bloqueia transmitir pelo sistema. Responde 200 OK.

É idempotente: se já marcado, devolve a marcação vigente e atualiza o recibo quando vem um novo (autor e data da primeira marcação são preservados).

Parâmetros

Sem parâmetros de rota ou query. Corpo (campo desconhecido resulta em 422):

CampoTipoObrigatórioObservações
id_clienteintsimID do cliente.
competenciastrsimAAAA-MM, mês de 01 a 12.
nr_recibo_ecacstr | nullnãoRecibo emitido pelo e-CAC. Espaços nas pontas são removidos; vazio vira null; máx. 60 caracteres, sem caracteres de controle.

Request

{
  "id_cliente": 123,
  "competencia": "2026-08",
  "nr_recibo_ecac": "12.34.56.78.90-12"
}

Response 200 OK

{
  "status": "success",
  "message": "DCTFWeb marcada como transmitida no e-CAC (nada foi enviado à Receita).",
  "data": {
    "id_cliente": 123,
    "competencia": "2026-08",
    "marcado": true,
    "nr_recibo_ecac": "12.34.56.78.90-12",
    "marcado_em": "2026-08-20T10:15:00-03:00",
    "id_usuario_marcou": 7
  }
}

Erros: 403 (credencial de integração ou sem permissão); 404 se o cliente não existe; 422 para competência malformada ou recibo inválido.

Escopo: dctfweb:write. Exige login de usuário (sessão) com permissão; credenciais de integração recebem 403.

POST /dctfweb/transmissao/desmarcar-externa

Retira a marcação de transmissão externa da competência. Sempre permitido e idempotente: responde 200 OK mesmo sem marcação (marcado: false).

Parâmetros

Sem parâmetros de rota ou query. Corpo (campo desconhecido resulta em 422):

CampoTipoObrigatórioObservações
id_clienteintsimID do cliente.
competenciastrsimAAAA-MM, mês de 01 a 12.

Request

{
  "id_cliente": 123,
  "competencia": "2026-08"
}

Response 200 OK

{
  "status": "success",
  "message": "Marcação de transmissão externa (e-CAC) retirada.",
  "data": {
    "id_cliente": 123,
    "competencia": "2026-08",
    "marcado": false,
    "nr_recibo_ecac": null,
    "marcado_em": null,
    "id_usuario_marcou": null
  }
}

Erros: 403 (credencial de integração ou sem permissão); 404 se o cliente não existe; 422 para competência malformada.

Escopo: dctfweb:write. Exige login de usuário (sessão) com permissão; credenciais de integração recebem 403.

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

ParâmetroTipoDefaultObservações
id_clienteint-Filtra por cliente.
id_usuarioint-Filtra por autoria (quem disparou).
categoriastr-Ex.: GERAL_MENSAL. Case-insensitive, ignora espaços nas pontas.
competenciastr-AAAA-MM; AAAA nas categorias de 13º salário. Comparação exata.
estadostr-simulada | transmitida | ja_transmitida | indeterminado | falha. Case-insensitive.
modostr-real | simulacao. Case-insensitive.
start_datedatetime-data_hora_inicio >= start_date.
end_datedatetime-data_hora_inicio <= end_date.
sort_bystr (whitelist)data_hora_inicioWhitelist na seção Ordenação, abaixo. Valor fora dela → 422.
sort_dirasc | descdescValor fora da whitelist → 422.
pageint (≥ 1)1Página, 1-based.
per_pageint (1-500)-Itens por página. Se omitido, retorna todos (sem paginar).

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": null,
        "id_guia": null,
        "encadeamento_estado": null,
        "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
  }
}

Os campos id_recibo, id_guia, encadeamento_estado e encadeamento_detalhe só vêm preenchidos em registros antigos; em transmissões novas são null. A listagem não traz encadeamento_detalhe 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):

sort_byOrdena por
data_hora_inicioInício da tentativa (default).
data_hora_desfechoConclusão da tentativa.
estadoEstado do desfecho.
categoriaCategoria da declaração.
competenciaCompetência.
modoreal / simulacao.
clienteRazão social do cliente.

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/resumo-competencia

Quantos clientes já têm a DCTFWeb entregue na competência. É um agregado sobre todo o histórico (não depende de paginação). Conta transmissões reais com estado transmitida ou ja_transmitida; as marcações feitas no e-CAC vêm em campos separados.

Parâmetros de query

ParâmetroTipoObrigatórioObservações
competenciastrsimCompetência no formato AAAA-MM.

Request

GET /api/v1/dctfweb/transmissao/resumo-competencia?competencia=2026-04

Response 200 OK

{
  "status": "success",
  "message": "Resumo da competencia gerado com sucesso!",
  "data": {
    "competencia": "2026-04",
    "clientes_transmitidos": 2,
    "ids_clientes": [123, 456],
    "clientes_transmitidos_externo": 1,
    "ids_clientes_externo": [789]
  }
}
CampoTipoObservações
clientes_transmitidosintClientes com declaração entregue por este sistema.
ids_clientesList[int]IDs desses clientes, em ordem crescente.
clientes_transmitidos_externointClientes com transmissão marcada como feita no e-CAC.
ids_clientes_externoList[int]IDs desses clientes.

Escopo: dctfweb:read

GET /dctfweb/transmissao/{transmissao_id}

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

Parâmetros de rota

ParâmetroTipoObservações
transmissao_idintID do registro. Obrigatório.

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": null,
    "id_recibo": null,
    "id_guia": null,
    "encadeamento_estado": null,
    "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.

Por que esta rota existe

Ela resolve o caso mais tenso do fluxo. Quando uma transmissão fica em indeterminado, a regra é não retransmitir - e, sem esta rota, a única saída seria conferir no e-CAC por fora. Aqui o operador descobre no próprio app se a declaração entrou.

Também serve para ver o guard antes de transmitir: se a situação é ATIVA, o POST vai responder ja_transmitida (a menos que se force a retransmissão).

Parâmetros de query

ParâmetroTipoObrigatórioObservações
cnpjstrsimCNPJ/CPF do contribuinte, com ou sem máscara. 11 a 20 caracteres.
categoriaenumsimRótulo da categoria (ex.: GERAL_MENSAL). Ver Catálogos.
anoPAstrsimAno de apuração, 4 dígitos: "2026".
mesPAstrcondicionalMês com zero à esquerda ("01"-"12"). Não se aplica ao 13º salário (41/51).
diaPAstrcondicionalDia do evento ("01"-"31"). Somente em ESPETACULO_DESPORTIVO (45).
cnoAfericaointcondicionalNúmero da obra (CNO), ≥ 0. Somente em AFERICAO (44).
numProcReclamatoriastrcondicionalNº do processo, até 60 caracteres. Somente em RECLAMATORIA_TRABALHISTA (46).

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=11222333000181&categoria=GERAL_MENSAL&anoPA=2026&mesPA=04

Response 200 OK

{
  "status": "success",
  "message": "Situação consultada com sucesso!",
  "data": {
    "id_cliente": 123,
    "cnpj": "11222333000181",
    "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:

situacaoDerivado deSignificado
ATIVAA consulta respondeu com sucessoHá declaração entregue no período. numero_recibo vem quando a Receita o informa.
EM_ANDAMENTOCódigo MG10A declaração mais recente do período ainda não foi transmitida.
SEM_DECLARACAOCódigo RELAT00Não há declaração ativa no período. É a única resposta que libera uma transmissão.
INDETERMINADOQualquer outro desfechoNão deu para concluir (timeout, indisponibilidade, código não mapeado).

`INDETERMINADO` nunca significa "não transmitida"

A derivação é fail-closed: timeout, código não mapeado ou indisponibilidade nunca viram SEM_DECLARACAO. O estado negativo não é inferido de falha - SEM_DECLARACAO só é afirmado quando a Receita o diz explicitamente (RELAT00).

Um falso "não há declaração" faria o operador retransmitir algo já entregue, que é exatamente o dano que este domínio existe para evitar. Diante de INDETERMINADO: tente de novo em instantes, ou confira no portal da DCTFWeb.

Não existe campo `pode_transmitir` - de propósito

Não há resposta binária honesta. SEM_DECLARACAO libera; ATIVA normalmente barra, mas é exatamente o estado de quem reabriu e reencerrou a apuração e precisa retransmitir; e INDETERMINADO não autoriza nada. Um booleano teria de escolher uma dessas leituras e mentiria nas outras.

A decisão fica com quem tem o contexto, informada por situacao + mensagem + ultima_tentativa_local. É a divergência entre o que a Receita tem e o que nós registramos que explica o caso "mandei e não sei se entrou".

Escopo: dctfweb:read

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

Transmitir de novo um período que já consta entregue não duplica a declaração: sem forcar_retransmissao, a API responde 200 com estado: "ja_transmitida" e não reenvia nada. Duas requisições simultâneas para o mesmo cliente e período resultam em uma única transmissão; a outra recebe 409.

`TRANS11` é sucesso idempotente, não erro

Quando o Serpro devolve o código TRANS11 ("a declaração já foi transmitida"), a API não trata como falha: a operação já estava no estado desejado. O desfecho é 200 OK com estado: "ja_transmitida", classe_desfecho: "idempotente" e o fluxo segue para o encadeamento - recibo e guia são buscados normalmente.

Isso inclui o TRANS11 que chega escondido num HTTP 200: o Integra Contador tem envelope próprio e pode responder 200 com mensagens: [{"codigo": "[Erro-DCTFWEB-TRANS11]"}]. A API inspeciona o corpo, não só o status.

O numero_recibo pode vir null em um resultado ja_transmitida ou em uma situacao: "ATIVA"; isso afeta apenas a informação exibida, não o desfecho.

Retransmitir é um caso de uso legítimo: use forcar_retransmissao: true (veja POST /dctfweb/transmissao/).

A chave que identifica o que se declara

A identificação 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.

Regra de consumo em `indeterminado` / HTTP 504

  1. NÃO retransmita - nem manualmente, nem com retry automático do seu cliente HTTP. Configure o cliente para não repetir POST /dctfweb/transmissao/.
  2. Chame GET /dctfweb/situacao com o mesmo período. ATIVA ⇒ entrou; SEM_DECLARACAO ⇒ não entrou; INDETERMINADO ⇒ ainda não dá para concluir - espere e tente a consulta de novo.
  3. Se preferir, repita o mesmo POST: a API detecta o registro anterior em indeterminado e consulta o recibo antes de qualquer envio. Se a declaração estiver ATIVA, ela responde 200 com ja_transmitida e a mensagem "A transmissão anterior deste período havia ficado sem confirmação, mas a consulta de recibo mostrou que a declaração ESTÁ entregue. Nada foi reenviado."
  4. Para resolver o registro sem tentar transmitir, use POST /dctfweb/transmissao/reconciliar: ele consulta o recibo e atualiza o estado (ja_transmitida, falha ou segue indeterminado), e nunca envia nada.
  5. Se a consulta não esclarecer, a transmissão responde 409 e recusa - forcar_retransmissao não libera este caso. O corpo traz {"message": {"estado": "indeterminado", "codigo": "...", "mensagem": "...", "transmissao_id": 118}}.

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:

Classe (classe_desfecho)HTTPQuandoRetry adianta?
sucesso_com_aviso200Aceito com ressalva (ex.: TRANS14, fora do prazo → MAED).-
idempotente409TRANS11. Na transmissão é interceptado e vira 200 (ver acima).Não
negocio422Estado da declaração, prazo, ausência de débito. Acionável pelo contador.Não
assinatura500Defeito nosso no XML/assinatura. Acionável pela equipe técnica.Não
transitorio502Falha momentânea do parceiro (5xx interno, 429, rede).Sim, com backoff
indeterminado504/Declarar sem veredito. Exclusivo de escrita.Nunca
desconhecido502Código não mapeado. Tratado como permanente (fail-closed).Não

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

CódigoClasseLeitura
TRANS11idempotenteJá havia sido transmitida. Não é erro.
TRANS14sucesso_com_avisoTransmitida fora do prazo: a Receita gerará multa por atraso (MAED). A transmissão foi aceita.
TRANS01negocioA declaração não está em estado que permita transmissão.
TRANS13negocioPeríodo só admite consulta - não aceita mais transmissão.
TRANS02assinaturaAssinatura fora do padrão (deve ter exatamente uma referência assinada).
TRANS04assinaturaXML enviado não confere com o gerado pela Receita (hash divergente).
TRANS09assinaturaAssinatura digital inválida.
TRANS17assinaturaAssinatura posicionada no lugar errado do XML.
TRANS21assinaturaXML assinado em base64 não foi enviado.
MG10negocioExiste declaração mais recente em andamento. Na transmissão não é recusa: a transmissão segue.
MG12 / MG19 / MG21transitorioFalha interna momentânea da Receita.
RELAT00negocioNão há declaração ativa para o período.
GUIA03negocioNão há débitos com saldo a pagar para emissão da guia.

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

StatusQuando
403Sem permissão; credencial de integração nas rotas POST; CNPJ que não é de cliente do escritório.
404GET /dctfweb/transmissao/{id} com ID inexistente; /reconciliar sem tentativa registrada; /marcar-externa e /desmarcar-externa com cliente inexistente.
409Já existe transmissão em andamento para o mesmo cliente e período; indeterminado não resolvido; cliente inativo (transmitir e simular); /reconciliar com a última tentativa fora de indeterminado.
422Corpo/query inválidos; categoria não transmissível; regras condicionais por categoria violadas; campos que não existem no corpo (numeroReciboEntrega, idsSistemaOrigem); erro de negócio da Receita; XML da declaração ausente na Receita; XML não assinável.
500Certificado digital indisponível para assinar ("Certificado digital indisponível para assinar a DCTFWeb.") ou erro de assinatura reportado pelo Serpro.
504/Declarar sem veredito → estado indeterminado.

Um 422 merece destaque, porque acontece antes de qualquer envio:

  • 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 fonte 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.

`cnoAfericao` identifica a obra, mas não é enviado à Receita

Na categoria AFERICAO (44) o cnoAfericao continua obrigatório no corpo: ele identifica a obra e compõe a chave do período (duas aferições de obras diferentes são declarações distintas). O valor não é repassado no TRANSDECLARACAO310.

Schemas

DctfwebTransmitirRequest

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

CampoTipoObrigatórioObservações
cnpjstr (11-20)simCNPJ/CPF do contribuinte, com ou sem máscara. Precisa pertencer a um cliente do escritório.
categoriaenumsimRótulo da categoria (ex.: GERAL_MENSAL). Categoria não transmissível → 422.
anoPAstr (^\d{4}$)simAno de apuração: "2026". String, não inteiro.
mesPAstrcondicional"01"-"12", com zero à esquerda. Ver campos condicionais.
diaPAstrcondicional"01"-"31". Somente em ESPETACULO_DESPORTIVO.
cnoAfericaoint (≥ 0)condicionalNúmero da obra. Numérico, ao contrário de ano/mês. Somente em AFERICAO, onde é obrigatório; não é repassado à Receita.
numProcReclamatoriastr (≤ 60)condicionalNº do processo. Somente em RECLAMATORIA_TRABALHISTA.
forcar_retransmissaoboolnãoDefault false. Segue mesmo havendo declaração ATIVA. Não libera o estado indeterminado.

Note a convenção mista de nomes, que é deliberada: campos que seguem o contrato do Integra Contador mantêm o nome em camelCase (anoPA, mesPA, diaPA, cnoAfericao, numProcReclamatoria); campos nossos usam snake_case (cnpj, forcar_retransmissao).

Campo desconhecido é recusado

Ao contrário de outros schemas do domínio Serpro, este rejeita campos desconhecidos: qualquer campo não listado acima resulta em 422. Numa requisição de transmissão, um campo desconhecido quase sempre é erro de digitação - e aceitá-lo em silêncio faria a declaração sair com o período errado sem ninguém perceber.

`numeroReciboEntrega` e `idsSistemaOrigem` não existem mais no corpo

A transmissão só recebe o período e forcar_retransmissao. Enviar numeroReciboEntrega ou idsSistemaOrigem resulta em 422. A emissão de guia com filtro de origens fica em Emissão.

DctfwebTransmissaoResultado

data das duas rotas POST.

CampoTipoObservações
idint | nullID do registro persistido no histórico.
id_clienteintCliente resolvido a partir do cnpj.
cnpjstrSomente dígitos (a máscara enviada é descartada).
categoriastrRótulo da categoria.
competenciastrAAAA-MM; AAAA nas categorias anuais.
modostrreal | simulacao.
estadostrsimulada | transmitida | ja_transmitida | indeterminado | falha.
mensagemstrTexto em pt-BR, acionável.
codigo_serprostr | nullCódigo do parceiro, ou marcador interno (DRY-RUN, GUARD-LOCAL, GUARD-REMOTO, INDETERMINADO-RESOLVIDO).
classe_desfechostr | nullClasse do desfecho - ver a tabela de classes.
numero_recibostr | nullRecibo de entrega, quando obtido. Pode ser null mesmo em sucesso.
encadeamentoEncadeamentoOut | nullSempre null nas transmissões atuais (a transmissão não emite recibo nem guia).
payload_simuladoPayloadSimulado | nullSó no dry-run.

EncadeamentoOut

Legado: presente apenas em registros antigos do histórico.

CampoTipoObservações
estadostrnao_executado | ok | parcial | falha.
numero_recibostr | nullRecibo obtido no CONSRECIBO32.
id_reciboint | nullID do registro criado em Recibos.
id_guiaint | nullID do registro criado em Guias.
detalhestr | nullFalhas acumuladas, separadas por |. null quando não houve nenhuma.

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.

CampoTipoObservações
idSistemastrDCTFWEB.
idServicostrTRANSDECLARACAO310.
acionamentostrEndpoint que seria chamado: /Declarar.
contribuinteobject{ tipo, numero } - 1 = PF (CPF), 2 = PJ (CNPJ), derivado do comprimento.
dadosobjectPayload completo, exceto xmlAssinadoBase64.
xml_assinadoBase64ResumoResumo do XML já assinado.
xml_originalBase64ResumoResumo do que veio do CONSXMLDECLARACAO38.

Base64Resumo

CampoTipoObservações
tamanhointComprimento do base64, em caracteres.
sha256strSHA-256 do base64, em hex - os 16 primeiros caracteres. Para comparar execuções.
previewstrPrimeiros 64 caracteres, para conferência visual.

O base64 completo nunca é devolvido.

DctfwebSituacaoOut

data de GET /dctfweb/situacao.

CampoTipoObservações
id_clienteintCliente resolvido a partir do cnpj.
cnpjstrSomente dígitos.
categoriastrRótulo da categoria.
competenciastrAAAA-MM; AAAA nas anuais.
situacaostrATIVA | EM_ANDAMENTO | SEM_DECLARACAO | INDETERMINADO.
numero_recibostr | nullRecibo de entrega, quando ATIVA. Pode vir nulo mesmo em ATIVA.
codigo_serprostr | nullMG10, RELAT00, etc. null quando a consulta respondeu com sucesso.
mensagemstrTexto em pt-BR explicando a situação.
ultima_tentativa_localUltimaTentativaLocal | nullA última tentativa real registrada por nós para o mesmo período.

UltimaTentativaLocal

CampoTipoObservações
idintID no histórico de transmissões.
estadostrEstado daquela tentativa.
codigo_serprostr | nullCódigo registrado.
numero_recibostr | nullRecibo registrado.
data_hora_iniciodatetime | nullInício da tentativa.

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

CampoTipoObservações
idint-
id_clienteint-
id_usuarioint | nullAutoria. Fica null se o usuário for excluído.
atividade_idint | nullAtividade registrada na timeline do cliente.
categoriastr-
competenciastr-
modostrreal | simulacao.
estadostr-
numero_recibostr | null-
codigo_serprostr | null-
classe_desfechostr | null-
mensagemstr | nullCurta e acionável - é o que serve numa lista de falhas.
id_reciboint | null-
id_guiaint | null-
encadeamento_estadostr | null-
data_hora_iniciodatetime | null-
data_hora_desfechodatetime | nullnull enquanto a tentativa não fechou.

DctfwebTransmissaoRead

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

CampoTipoObservações
chave_periodostrChave de idempotência do período - ver a chave que identifica o que se declara.
ano_pastr-
mes_pastr | null-
dia_pastr | null-
cno_afericaostr | nullGravado como texto, ainda que trafegue como número na requisição.
num_proc_reclamatoriastr | null-
numero_recibo_alvostr | nullLegado: null nas transmissões atuais.
ids_sistema_origemstr | nullLegado: null nas transmissões atuais.
encadeamento_detalhestr | nullLegado: texto das falhas do encadeamento antigo.

PaginatedDctfwebTransmissoes

CampoTipoObservações
itemsList[object]DctfwebTransmissaoListItem.
totalintTotal de registros que casam com os filtros.
total_pagesint1 quando per_page é omitido.
current_pageintPágina atual.
per_pageint | nullnull quando o cliente não paginou.

Notas

  • As cinco rotas POST (transmitir, simular, reconciliar, marcar e desmarcar externa) exigem login de usuário; credenciais de integração recebem 403.
  • 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 a atividade referenciada.
  • 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.