Improvements to api docs & test env

[MattiaMarchiorato]

Ciao FIC Team,

La documentazione API è scritta a tratti in maniera approssivativa, non ci sono informazioni essenziali per poter usarele in maniera completa, un esempio non dite come verificate se un cliente esiste già e non date un elenco (o almeno non l'ho visto) di response per i vari scenari. Sarebbe anche utile un ambiente di playground dove si possano effettuare chiamate senza autenticare la propria utenza di FIC e senza scrivere dati in produzione.

Cosa ancora più importante avere per l'account un abiente di test, ad oggi quando si sviluppa e si testa si scrive in produzione, questo è abbastanza preoccupante.

Buon lavoro

MM

[valmoz]

Buongiorno Mattia.
Grazie mille per i suggerimenti che ha condividiso con noi.

Ritengo che definire la nostra documentazione "approssimativa" sia quantomeno ingeneroso, data la quantità di materiale che abbiamo messo a disposizione. In ogni caso, la documentazione non ha la pretesa di coprire tutte le funzionalità esistenti in questo momento e i relativi scenari, e proprio per coprire eventuali mancanze abbiamo deciso di creare questa community, in modo tale da permettere:

• una risposta rapida e puntuale a specifiche domande da parte degli sviluppatori
• nel caso in cui dovessimo individuare eventuali domande ricorrenti, un aggiornamento, correzione o integrazione della documentazione esistente

Anche il supporto clienti può essere utile per le stesse motivazioni, e risulta particolarmente utile nel caso in cui dovesse essere necessario condividere informazioni riservate, che non possono essere condivise sulla pagina pubblica della community.

Ad esempio, per la domanda relativa ai clienti suggerirei di aprire una discussion dedicata nella sezione Q&A, in modo tale da poter condividere una risposta con tutta la community a riguardo. Questa è la prima volta che ci viene condiviso questo dubbio, e per questo non abbiamo una risposta già disponibile tramite community.

Per quanto riguarda le risposte API, puoi trovare esempi di risposte all'interno della sezione API Reference, suddivise per ciascuno dei metodi API a disposizione.
Come già detto in precedenza non coprono tutte le casistiche possibili, ma permettono comunque di ottenere la struttura attesa delle risposte in caso di 200 OK e dei principali errori che possono verificarsi.

Per quanto riguarda ambiente di playground/di test, siamo già a conoscenza della problematica. Purtroppo non abbiamo una tempistica di risoluzione al momento.
Per come sono state definite le API è però possibile procedere con la creazione/cancellazione delle risorse senza problemi, permettendo di testare i diversi metodi API senza compromettere l'account. Molti nostri utenti hanno comunque deciso di creare un secondo account FIC di TEST che utilizzano per testare il codice senza sporcare l'account principale. Per evitare di dover acquistare una seconda licenza, è possibile richiedere al supporto clienti una licenza di prova per fini di developent e testing.
L'unico metodo che può effettivamente creare problemi è il Send E-Invoice, cioé il metodo utilizzato per inviare materialmente i documenti al SDI: in tal caso è necessario utilizzare il metodo con cautela, considerando però che:

• Se la fatturazione elettronica è disabilitata sull'account, il documento non viene comunque inviato all'SDI
• Se l'account ha una licenza di prova, non invia la fattura
• Stiamo comunque studiando una soluzione per aggirare il problema, ad esempio permettendo di utilizzare il metodo in modalità Dry Run

Spero di aver risposto ai suoi dubbi e perplessità. Ovviamente restiamo a disposizione per ulteriori domande e considerazioni da parte sua.

Grazie
Mauro

[MattiaMarchiorato]

Ciao Mauro,

grazie per la tua risposta, la mia segnalazione è volta al poter migliorare la documentazione già esistente, il nostro team si è trovato parecchie volte in difficoltà, specialmente analizzando le response delle api perchè non contengono informazioni sufficienti alla risoluzione del problema, essendo la documentazione sprovvista di questa documentazione (404 e 401 possono anche non essere documentate a nostro avviso), diventa lungo e difficoltoso aprire un issue o una Q&A o un ticket/chat di assistenza ogni volta che vengono riscontrate queste difficoltà, capiamo che è un progetto nella sua fase di crescita ma riteniamo che alcune informazioni siano fondamentali per avere delle API utilizzabili senza supporto diretto del team di sviluppo.

Vi metto qui qualche link che magari può aiutarvi nel processo di creazione della documentazione
https://swagger.io/blog/api-documentation/best-practices-in-api-documentation/
https://mailchimp.com/developer/marketing/docs/errors/

Per quanto riguarda testare in ambiente live l'unicoil Send E-Invoice non è l'unico problema se l'applicativo che usa API genera per esempio un centiaio di fatture al giorno, facendo dei test potrebbero saltare delle numerazioni e dovrebbero essere emesse manualmente note di credito causando non pochi problemi alla contabilità, per quanto riguarda invece la licenza free per test/sviluppo procederemo con una richiesta.

Buon lavoro

MM

[valmoz]

Ciao Mattia,
gentilmente, vi chiederei di fare un esempio di questa mancanza di informazioni sufficienti, a quanto mi dice dovrebbe avere diversi esempi a disposizione e potrebbero esserci utili per migliorare quanto documentato.

Per quanto riguarda la quantità di fatture generate, in ambiente di test non dovreste avere una quantità elevata di fatture, o sbaglio? (a meno di test di carico ovviamente) Comunque, utilizzando un account di test dovrebbe essere possibile risolvere il problema, perché la numerazione verrebbe "danneggiata" solamente sull'account secondario, senza influire su quello di PROD.

In ogni caso, comprendo che non avere un ambiente di test possa creare difficoltà, ma come già detto non abbiamo una tempistica di risoluzione al momento.
Se necessario, possiamo suggerirvi un workaround per tamponare il problema, anche se mi rendo conto che è una soluzione di molto inferiore all'avere un vero ambiente di test: utilizzando il nostro file OpenAPI è possibile generare un Mock per permettere di simulare i metodi API a disposizione. Ripeto, non è una soluzione ottimale, ma meglio di nulla.

Grazie mille,
Mauro

[MattiaMarchiorato]

Ciao Mauro,

Non abbiamo uno storico ma recupero da alcune chat che avevamo aperto:

Caso 1)
POST c/COMPANY_ID/issued_documents
Restituiva un 500 che come sapete un internal server error, non ci è mai capitato di ricevere un 500 da una API.

Caso 2)
POST c/COMPANY_ID/issued_documents
Restituiva un 404 perchè non si stava passando l'id del payment account all'interno del payment_list, ma un 404 è "The server can not find the requested resource. In the browser, this means the URL is not recognized." quindi la risposta non è coerente ne alla chiamata http ne alla problematica dato che l'endpoint esisteva.

Per quanto riguarda l'ambiente di test tu dicevi di usarle in produzione e cancellare il documento, ma come ti ho spiegato se creiamo il documento e verifichiamo da fatture in cloud e successivamente viene emessa una fattura reale prima di cancellare il test sballa tutta la numerazione. Ora abbiamo richiesto licenza di test come hai suggerito, direi di comunicare questa possibilità a livello di documentazione api, cosa ne pensi?

Rispetto al Mock l'account con licenza di test sarebbe una soluzione ottimale.

Grazie ancora

A presto

MM

[valmoz]

Caso 1)
Il 500 è dovuto al fatto he un errore imprevisto è avvenuto lato nostro (nessuno è esente da bug purtroppo), quindi ogni segnalazione a riguardo è bene accetta. Penso che in questo caso potesse essere legata al Payment Method assente, abbiamo risolto un bug relativo a questo problema di recente.

Caso 2)
A volte effettivamente ritorniamo codici non compatibili con la tipologia dell'errore, e stiamo procedendo a risolvere i casi che ci vengono sottoposti. In queto caso però non mi pare ci sia una incongruenza.
Secondo la documentazione mozilla:

The server can not find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist.

Quindi a nostro avviso rientriamo nel secondo caso, anche se la risorsa non è direttamente quella principale ma una sottorisorsa come il payment account, e per questo motivo secondo noi il codice d'errore è corretto.

Se si usa una diversa Company per i TEST, separata da quella di PROD e legata ad un diverso account dedicato ai test, le fatture vere verrebbero create solo sulla company A, mentre tutte le fatture di test verrebbero create solo sulla Company B, evitando di sballare la documentazione. Vi torna questa casistica?

L'informazione riguardante la trial licence è già disponibile sulla documentazione.

Sono sicuro che la licenza di test vi verrà approvata in poco tempo dai colleghi del supporto.

Grazie,
Mauro

[MattiaMarchiorato]

Ciao Mauro,

Ma certo ci mancherebbe, un errore 500 per un bug può capitare, però il 404 su quella chiamata non mi sembra corretto perchè comunque l'endpoint è relativo ai documenti emessi (esistenti), se non viene passato un parametro obbligatorio dovreste validare la richiesta e rispondere in base all'esito della validazione perchè altrimenti chi riceve un 404 non sa quale sia il problema, concordi?

Si riguardo all'account Test è tutto chiaro, tu facevi riferimento però alla produzione e per noi è molto difficile lavorare in produzione per il caso specifico che ti ho indicato, ottimo invece per l'aggiunta del trial license (quando abbiamo sviluppato eravate ancora in beta e forse mancava questa parte).

A presto

MM

[valmoz]

Ciao Mattia,
per noi è più corretto un 404, perché consideriamo la validazione come ricerca di valori formali (ad esempio un campo richiesto mancante) piuttosto che un errore del valore effettivo che tale dato assume (che richiede quindi altre tipologie di errori).
In questo caso il problema non è la mancanza di un parametro, ma il riferimento (formalmente valido, in quanto intero) punta ad un cliente che però non esiste, e per questo motivo riteniamo il 404 comunque corretto, anche se siamo un po' borderline in questo caso.

Per fortuna non abbiamo molte casistiche di questo tipo.

Grazie,
Mauro

[MattiaMarchiorato]

Ciao Mauro,

ora non ricordo il caso specifico ma l'errore credo fosse relativo alla mancanza di un parametro "l'id del payment account all'interno del payment_list" quindi non credo si tratti di una risorsa inesistente e un 404 non è la risposta corretta; comunque a prescindere se non viene specificato nella documentazione quali sono i dati obbligatori e restituite un 404 un developers come può capire cosa non sta funzionando? Mi sembra di difficile debug non credi?

Grazie mille

MM

[cleoni]

Salve, vorrei unirmi al post di Mattia che condivido in pieno.

Per favore, usciamo dalla logica per cui lo staff sente di doversi difendere per aver ricevuto una critica sulla qualità del proprio lavoro, non è di questo che stiamo parlando, la documentazione è estesissima e copre bene le operazioni più fondamentali tipo l'autenticazine iniziale ma secondo me manca una cosa davvero fondamentale, cerco di dare il mio punto di vista ben conscio che chi sta dall'altra parte affronta una enorme mole di lavoro (moltisime funzioni, api per più linguaggi).

Io uso PHP, vado sulla documentazione API reference che per qualsiasi operazione fornisce un codice JSON che in teoria potrebbe andare bene per tutti i linguaggi. Mi piacerebbe (e mi aspetto) di poter usare il codice dell'esempio.

Premo il pulsante TRY che si trova sotto a ogni esempio e ricevo sempre un messaggio d'errore "unhautorized".
Non so se sia un problema solo mio, ma la sostanza è che per provare qualsiasi cosa devo usare del codice fatto da me, e ho PHP.

E appunto, mi trovo un SDK che dopo aver fatto l'autenticazione (che OK è ben documentata e riesce senza problemi), invece di implementare una chiamata standard a cui io possa passare il JSON che vedo negli esempi della documentazione (pari pari, tipo copia-incolla) implementa invece tutta una serie di metodi per generare e trasmettere ciò che ho già visto nell'esempio. E' più di una volta che devo andare a spulciarmi il sorgente per capire quale metodo chiamare per fare una determinata cosa. Così non va bene.

Si può avere per favore un codice generico per mandare il JSON al vostro endpoint includendo il token ottenuto dopo l'autenticazione in modo che uno lo possa prendere dagli esempi e poi inviare così come lo trova?

Perché se questo non c'è purtroppo, (e dico purtroppo) bisogna che documentiate ogni singola classe e metodo della API, e a parte l'autenticazione iniziale per il resto io trovo documentato ben poco.
Ad esempio, per creare un nuovo cliente che classe e metodo devo chiamare?
ripeto, capisco le difficoltà (avete fatto gli SDK in molti linguaggi) ma cerchiamo di venirci incontro, con il codice generico copriamo tutti i casi già documentati nella API reference e abbiamo già risolto.
Più avanti, quando i vari metodi sarano tutti documentati uno potrà magari usare le classi specifiche per fare le varie operazioni.

[MattiaMarchiorato]

@cleoni per quanto riguarda l'errore "unhautorized" devi completare l'autenticazione con le credenziali https://developers.fattureincloud.it/api-reference#auth (noi usiamo il HTTP Bearer token) anche in fase di test, considera che poi le operazioni che fai hanno effetto operativamente l'account, quindi se fai una chiamata dall'ambiente di documentazione quella chiamata fa effetivamente qualcosa nell'account che hai inserito.

Per quanto riguarda l'sdk si "stacca" dalla documentazione api perchè è un livello sovrastante, diciamo che la documentazione è delle API (quindi puoi chiamare l'endpount passando un json come documentato) mentre i vari sdk sono documentati nel git https://github.com/fattureincloud/fattureincloud-php-sdk

Spero di esserti stato di aiuto.

A presto

MM

[valmoz]

Ciao @cleoni
come già detto, accettiamo ben volentieri ogni critica costruttiva, tra cui anche le sue. Cerchiamo però di esporre anche il nostro punto di vista, non tanto per difesa del nostro lavoro (che comunque mi sembra doverosa) ma per potersi confrontare ed eventualmente rivedere il nostro approccio se necessario.

Passando ai suoi punti:

• L'API Reference è un tool generico, utilizzabile da tutti e che quindi ha la necessità di ottenere un'autenticazione per poter effettuare chiamate REST effettive. Se così non fosse, significherebbe che tutti possono fare richieste sul suo account, e ciò equivarrebbe a sicurezza 0 ;) All'inizio della pagina della API Reference può trovare due modalità di autenticazione, cioé OAuth (in cui può passare il suo clientId e clientSecret ed ottenere un access token) oppure HTTP Bearer (in cui si passa direttamente l'access token, che può essere ottenuto o tramite OAuth o tramite autenticazione manuale); settando tale token dovrebbe risolvere il problema dell'unauthorized
• Purtroppo gli esempi copy-and-paste non possono essere funzionanti, e cercherò di spiegarle il motivo. Prendiamo ad esempio la Create Issued Document. All'interno del body contiene due riferimenti a risorse di diverso tipo, e cioé i Payment Account e i Payment Method. Questi ID cambiano per ciascun utente, e quindi l'unico modo per creare un metodo copy-and-paste funzionante consisterebbe nel generare automaticamente l'esempio ad personam, sulla base dell'utente che sta osservando la documentazione in quel momento. Ciò è purtroppo infattibile, richiederebbe una login alla documentazione.
• Per tutte le SDK (quindi non solo la PHP) i modelli delle richieste e delle risposte subiscono un marshal/unmarshal da e verso JSON (quindi i le richieste vengono trasformate in JSON per effettuare la richiesta, e la risposta JSON viene parsata per ottenere il modello della risposta). Ciò significa che, se volete, per tutte le SDK potete tranquillamente lavorare con JSON, e utilizzare librerie standard per trasformare il vostro JSON nel tipo richiesto dallo specifico modello. In particolare, per PHP può osservare un esempio di utilizzo parsing del JSON nelle classi di test della libreria PHP. Comunque sia, ho aperto un task per aggiungere una nota sull'unmarshal dei modelli alla documentazione delle SDK per non obbligare a cercare sulle classi di test (il marshal in realtà è già stato aggiunto)
• Nella pagina principale della repo di ogni SDK è presente il Readme della SDK. Ad esempio questo è il readme della PHP SDK. Scorrendo il readme, è presente la lista di tutti i metodi e di tutte le classi disponibili. Seguendo i link di ciascuna richiesta, è possibile osservare quali sono i modelli di richiesta e i modelli di risposta. Quindi mi pare che tutti i metodi siano documentati a sufficienza, senza poi contare che adottano quasi tutti una struttura standard, e che una volta compreso il funzionamento di un metodo gli altri dovrebbero venire di conseguenza. In generale, salvo specifiche funzionalità aggiuntive (ad esempio la Send E-Invoice) ogni classe API contiene un metodo List, Create, Modify e Delete. Ciascun metodo restituisce un risultato di tipo NomeDelMetodoResponse e, nel caso richieda un body, si aspetta in ingresso un parametro di tipo NomeDelMetodoRequest. Per tutte le API la modalità di inizializzazione con token è la stessa, quindi una volta inizializzata una API basta seguire la stessa procedura con le altre.
• A parte la documentazione presente sul Readme, abbiamo deciso di creare delle guide aggiuntive. Queste guide non copriranno mai tutti i casi possibili, perché molti casi d'uso in realtà sono standard e quindi non richiedono necessariamente una nostra spiegazione dettagliata. Ad esempio, abbiamo deciso di creare la guida per la creazione degli issued document perché, oltre ad essere il caso d'uso più comune tra gli utenti, richiede degli step aggiuntivi (come la ricerca del payment method e payment account) che non sono intuitivi e che richiedono quindi un supporto maggiore da parte nostra. Queste guide comunque possono essere integrate con informazioni aggiuntive, e per questo motivo ad esempio abbiamo deciso di creare in futuro una guida proprio per creare clienti/supplier senza avere duplicati (la consideravamo una operazione standard, ma visti i dubbi sorti è meglio scendere più nel dettaglio). Per tutto il resto esiste la community, a cui rispondiamo quasi in tempo reale.

Restiamo ovviamente aperti ad ulteriori osservazioni e suggerimenti. Stiamo solo cercando di fornire il miglior supporto possibile compatibilmente con le nostre possibilità (come può immaginare, nel nostro team API non ci occupiamo solo di Community, Documentazione ed SDK). :)

Buona giornata
Mauro

[cleoni]

Salve, rimango della mia idea.

Alla fine son riuscito per tentativi e usando la sola libreria Guzzle a mettere insieme una funzioncina la quale, ricevuto in input il codice JSON degli esempi della documentazione, funziona senza problemi sia per GET che per le altre oerazioni (ovviamente aggiunge l'header della autenticazione per il mio account).

Quindi ho risolto. Potete chiudere il ticket.

[valmoz]

Ciao @cleoni
siamo felici del fatto che sia riuscito a integrarsi correttamente con le nostre API.

Buona giornata
Mauro