DCTFWeb: visão geral

Toda a superfície DCTFWeb da WebApiAlcance passou a viver sob um prefixo único: /api/v1/dctfweb. Antes ela estava espalhada por quatro prefixos diferentes - /dctfweb-guias, /dctfweb-recibos, /integra-contador/radar/guias e /integra-contador/radar/recibos -, o que rendia quatro famílias de escopo distintas para um mesmo domínio de negócio.

A consolidação é aditiva: os caminhos antigos continuam registrados e funcionando como alias deprecado, servindo exatamente o mesmo handler do caminho novo. Migrar não muda requisição nem resposta - só o caminho e o escopo exigido.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key e JWT. O Swagger oficial está em api.contabilidadealcance.com.br/docs, nas tags que começam com DCTFWeb:.

Base path

/api/v1/dctfweb

Escopos necessários

O escopo é derivado do primeiro segmento do path após /api/v1/ (hífen → underscore), e o método HTTP define a ação (read para GET/HEAD/OPTIONS, write para POST/PUT/PATCH/DELETE). Como o primeiro segmento agora é dctfweb, todas as rotas novas derivam para:

dctfweb:read - listagens, consulta por ID, download de PDF, os catálogos, o histórico de transmissões e a consulta de situação (GET).
dctfweb:write - registro, atualização, remoção, todas as rotas de emissão e a transmissão/simulação (POST/PUT/DELETE).

A transmissão exige mais do que o escopo: perfil administrador/diretoria e sessão de usuário (API Key é recusada). Ver DCTFWeb: Transmissão.

Migrar exige um novo login (ou uma nova API Key)

O escopo entra no token no momento em que ele é emitido. Tokens gerados antes desta mudança não carregam dctfweb:read / dctfweb:write - usá-los contra os caminhos novos resulta em 403 Forbidden com "Escopo necessario: dctfweb:<acao>".

Para usuários humanos, basta relogar. Para automações, a API Key precisa receber os dois escopos novos antes do corte. É exatamente por isso que os caminhos antigos foram mantidos vivos: eles seguem exigindo os escopos antigos (dctfweb_guias, dctfweb_recibos, integra_contador), então nenhum consumidor publicado quebra durante a transição.

Mapa de migração

Cada linha aponta o substituto exato da rota, não apenas do prefixo. O handler é o mesmo objeto nos dois caminhos - não há cópia de código nem divergência de comportamento.

Registro de guias

Caminho legado (deprecado)	Caminho novo
`POST /dctfweb-guias/`	`POST /dctfweb/guias/`
`GET /dctfweb-guias/`	`GET /dctfweb/guias/`
`GET /dctfweb-guias/{guia_id}`	`GET /dctfweb/guias/{guia_id}`
`PUT /dctfweb-guias/{guia_id}`	`PUT /dctfweb/guias/{guia_id}`
`DELETE /dctfweb-guias/{guia_id}`	`DELETE /dctfweb/guias/{guia_id}`
`GET /dctfweb-guias/{guia_id}/pdf`	`GET /dctfweb/guias/{guia_id}/pdf`

Escopo antigo: dctfweb_guias:read / dctfweb_guias:write. Referência completa em DCTFWeb: Guias.

Registro de recibos

Caminho legado (deprecado)	Caminho novo
`POST /dctfweb-recibos/`	`POST /dctfweb/recibos/`
`GET /dctfweb-recibos/`	`GET /dctfweb/recibos/`
`GET /dctfweb-recibos/{recibo_id}`	`GET /dctfweb/recibos/{recibo_id}`
`PUT /dctfweb-recibos/{recibo_id}`	`PUT /dctfweb/recibos/{recibo_id}`
`DELETE /dctfweb-recibos/{recibo_id}`	`DELETE /dctfweb/recibos/{recibo_id}`
`GET /dctfweb-recibos/{recibo_id}/pdf`	`GET /dctfweb/recibos/{recibo_id}/pdf`

Escopo antigo: dctfweb_recibos:read / dctfweb_recibos:write. Referência completa em DCTFWeb: Recibos.

Emissão / coleta em lote (Integra Contador)

Caminho legado (deprecado)	Caminho novo
`POST /integra-contador/radar/guias/baixar-todas`	`POST /dctfweb/emissao/guias/baixar-todas`
`POST /integra-contador/radar/guias/baixar-mensal/esocial`	`POST /dctfweb/emissao/guias/baixar-mensal/esocial`
`POST /integra-contador/radar/guias/baixar-mensal/mit`	`POST /dctfweb/emissao/guias/baixar-mensal/mit`
`POST /integra-contador/radar/recibos/baixar-todas`	`POST /dctfweb/emissao/recibos/baixar-todas`
`POST /integra-contador/radar/recibos/baixar-mensal`	`POST /dctfweb/emissao/recibos/baixar-mensal`

Escopo antigo: integra_contador:write. Referência completa em DCTFWeb: Emissão.

A emissão sob demanda é rota NOVA, sem caminho legado

POST /dctfweb/emissao/guias/emitir não está no mapa acima: ela nasceu sob o prefixo consolidado e nunca existiu em /integra-contador/radar/*. É a única rota de emissão em que idsSistemaOrigem e categoria são parâmetros do corpo - as cinco rotas baixar-* continuam com origens fixas no código ([1, 6, 7] ou [8]) e servem à automação agendada. As três coexistem.

Como toda emissão, ela exige apenas dctfweb:write (sem perfil de gestão, e API Key é aceita) - emitir guia não declara nada ao fisco. Detalhes em DCTFWeb: Emissão.

"Radar" saiu só do caminho

radar era o nome de um produto que não existe mais - a reescrita atinge apenas o prefixo da rota. As automações agendadas de guias e recibos (fluxos eSocial e MIT) continuam em produção, servidas pelo mesmo código.

O restante de /integra-contador/* não foi movido: Simples Nacional, DCTFWeb via Integra Contador, MIT e Radar: Pagamentos seguem nos caminhos e escopos de sempre.

O que fazer agora

Adicione dctfweb:read e dctfweb:write à API Key (ou relogue, no caso de JWT humano) - sem isso, os caminhos novos respondem 403.
Troque o caminho conforme o mapa acima. Corpo, query string e resposta são idênticos.
Remova o escopo antigo só depois que nenhum consumidor seu chamar mais o caminho legado.

Os caminhos legados serão removidos

Os alias deprecados existem para não quebrar clientes já publicados e serão removidos numa versão futura, depois de validada a migração em produção. Não há data anunciada - a remoção será comunicada por changelog. Trate cada caminho legado como prazo, não como alternativa permanente.

Páginas de referência

DCTFWeb: Guias

Registro das guias emitidas (DCTFWeb e PGDAS): CRUD, listagem paginada com filtros e download do PDF.

DCTFWeb: Recibos

Registro dos recibos de transmissão: CRUD, listagem paginada com filtros e download do PDF.

DCTFWeb: Emissão

Emissão sob demanda com sistemas de origem configuráveis, mais a coleta em lote via Integra Contador (Serpro): guias e recibos, por ano ou por competência.

DCTFWeb: Catálogos

Categorias de declaração e sistemas de origem da guia - os dois catálogos que a interface consome.

DCTFWeb: Transmissão

Transmitir a declaração (TRANSDECLARACAO310), simular em DRY-RUN, histórico de tentativas e situação da declaração na Receita.

Transmissão da declaração

O prefixo consolidado também recebe a transmissão da DCTFWeb (TRANSDECLARACAO310), sob /api/v1/dctfweb/transmissao, mais a consulta de situação da declaração na Receita, em /api/v1/dctfweb/situacao.

Rota	Papel
`POST /dctfweb/transmissao/`	Transmite (ou retransmite) a declaração. Irreversível.
`POST /dctfweb/transmissao/simular`	DRY-RUN: monta e assina o XML, e para antes do envio.
`GET /dctfweb/transmissao/`	Histórico paginado das tentativas.
`GET /dctfweb/transmissao/{transmissao_id}`	Detalhe de uma tentativa.
`GET /dctfweb/situacao`	Situação da declaração na Receita - leitura, não muta nada.

Estas rotas nasceram sob o prefixo consolidado: não há caminho legado nem alias. Referência completa em DCTFWeb: Transmissão.

As rotas antigas de transmissão foram REMOVIDAS, sem alias

POST /integra-contador/dctf/transmitir e POST /integra-contador/dctf/consultar-xml foram removidas da API - validavam contra schemas incorretos (numeroControle, conteudoAssinado) e nunca operaram. Elas não ganharam alias de compatibilidade e respondem 404.

A superfície nova não é uma renomeação daquelas: o contrato é outro, e a transmissão passou a exigir perfil de gestão e sessão de usuário (API Key é recusada).

Antes de integrar contra a transmissão

Três regras que não têm equivalente no resto da API:

Não retransmita em caso de 504 / estado indeterminado. A declaração pode ter entrado; consulte GET /dctfweb/situacao antes de qualquer nova tentativa. Configure seu cliente HTTP para não repetir o POST automaticamente.
TRANS11 ("já transmitida") é sucesso, não erro: responde 200 com estado: "ja_transmitida".
INDETERMINADO nunca significa "não transmitida" - o estado negativo só é afirmado quando a Receita o diz explicitamente.