Atura
Atura

API Atura

Autenticação

API Keys

A API Atura usa chaves de API (API Keys) para autenticação. Todas as chamadas à API devem incluir uma chave válida.

Documentação em Desenvolvimento

Esta documentação está ainda em desenvolvimento ativo. Algumas secções podem estar incompletas ou sujeitas a alterações. Para questões específicas, contacta o nosso suporte técnico.

Como Funciona

Cada pedido à API deve incluir a tua chave de API no cabeçalho Authorization usando o esquema Bearer Token.

Bash
Authorization: Bearer atura_live_1234567890abcdef...

Obter Chaves de API

1. Acede ao Painel de Administração

Faz login no teu painel Atura e navega para a secção "Configurações" → "API Keys".

2. Criar Nova Chave

Clica em "Criar Nova Chave" e dá-lhe um nome descritivo (ex: "Aplicação Web", "Sistema ERP").

3. Copiar e Guardar

A chave será mostrada apenas uma vez. Copia-a imediatamente e guarda-a num local seguro.

Importante

Por motivos de segurança, não conseguirás ver a chave novamente após fechar esta janela. Se perderes a chave, terás de criar uma nova.

Ambientes: Teste vs Produção

Teste

Chaves de Teste

Para desenvolvimento e testes. Começam com atura_test_

  • Não geram documentos oficiais
  • Sem custos associados
  • Ideais para integração
Produção

Chaves de Produção

Para ambiente de produção. Começam com atura_live_

  • Geram documentos oficiais
  • Conformes com AT
  • Sujeitas a faturação

Exemplos de Implementação

// Configurar o cliente HTTP
const API_KEY = process.env.ATURA_API_KEY;
const BASE_URL = 'https://api.atura.pt/v1';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

// Exemplo de chamada
const response = await fetch(`${BASE_URL}/documents/drafts`, {
  method: 'POST',
  headers,
  body: JSON.stringify(data)
});

if (!response.ok) {
  throw new Error(`API Error: ${response.status}`);
}

const result = await response.json();

Boas Práticas de Segurança

Fazer

  • • Guardar chaves em variáveis de ambiente
  • • Usar HTTPS em todas as chamadas
  • • Rodar chaves regularmente
  • • Usar chaves de teste durante desenvolvimento
  • • Monitorizar uso das chaves
  • • Implementar rate limiting

Não Fazer

  • • Nunca commitar chaves no código
  • • Não partilhar chaves publicamente
  • • Evitar hard-coding de chaves
  • • Não usar chaves de produção em teste
  • • Não logar chaves em ficheiros
  • • Evitar transmissão por email/chat

Tratamento de Erros de Autenticação

401 Unauthorized

Chave de API inválida ou em falta.

JSON
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "A chave de API fornecida é inválida"
  }
}

403 Forbidden

Chave válida mas sem permissões para este recurso.

JSON
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permissions",
    "message": "Esta chave não tem permissões para aceder a este recurso"
  }
}