API: Dati Comuni

Descrizione

Questa sezione descrive i parametri comuni richiesti da tutte le API disponibili in questo servizio dopo aver effettuato il "First Login". La struttura indicata si applica a tutte le API tranne firstLogin e getAuth, che seguono una struttura diversa. Questi parametri devono essere inclusi in ogni altra chiamata API per garantire l'autenticazione e l'autorizzazione delle richieste.

Parametri Comuni

  • action (obbligatorio): Specifica l'azione API da eseguire. Questo parametro determina quale funzione dell'API verrà invocata (es. login, auth, inviaFattura, ecc.).
  • key (obbligatorio): La chiave API unica associata all'utente. Questa chiave è necessaria per autenticare la richiesta.
  • code (obbligatorio): Il codice univoco associato alla chiave API. Serve a rafforzare l'autenticazione della richiesta.
  • payload (obbligatorio): Un oggetto JSON che contiene i dati specifici per l'azione API richiesta. La struttura e il contenuto di payload variano a seconda dell'azione specificata.

Formato di una Chiamata API Tipica

Le richieste API devono essere inviate tramite POST all'endpoint:

https://www.fattureweb.com/api/

Di seguito è riportato un esempio generale di chiamata API:

{
    "action": "nome_azione",
    "key": "esistenteAPIKey",
    "code": "randomCode123",
    "payload": {
        "api_name": "NomeAPI",
        "method": "nomeMetodo",
        "input": {
            "parametro1": "valore1",
            "parametro2": "valore2"
        }
    }
}

Ogni chiamata API richiede la specificazione dell'azione (action) e l'inclusione della chiave (key) e del codice (code). Il payload contiene i dati specifici per l'azione richiesta.

Esempi di Codice



$url = 'https://www.fattureweb.com/api/';
$data = array(
    'action' => 'nome_azione',
    'key' => 'esistenteAPIKey',
    'code' => 'randomCode123',
    'payload' => array(
        'api_name' => 'NomeAPI',
        'method' => 'nomeMetodo',
        'input' => array(
            'parametro1' => 'valore1',
            'parametro2' => 'valore2'
        )
    )
);
$options = array(
    'http' => array(
        'header'  => "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data),
    ),
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) { /* Handle error */ }

var_dump($result);

                    

import requests

url = 'https://www.fattureweb.com/api/'
data = {
    'action': 'nome_azione',
    'key': 'esistenteAPIKey',
    'code': 'randomCode123',
    'payload': {
        'api_name': 'NomeAPI',
        'method': 'nomeMetodo',
        'input': {
            'parametro1': 'valore1',
            'parametro2': 'valore2'
        }
    }
}

response = requests.post(url, json=data)
print(response.text)
                    

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://www.fattureweb.com/api/");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json; utf-8");
            conn.setDoOutput(true);

            String jsonInputString = "{\"action\": \"nome_azione\", \"key\": \"esistenteAPIKey\", \"code\": \"randomCode123\", \"payload\": {\"api_name\": \"NomeAPI\", \"method\": \"nomeMetodo\", \"input\": {\"parametro1\": \"valore1\", \"parametro2\": \"valore2\"}}}";
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);
            }

            int responseCode = conn.getResponseCode();
            System.out.println("Response Code: " + responseCode);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
                    

Risposta di Successo Generica

Di seguito è riportato un esempio di risposta di successo generica che potrebbe essere restituita da una qualsiasi delle API:

{
    "code": "200",
    "result": {
        "chiave_specifica1": "valore1",
        "chiave_specifica2": "valore2"
    }
}

Il campo result contiene le informazioni specifiche dell'azione eseguita.

Risposta di Errore Generica

Di seguito è riportato un esempio di risposta di errore generica che potrebbe essere restituita da una qualsiasi delle API:

{
    "code": "401.0",
    "error": "Unauthorized access. Invalid auth_key, please verify it."
}

Il campo error contiene il messaggio di errore che descrive il problema riscontrato.