Guides
  1. AUTENTICAÇÃO

Autenticação

O Toktus API utiliza API Keys para autenticar todas as requisições (exceto registro de conta e webhooks).

Fluxo de Autenticação

graph LR
    A[Registrar Conta] --> B[Receber API Key]
    B --> C[Incluir em x-api-key]
    C --> D[Fazer Requisições]

1. Registrar Conta

Para começar, você precisa criar uma conta:

curl -X POST https://api.toktus.com/api/v1/clients \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Minha Empresa LTDA",
    "email": "[email protected]"
  }'

Resposta:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Minha Empresa LTDA",
    "email": "[email protected]",
    "apiKey": "tk_a1b2c3d4e5f6789abcdef...",
    "createdAt": "2026-02-17T14:30:00Z"
  }
}

[!WARNING]
A API Key é exibida uma única vez e não pode ser recuperada. Armazene-a em local seguro antes de prosseguir!

2. Configurar a Conta (opcional, mas recomendado)

Com a API Key em mãos, você pode configurar o comportamento padrão da conta antes de começar a processar pagamentos. Todas essas configurações são feitas via um único endpoint:

curl -X PATCH https://api.toktus.com/api/v1/clients/settings \
  -H "x-api-key: tk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryGateway": "pagarme",
    "gatewayFallbacks": ["asaas", "stripe"],
    "compatibilityMode": null,
    "responseFormat": "normalized"
  }'
CampoO que faz
primaryGatewayDefine o gateway padrão — o campo gateway no payload deixa de ser obrigatório
gatewayFallbacksLista ordenada de gateways tentados caso o primário falhe
compatibilityModeAceita payloads e retorna respostas no formato nativo de outro gateway (migração zero-código)
responseFormatControla o shape da resposta: full (padrão), normalized ou raw

[!TIP]
Configurar primaryGateway é especialmente útil se você usa sempre o mesmo gateway — elimina o campo gateway de todas as suas chamadas. Consulte Configurações da Conta para detalhes completos e exemplos.

3. Usar a API Key

Inclua sua API Key no header x-api-key em todas as requisições:

curl -X GET https://api.toktus.com/api/v1/credentials \
  -H "x-api-key: tk_a1b2c3d4e5f6789abcdef..."

Exemplos por linguagem

Segurança da API Key

Faça

  • Armazene em variáveis de ambiente (.env, não commite no Git)
  • Use cofres de segredos em produção (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
  • Implemente rotação periódica de chaves
  • Monitore uso suspeito (IPs desconhecidos, volumes anormais)
  • Use HTTPS sempre (nunca HTTP)

Não Faça

  • Commitar no Git ou repositórios públicos
  • Hardcodear no código-fonte
  • Expor em requisições client-side (JavaScript no navegador)
  • Compartilhar via e-mail, chat ou canais não criptografados
  • Registrar em logs ou sistemas de monitoramento em texto claro
  • Incluir em URLs ou query parameters

Exemplo: Armazenando com Segurança

.env (Local)

    # .env (adicione ao .gitignore!)
    TOKTUS_API_API_KEY=tk_a1b2c3d4e5f6789abcdef...
    ```

## Docker Compose

```yaml
    version: '3.8'
    services:
      api:
        image: sua-api:latest
        environment:
          - TOKTUS_API_API_KEY=${TOKTUS_API_API_KEY}
        env_file:
          - .env.production
    ```

## Kubernetes

```bash
    kubectl create secret generic toktus-api-credentials \
      --from-literal=api-key='tk_a1b2c3d4e5f6789abcdef...'
    ```

    ```yaml
    apiVersion: v1
    kind: Pod
    metadata:
      name: sua-api
    spec:
      containers:
      - name: app
        image: sua-api:latest
        env:
        - name: TOKTUS_API_API_KEY
          valueFrom:
            secretKeyRef:
              name: toktus-api-credentials
              key: api-key
    ```

## Endpoints Públicos (Sem Autenticação)

Apenas 2 grupos de endpoints **não** exigem `x-api-key`:

| Endpoint | Motivo |
|----------|--------|
| `POST /api/v1/clients` | Criação de conta (você ainda não tem API Key) |
| `POST /api/v1/webhooks/*` | Webhooks recebidos dos gateways (validação interna) |

**Todos os demais endpoints** exigem o header `x-api-key`.

## Erros de Autenticação

### 401 MISSING_API_KEY - Header ausente

```json
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Header x-api-key is required"
  }
}

Solução: Adicione o header x-api-key: tk_sua_chave.

401 INVALID_API_KEY - API Key inválida

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Possíveis causas:

  • API Key digitada incorretamente
  • API Key revogada

403 CLIENT_INACTIVE - Conta desativada

{
  "success": false,
  "error": {
    "code": "CLIENT_INACTIVE",
    "message": "Your account has been deactivated"
  }
}

Solução: Entre em contato com o suporte para reativar sua conta.

Listar Contas Registradas

Para ver todas as contas cadastradas (sem expor as API Keys):

curl -X GET https://api.toktus.com/api/v1/clients \
  -H "x-api-key: tk_a1b2c3d4e5f6789abcdef..."

Resposta:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Minha Empresa LTDA",
      "email": "[email protected]",
      "isActive": true,
      "createdAt": "2026-02-17T14:30:00Z"
    }
  ]
}

[!NOTE]
Por segurança, a API Key nunca é retornada após o registro inicial.

Rate Limiting

Para proteger a API, implementamos limites de taxa:

LimiteValorAção quando excedido
Por API Key100 req/minHTTP 429 + Retry-After header
Por IP (sem API Key)100 req/minHTTP 429 + Retry-After header

Resposta HTTP 429:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições excedido. Aguarde 45 segundos antes de tentar novamente."
  }
}

Headers incluídos:

  • Retry-After: 45 (segundos até poder tentar novamente)
  • X-RateLimit-Limit: 100 (limite total)
  • X-RateLimit-Remaining: 0 (requisições restantes)
  • X-RateLimit-Reset: 60 (segundos até reset da janela)

Próximos Passos

Updated about 2 hours ago