Radar DCTFWeb: Guias

Endpoints da WebApiAlcance para emissão e coleta de guias de pagamento pelo Radar, integrando o Integra Contador (Serpro). Cobrem a emissão de DCTFWeb (DARF) e PGDAS-D (DAS do Simples Nacional) para um único CNPJ ou para toda a carteira interna de clientes - em janela anual (últimos N anos, máx. 3) ou em uma competência mensal específica, com as variantes eSocial e MIT.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs (tag Automation DCTFWEB: Guias).

Escopo compartilhado do recurso integra-contador

O recurso de escopo é derivado do primeiro segmento do path após /api/v1: integra-contador → integra_contador. Logo, os escopos integra_contador:read / integra_contador:write são compartilhados por todas as rotas sob /integra-contador/* - Simples Nacional (/sn), DCTFWeb (/dctf), MIT (/mit) e as demais rotas do Radar (/radar/guias, /radar/recibos, /radar/pagamentos). Conceder integra_contador:write a uma API Key habilita a emissão de guias em todos esses domínios.

Base path

/api/v1/integra-contador/radar/guias

Escopos necessários

integra_contador:read - leitura de recursos do domínio integra-contador.
integra_contador:write - todas as rotas desta página (as três são POST, ou seja, emissão/coleta de guias).

O escopo é derivado da rota: o recurso vem do primeiro segmento (integra-contador → integra_contador, hífen → underscore) e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE). Como todos os endpoints de guias são POST, exigem integra_contador:write.

Execução síncrona, não Celery

A coleta de guias não enfileira tasks Celery. Cada requisição executa a orquestração das chamadas ao Serpro de forma síncrona, porém fora do event loop - via anyio.to_thread.run_sync - e só responde ao cliente quando toda a coleta termina. Para carteiras grandes (usar_lista_interna=true), a chamada pode ser demorada, pois percorre CNPJ × competência sequencialmente.

Endpoints

`POST /integra-contador/radar/guias/baixar-todas`

Baixa/lista todas as guias (DCTFWeb e PGDAS-D) dos últimos N anos (máx. 3, equivalente a até 36 competências mensais retroativas a partir do mês atual). Aceita um único CNPJ (contribuinte) ou toda a lista interna de clientes (usar_lista_interna=true). Para cada CNPJ/competência, coleta a DCTFWeb (recibo CONSRECIBO32 + geração do DARF com idsSistemaOrigem = [1, 6, 7]) e o PGDAS-D (pgdasd_gerar_das, com fallback para pgdasd_consultar_extrato_das).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (GuiasDownloadRequest, ver Schema GuiasDownloadRequest). Para esta rota, os campos relevantes são contribuinte ou usar_lista_interna, e anos (1-3, default 1).

Request

{
  "contribuinte": { "tipo": 2, "numero": "27898481000150" },
  "anos": 1
}

Response 200 OK

{
  "success": true,
  "message": "Guias coletadas com sucesso!",
  "data": {
    "summary": {
      "total": 24,
      "abertas": 0,
      "pagas": 0,
      "vencidas": 0,
      "porTipo": { "DCTF": 12, "PGDAS": 12 }
    },
    "guias": [
      {
        "id": "DCTFWeb:27898481000150:2025-06",
        "tipo": "DCTF",
        "competencia": "2025-06",
        "valor": 0.0,
        "dataVencimento": null,
        "status": "desconhecida",
        "clienteNumero": "27898481000150",
        "clienteNome": null,
        "descricao": "DCTFWeb - 2025-06",
        "codigoBarras": null,
        "dataGeracao": "2026-07-03",
        "observacoes": null,
        "origem": "DCTFWeb",
        "extras": { "emitir": {}, "pdfGuiaPath": "..." }
      }
    ],
    "erros": []
  }
}

Erros por CNPJ/competência não interrompem a coleta: são acumulados em erros[] (ver Schema GuiaErro) e a resposta ainda é 200 OK. Falha global na orquestração retorna 500 com detail: "Erro ao coletar guias".

Escopo: integra_contador:write

`POST /integra-contador/radar/guias/baixar-mensal/esocial`

Baixa/lista guias (DCTFWeb e PGDAS-D) de uma única competência mensal, para 1 CNPJ ou todos. É a variante eSocial da coleta DCTFWeb - usa idsSistemaOrigem = [1, 6, 7] na geração do documento de arrecadação.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (GuiasDownloadRequest, ver Schema GuiasDownloadRequest). Exige a competência via competencia ("YYYY-MM") ou o par ano + mes, e o alvo via contribuinte ou usar_lista_interna. Competência inválida retorna 422 ("Formato de 'competencia' inválido. Use 'YYYY-MM'." ou "Informe 'competencia' (YYYY-MM) ou 'ano' e 'mes' válidos.").

Request

{
  "contribuinte": { "tipo": 2, "numero": "27898481000150" },
  "competencia": "2025-06"
}

Response 200 OK

{
  "success": true,
  "message": "Guias mensais coletadas com sucesso!",
  "data": {
    "summary": {
      "total": 2,
      "abertas": 0,
      "pagas": 0,
      "vencidas": 0,
      "falhas": 0,
      "sucessos": 2,
      "porTipo": { "DCTF": 1, "PGDAS": 1 }
    },
    "guias": [
      {
        "id": "DCTFWeb:27898481000150:2025-06",
        "tipo": "DCTF",
        "competencia": "2025-06",
        "valor": 0.0,
        "dataVencimento": null,
        "status": "desconhecida",
        "clienteNumero": "27898481000150",
        "clienteNome": null,
        "descricao": "DCTFWeb - 2025-06",
        "codigoBarras": null,
        "dataGeracao": "2026-07-03",
        "observacoes": null,
        "origem": "DCTFWeb",
        "extras": { "emitir": {}, "pdfGuiaPath": "..." }
      }
    ],
    "erros": []
  }
}

Mesmo envelope de baixar-todas, restrito à competência informada; o summary inclui também falhas e sucessos. Para CNPJs matriz (contêm 0001) resolvidos na lista interna, é registrada uma atividade DCTFWeb (created_activity_dctfweb) por cliente, com status "Concluído" ou "Falha". Erro global retorna 500 com detail: "Erro ao coletar guias mensais".

Escopo: integra_contador:write

`POST /integra-contador/radar/guias/baixar-mensal/mit`

Idêntico ao baixar-mensal/esocial, porém na variante MIT (Módulo de Inclusão de Tributos): a geração do documento de arrecadação DCTFWeb usa idsSistemaOrigem = [8]. Baixa/lista guias de uma única competência, para 1 CNPJ ou todos.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (GuiasDownloadRequest, ver Schema GuiasDownloadRequest). Mesmas regras de competência (competencia "YYYY-MM" ou ano + mes) e de alvo (contribuinte ou usar_lista_interna) da variante eSocial.

Request

{
  "usar_lista_interna": true,
  "competencia": "2025-06"
}

Response 200 OK

{
  "success": true,
  "message": "Guias mensais coletadas com sucesso!",
  "data": {
    "summary": {
      "total": 2,
      "abertas": 0,
      "pagas": 0,
      "vencidas": 0,
      "falhas": 0,
      "sucessos": 2,
      "porTipo": { "DCTF": 1, "PGDAS": 1 }
    },
    "guias": [
      {
        "id": "DCTFWeb:27898481000150:2025-06",
        "tipo": "DCTF",
        "competencia": "2025-06",
        "valor": 0.0,
        "dataVencimento": null,
        "status": "desconhecida",
        "clienteNumero": "27898481000150",
        "clienteNome": null,
        "descricao": "DCTFWeb - 2025-06",
        "codigoBarras": null,
        "dataGeracao": "2026-07-03",
        "observacoes": null,
        "origem": "DCTFWeb",
        "extras": { "emitir": {}, "pdfGuiaPath": "..." }
      }
    ],
    "erros": []
  }
}

Mesmo envelope. Também registra atividade DCTFWeb por cliente matriz da lista interna. Erro global retorna 500 com detail: "Erro ao coletar guias mensais".

Escopo: integra_contador:write

Integração com o Serpro (Integra Contador)

A coleta orquestra as seguintes chamadas ao Integra Contador por CNPJ/competência:

Serviço	Método interno	Papel na coleta
DCTFWeb - `CONSRECIBO32`	`consultar_recibo_transmissao`	Obtém o `numeroReciboEntrega` da transmissão; usado na emissão do DARF.
DCTFWeb - geração de DARF	`gerar_documento_arrecadacao`	Emite a guia DCTFWeb (`categoria = GERAL_MENSAL`). `idsSistemaOrigem`: `[1, 6, 7]` (eSocial) ou `[8]` (MIT).
PGDAS-D - geração do DAS	`pgdasd_gerar_das`	Emite o DAS do Simples Nacional para o `periodoApuracao` (`YYYYMM`).
PGDAS-D - extrato do DAS	`pgdasd_consultar_extrato_das`	Fallback: recupera PDF/linha digitável/vencimento quando o DAS não vem inline.

Todos usam contribuinte = ParteIdentificacao(tipo=2, numero=<CNPJ>) (PJ). Os PDFs em base64 retornados pelo Serpro são decodificados e salvos em disco (diretórios RADAR_GUIAS_ESOCIAL_DIR / RADAR_GUIAS_MIT_DIR), e o caminho fica em extras.pdfGuiaPath (DCTFWeb) ou extras.pdfPath (PGDAS-D). Quando o Serpro sinaliza "Não há débitos com saldo a pagar para emissão da guia de pagamento.", a competência é reportada como erro 422.

Schemas

`GuiasDownloadRequest`

Campo	Tipo	Obrigatório	Observações
`contribuinte`	`ParteIdentificacao`	condicional	CNPJ único. Ver Schema `ParteIdentificacao`.
`usar_lista_interna`	`bool`	não	Default `false`. Se `true`, coleta para toda a carteira interna de clientes.
`anos`	`int` (1-3)	não	Default `1`. Usado apenas em `baixar-todas` (janela retroativa, máx. 36 meses).
`competencia`	`str`	condicional	Competência mensal `"YYYY-MM"`. Usada nas rotas `baixar-mensal/*`.
`ano`	`int`	não	Alternativa a `competencia` (par com `mes`) nas rotas mensais.
`mes`	`int` (1-12)	não	Alternativa a `competencia` (par com `ano`) nas rotas mensais.

O alvo deve ser informado por contribuinte.numero ou usar_lista_interna=true (o serviço também aceita cnpjs/customers como fontes adicionais de CNPJ). Se nenhum CNPJ válido for resolvido, retorna 422: "Informe 'contribuinte.numero' (CNPJ), ou 'cnpjs', ou 'usar_lista_interna=true'."

`ParteIdentificacao`

Campo	Tipo	Obrigatório	Observações
`tipo`	`int`	sim	`1` = PF (CPF), `2` = PJ (CNPJ). Guias usam `2`.
`numero`	`str`	sim	CPF/CNPJ, preferencialmente só dígitos.

`GuiasDownloadResponse`

Campo	Tipo	Observações
`summary`	`GuiasSummary`	Resumo agregado da coleta.
`guias`	`List[Guia]`	Guias emitidas/coletadas.
`erros`	`List[GuiaErro]`	Falhas por CNPJ/competência. Default `[]`.

`GuiasSummary`

Campo	Tipo	Observações
`total`	`int`	Total de guias coletadas.
`abertas`	`int`	Contagem (default `0`; status não é resolvido nesta coleta).
`pagas`	`int`	Contagem (default `0`).
`vencidas`	`int`	Contagem (default `0`).
`porTipo`	`Dict[str, int]`	Contagem por tipo (`DCTF`, `PGDAS`, ...).

Campos extras no summary mensal

Nas rotas baixar-mensal/*, o summary também traz falhas e sucessos (contagens da competência processada), além dos campos acima.

`Guia`

Campo	Tipo	Observações
`id`	`str`	Identificador (ex.: `DCTFWeb:<cnpj>:<competencia>`, `PGDAS:<cnpj>:<comp>:<numeroDas>`).
`tipo`	`str`	`DCTF`, `PGDAS`, `DAS`, `DARF`, `GPS`, etc.
`competencia`	`str`	`AAAA-MM`.
`valor`	`float`	Valor da guia. Default `0.0` (DCTFWeb não resolve valor nesta coleta).
`dataVencimento`	`str \| null`	Vencimento, quando disponível.
`status`	`str`	`aberta` \| `paga` \| `vencida` \| `desconhecida` (default).
`clienteNumero`	`str`	CNPJ do cliente (somente dígitos).
`clienteNome`	`str \| null`	Nome do cliente, quando disponível.
`descricao`	`str \| null`	Descrição legível (ex.: `DCTFWeb - 2025-06`).
`codigoBarras`	`str \| null`	Linha digitável / código de barras (PGDAS-D).
`dataGeracao`	`str \| null`	Data de geração (`YYYY-MM-DD`).
`observacoes`	`str \| null`	Observações.
`origem`	`str`	`DCTFWeb`, `PGDAS-D`, etc.
`extras`	`Dict[str, Any]`	Payload cru do Serpro (`emitir`) e caminhos de PDF (`pdfGuiaPath` / `pdfPath`, `numeroDas`).

`GuiaErro`

Campo	Tipo	Observações
`cnpj`	`str`	CNPJ que falhou.
`status`	`int \| null`	Código HTTP da falha do Serpro, quando houver.
`detail`	`str`	Descrição do erro.

Notas

Toda resposta segue o envelope { success, message, data } da WebApi; o data é o GuiasDownloadResponse descrito acima (ou { success: false, message, details } em erro).
Escopo compartilhado: as três rotas herdam o recurso integra_contador do primeiro segmento do path - a mesma família de escopos usada por /integra-contador/sn, /dctf, /mit, /radar/recibos e /radar/pagamentos.
A coleta é síncrona (via anyio.to_thread.run_sync), não usa Celery; percorre CNPJ × competência sequencialmente. Prefira contribuinte para respostas rápidas e reserve usar_lista_interna para lotes.
Diferença entre baixar-mensal/esocial e baixar-mensal/mit: apenas o idsSistemaOrigem na emissão DCTFWeb ([1, 6, 7] para eSocial, [8] para MIT). A coleta PGDAS-D é idêntica nas duas.
Erros por cliente/competência são não fatais e ficam em erros[]; a coleta continua para os demais CNPJs.