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 connessione di NoPos:

const connectUrl = new URL('https://app.nopos.it/connect');
connectUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
connectUrl.searchParams.set('redirect_uri', 'YOUR_REDIRECT_URI');
connectUrl.searchParams.set('scopes', 'payments:read payments:write fiscals:read');
connectUrl.searchParams.set('state', generateRandomState());

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

3. Ricevi il codice di autorizzazione

Dopo l'autorizzazione, l'utente viene reindirizzato alla tua app con un codice di autorizzazione:

https://your-app.com/callback?
code=AUTHORIZATION_CODE&
state=RANDOM_STATE_VALUE

4. Scambia il codice per il token

Scambia il codice di autorizzazione con il token usando il tuo client_secret:

curl -X POST https://api.nopos.it/v1/auth/token \
   -H "Content-Type: application/json" \
   -d '{
     "code": "AUTHORIZATION_CODE",
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET",
     "redirect_uri": "https://your-app.com/callback"
   }'

5. 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

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

E-commerce

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

Esempi di integrazione

JavaScript/Node.js

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

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

// 2. Gestisci il callback e scambia il code per il token
app.get('/callback', async (req, res) => {
const { code, state } = req.query;

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

// Scambia il code per il token
const tokenResponse = await fetch('https://api.nopos.it/v1/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code: code,
    client_id: process.env.NOPOS_CLIENT_ID,
    client_secret: process.env.NOPOS_CLIENT_SECRET,
    redirect_uri: 'https://your-app.com/callback'
  })
});

const tokenData = await tokenResponse.json();

// Salva il token e procedi
saveToken(tokenData.accessToken);
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
import os

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

connect_url = f"https://app.nopos.it/connect?{urlencode(connect_params)}"
print(f"Redirect user to: {connect_url}")

# 2. Gestisci il callback e scambia il code per il token
@app.route('/callback')
def callback():
  code = request.args.get('code')
  state = request.args.get('state')
  
  # Valida lo state
  if state != expected_state:
      return "Invalid state", 400
  
  # Scambia il code per il token
  token_response = requests.post('https://api.nopos.it/v1/auth/token', json={
      'code': code,
      'client_id': os.getenv('NOPOS_CLIENT_ID'),
      'client_secret': os.getenv('NOPOS_CLIENT_SECRET'),
      'redirect_uri': 'https://your-app.com/callback'
  })
  
  token_data = token_response.json()
  
  # Salva il token
  save_token(token_data['accessToken'])
  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
$connectParams = [
  'client_id' => 'YOUR_CLIENT_ID',
  'redirect_uri' => 'https://your-app.com/callback',
  'scopes' => 'payments:read payments:write',
  'state' => generateRandomState()
];

$connectUrl = 'https://app.nopos.it/connect?' . http_build_query($connectParams);
echo "Redirect user to: " . $connectUrl;

// 2. Gestisci il callback e scambia il code per il token
if (isset($_GET['code'])) {
  $code = $_GET['code'];
  $state = $_GET['state'];
  
  // Valida lo state
  if ($state !== $expectedState) {
      http_response_code(400);
      echo "Invalid state";
      exit;
  }
  
  // Scambia il code per il token
  $ch = curl_init('https://api.nopos.it/v1/auth/token');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'code' => $code,
      'client_id' => getenv('NOPOS_CLIENT_ID'),
      'client_secret' => getenv('NOPOS_CLIENT_SECRET'),
      'redirect_uri' => 'https://your-app.com/callback'
  ]));
  
  $response = curl_exec($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);
  
  if ($httpCode === 200) {
      $tokenData = json_decode($response, true);
      
      // Salva il token
      saveToken($tokenData['accessToken']);
      header('Location: /dashboard');
  } else {
      http_response_code(400);
      echo "Token exchange failed";
  }
}

// 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
• Configura i domini consentiti nella dashboard dell'app (es. example.com, app.example.com)
• 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 i domini consentiti 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