Autenticação

Todas as requisições à API pública do Nixfy Gateway requerem autenticação via API Keys.

API Keys

As API Keys são compostas por dois componentes:

Chave Pública (Public Key): Identifica sua conta
Chave Privada (Private Key): Autentica suas requisições

Obtendo suas API Keys

Acesse o Dashboard

Acesse o Dashboard Nixfy Gateway e faça login na sua conta.

Navegue até API Keys

No menu lateral, navegue até Integrações → Credenciais de API.

Gere um novo par de chaves

Clique em Gerar Nova Chave e confirme a ação.

Guarde suas chaves com segurança

Importante: Guarde a chave privada com segurança, ela não será exibida novamente após a geração.

Recomendamos salvar as chaves em um gerenciador de senhas ou variáveis de ambiente seguras.

Como Usar

Inclua as chaves de API nos cabeçalhos de todas as requisições:

string

required

Sua chave pública da API (formato: pk_...)

string

required

Sua chave privada da API (formato: sk_...)

Exemplos de Requisição

curl -X GET https://api.nixfypagamentos.com/api/transactions/123 \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui"

const response = await fetch('https://api.nixfypagamentos.com/api/transactions/123', {
  method: 'GET',
  headers: {
    'X-Api-Public-Key': 'sua_chave_publica_aqui',
    'X-Api-Private-Key': 'sua_chave_privada_aqui',
    'Content-Type': 'application/json'
  }
});

import requests

headers = {
    'X-Api-Public-Key': 'sua_chave_publica_aqui',
    'X-Api-Private-Key': 'sua_chave_privada_aqui',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.nixfypagamentos.com/api/transactions/123',
    headers=headers
)

Restrição por IP

Além das chaves, você pode limitar de quais endereços IP sua API key funciona. É a defesa que continua valendo mesmo se a chave privada vazar: uma requisição com as chaves corretas, mas vinda de um IP fora da lista, é recusada.

A lista começa vazia, e lista vazia significa sem restrição — sua chave funciona de qualquer origem. A proteção só passa a valer depois que você cadastra o primeiro IP.

Como funciona

exata

O IP de origem precisa ser idêntico a um da lista. Não há suporte a faixas CIDR (192.168.0.0/24) nem curingas — cadastre cada endereço individualmente.

IPv4 e IPv6

Ambos são aceitos. Endereços IPv4 mapeados em IPv6 (::ffff:200.150.100.50) são normalizados para a forma IPv4, então cadastrar 200.150.100.50 cobre as duas representações.

20 endereços

Cada conta pode cadastrar até 20 IPs.

A restrição vale apenas para requisições autenticadas por API key. O acesso ao painel pela sua sessão de login não passa por essa verificação — trancar a API não tranca o dashboard.

Configurando

No painel, vá em Integrações → Credenciais de API e edite a lista de IPs autorizados. A mesma operação está disponível na rota abaixo, autenticada pela sessão do painel (não pela API key): Para remover a restrição e voltar a aceitar qualquer origem, envie uma lista vazia: Um endereço malformado faz a requisição inteira falhar, sem alterar nada — a resposta diz qual valor foi recusado:

{
  "message": "IP inválido: 999.1.1.1",
  "code": "INVALID_IP"
}

Quando um IP é bloqueado

Requisições vindas de fora da lista recebem 403 com o código IP_NOT_ALLOWED:

{
  "message": "Requisição recusada: o IP de origem não está na lista de IPs autorizados desta chave.",
  "code": "IP_NOT_ALLOWED"
}

Se você usa servidores com IP dinâmico, ou um provedor que roteia a saída por vários endereços, cadastre todos os IPs de saída possíveis — ou deixe a lista vazia e proteja a chave por outros meios. Uma lista incompleta derruba requisições legítimas em produção.

Segurança

Importante: Nunca exponha suas chaves de API em código frontend ou repositórios públicos. Sempre use variáveis de ambiente ou serviços de gerenciamento de segredos.

Boas Práticas

✅ Armazene as chaves em variáveis de ambiente
✅ Use serviços de gerenciamento de segredos (AWS Secrets Manager, HashiCorp Vault, etc.)
✅ Rotacione suas chaves regularmente
✅ Revogue chaves comprometidas imediatamente
❌ Nunca commite chaves em repositórios Git
❌ Nunca exponha chaves em código frontend

Erros de Autenticação

401 Unauthorized

Retornado quando as chaves de API são inválidas ou ausentes:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Chaves de API inválidas ou ausentes"
  }
}

403 Forbidden

Retornado quando a operação não é permitida para sua conta:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Operação não permitida para esta conta"
  }
}

Começando

MCP (Model Context Protocol)

Transações

Transferências

Saldo

API Keys

Obtendo suas API Keys

Como Usar

Exemplos de Requisição

Restrição por IP

Como funciona

Configurando

Quando um IP é bloqueado

Segurança

Boas Práticas

Erros de Autenticação

401 Unauthorized

403 Forbidden

​API Keys

​Obtendo suas API Keys

​Como Usar

​Exemplos de Requisição

​Restrição por IP

​Como funciona

​Configurando

​Quando um IP é bloqueado

​Segurança

​Boas Práticas

​Erros de Autenticação

​401 Unauthorized

​403 Forbidden

API Keys

Obtendo suas API Keys

Como Usar

Exemplos de Requisição

Restrição por IP

Como funciona

Configurando

Quando um IP é bloqueado

Segurança

Boas Práticas

Erros de Autenticação

401 Unauthorized

403 Forbidden