Prepare o ambiente

Use Go 1.22 ou superior. Crie uma pasta de exemplo e prepare o cliente HTTP.

go mod init exemplo-apifordevs
# net/http e encoding/json fazem parte da biblioteca padrão.

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

package main

import (
  "crypto/rand"
  "encoding/hex"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
  "time"
)
func env(key string) string {
  value := os.Getenv(key); if value == "" { panic("Configure " + key) }; return value
}
func read(client *http.Client, request *http.Request) map[string]interface{} {
  response, err := client.Do(request); if err != nil { panic(err) }; defer response.Body.Close()
  var payload map[string]interface{}
  if err := json.NewDecoder(response.Body).Decode(&payload); err != nil { panic(err) }
  if response.StatusCode >= 400 || payload["success"] != true {
    codes := []interface{}{}
    if errors, ok := payload["errors"].([]interface{}); ok {
      for _, raw := range errors { if e, ok := raw.(map[string]interface{}); ok { codes = append(codes, e["code"]) } }
    }
    panic(fmt.Sprintf("HTTP %d codes=%v Retry-After=%s", response.StatusCode, codes, response.Header.Get("Retry-After")))
  }
  return payload
}
func main() {
  client := &http.Client{Timeout: 30 * time.Second}
  key := make([]byte, 16); if _, err := rand.Read(key); err != nil { panic(err) }
  ping, err := http.NewRequest("GET", "https://api.apifordevs.com/api/v1/ping/billable?dev_mode=true", nil); if err != nil { panic(err) }
  ping.SetBasicAuth(env("AFD_PUBLIC_KEY"), env("AFD_SECRET_KEY"))
  ping.Header.Set("X-Project-Id", env("AFD_PROJECT_ID"))
  ping.Header.Set("Idempotency-Key", hex.EncodeToString(key))
  fmt.Println(read(client, ping))
  cnpj, err := http.NewRequest("GET", "https://api.apifordevs.com/api/v1/cnpj/00000000007951", nil); if err != nil { panic(err) }
  fmt.Println(read(client, cnpj)["data"].([]interface{})[0])
}
go run main.go

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