# API de CND Federal: certidão da Receita e da PGFN por CNPJ > Devolve a Certidão de Débitos relativos a Tributos Federais e à Dívida Ativa da União (RFB e PGFN), a que ainda vale ou uma emitida na hora, com o PDF oficial. URL: https://docs.fiscalapi.com.br/docs/certidoes-federais/consultar-cnd-federal Atualizado em 06/11/2026 `GET /api/consultar-cnd-federal` devolve a certidão de débitos relativos a tributos federais e à Dívida Ativa da União de um CNPJ, emitida em conjunto pela Receita Federal (RFB) e pela Procuradoria-Geral da Fazenda Nacional (PGFN), com o PDF oficial, e conta como **1 consulta** (de R$ 0,025 a R$ 0,67, conforme o plano), seja a certidão que já existia ou uma emitida na hora. A certidão vale **180 dias** a partir da emissão e é aceita para o estabelecimento matriz e suas filiais. ## ## Resumo | Item | Valor | | -------------------- | ------------------------------------------------------------------------------------------------- | | Endpoint | `GET https://api.fiscalapi.com.br/api/consultar-cnd-federal` | | Você envia | `cnpj` (por enquanto, só CNPJ) | | Órgão emissor | Receita Federal e PGFN | | Volta | `status`, validade, emissão, número da certidão, `modo` (`consulta` ou `emissao`) e PDF em base64 | | Validade da certidão | 180 dias | | Tempo | Até cerca de 60 segundos quando precisa emitir | ## ## Quanto custa cada chamada | Chamada | Conta como | Lite | Starter | Pro | Enterprise | | ------------------------------------------ | ---------- | ------- | ------- | -------- | ---------- | | CND Federal (`/api/consultar-cnd-federal`) | 1 consulta | R$ 0,67 | R$ 0,10 | R$ 0,065 | R$ 0,025 | Valores por consulta dentro da franquia mensal; recarga a R$ 0,12 (Starter), R$ 0,07 (Pro) ou R$ 0,02 (Enterprise). Veja [Planos e limites](/docs/referencia/plans-and-limits). * **Não é cobrada:** erro HTTP, `status: "erro"`, `EM_PROCESSAMENTO` e os demais códigos de `source_status`. * **É cobrada:** a certidão devolvida, inclusive com `emitir_nova=true`. ## ## Como funciona * **Já existe certidão válida por mais de 3 dias:** a API devolve essa certidão, com o PDF oficial (`modo: "consulta"`). Nada é emitido. * **Não existe, ou a existente vence em até 3 dias:** a API emite uma certidão nova na Receita e devolve o PDF (`modo: "emissao"`). * **`emitir_nova=true`:** a API sempre emite uma certidão nova, mesmo que já exista uma válida. Por enquanto, somente **CNPJ**. A Receita exige a data de nascimento para emitir a certidão de pessoa física, e este endpoint ainda não recebe esse dado: consultas por `cpf` voltam `status: "erro"`, sem cobrança. ## ## Autenticação Envie sua chave no header `X-API-Key`. Veja [Autenticação](/docs/getting-started/authentication) para detalhes. ## ## Parâmetros de consulta Informe o parâmetro `cnpj`. Se `cpf` e `cnpj` forem enviados juntos, `cnpj` tem precedência. | Name | Type | Required | Description | | ------------- | ------- | -------- | --------------------------------------------------------------------------------- | | `cnpj` | string | Sim | CNPJ do contribuinte (somente números, 14 dígitos). | | `emitir_nova` | boolean | Não | `true` emite sempre uma certidão nova, sem usar a que já existe. Padrão: `false`. | ## ## Exemplos ### ### CND Federal de um CNPJ ```bash curl -X GET "https://api.fiscalapi.com.br/api/consultar-cnd-federal?cnpj=12345678000195" \ -H "X-API-Key: fapi_sua_chave_aqui" ``` ```javascript const response = await fetch( "https://api.fiscalapi.com.br/api/consultar-cnd-federal?cnpj=12345678000195", { headers: { "X-API-Key": "fapi_sua_chave_aqui" } } ); const data = await response.json(); console.log(data.result.status, data.result.modo); ``` ```python import requests response = requests.get( "https://api.fiscalapi.com.br/api/consultar-cnd-federal", headers={"X-API-Key": "fapi_sua_chave_aqui"}, params={"cnpj": "12345678000195"}, ) data = response.json() print(data["result"]["status"], data["result"]["modo"]) ``` ```php $response = Http::withHeaders([ 'X-API-Key' => 'fapi_sua_chave_aqui', ])->get('https://api.fiscalapi.com.br/api/consultar-cnd-federal', [ 'cnpj' => '12345678000195', ]); $data = $response->json(); ``` ```csharp var client = new HttpClient(); client.DefaultRequestHeaders.Add("X-API-Key", "fapi_sua_chave_aqui"); var response = await client.GetAsync( "https://api.fiscalapi.com.br/api/consultar-cnd-federal?cnpj=12345678000195" ); var data = await response.Content.ReadAsStringAsync(); ``` ### ### Emitir sempre uma certidão nova ```bash curl -X GET "https://api.fiscalapi.com.br/api/consultar-cnd-federal?cnpj=12345678000195&emitir_nova=true" \ -H "X-API-Key: fapi_sua_chave_aqui" ``` Chamadas repetidas com `emitir_nova=true` para o mesmo CNPJ em até 15 minutos devolvem a mesma emissão, sem emitir outra. Se a Receita já emitiu uma certidão para o CNPJ no mesmo dia, ela pode devolver o mesmo código de controle. ## ## Resposta ### ### Campos de nível superior | Campo | Tipo | Descrição | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `request_id` | string | Identificador único da requisição (UUID). | | `document` | string | Documento consultado. | | `document_type` | string | Tipo do documento: `cnpj` ou `cpf`. | | `cached` | boolean | `true` quando a certidão já estava guardada. A mesma certidão é devolvida enquanto valer por mais de 3 dias. | | `source_status` | object | Status da fonte (`status`, `error_code`, `error_message`). | | `result` | object | Dados da certidão. Vem `null` quando `source_status.status` não é `success`. | ### ### Campos de `result` | Campo | Tipo | Descrição | | ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | | `tipo` | string | Sempre `cnd_federal` neste endpoint. | | `status` | string | Status normalizado da certidão. Veja tabela abaixo. | | `status_raw` | string | Título da certidão ou mensagem da Receita. | | `modo` | string | `consulta`: certidão que já existia. `emissao`: certidão emitida nesta consulta. | | `validade` | string | Data de validade (`DD/MM/AAAA`). | | `validade_iso` | string | Data de validade em ISO 8601 (`YYYY-MM-DD`). | | `emissao` | string | Data de emissão (`DD/MM/AAAA`). | | `emissao_iso` | string | Data de emissão em ISO 8601 (`YYYY-MM-DD`). | | `protocolo` | string | Código de controle da certidão, no formato `XXXX.XXXX.XXXX.XXXX`. | | `pdf_base64` | string | PDF oficial da certidão em base64. Vazio quando a Receita não emite (pendências). | | `url_verificacao` | string | Reservado; hoje vem vazio. A autenticidade é conferida com o código de controle nos sites da Receita Federal ou da PGFN. | | `orgao` | string | Sempre `RFB+PGFN` neste endpoint. | ### ### Valores de status | Status | Significado | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `negativa` | **Não constam pendências** relativas a tributos federais e a dívida ativa da União. Situação regular. | | `positiva` | **Há pendências.** Inclui o caso em que a Receita não emite a certidão pela internet por pendência ou situação cadastral: vem sem PDF, com a mensagem da Receita em `status_raw`. | | `positiva_com_efeitos_de_negativa` | Há débitos, mas **suspensos ou garantidos** (parcelamento, decisão judicial etc.). Tem os mesmos efeitos da certidão negativa. | | `nao_contribuinte` | O CNPJ não está cadastrado na Receita Federal. | | `erro` | A Receita recusou o pedido (ex.: CNPJ de filial — a certidão sai para a matriz) ou o PDF não pode ser validado. A mensagem vem em `status_raw`. Não é cobrada. | ### ### Exemplo de resposta (certidão que já existia) ```json { "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "document": "12345678000195", "document_type": "cnpj", "cached": false, "source_status": { "status": "success", "error_code": "", "error_message": "" }, "result": { "tipo": "cnd_federal", "status": "negativa", "status_raw": "Certidao Negativa de Debitos relativos aos Tributos Federais e a Divida Ativa da Uniao", "modo": "consulta", "validade": "13/03/2027", "validade_iso": "2027-03-13", "emissao": "14/09/2026", "emissao_iso": "2026-09-14", "protocolo": "1A2B.3C4D.5E6F.7A8B", "pdf_base64": "JVBERi0xLjQK...", "url_verificacao": "", "orgao": "RFB+PGFN" } } ``` O `status`, as datas e o código de controle são lidos do próprio PDF da Receita, e a certidão só é entregue se o PDF declarar o CNPJ consultado. Quando isso não dá para confirmar, a API responde `status: "erro"` em vez de presumir regularidade. ## ## Quando a emissão ainda está em andamento A consulta pode levar até cerca de 60 segundos. Se a certidão não ficar pronta nesse tempo, a API responde **HTTP 200** com `error_code: "EM_PROCESSAMENTO"` e o header `Retry-After` (em segundos). A emissão continua em segundo plano: consulte de novo depois do tempo indicado para receber a certidão. Consultar de novo não dispara outra emissão e essa resposta não é cobrada. ```http HTTP/1.1 200 OK Retry-After: 45 ``` ```json { "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "document": "12345678000195", "document_type": "cnpj", "cached": false, "source_status": { "status": "error", "error_code": "EM_PROCESSAMENTO", "error_message": "A emissao desta certidao esta em andamento. Consulte novamente em cerca de 45 s." }, "result": null } ``` ```python import time import requests def consultar_cnd_federal(cnpj: str) -> dict: while True: response = requests.get( "https://api.fiscalapi.com.br/api/consultar-cnd-federal", headers={"X-API-Key": "fapi_sua_chave_aqui"}, params={"cnpj": cnpj}, ) data = response.json() if data["source_status"].get("error_code") != "EM_PROCESSAMENTO": return data time.sleep(int(response.headers.get("Retry-After", 30))) ``` ## ## Códigos de erro ### ### Em `source_status` (HTTP 200) | Código | Descrição | | -------------------------------- | ------------------------------------------------------------------------------------- | | `EM_PROCESSAMENTO` | A certidão ainda está sendo emitida. Consulte de novo depois do `Retry-After`. | | `PROVIDER_ERROR` | A Receita Federal não concluiu a emissão agora. Consulte novamente em alguns minutos. | | `CNPJ_INVALIDO` / `CPF_INVALIDO` | Documento com formato inválido ou dígito verificador que não confere. | ### ### HTTP | Código | HTTP Status | Descrição | | --------------------- | ----------- | ------------------------------------------------- | | `PARAMETRO_AUSENTE` | 400 | Nenhum documento (`cnpj` ou `cpf`) foi informado. | | `LIMITE_ATINGIDO` | 402 | Cota mensal do plano esgotada e sem recarga. | | `RATE_LIMIT_EXCEEDED` | 429 | Rate limit do plano excedido. | | `ERRO_INTERNO` | 500 | Erro interno no servidor. | ## ## Integração com ERPs A chamada é um `GET` com o header `X-API-Key`, em geral na homologação de fornecedores, em licitações ou antes de liberar crédito. Não existe conector pronto. | Sistema | Como chamar a API REST | | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | TOTVS Protheus | Num fonte ADVPL/TLPP, com a classe `FWRest` ou a função `HttpGet`. | | SAP (ECC, S/4HANA) | Em ABAP, com `cl_http_client`, ou por um fluxo no SAP Integration Suite. | | Sankhya, Senior, Omie, Bling | Por um serviço intermediário (script, n8n, Make) que chama a FiscalAPI e grava o resultado pela API do ERP. | | Odoo | Num módulo próprio em Python, com `requests`. | ## ## Perguntas frequentes ### ### Existe API de CND Federal? Sim. `GET /api/consultar-cnd-federal` recebe o CNPJ e devolve a certidão de tributos federais e Dívida Ativa da União com o PDF oficial. Se já existe uma válida por mais de 3 dias, volta essa; se não, a API emite uma nova. ### ### Quanto custa a CND Federal por API? 1 consulta por chamada: R$ 0,025 no Enterprise, R$ 0,065 no Pro, R$ 0,10 no Starter e R$ 0,67 no Lite, dentro da franquia. Erro e emissão ainda em andamento não são cobrados. ### ### Funciona com CPF? Ainda não. A Receita exige a data de nascimento para emitir a certidão de pessoa física, e o endpoint não recebe esse dado. Consulta por `cpf` volta `status: "erro"`, sem cobrança. ### ### Qual a validade da CND Federal? 180 dias a partir da emissão. A data vem no campo `validade`.