Índice

1. Objetivo
2. Histórico de versão
3. Regras de retorno
4. Endpoint da api
5. Estrutura principal do JSON do arquivo de retorno (download via urlAssinada)
6. Exemplo do JSON de retorno (download via urlAssinada)

Consultar pagamentos de CBS

1. Objetivo

Retorna as atualizações de pagamentos de CBS que extinguem os débitos do contribuinte, compreendendo: o pagamento do próprio contribuinte e o recolhimento de seus adquirentes.

Esta API funciona em modo assíncrono. Para orientações de uso, consulte as Regras Comuns às APIs Assíncronas da Apuração de CBS: regras de APIs assíncronas

2. Histórico de versão

3. Regras de retorno

Para solicitações com consulta concluída nos últimos 3 meses, são retornadas as inclusões e atualizações desde a data de atualização da solicitação concluída mais recente, limitada aos últimos 8 dias. Quando não há consulta concluída nesse período, a busca começa no 1º dia do mês corrente.

4. Endpoint da api

• URL de Produção:
  • https://api.receitafederal.gov.br/apuracao-cbs/v2/pagamentos/{cnpj}

4.1 Campos de Entrada

4.2 Header

4.3 Request Body

4.4 Acionar o endpoint

1. Substitua $TOKEN pelo valor de access_token.
2. Substitua {cnpj} pelo CNPJ base com 8 dígitos.
3. Opcionalmente, informe no corpo uma urlRetorno (URL do webhook) acessível por HTTP ou HTTPS para receber a notificação de conclusão da solicitação ou de erro no processamento. Quando não houver webhook, informar "" (string vazia). Sem esse campo, consulte a situação da solicitação para acompanhar o processamento.

Exemplo de chamada (com variável TOKEN)

curl --location --request POST 'https://api.receitafederal.gov.br/apuracao-cbs/v2/pagamentos/{cnpj}' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{ "urlRetorno": "https://cliente.exemplo.com/webhooks/apuracao-cbs" }'

Exemplo com dados fictícios

curl --location --request POST 'https://api.receitafederal.gov.br/apuracao-cbs/v2/pagamentos/12345678' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.dadoFicticio.assinaturaFicticia' \
  --data '{ "urlRetorno": "https://cliente.exemplo.com/webhooks/apuracao-cbs" }'

Exemplo de chamada (sem webhook)

curl --location --request POST 'https://api.receitafederal.gov.br/apuracao-cbs/v2/pagamentos/{cnpj}' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"urlRetorno":""}'

4.5 Campos Retornados

Exemplo de retorno em caso de sucesso (HTTP 201)

{
  "tiqueteSolicitacao": "692b7b25-44cb-4415-8625-2b9522dd7933.B5E08D55",
  "tEASegundos": 120
}

Exemplos de retorno em caso de erro

Requisição inválida (HTTP 400):

{
  "codigoErro": "REQUISICAO_INVALIDA",
  "mensagemErro": "corpo da requisição inválido"
}

Não autorizado (HTTP 401):

{
  "codigoErro": "NAO_AUTORIZADO",
  "mensagemErro": "consumidor não autorizado para este NI"
}

Erro interno (HTTP 500):

{
  "codigoErro": "ERRO_INTERNO",
  "mensagemErro": "erro interno ao processar solicitação"
}

Exemplo de objeto enviado para urlRetorno(webhook) em caso de sucesso (HTTP 2xx)

{
  "tiqueteSolicitacao":"48d88a3c-eff9-4489-8e3a-cde8d878d3f7.1E0CE7A4",
  "situacao": "CONCLUIDA"  
 } 

5. Estrutura principal do JSON do arquivo de retorno(download via urlAssinada)

6. Exemplo do JSON de retorno (download via urlAssinada)

{
  "tiqueteSolicitacao": "48d88a3c-eff9-4489-8e3a-cde8d878d3f7.1E0CE7A4",
  "ni": "12345678",
  "niConsumidor": "12345678",
  "geradoEm": "2026-08-27T14:48:05Z",
  "apuracao": [
    {
      "dataArrecadacao": "2026-08-27T14:48:05.745Z",
      "pagamentos": [
        {
          "numeroDARF": "20260827000000001",
          "tipo": 1,
          "niAdquirente": "",
          "composicao": [
            {
              "sequencial": 1,
              "pa": "08/2026",
              "vencimento": "2026-09-20T00:00:00Z",
              "ni_contribuinte": "12345678000195",
              "chaveDFE": "",
              "principal": 100.00,
              "multa": 2.00,
              "juros": 1.00,
              "total": 103.00
            }
          ]
        },
        {
          "numeroDARF": "20260827000000002",
          "tipo": 2,
          "niAdquirente": "98765432000123",
          "composicao": [
            {
              "sequencial": 2,
              "pa": "08/2026",
              "vencimento": "2026-09-20T00:00:00Z",
              "ni_contribuinte": "12345678000195",
              "chaveDFE": "35260812345678000195550010000001231234567890",
              "principal": 80.00,
              "multa": 0.50,
              "juros": 1.25,
              "total": 81.75
            }
          ]
        }
      ]
    }
  ]
}