L’API import documenti consente ad un sistema esterno (ad esempio un gestionale di magazzino) di aggiungere o aggiornare uno o più documenti di vendita (ordini o fatture), compresi eventuali allegati.
Configurazione connettore su bindCommerce
Per effettuare la configurazione dell’apposito connettore è necessario andare al menù
Processi >> Connettori
Cliccare su Aggiungi e compilare i campi come segue:
- Nome connettore: indicare il nome che si preferisce
- Tipo nodo (tecnologia): API
- Nodo: il nodo di tipo API precedentemente creato. Per maggiori informazioni in merito alla creazione di questo nodo visitare la pagina Nodo API
- Tipo connettore: API [import documenti]
Cliccando su SALVA E CONTINUA si avrà accesso all’URL a cui il sistema chiamante dovrà effettuare la chiamata.
Chiamata ed autenticazione
La chiamata viene effettuata all’URL generato da bindCommerce per lo specifico connettore (da configurare attraverso l’interfaccia di bindCommerce come spiegato al precedente paragrafo).
L’autenticazione avviene attraverso token assegnato per il nodo API. Il parametro viene trasmesso nell'header della richiesta.
<?php
// $strXml = … contenuto del file xml
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://miohost.bindcommerce.cloud/integrator-tool/api/documents.php?connector=N",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $strXml,
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: text/xml",
"token: 0a09039b989e7b705da2575ec4ae882f"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Questa chiamata restituisce un json così formato:
[ 'status' => success || error 'message' => Stringa con la descrizione del log del connettore 'code' => un codice numerico che esprime successo o fallimento v. di seguito (CHIAMATA DI CONTROLLO DELLO STATO) per un elenco completo 'id_exec' => opzionale - id esecuzione, viene fornito nel caso sia necessario utilizzarlo nella CHIAMATA DI CONTROLLO DELLO STATO 'id_procedure' => opzionale - id procedura, viene fornito nel caso sia necessario utilizzarlo nella CHIAMATA DI CONTROLLO DELLO STATO ]
File Documenti
Nel file XML inviato è necessario specificare il tipo di operazione che si intende effettuare attraverso il tag:
<bindCommerceDocuments mode="[inserire il tipo di azione]">
I possibili valori sono
- CreateModify: serve a creare o modificare un documento, il quale avrà come nodo assegnatario quello di tipo API che sta effettuando la chiamata. Questa modalità può ad esempio essere utilizzata da una piattaforma eCommerce o un marketplace per gestire l'integrazione con bindCommerce.
- StatusUpdate: serve ad aggiornare lo stato di un documento o di una o più righe del documento, anche nel caso in cui l'ordine sia stato generato da un canale di vendita diverso dal nodo che sta effettuando la chiamata.
Quando la modalità scelta è StatusUpdate lo stato che viene inviato per l'ordine o la riga ordine (<State>) deve trovare una corrispondenza con i possibili stati già presenti in bindCommerce nella tabella delle corrispondenze (consultabile e modificabile seguendo il menu "Processi > Conversioni e normalizzazioni > Conversione stati ordine"). La tecnologia di partenza dovrà essere "API" e lo stato di partenza quello scritto nel file XML inviato. Se tale stato non è presente in bindCommerce sarà necessario crearlo (seguendo il menu "Parametri di sistema > Stati ordine").
In mancanza di corrispondenza lo stato dell'ordine non verrà aggiornato.
Quando la modalità scelta è CreateModify, se non è già presente lo stato inviato per l'ordine o la riga ordine (<State>), bindCommerce provvederà a crearlo (abbinato al nodo di tipo API che ha effettuato la creazione o modifica dell'ordine.
<?xml version="1.0" encoding="UTF-8"?>
<bindCommerceDocuments mode="StatusUpdate">
<Documents>
<Document>
<General>
<bindNumber>15918</bindNumber>
(oppure <OrderNumber>89568-GFGNJK</OrderNumber>)
<LastUpdate>2021:01:10 12:36:19</LastUpdate>
<State>Shipped</State>
</General>
<Shipping>
<Carrier>UPS</Carrier>
<TrackingNumber>254131634364326012</TrackingNumber>
<TransportedWeight>0.2</TransportedWeight>
<ShippedTime>2021-03-23 16:47:22</ShippedTime>
</Shipping>
</Document>
<Document>
[…..]
</Document>
</Documents>
</bindCommerceDocuments>
Campi del file
DICHIARAZIONI GENERALI
Campo | Descrizione |
---|---|
Documents | Contiene uno o più tag <Document> |
INFORMAZIONI SUL DOCUMENTO (GENERAL)
Campo | Descrizione |
---|---|
DocumentType | Tipo di documento. Nelle implementazioni standard viene usato (C = Ordine cliente, E = Ordine fornitore, I = Fattura, N = Nota di credito, R = Ricevuta) |
bindNumber | Identificativo interno bindCommerce, Non deve essere compilato per creare un nuovo documento |
OrderNumber | Numero ordine cliente o fornitore relativo al nodo di origine del documento. Non verrà considerato in fase di aggiornamento se è anche presente il campo Id. |
DocumentNumber | Numero documento diverso da ordine (fattura, nota di credito o ricevuta). Non verrà considerato in fase di aggiornamento se è anche presente il campo Id. |
Date | Data ed ora di creazione (Orario UTC) |
LastUpdate | Data ed ora di ultimo aggiornamento (Orario UTC) |
State | Stato del documento. Valore libero per identificare lo stato del documento nel nodo di origine. Il valore trasmesso assume valenza di codice sebbene possa essere parlante (es. Shipped, Cancelled, Unshipped, Sent, ecc..) |
B2B | Ordine B2B (1 oppure 0) |
Currency | Valuta ISO 4217 (es. EUR, CHF, GBP, USD). |
Notes | Note inserite dall’acquirente (rif. notes) |
SellerNote | Note inserite dal venditore (rif. seller_note) |
ALLEGATI (ATTACHMENTS)
Campo | Descrizione |
---|---|
Attached | Contenuto del file da allegare codificato in MIME base64. |
INFORMAZIONI DI FATTURAZIONE (CUSTOMER)
Campo | Descrizione |
---|---|
Code | Codice alfanumerico che identifica il cliente |
Name | Nome |
Surname | Cognome |
Company | Azienda |
Address | Via e numero civico |
Postcode | Codice di avviamento postale |
City | Comune |
Province | Provincia |
CountryCode | Codice nazione ISO 3166-1 Alpha-2 (es. IT) |
VatCode | Partita IVA |
FiscalCode | Codice fiscale o identificativo analogo (per clienti esteri) |
Phone | Telefono |
MobPhone | Telefono mobile |
EInvoiceDestCode | Codice destinatario per la fatturazione elettronica (SDI) o indirizzo PEC |
Pec | Posta Elettronica Certificata |
INFORMAZIONI DI SPEDIZIONE (DELIVERY)
Campo | Descrizione |
---|---|
Name | Nome |
Surname | Cognome |
Company | Azienda |
Address | Via e numero civico |
Postcode | Codice di avviamento postale |
City | Comune |
Province | Provincia |
CountryCode | Codice nazione ISO 3166-1 Alpha-2 (es. IT) |
Phone | Telefono |
MobPhone | Telefono mobile |
INFORMAZIONI SUL PAGAMENTO (PAYMENTS)
Campo | Descrizione |
---|---|
PaymentName | Nome del metodo di pagamento |
PaymentCode | Codice del metodo di pagamento |
PaymentStatus | Stato del pagamento. Valori possibili: "Complete", "Incomplete", "Pending" |
PaymentTotal | Costo di incasso IVA compresa (ad esempio per i pagamenti in contrassegno è previsto un costo aggiuntivo a carico del cliente) |
PaidTime | Data ed ora del pagamento |
RIGHE ORDINE (ROWS)
Ogni riga ordine è contenuta in un tag <Row>
Campo | Descrizione |
---|---|
Code | Codice SKU del prodotto |
Description | Descrizione della riga ordine come compare sul canale di vendita. |
Qty | Quantità acquistata (numero) |
PriceVatExcluded | Prezzo unitario IVA esclusa (eventualmente già scontato) |
Price | Prezzo unitario IVA compresa (eventualmente già scontato) |
VatRate | Aliquota IVA (es. 0.22 per indicare il 22%). |
IMPORTI (AMOUNTS)
Campo | Descrizione |
---|---|
ShippingCost | Costo spedizione IVA compresa |
ShippingTax | IVA sulla spedizione |
CouponDiscount | Sconto coupon (rif. coupon_discount) |
CouponCode | Codice coupon |
DiscountToCart | Sconto al carrello |
Total | Totale ordine comprensivo di tutte le spese e tutti i costi |
INFORMAZIONI SULLA SPEDIZIONE (SHIPPING)
Campo | Descrizione |
---|---|
Carrier | Spedizioniere |
TrackingNumber | Codice di tracciabilità |
TransportedWeight | Peso trasportato |
ShippedTime | Data ed ora di spedizione |
ShippingMethod | Metodo di spedizione |
CHIAMATA DI CONTROLLO DELLO STATO
La chiamata precedente di importazione dei documenti ti via API prende in consegna tutti i documenti e fornisce un risultato di successo solo in merito alla presa in consegna, ma non in merito all’esito finale di importazione. Ciò perché è una chiamata batch che può richiedere diversi minuti. Per controllare invece l’esito dell’importazione occorre effettuare una nuova chiamata che fornisce il log di stato dell’esecuzione.
Lo stesso log può essere consultato dal menu “Logs > Log esecuzione connettori”
Per farlo invece a livello programmatico si può usare la seguente funzione (dove N = id del connettore).
In aggiunta al parametro id (che è sempre obbligatorio) è possibile utilizzare i parametri id_exec e id_procedure così come restituiti dalla chiamata precedente (v. Chiamata ed autenticazione).
L’autenticazione avviene attraverso lo stesso token assegnato per il nodo API.
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://miohost.bindcommerce.cloud/integrator-tool/api/connector_status.php?id=N",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: text/xml",
"token: 0a09039b989e7b705da2575ec4ae882f"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Questa chiamata restituisce un json così formato:
[ 'status' => success || error 'message' => Stringa con la descrizione del log del connettore 'code' => un codice numerico che esprime successo o fallimento ]
Nel caso in cui vengano specificati i parametri id_exec oppure id_exec e id_procedure il campo "message" verrà valorizzato con il contenuto del file di log in formato CSV.
Di seguito si riportano i valori del parametro code
200 => nessun connettore in esecuzione
201 => connettore in esecuzione
401 => errore interno
402 => manca il connettore
403 => errore interno
404 => manca il token di autenticazione
405 => token non configurato nel nodo
406 => autenticazione fallita
407 => connettore inesistente