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:
Criar Chave de API
Crie uma Chave de API (client_id e client_secret) no painel da Cakto
Solicitar Token
Envie uma requisição POST para o endpoint de token com suas credenciais
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:
Acesse o painel da Cakto .
Navegue até a seção Integrações e depois em Cakto API .
Clique em “Criar Chave de API” .
Preencha o formulário com um nome descritivo e selecione os escopos de acesso necessários.
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/
Content-Type
string
default: "application/x-www-form-urlencoded"
required
application/x-www-form-urlencoded
Parâmetros do Corpo
O identificador único da sua aplicação
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"
}
Token JWT que deve ser usado no header Authorization das requisições
Tempo de validade do token em segundos (exemplo: 36000 = 10 horas)
Tipo do token, sempre “Bearer”
Escopos de acesso concedidos ao token, separados por espaço. Exemplo: read write products
Erros Comuns
401 Unauthorized - Credenciais Inválidas
{
"error" : "invalid_client"
}
Solução : Verifique se seu client_id e client_secret estão corretos
400 Bad Request - Escopo Inválido
{
"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:
Escopo Descrição Permissões readLeitura Permite consultar recursos (GET) writeEscrita Permite criar e modificar recursos (POST, PUT, DELETE) productsProdutos Acesso ao gerenciamento de produtos offersOfertas Acesso ao gerenciamento de ofertas ordersPedidos Acesso à 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
Armazenamento Seguro de Credenciais
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
Princípio do Menor Privilégio
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