Autenticação

A API do Clakta autentica com uma chave de API, enviada como bearer token em toda requisição. Não há endpoints sem autenticação.

Criar uma chave de API

1. Abra Configurações → Chaves de API na sua equipe.
2. Clique em Criar chave de API e dê um nome que indique onde ela será usada (por exemplo shopify-producao).
3. Selecione os escopos necessários.
4. Copie a chave imediatamente — ela é exibida uma única vez e armazenada apenas como hash, portanto não pode ser recuperada depois.

Autenticar uma requisição

Envie a chave no cabeçalho Authorization, com o prefixo Bearer :

curl https://api.clakta.com/v1/orders \
  -X POST \
  -H "Authorization: Bearer $CLAKTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_xxxxxxxx",
    "orderId": "1042",
    "platform": "shopify",
    "paymentMethod": "credit_card",
    "status": "pending",
    "totalPrice": 10.4,
    "products": [
      { "id": "sku-1", "name": "Camisa azul", "quantity": 1, "price": 10.4 }
    ],
    "customer": { "name": "João Silva", "email": "joao@exemplo.com", "ip": "203.0.113.42" },
    "tracking": { "clkt": null, "utm_source": null, "utm_medium": null, "utm_campaign": null, "utm_content": null }
  }'

Esquecer o prefixo é o erro mais comum e retorna 400 bad_request — o valor do cabeçalho deve ser Bearer <chave>, não a chave sozinha.

Escopos

Uma chave alcança apenas o que seus escopos permitem, e cada endpoint desta referência informa a permissão que exige. Os escopos seguem o formato <recurso>.<acesso>:

Um escopo write implica o read correspondente. Conceda o conjunto mais restrito possível: uma integração de loja que só registra pedidos precisa apenas de orders.write.

Vale distinguir duas falhas:

• 401 unauthorized — a chave está ausente, malformada ou revogada.
• 403 forbidden — a chave é válida, mas não tem o escopo exigido pelo endpoint.

Rotação e revogação

As chaves podem ser revogadas a qualquer momento em Configurações → Chaves de API; uma chave revogada para de funcionar imediatamente. Para rotacionar sem indisponibilidade, crie a nova chave primeiro, faça o deploy e só então revogue a antiga.

As requisições feitas com suas chaves são registradas em Configurações → Logs da API, a forma mais rápida de confirmar que uma rotação funcionou ou de descobrir o que uma integração com falha realmente enviou.