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.

api import documenti1 

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.

Esempio script PHP per eseguire la chiamata

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

Esempio per aggiornare lo stato 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.
L’attributo filename è obbligatorio e deve contenere il nome del file da importare

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

Email

Email

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

Email

Email

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.

Esempio script PHP per eseguire il controllo del log del connettore

<?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

 

 

0 su 5 - 0 valutazioni
Grazie per aver valutato questo contenuto.

bindCommerce

bindCommerce s.r.l.

Partita IVA IT07798861212 - SDI M5UXCR1
Registro imprese di Napoli - REA: NA - 910618
Capitale Sociale € 20.000,00 interamente versato
Tel: +39 011 089 122 0
E-mail: [email protected]

PON 2014>20 Riaccendiamo lo sviluppo