Autenticação da API: documentação do CheckoutOS

A API do CheckoutOS usa chaves de API para autenticação. Este guia explica como gerar chaves, autenticar requisições e gerenciar o acesso à API com segurança.

Chaves de API

As chaves de API autenticam todas as requisições à API do CheckoutOS. Cada chave está vinculada à sua loja e tem permissões configuráveis.

Geração de chaves de API

Acessar as configurações

Acesse CheckoutOS → Settings → API.

Criar nova chave

Clique em "Create API Key".

Nomear a chave

Dê um nome descritivo, como "Servidor de produção".

Definir permissões

Escolha os escopos da API que a chave pode acessar.

Copiar a chave

Copie a chave imediatamente, pois ela não será exibida novamente.

Segurança das chaves

As chaves de API são exibidas apenas uma vez, ao serem criadas. Guarde-as com segurança. Se perder uma chave, será necessário gerar outra.

Métodos de autenticação

Token Bearer (recomendado)

Inclua a chave de API como token Bearer no cabeçalho Authorization:

Autenticação com token Bearer

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Cabeçalho X-API-Key

Como alternativa, use o cabeçalho X-API-Key:

Autenticação com X-API-Key

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Permissões da API

As chaves de API podem ter escopos limitados a permissões específicas:

Escopos disponíveis

{
  "scopes": {
    "read:upsells": "View upsell configurations",
    "write:upsells": "Create and modify upsells",
    "read:bundles": "View bundle configurations",
    "write:bundles": "Create and modify bundles",
    "read:analytics": "Access analytics data",
    "read:orders": "View order data",
    "write:orders": "Modify orders (edits)",
    "read:settings": "View CheckoutOS settings",
    "write:settings": "Modify settings",
    "webhooks:manage": "Create and manage webhooks"
  }
}

Privilégio mínimo

Conceda apenas as permissões necessárias para sua integração. Uma chave para painéis de análise não deve ter acesso de escrita às vendas adicionais.

Limitação de requisições

As requisições à API têm limites para garantir o uso justo:

Limites de requisições

{
  "rate_limits": {
    "requests_per_minute": 120,
    "requests_per_hour": 3600,
    "burst_limit": 20
  },
  "headers": {
    "X-RateLimit-Limit": "120",
    "X-RateLimit-Remaining": "115",
    "X-RateLimit-Reset": "1640000000"
  }
}

Ao atingir o limite, você receberá uma resposta 429:

Resposta de limite de requisições

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Ambientes

O CheckoutOS oferece ambientes separados para desenvolvimento e produção:

Ambientes da API

{
  "production": {
    "base_url": "https://api.chargezen.com/v1",
    "key_prefix": "live_"
  },
  "sandbox": {
    "base_url": "https://sandbox.api.chargezen.com/v1",
    "key_prefix": "test_"
  }
}

Ambiente sandbox

Use o sandbox para desenvolvimento e testes. Os dados do sandbox são separados dos de produção e podem ser redefinidos a qualquer momento.

SDKs oficiais

Os SDKs oficiais fazem a autenticação automaticamente:

SDK para Node.js

import { CheckoutOS } from '@chargezen/checkoutos-sdk';

const client = new CheckoutOS({
  apiKey: process.env.CHARGEZEN_API_KEY,
  environment: 'production'
});

const upsells = await client.upsells.list();

SDK para Python

from chargezen import CheckoutOS

client = CheckoutOS(
    api_key=os.environ['CHARGEZEN_API_KEY'],
    environment='production'
)

upsells = client.upsells.list()

Gerenciamento de chaves

Boas práticas

Use variáveis de ambiente — Nunca coloque chaves diretamente no código
Rotacione as chaves regularmente — Pelo menos a cada trimestre
Use chaves separadas por ambiente — Desenvolvimento, homologação e produção
Revogue chaves sem uso — Exclua as que não são mais usadas
Monitore o uso das chaves — Observe padrões anormais
Use o mínimo de escopos — Conceda apenas as permissões necessárias

Revogação de chaves

Acessar as configurações da API

Acesse CheckoutOS → Settings → API.

Encontrar a chave

Localize na lista a chave que deseja revogar.

Revogar

Clique em "Revoke" e confirme.

Efeito imediato

A revogação da chave é imediata. Todas as requisições que usarem a chave revogada falharão. Atualize suas aplicações antes de revogá-la.

Referência da API

Endpoints da API

Endpoints disponíveis da API

Saiba mais

Webhooks

Notificações de eventos em tempo real

Saiba mais