Radar DCTFWeb: Pagamentos

Endpoints da WebApiAlcance para a confirmação de pagamentos do Radar DCTFWeb. São a ponte com o serviço PAGTOWEB do Integra Contador (SERPRO): consultam os pagamentos arrecadados (DARF, DAS etc.) de um CNPJ - ou de todos os clientes cadastrados - dentro de um período em anos, baixam os comprovantes em PDF em lote e emitem o comprovante individual de um pagamento específico.

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: Pagamentos).

Escopo compartilhado: integra_contador

O recurso do escopo é derivado do primeiro segmento da rota após /api/v1/. Como todas estas rotas começam por /integra-contador/..., o recurso é integra_contador (hífen → underscore) - o mesmo recurso usado por todos os demais serviços do Integra Contador (guias, recibos, situação fiscal etc.). Portanto o escopo não é exclusivo de pagamentos: uma API Key com integra_contador:write habilita todos os endpoints de escrita do Integra Contador, não só os desta página.

Base path

/api/v1/integra-contador/radar/pagamentos

Escopos necessários

integra_contador:read - ações de leitura (GET) sobre o recurso compartilhado integra_contador.
integra_contador:write - ações de escrita (POST/PUT/PATCH/DELETE).

A ação é derivada do método HTTP: GET/HEAD/OPTIONS → read; POST/PUT/PATCH/DELETE → write. Os três endpoints desta página são POST - mesmo os de consulta - e portanto todos exigem integra_contador:write. O escopo integra_contador:read é listado porque pertence ao mesmo recurso compartilhado, mas não é o que habilita estas rotas.

Endpoints

`POST /integra-contador/radar/pagamentos/consultar`

Consulta os pagamentos (PAGTOWEB) no período de anos para um CNPJ ou para todos os clientes da lista interna. Não baixa PDFs - apenas normaliza e retorna os itens encontrados. Para cada CNPJ, chama o serviço SERPRO PagtoWebService.consultar_pagamentos (sistema PAGTOWEB, serviço PAGAMENTOS71), com o intervalo de datas calculado a partir de anos (mês atual para trás, até 36 meses).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (PagamentosRequest): informe contribuinte.numero (CNPJ de 14 dígitos) ou usar_lista_interna: true, com anos (1 a 3) e codigos_receita opcionais. Se nenhum dos dois resultar em CNPJ válido, retorna 422.

Request

{
  "contribuinte": { "tipo": 2, "numero": "27898481000150" },
  "anos": 1,
  "codigos_receita": ["2172", "8109"]
}

Para processar todos os clientes cadastrados, envie usar_lista_interna:

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

Response 200 OK

{
  "summary": {
    "total": 2,
    "porCodigoReceita": { "2172": 1, "8109": 1 }
  },
  "pagamentos": [
    {
      "id": "PGTO:27898481000150:2024-11-21:7162432625395640",
      "clienteNumero": "27898481000150",
      "dataArrecadacao": "2024-11-21",
      "codigoReceita": "2172",
      "tipoDocumento": "DARF",
      "valor": 1234.56,
      "origem": "PAGTOWEB",
      "pdfPath": null,
      "extras": { "raw": {} }
    }
  ]
}

Escopo: integra_contador:write

`POST /integra-contador/radar/pagamentos/baixar-comprovantes`

Consulta os pagamentos do período e baixa os comprovantes (PDF) de cada um, para um CNPJ ou para toda a lista interna. Aceita o mesmo body (PagamentosRequest) e retorna o mesmo envelope (PagamentosResponse) do /consultar, com a diferença de que o campo pdfPath de cada item é preenchido com o caminho do PDF salvo (na pasta configurada por RADAR_PAGTOS_DIR) quando o download é bem-sucedido. Internamente, além do PAGAMENTOS71, dispara a emissão de cada comprovante via PagtoWebService.emitir_comprovante_pagamento (serviço COMPARRECADACAO72).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (PagamentosRequest), idêntico ao /consultar.

Request

{
  "contribuinte": { "tipo": 2, "numero": "27898481000150" },
  "anos": 1,
  "codigos_receita": ["2172"]
}

Response 200 OK

{
  "summary": { "total": 1, "porCodigoReceita": { "2172": 1 } },
  "pagamentos": [
    {
      "id": "PGTO:27898481000150:2024-11-21:7162432625395640",
      "clienteNumero": "27898481000150",
      "dataArrecadacao": "2024-11-21",
      "codigoReceita": "2172",
      "tipoDocumento": "DARF",
      "valor": 1234.56,
      "origem": "PAGTOWEB",
      "pdfPath": "/dados/radar/pagtos/PAGTO_27898481000150_2024-11-21_7162432625395640.pdf",
      "extras": { "raw": {} }
    }
  ]
}

Escopo: integra_contador:write

`POST /integra-contador/radar/pagamentos/emitir-comprovante`

Emite (baixa) o comprovante de um pagamento específico, identificado pelo identificador_pagamento retornado na consulta. Chama PagtoWebService.emitir_comprovante_pagamento (sistema PAGTOWEB, serviço COMPARRECADACAO72) com o numeroDocumento extraído do identificador, decodifica o PDF (base64) e o salva em disco (pasta RADAR_PAGTOS_DIR).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (EmitirComprovanteRequest): contribuinte (CNPJ de 14 dígitos) e identificador_pagamento no padrão PGTO:{cnpj}:{data}:{numeroDocumento} (o mesmo id devolvido por /consultar).

Request

{
  "contribuinte": { "tipo": 2, "numero": "27898481000150" },
  "identificador_pagamento": "PGTO:27898481000150:2024-11-21T00:00:00-03:00:7162432625395640"
}

Response 200 OK

Retorna o caminho do PDF salvo (string):

"/dados/radar/pagtos/PAGTO_27898481000150_2024-11-21_7162432625395640.pdf"

Erros: 422 se faltar contribuinte (numero/tipo) ou se o identificador_pagamento não contiver numeroDocumento; 502 se o SERPRO falhar ou não retornar o PDF.

Escopo: integra_contador:write

Schemas

`PagamentosRequest`

Usado por /consultar e /baixar-comprovantes. Informe um CNPJ (via contribuinte) ou usar_lista_interna: true.

Campo	Tipo	Obrigatório	Observações
`contribuinte`	`ParteIdentificacao`	condicional	CNPJ alvo. Obrigatório se `usar_lista_interna` for `false`.
`usar_lista_interna`	`bool`	não	Default `false`. Se `true`, processa todos os CNPJs dos clientes cadastrados.
`anos`	`int` (1-3)	não	Default `1`. Período retroativo a partir do mês atual (até 36 meses).
`codigos_receita`	`List[str]`	não	Filtra por códigos de receita. Vazio = sem filtro.

`EmitirComprovanteRequest`

Usado por /emitir-comprovante.

Campo	Tipo	Obrigatório	Observações
`contribuinte`	`ParteIdentificacao`	sim	CNPJ (14 dígitos) do pagamento.
`identificador_pagamento`	`str`	sim	Identificador retornado pela consulta (PAGAMENTOS71), no padrão `PGTO:{cnpj}:{data}:{numeroDocumento}`.

`ParteIdentificacao`

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

`PagamentosResponse`

Envelope de resposta de /consultar e /baixar-comprovantes.

Campo	Tipo	Notas
`summary`	`PagamentosSummary`	Contadores agregados dos pagamentos encontrados.
`pagamentos`	`List[Pagamento]`	Itens normalizados (vazio quando nada é encontrado).

`PagamentosSummary`

Campo	Tipo	Notas
`total`	`int`	Total de pagamentos retornados.
`porCodigoReceita`	`Dict[str, int]`	Contagem de pagamentos por código de receita.

`Pagamento`

Campo	Tipo	Notas
`id`	`str`	Identificador `PGTO:{cnpj}:{data}:{numeroDocumento}`.
`clienteNumero`	`str`	CNPJ (14 dígitos).
`dataArrecadacao`	`str` \| `null`	`YYYY-MM-DD`.
`codigoReceita`	`str` \| `null`	Código da receita do documento.
`tipoDocumento`	`str` \| `null`	Tipo do documento (DARF, DAS etc.).
`valor`	`float`	Valor total do pagamento. Default `0.0`.
`origem`	`str`	Sempre `"PAGTOWEB"`.
`pdfPath`	`str` \| `null`	Caminho do PDF do comprovante (preenchido só ao baixar).
`extras`	`Dict[str, Any]`	Metadados adicionais; inclui `raw` (item bruto do SERPRO).

Notas

Origem dos dados: SERPRO Integra Contador, sistema PAGTOWEB - serviço PAGAMENTOS71 (consulta) e COMPARRECADACAO72 (emissão do comprovante).
Sem Celery: o processamento dos CNPJs roda de forma síncrona em threadpool (anyio.to_thread.run_sync), não em tasks Celery. As chamadas ao SERPRO são bloqueantes e executadas fora do event loop.
Período: anos (1 a 3) define a janela retroativa a partir do mês atual, até no máximo 36 meses.
Lista interna: com usar_lista_interna: true, os CNPJs vêm de customer_service.list_customers(); apenas números com 14 dígitos são considerados.
PDFs: os comprovantes baixados são salvos na pasta definida por RADAR_PAGTOS_DIR (variável de ambiente / RADAR_PAGTOS_DIR em config).
Erros do SERPRO propagam como HTTPException - tipicamente 502 (falha na integração) ou 422 (payload inválido); erros inesperados retornam 500.