Prepare o ambiente

Use Java 17 ou superior e Maven. Crie uma pasta de exemplo e prepare o cliente HTTP.

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.exemplo</groupId>
  <artifactId>integracao-apifordevs</artifactId>
  <version>1.0.0</version>
  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.18.6</version>
    </dependency>
  </dependencies>
  <build><plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.14.1</version>
    </plugin>
  </plugins></build>
</project>

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 src/main/java/Integracao.java. Ele faz duas chamadas: primeiro o ping autenticado em DEV; depois a consulta real e aberta do CNPJ de exemplo.

import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.*;
import com.fasterxml.jackson.databind.*;

public class Integracao {
  static final ObjectMapper JSON = new ObjectMapper();
  static String env(String key) {
    String value = System.getenv(key);
    if (value == null || value.isBlank()) throw new IllegalArgumentException("Configure " + key);
    return value;
  }
  static JsonNode read(HttpResponse<String> response) throws Exception {
    JsonNode payload = JSON.readTree(response.body());
    if (response.statusCode() >= 400 || !payload.path("success").asBoolean()) {
      List<String> codes = new ArrayList<>();
      payload.path("errors").forEach(error -> codes.add(error.path("code").asText()));
      throw new IllegalStateException("HTTP " + response.statusCode() + " " + codes
        + " Retry-After=" + response.headers().firstValue("Retry-After").orElse(""));
    }
    return payload;
  }
  public static void main(String[] args) throws Exception {
    var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build();
    String basic = Base64.getEncoder().encodeToString(
      (env("AFD_PUBLIC_KEY") + ":" + env("AFD_SECRET_KEY")).getBytes(StandardCharsets.UTF_8));
    String operationKey = UUID.randomUUID().toString();
    var ping = HttpRequest.newBuilder(URI.create("https://api.apifordevs.com/api/v1/ping/billable?dev_mode=true"))
      .timeout(Duration.ofSeconds(30)).header("Authorization", "Basic " + basic)
      .header("X-Project-Id", env("AFD_PROJECT_ID")).header("Idempotency-Key", operationKey).GET().build();
    System.out.println(read(client.send(ping, HttpResponse.BodyHandlers.ofString())));
    var cnpj = HttpRequest.newBuilder(URI.create("https://api.apifordevs.com/api/v1/cnpj/00000000007951"))
      .timeout(Duration.ofSeconds(30)).GET().build();
    System.out.println(read(client.send(cnpj, HttpResponse.BodyHandlers.ofString())).path("data").get(0));
  }
}
mvn compile
mvn org.codehaus.mojo:exec-maven-plugin:3.5.0:java -Dexec.mainClass=Integracao

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