Radar DCTFWeb: Recibos

Endpoints da WebApiAlcance para consulta e download de recibos de declarações - DCTFWeb (e, opcionalmente, PGDAS-D do Simples Nacional) - obtidos através do Integra Contador do Serpro. Cobrem dois modos de coleta: anual (percorre os últimos N anos, máximo 3) e mensal (uma única competência AAAA-MM). Cada modo aceita um único CNPJ (contribuinte) ou toda a lista interna de customers (usar_lista_interna=true).

Para cada competência, o serviço chama o Serpro, extrai o PDF do recibo (quando presente, em Base64) e devolve um resumo agregado + a lista de recibos coletados.

Base path

/api/v1/integra-contador/radar/recibos

Escopos necessários

• integra_contador:read - leitura/consulta no recurso integra_contador (compartilhado).
• integra_contador:write - coleta/download de recibos (as duas rotas são POST).

O recurso é integra_contador (fixo, comum a todo o prefixo /integra-contador), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

POST /integra-contador/radar/recibos/baixar-todas

Coleta/lista os recibos dos últimos N anos (anos, mínimo 1, máximo 3), para um único CNPJ ou para toda a lista interna de customers. Percorre todas as competências mensais do intervalo e, para cada CNPJ, consulta o recibo de transmissão da DCTFWeb no Serpro. O processamento roda inline em threadpool síncrono (anyio.to_thread.run_sync), sem task Celery; falhas por competência são registradas em log e não interrompem a coleta das demais.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (RecibosDownloadRequest): informe contribuinte (um único CNPJ) ou usar_lista_interna: true (todos os customers), com anos opcional (1 a 3, default 1). Ver Schema RecibosDownloadRequest. Se nenhum CNPJ for resolvido, retorna 422 com a mensagem "Informe 'contribuinte.numero' (CNPJ), ou 'cnpjs', ou 'usar_lista_interna=true' com customer_service válido.".

Request

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

Alternativa - todos os customers:

{
  "usar_lista_interna": true,
  "anos": 1
}

Response 200 OK

{
  "summary": {
    "total": 12,
    "abertas": 0,
    "pagas": 0,
    "vencidas": 0,
    "porTipo": { "DCTF": 12 }
  },
  "recibos": [
    {
      "id": "DCTFWeb:27898481000150:2025-06",
      "tipo": "DCTF",
      "competencia": "2025-06",
      "clienteNumero": "27898481000150",
      "descricao": "Recibo DCTFWeb - 2025-06",
      "origem": "DCTFWeb",
      "dataGeracao": "2026-07-03",
      "pdfPath": "/caminho/RECIBO_DCTF/.../DCTFWeb_27898481000150_2025-06.pdf",
      "extras": { "consulta": { "resposta": "bruta do Serpro" } }
    }
  ]
}

Em caso de erro não tratado, retorna 500 com detail: "Erro ao coletar recibos".

Escopo: integra_contador:write

POST /integra-contador/radar/recibos/baixar-mensal

Coleta/lista os recibos de uma única competência (mês), para um CNPJ ou para toda a lista interna. Ao contrário do baixar-todas, percorre apenas o mês informado. Ao coletar, registra uma atividade de auditoria via ActivityService.created_activity_dctfweb_recibo (no modo usar_lista_interna, apenas para CNPJs de matriz, contendo 0001); o processamento também roda inline em threadpool síncrono, sem Celery.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (RecibosMensalRequest): informe contribuinte ou usar_lista_interna: true, e a competência via competencia no formato "AAAA-MM" ou o par ano + mes. Ver Schema RecibosMensalRequest. Formato de competencia inválido retorna 422 ("Formato de 'competencia' inválido. Use 'YYYY-MM'."); ausência de competência e de ano/mes válidos retorna 422 ("Informe 'competencia' (YYYY-MM) ou 'ano' e 'mes' válidos.").

Request

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

Alternativa - todos os customers:

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

Alternativa - competência via ano + mes:

{
  "contribuinte": { "tipo": 2, "numero": "27898481000150" },
  "ano": 2025,
  "mes": 6
}

Response 200 OK

{
  "summary": {
    "total": 1,
    "abertas": 0,
    "pagas": 0,
    "vencidas": 0,
    "porTipo": { "DCTF": 1 }
  },
  "recibos": [
    {
      "id": "DCTFWeb:27898481000150:2025-06",
      "tipo": "DCTF",
      "competencia": "2025-06",
      "clienteNumero": "27898481000150",
      "descricao": "Recibo DCTFWeb - 2025-06",
      "origem": "DCTFWeb",
      "dataGeracao": "2026-07-03",
      "pdfPath": "/caminho/RECIBO_DCTF/.../DCTFWeb_27898481000150_2025-06.pdf",
      "extras": { "consulta": { "resposta": "bruta do Serpro" } }
    }
  ]
}

Mesmo envelope RecibosDownloadResponse do baixar-todas (summary + recibos), restrito à competência informada. Em caso de erro não tratado, retorna 500 com detail: "Erro ao coletar recibos mensais".

Escopo: integra_contador:write

Integração com o Serpro (Integra Contador)

Para cada (CNPJ, competência), o serviço RadarRecibosService consulta o Serpro assim:

• DCTFWeb (ativo): DCTFWebService.consultar_recibo_transmissao, com dados = { "categoria": "GERAL_MENSAL", "anoPA": <ano>, "mesPA": <mes> } e contribuinte = { tipo: 2, numero: <cnpj> }. O PDF (PDFByteArrayBase64 / variações) é extraído e, se válido (> 100 chars), salvo em disco; o caminho vai em pdfPath.
• PGDAS-D (Simples Nacional): há suporte a pgdasd_consultar_declaracao_receitas (serviço CONSDECREC15) com fallback para pgdasd_consultar_declaracao (CONSDECLARACAO13), usando dados = { "periodoApuracao": "AAAAMM" }. Atualmente essa coleta está desativada (comentada) no fluxo de processamento - as respostas trazem apenas recibos de origem DCTFWeb.

Schemas

RecibosDownloadRequest

Body de POST /baixar-todas.

Informe contribuinte ou usar_lista_interna: true - ao menos um CNPJ precisa ser resolvido, senão 422.

RecibosMensalRequest

Body de POST /baixar-mensal.

Informe competencia ou o par ano + mes.

ParteIdentificacao

Identifica o contribuinte na consulta ao Serpro.

RecibosDownloadResponse

Envelope de resposta comum aos dois endpoints.

RecibosSummary

O shape é mantido idêntico ao de Guias para compatibilidade; para recibos, os campos de situação de pagamento ficam sempre em 0.

Recibo

Notas

• As duas rotas são POST e, portanto, exigem integra_contador:write - o recurso integra_contador é compartilhado por todo o prefixo /integra-contador.
• A coleta de PGDAS-D está implementada no serviço, mas desativada (comentada) no fluxo atual; as respostas trazem apenas recibos DCTFWeb.
• Não há tasks Celery: o processamento roda inline em threadpool; coletas grandes (muitos CNPJs/anos) aumentam o tempo de resposta.
• Falhas na consulta de uma competência específica são registradas em log e não abortam a coleta das demais.
• baixar-todas limita anos a no máximo 3; baixar-mensal restringe a coleta a uma única competência.
• Relaciona-se com Radar DCTFWeb: Guias, que compartilha os helpers de resolução de CNPJs, competências e salvamento de PDF.