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