Skip to main content

Visão Geral

A API Cakto utiliza o protocolo OAuth2 para autenticar requisições. Neste guia, você aprenderá como obter um token de acesso e usá-lo para autenticar suas chamadas à API.

Fluxo de Autenticação

Esse é o fluxo básico para autenticar suas requisições, mais adiante detalharemos cada etapa:
1

Criar Chave de API

Crie uma Chave de API (client_id e client_secret) no painel da Cakto
2

Solicitar Token

Envie uma requisição POST para o endpoint de token com suas credenciais
3

Usar Token

Inclua o token de acesso no header Authorization de cada requisição

1 - Criando Chaves de API

Para começar a usar a API Cakto, você precisa criar suas chaves de API. Siga estas etapas:
  1. Acesse o painel da Cakto.
  2. Navegue até a seção Integrações e depois em Cakto API.
  3. Clique em “Criar Chave de API”.
  4. Preencha o formulário com um nome descritivo e selecione os escopos de acesso necessários.
  5. Salve o client_id e o client_secret gerados após finalizar a criação, especialmente o client_secret que será exibido apenas nesse momento da criação.

2 - Solicitando Token de Acesso

Use este endpoint para trocar suas credenciais de API por um token de acesso OAuth2.
    https://api.cakto.com.br/public_api/token/

Headers

Content-Type
string
default:"application/x-www-form-urlencoded"
required
application/x-www-form-urlencoded

Parâmetros do Corpo

client_id
string
required
O identificador único da sua aplicação
client_secret
string
required
A chave secreta da sua aplicação (Fornecido apenas no momento da criação da chave de API)

Exemplo de Requisição

curl -X POST https://api.cakto.com.br/public_api/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=abc123xyz789" \
  -d "client_secret=secret_abc123xyz789def456" \

Resposta de Sucesso (200 OK)

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "read write products offers orders"
}
access_token
string
Token JWT que deve ser usado no header Authorization das requisições
expires_in
integer
Tempo de validade do token em segundos (exemplo: 36000 = 10 horas)
token_type
string
Tipo do token, sempre “Bearer”
scope
string
Escopos de acesso concedidos ao token, separados por espaço. Exemplo: read write products

Erros Comuns

{
  "error": "invalid_client"
}
Solução: Verifique se seu client_id e client_secret estão corretos
{
  "error": "invalid_scope"
}
Solução: Use apenas escopos configurados na sua chave de API

3 - Usando o Token de Acesso

Após obter o token, inclua-o no header Authorization de todas as requisições à API:
Authorization: Bearer {access_token}

Exemplo de Requisição Autenticada

curl -X GET https://api.cakto.com.br/public_api/products/ \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

Expiração do Token

Tokens de acesso expiram após determinado tempo, retornado na resposta de autenticação no campo expires_in. Após a expiração, outro token deve ser solicitado, não existe um endpoint para renovação.

Escopos de Acesso

Os escopos controlam quais recursos e operações sua aplicação pode acessar:
EscopoDescriçãoPermissões
readLeituraPermite consultar recursos (GET)
writeEscritaPermite criar e modificar recursos (POST, PUT, DELETE)
productsProdutosAcesso ao gerenciamento de produtos
offersOfertasAcesso ao gerenciamento de ofertas
ordersPedidosAcesso à consulta de pedidos
Os scopos read e write definem o nível de permissão do token, para leitura read e/ou escrita write. Outros escopos como products e offers definem quais recursos específicos o token pode acessar.

Segurança

Importante: Nunca exponha suas credenciais em código cliente ou repositórios públicos!

Melhores Práticas

  • Armazene client_secret em variáveis de ambiente
  • Nunca commite credenciais no controle de versão (git)
  • Armazene tokens de forma segura, não exponha em código client-side
  • Solicite apenas os escopos necessários
  • Crie chaves de API separadas para diferentes aplicações
  • Revise e atualize permissões regularmente

Exemplos de Clientes

import requests
from typing import Optional

class CaktoAPIClient:
  def __init__(self, client_id: str, client_secret: str):
      self.client_id = client_id
      self.client_secret = client_secret
      self.base_url = "https://api.cakto.com.br"
      self.access_token: Optional[str] = None
      self.refresh_token: Optional[str] = None
  
  def authenticate(self):
      """Obtém um novo access token"""
      url = f"{self.base_url}/public_api/token/"
      data = {
          "client_id": self.client_id,
          "client_secret": self.client_secret,
      }
      
      response = requests.post(url, data=data)
      response.raise_for_status()
      
      token_data = response.json()
      self.access_token = token_data["access_token"]
      self.refresh_token = token_data.get("refresh_token")
      
      return token_data
  
  def get_headers(self) -> dict:
      """Retorna headers com autenticação"""
      if not self.access_token:
          self.authenticate()
      
      return {
          "Authorization": f"Bearer {self.access_token}",
          "Content-Type": "application/json"
      }
  
  def get(self, endpoint: str, **kwargs):
      """Faz uma requisição GET"""
      url = f"{self.base_url}{endpoint}"
      response = requests.get(url, headers=self.get_headers(), **kwargs)
      response.raise_for_status()
      return response.json()
  
  def post(self, endpoint: str, data: dict, **kwargs):
      """Faz uma requisição POST"""
      url = f"{self.base_url}{endpoint}"
      response = requests.post(
          url, 
          headers=self.get_headers(), 
          json=data, 
          **kwargs
      )
      response.raise_for_status()
      return response.json()

# Uso
client = CaktoAPIClient(
    client_id="seu_client_id",
    client_secret="seu_client_secret"
)

# Listar produtos
products = client.get("/api/products/")
print(f"Total de produtos: {products['count']}")
  class CaktoAPIClient {
    private baseUrl = 'https://api.cakto.com.br';
    private accessToken?: string;
    private refreshToken?: string;

    constructor(
      private clientId: string,
      private clientSecret: string
    ) {}

    async authenticate(): Promise<void> {
      const response = await fetch(`${this.baseUrl}/public_api/token/`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
        },
        body: new URLSearchParams({
          client_id: this.clientId,
          client_secret: this.clientSecret,
        }),
      });

      if (!response.ok) {
        throw new Error(`Authentication failed: ${response.statusText}`);
      }

      const tokenData = await response.json();
      this.accessToken = tokenData.access_token;
      this.refreshToken = tokenData.refresh_token;
    }

    private async getHeaders(): Promise<HeadersInit> {
      if (!this.accessToken) {
        await this.authenticate();
      }

      return {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
      };
    }

    async get<T>(endpoint: string): Promise<T> {
      const response = await fetch(`${this.baseUrl}${endpoint}`, {
        method: 'GET',
        headers: await this.getHeaders(),
      });

      if (!response.ok) {
        throw new Error(`GET request failed: ${response.statusText}`);
      }

      return response.json();
    }

    async post<T>(endpoint: string, data: any): Promise<T> {
      const response = await fetch(`${this.baseUrl}${endpoint}`, {
        method: 'POST',
        headers: await this.getHeaders(),
        body: JSON.stringify(data),
      });

      if (!response.ok) {
        throw new Error(`POST request failed: ${response.statusText}`);
      }

      return response.json();
    }
  }

  // Uso
  const client = new CaktoAPIClient(
    'seu_client_id',
    'seu_client_secret'
  );

  // Listar produtos
  const products = await client.get('/api/products/');
  console.log(`Total de produtos: ${products.count}`);

Próximos Passos