---
title: "Autenticação da API: documentação do CheckoutOS | Chargezen"
description: "Acesso seguro à API do CheckoutOS. Da seção Referência da API da documentação do CheckoutOS da Chargezen."
url: "https://chargezen.com/pt-br/docs/checkoutos/api/authentication"
lang: "pt-BR"
updated: "2025-01-16"
---

Canonical URL: https://chargezen.com/pt-br/docs/checkoutos/api/authentication

# Autenticação da API

Acesso seguro à API do CheckoutOS

Última atualização: 2025-01-16

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

1

#### Acessar as configurações

Acesse CheckoutOS → Settings → API.

2

#### Criar nova chave

Clique em "Create API Key".

3

#### Nomear a chave

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

4

#### Definir permissões

Escolha os escopos da API que a chave pode acessar.

5

#### 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

```bash
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

```bash
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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```javascript
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

```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

1

#### Acessar as configurações da API

Acesse CheckoutOS → Settings → API.

2

#### Encontrar a chave

Localize na lista a chave que deseja revogar.

3

#### 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



](https://chargezen.com/pt-br/docs/checkoutos/api/endpoints)[

### Webhooks

Notificações de eventos em tempo real

Saiba mais



](https://chargezen.com/pt-br/docs/checkoutos/api/webhooks)

Esta página foi útil?

Precisa de mais ajuda? [Fale com o suporte](https://chargezen.com/pt-br/docs/checkoutos/troubleshooting/support)