Prepare o ambiente

Use PHP 8.1 ou superior com a extensão cURL. Crie uma pasta de exemplo e prepare o cliente HTTP.

php --ri curl
# Habilite a extensão cURL na instalação do PHP, se necessário.

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

<?php
function request(string $url, array $headers = [], ?string $basic = null): array {
    $curl = curl_init($url);
    $retryAfter = null;
    curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => $headers,
        CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$retryAfter) {
            if (stripos($line, 'Retry-After:') === 0) $retryAfter = trim(substr($line, 12));
            return strlen($line);
        }]);
    if ($basic !== null) curl_setopt($curl, CURLOPT_USERPWD, $basic);
    $body = curl_exec($curl);
    if ($body === false) throw new RuntimeException(curl_error($curl));
    $http = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    $payload = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    if ($http >= 400 || !($payload['success'] ?? false)) {
        throw new RuntimeException(json_encode(['http' => $http,
            'codes' => array_column($payload['errors'] ?? [], 'code'),
            'retry_after' => $retryAfter]));
    }
    return $payload;
}
foreach (['AFD_PUBLIC_KEY', 'AFD_SECRET_KEY', 'AFD_PROJECT_ID'] as $name) {
    if (!getenv($name)) throw new RuntimeException('Configure ' . $name);
}
$operationKey = bin2hex(random_bytes(16));
print_r(request('https://api.apifordevs.com/api/v1/ping/billable?dev_mode=true', [
    'X-Project-Id: ' . getenv('AFD_PROJECT_ID'), 'Idempotency-Key: ' . $operationKey
], getenv('AFD_PUBLIC_KEY') . ':' . getenv('AFD_SECRET_KEY')));
print_r(request('https://api.apifordevs.com/api/v1/cnpj/00000000007951')['data'][0]);
php integracao.php

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