Documentação da API

API N7
Documentação

Integre o score de reputação transacional em minutos. Nossa API N7 permite consultar e contribuir com dados de confiança em tempo real, reduzindo fraudes e melhorando aprovações.

API Request
# Consultar score de reputação
curl -X GET "https://api.nSeven.com/v1/score" \
-H "Authorization: Bearer {seu_token}" \
-H "Content-Type: application/json"
# Resposta
{
  "user_id": "1234-abcd",
  "score": 87,
  "risk_level": "low",
  "insights": [
    "Histórico de pagamentos consistente",
    "Baixo risco de inadimplência"
  ],
  "last_updated": "2024-01-15T10:30:00Z"
}
200 OK
~50ms response
Autenticação

Autenticação da API N7

Todas as requisições para a API N7 devem incluir um token de autenticação válido no header Authorization.

1

Obter token de API

Acesse seu dashboard e gere um novo token de API. Mantenha-o seguro e nunca o compartilhe publicamente.

2

Incluir no header

Adicione o token no header Authorization de todas as suas requisições usando o formato Bearer.

Seu token de API
lynx_live_••••••••••••••••••••••••••••••••••••••••

Segurança

Nunca exponha seu token em código client-side. Use sempre em requisições server-side ou através de proxies seguros.

cURL
curl -X GET "https://api.nSeven.com/v1/score" \
  -H "Authorization: Bearer lynx_live_..." \
  -H "Content-Type: application/json"
JavaScript
const response = await fetch('https://api.nSeven.com/v1/score', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer lynx_live_...',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
Python
import requests

headers = {
    'Authorization': 'Bearer lynx_live_...',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.nSeven.com/v1/score',
    headers=headers
)

Credenciais de teste

Use estas credenciais para testar a integração em ambiente de desenvolvimento:

lynx_test_1234567890abcdef1234567890abcdef12345678

* Tokens de teste retornam dados simulados e não afetam dados reais

Endpoints da API N7

Endpoints Principais

Explore todos os endpoints disponíveis na API N7 com exemplos de requisições e respostas.

Base URL

https://api.nSeven.com
GET

Consultar Score de Reputação

/v1/score

Obtém o score de reputação e insights de um usuário específico

Parâmetros

user_idstringobrigatório

ID único do usuário

include_insightsboolean

Incluir insights detalhados

Exemplo de Requisição

cURL
curl -X GET "https://api.nSeven.com/v1/score?user_id=1234-abcd&include_insights=true" \
  -H "Authorization: Bearer lynx_live_..." \
  -H "Content-Type: application/json"

Exemplo de Resposta

JSON200 OK
{
  "user_id": "1234-abcd",
  "score": 87,
  "risk_level": "low",
  "confidence": 0.94,
  "insights": [
    "Histórico de pagamentos consistente",
    "Baixo risco de inadimplência",
    "Ativo há mais de 12 meses"
  ],
  "last_updated": "2024-01-15T10:30:00Z",
  "data_points": 156
}

Códigos de Erro

400user_id é obrigatório
404Usuário não encontrado
429Rate limit excedido
POST

Enviar Evento de Feedback

/v1/events

Envia dados de feedback sobre uma transação para atualizar o score

GET

Obter Perfil do Usuário

/v1/profile/{id}

Retorna informações detalhadas do perfil de um usuário (requer permissões especiais)

Rate Limits

1,000
Requisições por hora
100
Requisições por minuto
10
Requisições por segundo

Limites podem ser aumentados para planos empresariais. Entre em contato para mais informações.

Exemplos de uso

Exemplos por Setor

Veja como integrar a API nSeven em diferentes setores com exemplos práticos e casos de uso reais.

Análise de Crédito

Fintech

Avalie o risco antes de aprovar empréstimos ou cartões

Caso de uso: Consultar score antes de aprovar um empréstimo de R$ 5.000

Verificação de Entregadores

Delivery

Valide a confiabilidade de entregadores e clientes

Caso de uso: Verificar entregador antes de aceitar na plataforma

Validação de Vendedores

Marketplace

Proteja compradores verificando vendedores confiáveis

Caso de uso: Verificar vendedor antes de destacar produtos

Gestão de Transportadoras

Logística

Monitore performance e confiabilidade de transportadoras

Caso de uso: Selecionar transportadora mais confiável para envio
Análise de Crédito
// 1. Consultar score do usuário
const response = await fetch('https://api.nSeven.com/v1/score?user_id=user_123', {
  headers: {
    'Authorization': 'Bearer lynx_live_...',
    'Content-Type': 'application/json'
  }
});

const scoreData = await response.json();

// 2. Tomar decisão baseada no score
if (scoreData.score >= 70) {
  // Aprovar empréstimo
  const approval = {
    approved: true,
    amount: 5000,
    interest_rate: 2.5 // Taxa reduzida para bom score
  };
  
  // 3. Enviar feedback da aprovação
  await fetch('https://api.nSeven.com/v1/events', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer lynx_live_...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_id: 'user_123',
      event_type: 'credit_approval',
      outcome: 'success',
      amount: 5000,
      metadata: {
        product: 'personal_loan',
        interest_rate: 2.5
      }
    })
  });
} else {
  // Rejeitar ou solicitar mais documentos
  console.log('Score insuficiente:', scoreData.score);
}
Resposta da API200 OK
{
  "user_id": "user_123",
  "score": 85,
  "risk_level": "low",
  "insights": [
    "Histórico de pagamentos excelente",
    "Renda comprovada estável",
    "Baixo endividamento atual"
  ]
}

Dicas de Integração

Cache inteligente

Implemente cache para scores consultados recentemente, respeitando o TTL de 1 hora.

Feedback consistente

Envie eventos de feedback sempre que possível para melhorar a precisão dos scores.

Tratamento de erros

Implemente fallbacks para quando a API estiver indisponível ou retornar erro.

Monitoramento

Configure alertas para monitorar o uso da API e identificar padrões anômalos.

Ambiente de teste

Sandbox da API

Teste a integração com dados simulados antes de implementar em produção. Sem custos ou limitações.

Credenciais de Teste

https://sandbox.api.nSeven.com
lynx_test_1234567890abcdef1234567890abcdef12345678
test_user_123

Nota: Tokens de teste são públicos e seguros para uso em desenvolvimento. Eles retornam dados simulados e não afetam dados reais.

Dados de Exemplo

test_user_001Score: 85

Usuário modelo com histórico excelente

test_user_002Score: 45

Usuário com histórico de inadimplência

test_user_003Score: 67

Usuário novo com poucos dados

Teste Interativo

Requisição

GET https://sandbox.api.nSeven.com/v1/score?user_id=test_user_123
Authorization: Bearer lynx_test_1234567890abcdef1234567890abcdef12345678
Content-Type: application/json

Resposta

Clique em "Testar API" para ver a resposta

Recursos do Sandbox

Dados simulados realistas
Todos os endpoints disponíveis
Sem rate limits
Resposta instantânea
Logs detalhados de requisições

Próximos Passos

1

Teste todos os endpoints no sandbox

2

Implemente a integração em desenvolvimento

3

Solicite credenciais de produção

Webhooks

Webhooks em Tempo Real

Receba notificações instantâneas sobre mudanças de score, alertas de risco e eventos importantes diretamente na sua aplicação.

Tipos de Eventos

Score Atualizado

score.updated
Tempo real

Disparado quando o score de um usuário é recalculado

Quando é disparado:
Novo evento de feedback recebido
Recálculo automático do score
Atualização de dados históricos
Payload do evento:
{
  "event": "score.updated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "user_id": "1234-abcd",
    "previous_score": 82,
    "new_score": 87,
    "change_reason": "positive_feedback",
    "risk_level": "low",
    "confidence": 0.94
  }
}

Alerta de Risco

risk.alert
Imediato

Disparado quando um usuário atinge um nível de risco crítico

Usuário Verificado

user.verified
Por evento

Disparado quando um usuário completa o processo de verificação

Configuração

1

Configurar endpoint

Defina a URL que receberá os webhooks

Código
// Endpoint que receberá os webhooks
POST https://sua-api.com/webhooks/nSeven

// Headers obrigatórios
Content-Type: application/json
X-nSeven-Signature: sha256=...
X-nSeven-Event: score.updated
2

Validar assinatura

Verifique a autenticidade dos webhooks

Código
const crypto = require('crypto');

function validateWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return `sha256=${expectedSignature}` === signature;
}

// Uso
const isValid = validateWebhook(
  req.body,
  req.headers['x-nSeven-signature'],
  process.env.nSeven_WEBHOOK_SECRET
);
3

Processar eventos

Implemente handlers para cada tipo de evento

Código
app.post('/webhooks/nSeven', (req, res) => {
  const event = req.headers['x-nSeven-event'];
  const payload = req.body;
  
  switch (event) {
    case 'score.updated':
      handleScoreUpdate(payload.data);
      break;
      
    case 'risk.alert':
      handleRiskAlert(payload.data);
      break;
      
    case 'user.verified':
      handleUserVerification(payload.data);
      break;
  }
  
  res.status(200).send('OK');
});

Configuração no Dashboard

1

Acesse a seção "Webhooks" no seu dashboard

2

Adicione a URL do seu endpoint

3

Selecione os eventos que deseja receber

4

Copie o secret para validação de assinatura

Melhores Práticas

🔄

Idempotência

Processe cada evento apenas uma vez usando o ID único do evento

⏱️

Timeout adequado

Configure timeout de 30 segundos para responder aos webhooks

🔁

Retry logic

Implemente retry com backoff exponencial para falhas temporárias

🔐

Validação de assinatura

Sempre valide a assinatura HMAC para garantir autenticidade

📝

Logs detalhados

Registre todos os eventos recebidos para debugging e auditoria

Processamento assíncrono

Processe eventos em background para resposta rápida

Segurança & LGPD

Segurança e Privacidade

Protegemos seus dados e dos seus usuários com os mais altos padrões de segurança e conformidade com a LGPD.

99.9% Uptime

Disponibilidade garantida

256-bit AES

Criptografia militar

LGPD Compliant

100% em conformidade

Zero Trust

Arquitetura de segurança

Proteção de Dados Pessoais

Cumprimos rigorosamente a LGPD e padrões internacionais de proteção de dados

Dados Anonimizados

Todos os dados são processados de forma anonimizada e criptografada

Hash SHA-256 para identificadores únicos
Remoção automática de dados sensíveis
Agregação estatística sem exposição individual

Consentimento Ativo

Coletamos dados apenas com consentimento explícito dos usuários

Opt-in obrigatório para coleta de dados
Transparência total sobre uso dos dados
Direito de revogação a qualquer momento

Minimização de Dados

Coletamos apenas dados estritamente necessários para o serviço

Coleta limitada ao mínimo necessário
Retenção por tempo determinado
Exclusão automática após período legal

Fluxo de Processamento Seguro

Veja como seus dados são processados de forma segura e em conformidade com a LGPD

📥
1

Coleta

Dados coletados com consentimento explícito

🔒
2

Anonimização

Remoção de identificadores pessoais

⚙️
3

Processamento

Análise em ambiente criptografado

📤
4

Entrega

Score entregue via API segura

Dúvidas sobre Segurança?

Nossa equipe de segurança está disponível para esclarecer qualquer dúvida sobre proteção de dados, conformidade ou implementação segura.

SDKs e Bibliotecas

SDKs Oficiais

Integre a API N7 rapidamente com nossos SDKs oficiais para as principais linguagens de programação.

🟨

JavaScript/TypeScript

v2.1.0

SDK oficial para Node.js e navegadores com suporte completo ao TypeScript

15.2k downloads
🐍

Python

v1.8.0

SDK Python com suporte a asyncio e integração com frameworks populares

8.7k downloads
🔵

Go

v1.5.0

SDK Go com performance otimizada e baixo overhead

3.1k downloads

Java

v1.3.0

SDK Java com suporte a Spring Boot e frameworks empresariais

2.8k downloads

Instalação

npm
npm install @nSeven/sdk
yarn
yarn add @nSeven/sdk
pnpm
pnpm add @nSeven/sdk

Quick Start

import { nSevenClient } from '@nSeven/sdk';

const client = new nSevenClient({
  apiKey: 'lynx_live_...',
  environment: 'production' // ou 'sandbox'
});

// Consultar score
const score = await client.getScore('user_123');
console.log('Score:', score.score);

// Enviar evento
await client.sendEvent({
  userId: 'user_123',
  eventType: 'payment',
  outcome: 'success',
  amount: 150.00
});

Recursos

TypeScript nativo
Suporte a Promise/async-await
Retry automático
Cache inteligente
Validação de tipos

SDKs da Comunidade

SDKs mantidos pela comunidade para outras linguagens e frameworks

💎

Ruby

SDK Ruby com suporte a Rails

Beta
🐘

PHP

SDK PHP com suporte a Laravel

Alpha
🔷

C#

SDK .NET Core e Framework

Em desenvolvimento
🦀

Rust

SDK Rust com async/await

Planejado
🍎

Swift

SDK iOS e macOS

Planejado
🟣

Kotlin

SDK Android e JVM

Planejado
Changelog

Histórico de Versões

Acompanhe todas as atualizações, melhorias e correções da API nSeven. Mantemos você informado sobre cada mudança.

v2.1.0

latestMajor

Novos endpoints de webhooks e melhorias de performance

2024-01-153 mudanças

Webhooks em tempo real

feature

Adicionados webhooks para notificações instantâneas de mudanças de score

Eventos: score.updated, risk.alert, user.verified
Validação HMAC para segurança
Retry automático com backoff exponencial

Performance otimizada

improvement

Redução de 40% no tempo de resposta da API

Cache distribuído implementado
Otimização de queries no banco
Compressão gzip habilitada

Novos insights de risco

feature

Análise mais detalhada dos fatores de risco

Categorização por tipo de risco
Recomendações personalizadas
Histórico de mudanças de score

v2.0.5

stable

Correções de bugs e melhorias de estabilidade

2024-01-082 mudanças

v2.0.0

stableMajor

Nova versão da API com breaking changes

2023-12-203 mudanças

v1.8.2

deprecated

Última versão da API v1 - migração recomendada

2023-12-102 mudanças

Migração da API v1

A API v1 será descontinuada em junho de 2024. Recomendamos migrar para a v2 o quanto antes para aproveitar as novas funcionalidades e melhorias de performance.

Fique por dentro das atualizações

Receba notificações sobre novas versões, breaking changes e melhorias importantes da API.

Pronto para transformar sua empresa?