Documentação da Claude API: por onde começar na sua primeira integração?

Fala aí, beleza? A documentação da Claude API não é pequena, e é justamente aí que mora o problema: você abre os docs oficiais, vê dezenas de páginas no menu lateral e não faz ideia de qual clicar primeiro

Aí o que acontece? Você desiste da fonte oficial e vai copiar tutorial de terceiro de sabe-se lá quando, com nome de modelo que já saiu de circulação e header faltando

Este post é um guia de leitura dos docs oficiais, publicados como Claude Platform Docs em platform.claude.com/docs

A ideia é simples: te mostrar QUAL página abrir em cada momento da sua primeira integração, e transformar a documentação em referência de consulta em vez de leitura linear infinita

Um detalhe que confunde bastante gente logo de cara: URLs antigas em docs.anthropic.com continuam resolvendo e mostrando o mesmo conteúdo dos Claude Platform Docs, então se você cair num link velho, não se assuste, é o mesmo material =)

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

O que você precisa antes de abrir o primeiro doc:

Antes de sair lendo, junta esse kit básico:

• Acesso ao Claude Console, com o detalhe bom: platform.claude.com e console.anthropic.com compartilham o mesmo sign-in, então é um login só
• Uma chave de API criada em Settings > API keys (console.anthropic.com/settings/keys)
• Um ambiente com Python ou Node.js rodando, ou um terminal com curl na mão se você quiser ver o HTTP cru

Sobre a chave, três coisas que a documentação avisa e que valem ouro:

Ela é exibida uma única vez, começa com o prefixo sk-ant- e a Anthropic não armazena o valor secreto

Ou seja: perdeu, não recupera, cria outra

Você também pode definir expiração no momento da criação, o que é bem massa pra chave de teste que você não quer deixar viva pra sempre

E a regra que não se negocia: a chave vive em variável de ambiente, nunca dentro do código

Já me ferrei uma vez com credencial em arquivo versionado, e não é uma experiência que eu recomende a ninguém haha

Passo a passo: da documentação até a primeira requisição

A ordem abaixo é a ordem real de leitura dos docs, do primeiro clique até a resposta chegar no seu terminal

1. Comece pelo Get started, em platform.claude.com/docs/en/get-started

Essa é a página inicial de integração, e o objetivo dela é te dar o fluxo mínimo: chave, SDK, primeira chamada

Leia inteira antes de sair copiando trecho, ela é curta e te poupa de voltar depois

O erro comum deste passo: pular direto pro exemplo de código sem entender o fluxo, e depois não saber diferenciar o que é problema de chave do que é problema de payload

2. Crie a chave no Console e exporte na variável de ambiente

O caminho confirmado na documentação é Settings > API keys

Criou? Copia na hora, porque a exibição é única

# Linux / macOS
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Os SDKs oficiais leem ANTHROPIC_API_KEY automaticamente do ambiente, então você não precisa passar a chave no construtor

O erro comum deste passo: colar a chave direto no código "só pra testar rapidinho" e esse rapidinho virar commit público

3. Instale o SDK, ou decida por HTTP direto

# Python
pip install anthropic

# Node.js / TypeScript
npm install @anthropic-ai/sdk

Se você conhece qualquer SDK de API HTTP, esse aqui não tem mistério: ele é um cliente que monta os headers e o corpo por você

Mas se a sua stack não for Python nem Node, ou se você só quer ENTENDER o que trafega, dá pra falar HTTP direto e ficar tudo certo também

O erro comum deste passo: instalar o SDK e mesmo assim seguir um tutorial de curl no meio do caminho, misturando as duas abordagens e se perdendo em qual header você já mandou

4. Abra o API overview pra montar a requisição

A página de visão geral da API é separada do guia de início e mora em platform.claude.com/docs/en/api/overview

É ali que você confirma o essencial: o header anthropic-version é obrigatório em todas as requisições

O endpoint principal pra enviar mensagens é a Messages API, via POST

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "NOME_DO_MODELO",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Oi, tudo certo?"}
    ]
  }'

Repara na anatomia: autenticação no header x-api-key, versão da API no anthropic-version: 2023-06-01, content-type: application/json e o corpo com model, max_tokens e messages

O erro comum deste passo: esquecer o anthropic-version e ficar achando que o problema é a chave

5. Escolha o modelo pelas páginas vivas, não pelo tutorial que você achou

São duas páginas, e elas fazem coisas diferentes:

• Models overview, pra ver o que existe hoje
• Choosing a model, pra decidir qual encaixa no seu caso

Nome de modelo muda, e é da página viva que você tira o identificador exato pra colar no campo model

E já que você está mexendo nisso, vale entender quando fixar a versão do modelo em vez de usar um apelido genérico, porque essa decisão te morde lá na frente

O erro comum deste passo: chutar o identificador do modelo a partir de um artigo antigo e receber um erro de requisição inválida que você vai jurar que é bug da API 😛

Erros da primeira integração e qual página dos docs resolve

Aqui está a parte que mais economiza tempo de iniciante

A documentação tem uma página de erros com os códigos HTTP e seus tipos, e ela responde quase tudo que você ia perguntar em fórum

Leia o JSON antes de sair pesquisando:

Todo erro volta em JSON com um objeto error contendo type e message, além de um request_id na resposta

Esses três campos são o seu diagnóstico

O error.type te diz a categoria, o error.message te diz o detalhe, e o request_id é o que identifica aquela chamada específica

É MUITO mais rápido ler isso no seu próprio terminal do que colar a mensagem numa busca e cair em thread de dois anos atrás, concorda?

Como prevenir metade dessas dores:

Usa os SDKs oficiais

Eles já reexecutam falhas transitórias automaticamente, com retry automático e backoff exponencial, 2 tentativas por padrão, respeitando o header retry-after

Ou seja: aquele 529 esporádico já é tratado sem você escrever uma linha

E se o 429 virar rotina, o lugar de olhar é a página de rate limits

Dois pontos importantes dela: os limites são definidos no nível da organização, e o seu tier com os limites atuais aparece na página Rate limits do Claude Console

O algoritmo por trás é o token bucket, o que explica por que às vezes você manda uma rajada e passa, e outras vezes trava na terceira chamada

Quando voltar em cada parte da documentação

Documentação boa não se lê de cabo a rabo, se consulta

Então guarda esse mapa de "quando doer aqui, abre aquilo":

• Vai trocar de modelo? Models overview e a página de choosing-a-model
• Quer saber o que sai de circulação? A página de model deprecations, que existe exatamente pra isso
• Quer acompanhar mudanças da plataforma? As release notes da plataforma
• Vai usar recurso ainda em beta? A página de beta headers
• A resposta terminou de um jeito estranho? A página de handling stop reasons
• Está migrando código que já falava com outra API? Tem página sobre compatibilidade com o SDK da OpenAI

E se a sua stack não é Python nem Node, respira: a documentação lista SDKs clientes oficiais para Python, TypeScript, C#, Go, Java, PHP e Ruby

Cadê código pronto pra copiar?

Quando você já fez a primeira chamada e quer partir pro caso de uso real, tem dois repositórios oficiais que valem mais que qualquer tutorial avulso:

• claude-cookbooks, o repositório oficial de receitas
• claude-quickstarts, com projetos iniciais

E tem ainda a página de recursos de aprendizado mantida pela Anthropic pra quem constrói com Claude

Se liga: o cookbook é pra DEPOIS da primeira chamada funcionar, não antes

Abrir receita avançada com autenticação quebrada é receita de frustração haha

Conclusão

A lógica do guia inteiro cabe em quatro movimentos

Começa pelo Get started pra pegar o fluxo mínimo, confirma os detalhes de headers e endpoint no API overview, resolve qualquer falha na página de erros lendo error.type e request_id, e depois volta na documentação como referência, seção por seção, conforme a dor aparece

Seu próximo passo concreto é bem pequeno: cria a chave em Settings > API keys, exporta ANTHROPIC_API_KEY, roda uma chamada mínima na Messages API e só então abre o cookbook pro seu caso de uso real

E o hábito que separa quem sofre de quem não sofre: conferir na fonte oficial em vez de copiar tutorial de terceiro

Nome de modelo muda, recurso sai do beta, limite é ajustado, e a página viva acompanha tudo isso, o post do blog aleatório não 🙂

Qualquer coisa, volta aqui e me conta como foi a sua primeira integração

até o próximo post!