NoPos Connect

NoPos Connect è il nostro sistema OAuth unificato che ti permette di integrare facilmente tutti i servizi NoPos nella tua applicazione con un'unica autenticazione.

Caratteristiche principali

• OAuth 2.0 standard - Implementazione completa dello standard OAuth
• Autenticazione unificata - Un token per tutti i servizi NoPos
• Permessi granulari - Controllo preciso su cosa può fare la tua app
• Sicurezza enterprise - Token JWT con scadenza e validazione
• Setup in 5 minuti - Integrazione rapida e semplice

Come funziona

1. Registra la tua app

Crea un'applicazione nella dashboard NoPos e ottieni le tue credenziali:

• client_id - Identificatore univoco della tua app
• client_secret - Chiave segreta per l'autenticazione
• redirect_uri - URL di ritorno dopo l'autenticazione

2. Richiedi l'autorizzazione

Reindirizza l'utente alla pagina di autorizzazione NoPos Connect:

const authUrl = new URL('https://app.nopos.it/auth');
authUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
authUrl.searchParams.set('client_secret', 'YOUR_CLIENT_SECRET');
authUrl.searchParams.set('redirect_uri', 'YOUR_REDIRECT_URI');
authUrl.searchParams.set('scopes', 'payments:read payments:write fiscal:read');
authUrl.searchParams.set('state', generateRandomState());

window.location.href = authUrl.toString();

3. Ricevi il token

Dopo l'autorizzazione, l'utente viene reindirizzato alla tua app con il token:

https://your-app.com/callback?
access_token=ACCESS_TOKEN&
token_type=Bearer&
expires_in=3600&
scope=payments:read payments:write fiscal:read&
state=RANDOM_STATE_VALUE

4. Usa le API

Utilizza il token per accedere alle API NoPos:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
   https://api.nopos.it/v1/payments

Scopes disponibili

Pagamenti

• payments:read - Leggere informazioni sui pagamenti
• payments:write - Creare e gestire pagamenti

Fatturazione

• fiscal:read - Leggere fatture e documenti fiscali
• fiscal:write - Creare e inviare fatture

E-commerce

• store:read - Leggere ordini e prodotti
• store:write - Gestire ordini e inventario

Esempi di integrazione

JavaScript/Node.js

// 1. Reindirizza l'utente per l'autorizzazione
const authUrl = new URL('https://app.nopos.it/auth');
authUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
authUrl.searchParams.set('client_secret', 'YOUR_CLIENT_SECRET');
authUrl.searchParams.set('redirect_uri', 'https://your-app.com/callback');
authUrl.searchParams.set('scopes', 'payments:read payments:write');
authUrl.searchParams.set('state', generateRandomState());

window.location.href = authUrl.toString();

// 2. Gestisci il callback
app.get('/callback', (req, res) => {
const { access_token, scope, state } = req.query;

// Valida lo state per sicurezza
if (state !== expectedState) {
  return res.status(400).send('Invalid state');
}

// Salva il token e procedi
saveToken(access_token);
res.redirect('/dashboard');
});

// 3. Usa il token per le API
async function getPayments(token) {
const response = await fetch('https://api.nopos.it/v1/payments', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

return response.json();
}

Python

import requests
from urllib.parse import urlencode

# 1. Genera URL di autorizzazione
auth_params = {
  'client_id': 'YOUR_CLIENT_ID',
  'client_secret': 'YOUR_CLIENT_SECRET',
  'redirect_uri': 'https://your-app.com/callback',
  'scopes': 'payments:read payments:write',
  'state': generate_random_state()
}

auth_url = f"https://app.nopos.it/auth?{urlencode(auth_params)}"
print(f"Redirect user to: {auth_url}")

# 2. Gestisci il callback
@app.route('/callback')
def callback():
  access_token = request.args.get('access_token')
  scope = request.args.get('scope')
  state = request.args.get('state')
  
  # Valida lo state
  if state != expected_state:
      return "Invalid state", 400
  
  # Salva il token
  save_token(access_token)
  return redirect('/dashboard')

# 3. Usa il token per le API
def get_payments(token):
  headers = {
      'Authorization': f'Bearer {token}',
      'Content-Type': 'application/json'
  }
  
  response = requests.get('https://api.nopos.it/v1/payments', headers=headers)
  return response.json()

PHP

<?php
// 1. Genera URL di autorizzazione
$authParams = [
  'client_id' => 'YOUR_CLIENT_ID',
  'client_secret' => 'YOUR_CLIENT_SECRET',
  'redirect_uri' => 'https://your-app.com/callback',
  'scopes' => 'payments:read payments:write',
  'state' => generateRandomState()
];

$authUrl = 'https://app.nopos.it/auth?' . http_build_query($authParams);
echo "Redirect user to: " . $authUrl;

// 2. Gestisci il callback
if ($_GET['code']) {
  $accessToken = $_GET['access_token'];
  $scope = $_GET['scope'];
  $state = $_GET['state'];
  
  // Valida lo state
  if ($state !== $expectedState) {
      http_response_code(400);
      echo "Invalid state";
      exit;
  }
  
  // Salva il token
  saveToken($accessToken);
  header('Location: /dashboard');
}

// 3. Usa il token per le API
function getPayments($token) {
  $headers = [
      'Authorization: Bearer ' . $token,
      'Content-Type: application/json'
  ];
  
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.nopos.it/v1/payments');
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  return json_decode($response, true);
}
?>

Sicurezza

State Parameter

Sempre utilizzare il parametro state per prevenire attacchi CSRF:

const state = crypto.randomBytes(32).toString('hex');
// Salva lo state in sessione o database
// Verifica che corrisponda nel callback

Token Storage

• Non memorizzare il token nel localStorage per applicazioni web
• Usa sessionStorage o cookie sicuri
• Implementa refresh automatico del token

HTTPS

• Sempre utilizzare HTTPS in produzione
• Valida che redirect_uri sia HTTPS per sicurezza

Gestione errori

Errori comuni

Codice	Descrizione	Soluzione
invalid_client	Client ID o secret non validi	Verifica le credenziali
invalid_redirect_uri	Redirect URI non autorizzato	Configura l'URI nella dashboard
invalid_scope	Scope non supportato	Usa solo scope validi
access_denied	Utente ha negato l'autorizzazione	Richiedi nuovamente

Esempio gestione errori

app.get('/callback', (req, res) => {
  const { error, error_description, access_token } = req.query;
  
  if (error) {
    console.error(`OAuth error: ${error} - ${error_description}`);
    return res.redirect('/error?message=' + encodeURIComponent(error_description));
  }
  
  if (access_token) {
    // Successo - procedi con il token
    saveToken(access_token);
    res.redirect('/dashboard');
  }
});

Best Practices

1. Usa sempre HTTPS in produzione
2. Implementa il refresh token per sessioni lunghe
3. Valida sempre lo state per sicurezza CSRF
4. Gestisci gli errori in modo user-friendly
5. Logga le attività per debugging e sicurezza
6. Testa in sviluppo prima del deploy in produzione

Supporto

Hai bisogno di aiuto con NoPos Connect?

• Documentazione API
• Supporto tecnico
• Segnala bug

---

NoPos Connect - L'integrazione che funziona davvero