Prepare o ambiente

Use .NET 8 SDK ou superior. Crie uma pasta de exemplo e prepare o cliente HTTP.

dotnet new console --name ExemploApiForDevs
cd ExemploApiForDevs

Configure chave e projeto

Crie uma chave de Desenvolvimento no painel. O ping deste guia usa dev_mode=true: simula a resposta sem cobrança. A chave pública identifica sua integração; o segredo fica em uma variável de ambiente no servidor.

Defina as três variáveis no ambiente do terminal. Os valores abaixo são marcadores: substitua pela sua chave e pelo identificador real do projeto.

$env:AFD_PUBLIC_KEY="afd_test_pk_..."
$env:AFD_SECRET_KEY="seu_segredo_de_desenvolvimento"
$env:AFD_PROJECT_ID="proj_..."

A autenticação HTTP Basic codifica public_key:secret_key em Base64. O cabeçalho X-Project-Id seleciona o projeto. Na consulta pública de CNPJ, nenhum desses cabeçalhos é necessário.

Como criar e proteger suas chaves

Execute a primeira chamada

Salve o exemplo em Program.cs. Ele faz duas chamadas: primeiro o ping autenticado em DEV; depois a consulta real e aberta do CNPJ de exemplo.

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json.Nodes;

static string Env(string name) => Environment.GetEnvironmentVariable(name)
    ?? throw new InvalidOperationException("Configure " + name);
static async Task<JsonNode> Read(HttpResponseMessage response) {
    var payload = JsonNode.Parse(await response.Content.ReadAsStringAsync())
        ?? throw new InvalidOperationException("Resposta vazia");
    if (!response.IsSuccessStatusCode || payload["success"]?.GetValue<bool>() != true) {
        var codes = payload["errors"]?.AsArray().Select(e => e?["code"]?.ToString());
        throw new InvalidOperationException($"HTTP {(int)response.StatusCode} " +
            string.Join(",", codes ?? []) + " Retry-After=" + response.Headers.RetryAfter);
    }
    return payload;
}
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
var operationKey = Guid.NewGuid().ToString();
using var ping = new HttpRequestMessage(HttpMethod.Get, "https://api.apifordevs.com/api/v1/ping/billable?dev_mode=true");
ping.Headers.Authorization = new AuthenticationHeaderValue("Basic",
    Convert.ToBase64String(Encoding.UTF8.GetBytes(Env("AFD_PUBLIC_KEY") + ":" + Env("AFD_SECRET_KEY"))));
ping.Headers.Add("X-Project-Id", Env("AFD_PROJECT_ID"));
ping.Headers.Add("Idempotency-Key", operationKey);
using var pingResponse = await client.SendAsync(ping);
Console.WriteLine(await Read(pingResponse));
// Cliente sem cabeçalho de autenticação na consulta pública.
using var cnpjResponse = await client.GetAsync("https://api.apifordevs.com/api/v1/cnpj/00000000007951");
Console.WriteLine((await Read(cnpjResponse))["data"]?[0]);

dotnet run

Leia a resposta e os erros

O envelope inclui success, code, errors, header, data_count e data. No CNPJ, o primeiro resultado fica em data[0]. Confira found e reference_month antes de usar os campos.

Trate o status HTTP e errors[].code. Um CNPJ inválido retorna erro de validação; um CNPJ fora da base pode responder com sucesso e found: false. Ao receber HTTP 429, aguarde o período indicado em Retry-After. Não repita erros de validação sem corrigir a entrada.

Ver contrato e códigos da consulta CNPJ

Repita com segurança

O exemplo cria uma chave de operação. Nos endpoints que aceitam Idempotency-Key, reutilize o mesmo valor ao repetir a mesma operação lógica após uma falha de conexão. Uma operação nova recebe outra chave. Confira no detalhe do endpoint a janela e o comportamento de idempotência; o cabeçalho não transforma uma API sem suporte em idempotente.

Para testar esse comportamento, mantenha o valor de operationKey ou operation_key entre duas tentativas da mesma requisição. Não gere outro UUID dentro do loop de repetição. Respeite os limites mesmo quando repetir a operação.

Entenda idempotência na prática

Leve a consulta para o seu cadastro.

Explore os filtros de listagem, os campos de CNPJ e os demais serviços de empresas.

Conhecer as APIs de CNPJ