API Get Client - ottenere anagrafica cliente anche tramite vat_number o tax_code

[Picaland]

Salve,
Vorrei sottoporvi un problema che riscontro nella mia applicazione riguardante la generazione / aggiornamento di clienti presenti su FIC.

Secondo le API Get Client /c/{company_id}/entities/clients/{client_id} per ottenere un cliente è necessario passare il client_id.

Nella mia applicazione questa cosa è limitante per alcuni motivi.
Intanto stiamo parlando di un plugin per Woocommerce per la generazione delle fatture, clienti ecc ecc...

In merito alle anagrafiche clienti il problema è questo:

1. posso generare clienti solo per utenti registrati sul sito altrimenti ciò causerebbe una duplicazione delle anagrafiche in quanto posso salvare il client_id che ottengo dalla risposta solo in caso di utenti registrati e non posso farlo per utenti anonimi. Salvare il client_id in questo momento mi è utile per evitare la duplicazione delle anagrafiche.

2. se su FIC esiste già un'anagrafica cliente es con p.iva 1234567890 e io dal plugin cerco di creare l'anagrafica del cliente con la p.iva 1234567890 (quindi stesso cliente) ottengo l'errore:

Esiste già un cliente con la stessa partita IVA / VAT number ...

Invece potendo fare un Get Client tramite vat_number o tax_code si potrebbe ottenere il cliente esistente già su FIC e decidere se crearlo nel caso in cui non esiste o aggiornalo nel caso in cui esiste.

Questo modo di recuperare il cliente permetterebbe anche la possibilità di creare anagrafiche di clienti anonimi in quanto il controllo anagrafica verrà fatto tramite Get Client vat_number o tax_code che risponderà a seconda se esiste o meno.

Visto le problematiche esposte per il mio caso d'uso un'eventuale mofifica in tal senso delle API (permettere il Get Client tramite vat_number o tax_code ) è auspicabile ?

Grazie!

[valmoz]

Buongiorno @Picaland
direi di no, in quanto lo scopo dei metodi Get è quello di andare a colpo sicuro, recuperando la risorsa nel caso in cui se ne conosca l'esistenza. Inoltre è importante mantenere l'uniformità di tutti i metodi Get, che richiedono l'utilizzo dell'identificativo principale per il recupero della risorsa; in questo caso l'identificativo è l'ID del cliente.

In ogni caso, la funzionalità che desidera è già presente tramite i metodi List, che a differenza dei metodi Get hanno lo scopo di effettuare una ricerca fornendo un elenco delle risorse disponibili.
Nel caso in questione, il metodo che deve usare è il List Clients.

Per tutti i metodi List inoltre è possibile filtrare i risultati restituiti, in modo tale da non restituire tutte le risorse, ma solo quelle di nostro interesse. Il filtraggio funziona aggiungendo il parametro "q" in querystring, il cui valore deve essere una query scritta in modo simile a quello della clausola "where" di SQL (e poi sottoposta a URL encoding).

La documentazione relativa a questa funzionalità è disponibile qui: Filter Results

In particolare, dalla sezione "Filterable Fields" il metodo List Clients risulta essere filtrabile sia per vat_number sia per tax_code, quindi un esempio di query per il suo caso specifico potrebbe essere:

vat_number = '03812340161' or tax_code = 'RSSMRG99A23206D'

Segnalo inoltre che le SDK mettono tutte a disposizione un Filter Helper, che permette di realizzare facilmente la query necessaria senza preoccuparsi di comporre la stringa.

Immaginando di usare la PHP SDK, il codice potrebbe essere:

$filter = new Filter();
$filter->where('vat_number', Operator::EQ, '03812340161');
$filter->or('tax_code', Operator::EQ, 'RSSMRG99A23206D');

$query = $filter->buildQuery(); // (vat_number = '03812340161' or tax_code = 'RSSMRG99A23206D')

La chiamata API potrà poi essere effettuata nel modo seguente:

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = FattureInCloud\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');

$apiInstance = new FattureInCloud\Api\ClientsApi(
    new GuzzleHttp\Client(),
    $config
);
$company_id = 12345;
$fieldset = 'detailed';
$q = "YOUR QUERY";

try {
    $result = $apiInstance->listClients($company_id, null, $fieldset, null, null, null, $q);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ClientsApi->listClients: ', $e->getMessage(), PHP_EOL;
}

Ci faccia sapere se ciò soddisfa le sue necessità.

Grazie
Mauro

[Picaland]

Grazie @valmoz ,
Non avevo approfondito molto il metodo List Clients ma per come me lo hai esposto credo sia la soluzione perfetta per il mio caso visto che tra l'altro uso FattureInCloud PHP SDK.

Grazie!