Autenticacao

A API FluxiQ NPC utiliza autenticacao via API Key para proteger todos os endpoints. Cada requisicao deve incluir sua chave no cabecalho HTTP.

Como Funciona

Todas as requisicoes a API devem incluir o cabecalho X-API-Key com sua chave de acesso:

curl -X GET "https://api.pixconnect.com.br/api/v1/central/boletos" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"

Formato das API Keys

As API Keys seguem um formato padronizado que identifica o ambiente:

Prefixo	Ambiente	Exemplo	Uso
pk_test_	Sandbox	pk_test_abc123def456ghi789	Testes e homologacao
pk_live_	Producao	pk_live_xyz789abc123def456	Ambiente produtivo

Identificacao do Ambiente

O prefixo da sua API Key determina automaticamente qual ambiente sera utilizado. Nao e possivel usar uma chave de sandbox em producao e vice-versa.

Exemplo Completo

cURL

curl -X POST "https://sandbox.pixconnect.com.br/api/v1/central/boletos" \
  -H "X-API-Key: pk_test_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 15000,
    "vencimento": "2026-03-15",
    "pagador": {
      "nome": "Joao Silva",
      "documento": "12345678901"
    }
  }'

JavaScript

const response = await fetch(
  "https://sandbox.pixconnect.com.br/api/v1/central/boletos",
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_test_abc123def456ghi789",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      valor: 15000,
      vencimento: "2026-03-15",
      pagador: {
        nome: "Joao Silva",
        documento: "12345678901"
      }
    }),
  }
);

const data = await response.json();

Python

import requests

url = "https://sandbox.pixconnect.com.br/api/v1/central/boletos"
headers = {
    "X-API-Key": "pk_test_abc123def456ghi789",
    "Content-Type": "application/json"
}
payload = {
    "valor": 15000,
    "vencimento": "2026-03-15",
    "pagador": {
        "nome": "Joao Silva",
        "documento": "12345678901"
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Erros de Autenticacao

Quando a autenticacao falha, a API retorna um dos seguintes erros:

API Key Ausente

Status: 401 Unauthorized

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "O cabecalho X-API-Key e obrigatorio",
    "details": "Inclua sua API Key no cabecalho X-API-Key da requisicao"
  }
}

API Key Invalida

Status: 401 Unauthorized

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key invalida ou expirada",
    "details": "Verifique se a chave esta correta e ativa no portal"
  }
}

API Key Revogada

Status: 401 Unauthorized

{
  "error": {
    "code": "REVOKED_API_KEY",
    "message": "Esta API Key foi revogada",
    "details": "Gere uma nova chave no portal ou entre em contato com o suporte"
  }
}

Boas Praticas

Seguranca da API Key

Sua API Key e uma credencial sensivel. Nunca a exponha em codigo do lado do cliente (frontend), repositorios publicos ou logs de aplicacao.

Recomendacoes de Seguranca

1. Armazene com seguranca

   • Use variaveis de ambiente ou servicos de gerenciamento de segredos
   • Nunca commite API Keys em repositorios de codigo

2. Restrinja permissoes

   • Use chaves de sandbox para desenvolvimento e testes
   • Mantenha chaves de producao apenas em servidores seguros

3. Monitore o uso

   • Acompanhe as requisicoes no painel administrativo
   • Configure alertas para atividades suspeitas

4. Rotacione periodicamente

   • Troque suas chaves a cada 90 dias
   • Revogue imediatamente chaves comprometidas

# Exemplo: usando variavel de ambiente
export PIXCONNECT_API_KEY="pk_live_abc123def456"

curl -X GET "https://api.pixconnect.com.br/api/v1/central/health" \
  -H "X-API-Key: $PIXCONNECT_API_KEY"

Rotacao de Chaves

Para rotacionar sua API Key sem interromper o servico:

Passo a Passo

1. Gere uma nova chave no FluxiQ Portal
2. Atualize sua aplicacao com a nova chave
3. Teste a nova chave em ambiente de staging
4. Implante em producao com a nova chave
5. Revogue a chave antiga apos confirmar que tudo funciona

Periodo de Transicao

Recomendamos manter ambas as chaves ativas por pelo menos 24 horas durante a transicao para garantir que todos os servicos estejam atualizados.

Gerenciamento via Portal

No FluxiQ Portal voce pode:

• Visualizar todas as suas API Keys
• Gerar novas chaves de sandbox ou producao
• Revogar chaves comprometidas
• Monitorar o uso de cada chave
• Configurar alertas de seguranca

Proximos Passos

• Ambientes - Entenda os ambientes disponiveis
• Criar Boleto - Registre seu primeiro boleto
• Codigos de Erro - Referencia completa de erros