Í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 créditos em operações de consumo (CBS)

1. Objetivo

Retorna os créditos de Contribuição sobre Bens e Serviços (CBS) incluídos ou atualizados entre a data consulta e a data da última consulta anterior.

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/creditos/{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. 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/creditos/{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/creditos/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/creditos/{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)

Observação: Com exceção dos campos apurado e saldoCredor, os demais campos de valor não serão exibidos se o resultado for igual a zero.

Se não houver créditos que atendam à janela de consulta, o campo apuracao será retornado como uma lista vazia ([]). Valores numéricos zero marcados como opcionais não são incluídos no JSON; os objetos apropriacao, utilizacao e naoUtilizado são incluídos mesmo quando seus valores são zero.

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

{
  "tiqueteSolicitacao": "48d88a3c-eff9-4489-8e3a-cde8d878d3f7.1E0CE7A4",
  "ni": "12345678",
  "niConsumidor": "12345678",
  "geradoEm": "2026-08-26T16:00:00Z",
  "apuracao": [
    {
      "pa": "08/2026",
      "creditos": [
        {
          "origem": 0,
          "documento": 1,
          "chave": "string",
          "emissao": "2026-08-01T00:00:00Z",
          "registro": "2026-08-01T00:00:00Z",
          "atualizacao": "2026-08-01T00:00:00Z",
          "cbs": {
            "apurado": 15,
            "apropriacao": {
              "utilizacao": {
                "naoUtilizado": {
                  "saldoCredor": 0
                }
              }
            }
          }
        }
      ]
    }
  ]
}