Índice
- Objetivo
- Histórico de versão
- Regras de retorno
- Endpoint da API
- Schema JSON de retorno
- Exemplos de retorno
Gerar DARF para Pagamento de CBS como Contribuinte
1. Objetivo
Gerar DARF para pagamento de CBS como contribuinte (PCONT).
2. Histórico de versão
| Data | Versão | Descrição |
|---|---|---|
| 13/11/2026 | 1.0 | Versão inicial |
3. Regras de retorno
Esta API funciona em modo síncrono, gerando documentos de arrecadação de acordo com os valores processados pela Apuração Assistida de CBS.
4. Endpoint da API
- URL de Produção:
https://api.receitafederal.gov.br/apuracao-cbs/v2/pcont/{cnpj}
4.1 Campos de Entrada
| Campo | Formato | Descrição |
|---|---|---|
| cnpj | String (14) | CNPJ base informado no path. |
4.2 Header
| Campo | Formato | Descrição |
|---|---|---|
| Authorization | String | Bearer <token de acesso>, informado na requisição. |
4.3 Request Body
| Campo | Objeto da cardinalidade | Nível | Formato | Descrição |
|---|---|---|---|---|
| pa | raiz (body) | 1 | String(7) | Período de apuração, exemplo 08/2026. |
| opcaoPagamento | raiz (body) | 1 | String | Opção de pagamento selecionada para emissão do DARF. Valores possíveis: PAGAMENTO_PARCIAL e PAGAMENTO_TOTAL. |
| valorDarfParcial | raiz (body) | 1 | Number (18,2) | Valor parcial do DARF, quando opcaoPagamento = PAGAMENTO_PARCIAL. |
4.4 Acionar o endpoint
- Substitua
$TOKENpelo valor deaccess_token. - Substitua
{cnpj}pelo CNPJ com 14 dígitos.
Método: POST
Exemplo de chamada (Pagamento total)
curl --location --request POST 'https://api.receitafederal.gov.br/apuracao-cbs/v2/pcont/{cnpj}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"pa": "08/2026",
"opcaoPagamento": "PAGAMENTO_TOTAL"
}'
Exemplo de chamada (Pagamento parcial)
curl --location --request POST 'https://api.receitafederal.gov.br/apuracao-cbs/v2/pcont/12345678922222' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"pa": "08/2026",
"opcaoPagamento": "PAGAMENTO_PARCIAL",
"valorDarfParcial": 1500.75
}'
4.5 Campos Retornados
| Campo | Objeto da cardinalidade | Nível | Card. | Formato | Descrição |
|---|---|---|---|---|---|
| cdRetorno | raiz | 1 | 1:1 | String |
Código de retorno da operação:
DARF_GERADO = Documento fiscal encontrado, ainda não extinto e DARF gerado com sucesso DFE_NAO_ENCONTRADO = Documento fiscal não encontrado ou não vinculado ao CNPJ requisitante VALOR_PARCIAL_SUPERIOR_DFE = Valor informado para pagamento parcial é superior ao valor total do documento fiscal informado CNPJ_NAO_ADQUIRENTE = CNPJ não é o adquirente da DF-e DADOS_DE_ENTRADA_INVALIDOS = dados inválidos <lista de dados inválidos> |
| darf | raiz | 1 | 1:1 | Object | Grupo com dados de pagamento do DARF (presente quando cdRetorno = DARF_GERADO). |
| chavePIX | darf | 2 | 1:1 | String | Chave PIX para pagamento. |
| codigoBarras | darf | 2 | 1:1 | String | Código de barras do DARF. |
| linkDarfPDF | darf | 2 | 1:1 | String | Link para download do PDF do DARF. |
| informacoesPagamento | raiz | 1 | 1:1 | Object | Grupo com vencimento e valores (presente quando cdRetorno = DARF_GERADO). |
| dataMaximaPagamento | informacoesPagamento | 2 | 1:1 | String (date ISO 8601 - YYYY-MM-DD) | Data máxima para pagamento. |
| valorDarfPrincipal | informacoesPagamento | 2 | 1:1 | number (18,2) | Valor principal. |
| valorDarfMulta | informacoesPagamento | 2 | 1:1 | number (18,2) | Valor Multa. |
| valorDarfJuros | informacoesPagamento | 2 | 1:1 | number (18,2) | Valor Juros. |
| valorDarfTotal | informacoesPagamento | 2 | 1:1 | number (18,2) | Valor Total. |
| mensagem | raiz | 1 | 0:1 | String | Mensagem de erro. |
| dadosInvalidos | raiz | 1 | 0:N | Array de String | Lista de campos inválidos (quando cdRetorno = DADOS_DE_ENTRADA_INVALIDOS). |
5. Schema JSON de retorno
- Download (arquivo): gerar-darf-contrib-retorno.schema.json
- Padrão: JSON Schema Draft 2020-12
- Versão do schema:
1.0.0
6. Exemplos de retorno
Exemplo de retorno em caso de sucesso (HTTP 200)
{
"cdRetorno": "DARF_GERADO",
"darf": {
"chavePIX": "123e4567-e89b-12d3-a456-426614174000",
"codigoBarras": "85870000001512345678901234567890123456789012",
"linkDarfPDF": "https://api.receitafederal.gov.br/downloads/darf/abc123.pdf"
},
"informacoesPagamento": {
"dataMaximaPagamento": "2026-08-13",
"valorDarfPrincipal": 1500.75,
"valorDarfMulta": 25.10,
"valorDarfJuros": 10.25,
"valorDarfTotal": 1536.10
}
}
Exemplo de retorno em caso de erro (HTTP 400/401/404/500)
{
"cdRetorno": "DADOS_DE_ENTRADA_INVALIDOS",
"mensagem": "Dados de entrada inválidos.",
"dadosInvalidos": [
"pa",
"opcaoPagamento",
"valorDarfParcial"
]
}